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¶
Functions¶
-
esp_err_t
esp_spp_register_callback
(esp_spp_cb_t callback)¶ This function is called to init callbacks with SPP module.
- Return
ESP_OK: success
other: failed
- Parameters
[in] callback
: pointer to the init callback function.
-
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.
- Return
ESP_OK: success
other: failed
- Parameters
[in] mode
: Choose the mode of SPP, ESP_SPP_MODE_CB or ESP_SPP_MODE_VFS.
-
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() completes successfully.
- Return
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 funciton must be called after esp_spp_init() successful and before esp_spp_deinit().
- Return
ESP_OK: success
other: failed
- Parameters
[in] bd_addr
: Remote device bluetooth device address.
-
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 funciton must be called after esp_spp_init() successful and before esp_spp_deinit().
- Return
ESP_OK: success
other: failed
- Parameters
[in] sec_mask
: Security Setting Mask. Suggest to use ESP_SPP_SEC_NONE, ESP_SPP_SEC_AUTHORIZE or ESP_SPP_SEC_AUTHENTICATE only.[in] role
: Master or slave.[in] remote_scn
: Remote device bluetooth device SCN.[in] peer_bd_addr
: Remote device bluetooth device address.
-
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 funciton must be called after esp_spp_init() successful and before esp_spp_deinit().
- Return
ESP_OK: success
other: failed
- Parameters
[in] handle
: The connection handle.
-
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 funciton must be called after esp_spp_init() successful and before esp_spp_deinit().
- Return
ESP_OK: success
other: failed
- Parameters
[in] sec_mask
: Security Setting Mask. Suggest to use ESP_SPP_SEC_NONE, ESP_SPP_SEC_AUTHORIZE or ESP_SPP_SEC_AUTHENTICATE only.[in] role
: Master or slave.[in] local_scn
: The specific channel you want to get. If channel is 0, means get any channel.[in] name
: Server’s name.
-
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 funciton must be called after esp_spp_init() successful and before esp_spp_deinit().
- Return
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 funciton must be called after esp_spp_init() successful and before esp_spp_deinit().
- Return
ESP_OK: success
other: failed
- Parameters
[in] scn
: Server channel number.
-
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 funciton must be called after an connection between initiator and acceptor has been established.
- Return
ESP_OK: success
other: failed
- Parameters
[in] handle
: The connection handle.[in] len
: The length of the data written.[in] p_data
: The data written.
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
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
-
esp_spp_status_t
-
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
-
esp_spp_status_t
-
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
-
esp_spp_status_t
-
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
-
esp_spp_status_t
-
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
-
esp_spp_status_t
-
struct
spp_init_evt_param
¶ - #include <esp_spp_api.h>
SPP_INIT_EVT.
Public Members
-
esp_spp_status_t
status
¶ status
-
esp_spp_status_t
-
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
-
esp_spp_status_t
-
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
-
esp_spp_status_t
-
struct
spp_srv_stop_evt_param
¶ - #include <esp_spp_api.h>
ESP_SPP_SRV_STOP_EVT.
-
struct
spp_start_evt_param
¶ - #include <esp_spp_api.h>
ESP_SPP_START_EVT.
-
struct
spp_uninit_evt_param
¶ - #include <esp_spp_api.h>
SPP_UNINIT_EVT.
Public Members
-
esp_spp_status_t
status
¶ status
-
esp_spp_status_t
-
struct esp_spp_cb_param_t::spp_init_evt_param
Macros¶
-
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
-
ESP_SPP_MAX_MTU
¶ SPP max MTU
-
ESP_SPP_MAX_SCN
¶ SPP max SCN
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.
- Parameters
event
: Event typeparam
: Point to callback parameter, currently is union type
Enumerations¶
-
enum
esp_spp_status_t
¶ Values:
-
ESP_SPP_SUCCESS
= 0¶ Successful operation.
-
ESP_SPP_FAILURE
¶ Generic failure.
-
ESP_SPP_BUSY
¶ Temporarily can not handle this request.
-
ESP_SPP_NO_DATA
¶ No data
-
ESP_SPP_NO_RESOURCE
¶ No more resource
-
ESP_SPP_NEED_INIT
¶ SPP module shall init first
-
ESP_SPP_NEED_DEINIT
¶ SPP module shall deinit first
-
ESP_SPP_NO_CONNECTION
¶ Connection may have been closed
-
ESP_SPP_NO_SERVER
¶ No SPP server
-
-
enum
esp_spp_role_t
¶ Values:
-
ESP_SPP_ROLE_MASTER
= 0¶ Role: master
-
ESP_SPP_ROLE_SLAVE
= 1¶ Role: slave
-
-
enum
esp_spp_mode_t
¶ Values:
-
ESP_SPP_MODE_CB
= 0¶ When data is coming, a callback will come with data
-
ESP_SPP_MODE_VFS
= 1¶ Use VFS to write/read data
-
-
enum
esp_spp_cb_event_t
¶ SPP callback function events.
Values:
-
ESP_SPP_INIT_EVT
= 0¶ When SPP is inited, the event comes
-
ESP_SPP_UNINIT_EVT
= 1¶ When SPP is uninited, the event comes
-
ESP_SPP_DISCOVERY_COMP_EVT
= 8¶ When SDP discovery complete, the event comes
-
ESP_SPP_OPEN_EVT
= 26¶ When SPP Client connection open, the event comes
-
ESP_SPP_CLOSE_EVT
= 27¶ When SPP connection closed, the event comes
-
ESP_SPP_START_EVT
= 28¶ When SPP server started, the event comes
-
ESP_SPP_CL_INIT_EVT
= 29¶ When SPP client initiated a connection, the event comes
-
ESP_SPP_DATA_IND_EVT
= 30¶ When SPP connection received data, the event comes, only for ESP_SPP_MODE_CB
-
ESP_SPP_CONG_EVT
= 31¶ When SPP connection congestion status changed, the event comes, only for ESP_SPP_MODE_CB
-
ESP_SPP_WRITE_EVT
= 33¶ When SPP write operation completes, the event comes, only for ESP_SPP_MODE_CB
-
ESP_SPP_SRV_OPEN_EVT
= 34¶ When SPP Server connection open, the event comes
-
ESP_SPP_SRV_STOP_EVT
= 35¶ When SPP server stopped, the event comes
-