SPP API
Application Example
Check bluetooth/bluedroid/classic_bt folder in ESP-IDF examples, which contains the following application:
- This is a SPP demo. This demo can discover the service, connect, send and recive SPP data bluetooth/bluedroid/classic_bt/bt_spp_acceptor, bluetooth/bluedroid/classic_bt/bt_spp_initiator
API Reference
Header File
This header file can be included with:
#include "esp_spp_api.h"
- This header file is a part of the API provided by the
btcomponent. To declare that your component depends onbt, add the following to your CMakeLists.txt:
REQUIRES btor
> PRIV_REQUIRES bt
Functions
esp_err_t esp_spp_register_callback(esp_spp_cb_t callback)
This function is called to init callbacks with SPP module.
Parameters
callback -- [in] pointer to the init callback function.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_init(esp_spp_mode_t mode)
This function is called to init SPP module. When the operation is completed, the callback function will be called with ESP_SPP_INIT_EVT. This function should be called after esp_bluedroid_enable() completes successfully.
Parameters
mode -- [in] Choose the mode of SPP, ESP_SPP_MODE_CB or ESP_SPP_MODE_VFS.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_enhanced_init(const esp_spp_cfg_t *cfg)
This function is called to init SPP module. When the operation is completed, the callback function will be called with ESP_SPP_INIT_EVT. This function should be called after esp_bluedroid_enable() completes successfully.
Note
The member variable enable_l2cap_etrm in esp_spp_cfg_t can affect all L2CAP channel configurations of the upper layer RFCOMM protocol.
Parameters
cfg -- [in] SPP configuration.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_deinit(void)
This function is called to uninit SPP module. The operation will close all active SPP connection first, then the callback function will be called with ESP_SPP_CLOSE_EVT, and the number of ESP_SPP_CLOSE_EVT is equal to the number of connection. When the operation is completed, the callback function will be called with ESP_SPP_UNINIT_EVT. This function should be called after esp_spp_init()/esp_spp_enhanced_init() completes successfully.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_start_discovery(esp_bd_addr_t bd_addr)
This function is called to performs service discovery for the services provided by the given peer device. When the operation is completed, the callback function will be called with ESP_SPP_DISCOVERY_COMP_EVT. This function must be called after esp_spp_init()/esp_spp_enhanced_init() successful and before esp_spp_deinit().
Parameters
bd_addr -- [in] Remote device bluetooth device address.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_connect(esp_spp_sec_t sec_mask, esp_spp_role_t role, uint8_t remote_scn, esp_bd_addr_t peer_bd_addr)
This function makes an SPP connection to a remote BD Address. When the connection is initiated or failed to initiate, the callback is called with ESP_SPP_CL_INIT_EVT. When the connection is established or failed, the callback is called with ESP_SPP_OPEN_EVT. This function must be called after esp_spp_init()/esp_spp_enhanced_init() successful and before esp_spp_deinit().
Parameters
sec_mask -- [in] Security Setting Mask. Suggest to use ESP_SPP_SEC_NONE, ESP_SPP_SEC_AUTHORIZE or ESP_SPP_SEC_AUTHENTICATE only.
role -- [in] Master or slave.
remote_scn -- [in] Remote device bluetooth device SCN.
peer_bd_addr -- [in] Remote device bluetooth device address.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_disconnect(uint32_t handle)
This function closes an SPP connection. When the operation is completed, the callback function will be called with ESP_SPP_CLOSE_EVT. This function must be called after esp_spp_init()/esp_spp_enhanced_init() successful and before esp_spp_deinit().
Parameters
handle -- [in] The connection handle.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_start_srv(esp_spp_sec_t sec_mask, esp_spp_role_t role, uint8_t local_scn, const char *name)
This function create a SPP server and starts listening for an SPP connection request from a remote Bluetooth device. When the server is started successfully, the callback is called with ESP_SPP_START_EVT. When the connection is established, the callback is called with ESP_SPP_SRV_OPEN_EVT. This function must be called after esp_spp_init()/esp_spp_enhanced_init() successful and before esp_spp_deinit().
Parameters
sec_mask -- [in] Security Setting Mask. Suggest to use ESP_SPP_SEC_NONE, ESP_SPP_SEC_AUTHORIZE or ESP_SPP_SEC_AUTHENTICATE only.
role -- [in] Master or slave.
local_scn -- [in] The specific channel you want to get. If channel is 0, means get any channel.
name -- [in] Server's name.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_stop_srv(void)
This function stops all SPP servers. The operation will close all active SPP connection first, then the callback function will be called with ESP_SPP_CLOSE_EVT, and the number of ESP_SPP_CLOSE_EVT is equal to the number of connection. When the operation is completed, the callback is called with ESP_SPP_SRV_STOP_EVT. This function must be called after esp_spp_init()/esp_spp_enhanced_init() successful and before esp_spp_deinit().
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_stop_srv_scn(uint8_t scn)
This function stops a specific SPP server. The operation will close all active SPP connection first on the specific SPP server, then the callback function will be called with ESP_SPP_CLOSE_EVT, and the number of ESP_SPP_CLOSE_EVT is equal to the number of connection. When the operation is completed, the callback is called with ESP_SPP_SRV_STOP_EVT. This function must be called after esp_spp_init()/esp_spp_enhanced_init() successful and before esp_spp_deinit().
Parameters
scn -- [in] Server channel number.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_write(uint32_t handle, int len, uint8_t *p_data)
This function is used to write data, only for ESP_SPP_MODE_CB. When this function need to be called repeatedly, it is strongly recommended to call this function again after the previous event ESP_SPP_WRITE_EVT is received and the parameter 'cong' is equal to false. If the previous event ESP_SPP_WRITE_EVT with parameter 'cong' is equal to true, the function can only be called again when the event ESP_SPP_CONG_EVT with parameter 'cong' equal to false is received. This function must be called after an connection between initiator and acceptor has been established.
Parameters
handle -- [in] The connection handle.
len -- [in] The length of the data written.
p_data -- [in] The data written.
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_vfs_register(void)
This function is used to register VFS. For now, SPP only supports write, read and close. When the operation is completed, the callback function will be called with ESP_SPP_VFS_REGISTER_EVT. This function must be called after esp_spp_init()/esp_spp_enhanced_init() successful and before esp_spp_deinit().
Returns
ESP_OK: success
other: failed
esp_err_t esp_spp_vfs_unregister(void)
This function is used to unregister VFS. When the operation is completed, the callback function will be called with ESP_SPP_VFS_UNREGISTER_EVT. This function must be called after esp_spp_vfs_register() successful and before esp_spp_deinit().
Returns
ESP_OK: success
other: failed
Unions
union esp_spp_cb_param_t
#include <esp_spp_api.h>
SPP callback parameters union.
Public Members
struct esp_spp_cb_param_t::spp_init_evt_param init
SPP callback param of SPP_INIT_EVT
struct esp_spp_cb_param_t::spp_uninit_evt_param uninit
SPP callback param of SPP_UNINIT_EVT
struct esp_spp_cb_param_t::spp_discovery_comp_evt_param disc_comp
SPP callback param of SPP_DISCOVERY_COMP_EVT
struct esp_spp_cb_param_t::spp_open_evt_param open
SPP callback param of ESP_SPP_OPEN_EVT
struct esp_spp_cb_param_t::spp_srv_open_evt_param srv_open
SPP callback param of ESP_SPP_SRV_OPEN_EVT
struct esp_spp_cb_param_t::spp_close_evt_param close
SPP callback param of ESP_SPP_CLOSE_EVT
struct esp_spp_cb_param_t::spp_start_evt_param start
SPP callback param of ESP_SPP_START_EVT
struct esp_spp_cb_param_t::spp_srv_stop_evt_param srv_stop
SPP callback param of ESP_SPP_SRV_STOP_EVT
struct esp_spp_cb_param_t::spp_cl_init_evt_param cl_init
SPP callback param of ESP_SPP_CL_INIT_EVT
struct esp_spp_cb_param_t::spp_write_evt_param write
SPP callback param of ESP_SPP_WRITE_EVT
struct esp_spp_cb_param_t::spp_data_ind_evt_param data_ind
SPP callback param of ESP_SPP_DATA_IND_EVT
struct esp_spp_cb_param_t::spp_cong_evt_param cong
SPP callback param of ESP_SPP_CONG_EVT
struct esp_spp_cb_param_t::spp_vfs_register_evt_param vfs_register
SPP callback param of ESP_SPP_VFS_REGISTER_EVT
struct esp_spp_cb_param_t::spp_vfs_unregister_evt_param vfs_unregister
SPP callback param of ESP_SPP_VFS_UNREGISTER_EVT
struct spp_cl_init_evt_param
#include <esp_spp_api.h>
ESP_SPP_CL_INIT_EVT.
Public Members
esp_spp_status_t status
status
uint32_t handle
The connection handle
uint8_t sec_id
security ID used by this server
bool use_co
TRUE to use co_rfc_data
struct spp_close_evt_param
#include <esp_spp_api.h>
ESP_SPP_CLOSE_EVT.
Public Members
esp_spp_status_t status
status
uint32_t port_status
PORT status
uint32_t handle
The connection handle
bool async
FALSE, if local initiates disconnect
struct spp_cong_evt_param
#include <esp_spp_api.h>
ESP_SPP_CONG_EVT.
Public Members
esp_spp_status_t status
status
uint32_t handle
The connection handle
bool cong
TRUE, congested. FALSE, uncongested
struct spp_data_ind_evt_param
#include <esp_spp_api.h>
ESP_SPP_DATA_IND_EVT.
Public Members
esp_spp_status_t status
status
uint32_t handle
The connection handle
uint16_t len
The length of data
uint8_t *data
The data received
struct spp_discovery_comp_evt_param
#include <esp_spp_api.h>
SPP_DISCOVERY_COMP_EVT.
Public Members
esp_spp_status_t status
status
uint8_t scn_num
The num of scn_num
uint8_t scn[ESP_SPP_MAX_SCN]
channel # const char *service_name[ESP_SPP_MAX_SCN]
service_name
struct spp_init_evt_param
#include <esp_spp_api.h>
SPP_INIT_EVT.
Public Members
esp_spp_status_t status
status
struct spp_open_evt_param
#include <esp_spp_api.h>
ESP_SPP_OPEN_EVT.
Public Members
esp_spp_status_t status
status
uint32_t handle
The connection handle
int fd
The file descriptor only for ESP_SPP_MODE_VFS
esp_bd_addr_t rem_bda
The peer address
struct spp_srv_open_evt_param
#include <esp_spp_api.h>
ESP_SPP_SRV_OPEN_EVT.
Public Members
esp_spp_status_t status
status
uint32_t handle
The connection handle
uint32_t new_listen_handle
The new listen handle
int fd
The file descriptor only for ESP_SPP_MODE_VFS
esp_bd_addr_t rem_bda
The peer address
struct spp_srv_stop_evt_param
#include <esp_spp_api.h>
ESP_SPP_SRV_STOP_EVT.
Public Members
esp_spp_status_t status
status
uint8_t scn
Server channel number
struct spp_start_evt_param
#include <esp_spp_api.h>
ESP_SPP_START_EVT.
Public Members
esp_spp_status_t status
status
uint32_t handle
The connection handle
uint8_t sec_id
security ID used by this server
uint8_t scn
Server channel number
bool use_co
TRUE to use co_rfc_data
struct spp_uninit_evt_param
#include <esp_spp_api.h>
SPP_UNINIT_EVT.
Public Members
esp_spp_status_t status
status
struct spp_vfs_register_evt_param
#include <esp_spp_api.h>
ESP_SPP_VFS_REGISTER_EVT.
Public Members
esp_spp_status_t status
status
struct spp_vfs_unregister_evt_param
#include <esp_spp_api.h>
ESP_SPP_VFS_UNREGISTER_EVT.
Public Members
esp_spp_status_t status
status
struct spp_write_evt_param
#include <esp_spp_api.h>
ESP_SPP_WRITE_EVT.
Public Members
esp_spp_status_t status
status
uint32_t handle
The connection handle
int len
The length of the data written.
bool cong
congestion status
Structures
struct esp_spp_cfg_t
SPP configuration parameters.
Public Members
esp_spp_mode_t mode
Choose the mode of SPP, ESP_SPP_MODE_CB or ESP_SPP_MODE_VFS.
bool enable_l2cap_ertm
Enable/disable Logical Link Control and Adaptation Layer Protocol enhanced retransmission mode.
uint16_t tx_buffer_size
Tx buffer size for a new SPP channel. A smaller setting can save memory, but may incur a decrease in throughput. Only for ESP_SPP_MODE_VFS mode.
Macros
ESP_SPP_MAX_MTU
SPP max MTU
ESP_SPP_MAX_SCN
SPP max SCN
ESP_SPP_MIN_TX_BUFFER_SIZE
SPP min tx buffer
ESP_SPP_MAX_TX_BUFFER_SIZE
SPP max tx buffer size
BT_SPP_DEFAULT_CONFIG()
SPP default configuration.
ESP_SPP_SEC_NONE
No security. relate to BTA_SEC_NONE in bta/bta_api.h
ESP_SPP_SEC_AUTHORIZE
Authorization required (only needed for out going connection ) relate to BTA_SEC_AUTHORIZE in bta/bta_api.h
ESP_SPP_SEC_AUTHENTICATE
Authentication required. relate to BTA_SEC_AUTHENTICATE in bta/bta_api.h
ESP_SPP_SEC_ENCRYPT
Encryption required. relate to BTA_SEC_ENCRYPT in bta/bta_api.h
ESP_SPP_SEC_MODE4_LEVEL4
Mode 4 level 4 service, i.e. incoming/outgoing MITM and P-256 encryption relate to BTA_SEC_MODE4_LEVEL4 in bta/bta_api.h
ESP_SPP_SEC_MITM
Man-In-The_Middle protection relate to BTA_SEC_MITM in bta/bta_api.h
ESP_SPP_SEC_IN_16_DIGITS
Min 16 digit for pin code relate to BTA_SEC_IN_16_DIGITS in bta/bta_api.h
Type Definitions
typedef uint16_t esp_spp_sec_t
typedef void (*esp_spp_cb_t)(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
SPP callback function type. When handle ESP_SPP_DATA_IND_EVT, it is strongly recommended to cache incoming data, and process them in other lower priority application task rather than in this callback directly.
Param event
Event type
Param param
Point to callback parameter, currently is union type
Enumerations
enum esp_spp_status_t
Values:
enumerator ESP_SPP_SUCCESS
Successful operation.
enumerator ESP_SPP_FAILURE
Generic failure.
enumerator ESP_SPP_BUSY
Temporarily can not handle this request.
enumerator ESP_SPP_NO_DATA
No data
enumerator ESP_SPP_NO_RESOURCE
No more resource
enumerator ESP_SPP_NEED_INIT
SPP module shall init first
enumerator ESP_SPP_NEED_DEINIT
SPP module shall deinit first
enumerator ESP_SPP_NO_CONNECTION
Connection may have been closed
enumerator ESP_SPP_NO_SERVER
No SPP server
enum esp_spp_role_t
Values:
enumerator ESP_SPP_ROLE_MASTER
Role: master
enumerator ESP_SPP_ROLE_SLAVE
Role: slave
enum esp_spp_mode_t
Values:
enumerator ESP_SPP_MODE_CB
When data is coming, a callback will come with data
enumerator ESP_SPP_MODE_VFS
Use VFS to write/read data
enum esp_spp_cb_event_t
SPP callback function events.
Values:
enumerator ESP_SPP_INIT_EVT
When SPP is initialized, the event comes
enumerator ESP_SPP_UNINIT_EVT
When SPP is deinitialized, the event comes
enumerator ESP_SPP_DISCOVERY_COMP_EVT
When SDP discovery complete, the event comes
enumerator ESP_SPP_OPEN_EVT
When SPP Client connection open, the event comes
enumerator ESP_SPP_CLOSE_EVT
When SPP connection closed, the event comes
enumerator ESP_SPP_START_EVT
When SPP server started, the event comes
enumerator ESP_SPP_CL_INIT_EVT
When SPP client initiated a connection, the event comes
enumerator ESP_SPP_DATA_IND_EVT
When SPP connection received data, the event comes, only for ESP_SPP_MODE_CB
enumerator ESP_SPP_CONG_EVT
When SPP connection congestion status changed, the event comes, only for ESP_SPP_MODE_CB
enumerator ESP_SPP_WRITE_EVT
When SPP write operation completes, the event comes, only for ESP_SPP_MODE_CB
enumerator ESP_SPP_SRV_OPEN_EVT
When SPP Server connection open, the event comes
enumerator ESP_SPP_SRV_STOP_EVT
When SPP server stopped, the event comes
enumerator ESP_SPP_VFS_REGISTER_EVT
When SPP VFS register, the event comes
enumerator ESP_SPP_VFS_UNREGISTER_EVT
When SPP VFS unregister, the event comes