SPP API
Application Examples
bluetooth/bluedroid/classic_bt/bt_spp_acceptor demonstrates how to use Bluetooth capabilities to create a Serial Port Protocol (SPP) acceptor that acts as a server and integrate Secure Simple Pairing (SSP). This example also includes a demo for communicating with an SPP initiator that acts as a client.
bluetooth/bluedroid/classic_bt/bt_spp_initiator demonstrates how to use Bluetooth capabilities to create an SPP initiator that performs as a client and integrate SSP. This example also includes a demo for communicating with an SPP acceptor that acts as a server.
bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator demonstrates how to use SPP APIs to create an SPP initiator that acts as a client and communicates with an SPP acceptor, using Virtual File System (VFS) interface to send and receive data.
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
bt
component. To declare that your component depends onbt
, add the following to your CMakeLists.txt:REQUIRES bt
or
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
-
esp_spp_status_t status
-
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 status
-
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 status
-
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 status
-
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 status
-
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 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
-
esp_spp_status_t status
-
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 status
-
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 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
-
esp_spp_status_t 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
-
esp_spp_status_t status
-
struct esp_spp_cb_param_t::spp_init_evt_param init
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.
-
esp_spp_mode_t 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
-
enumerator ESP_SPP_SUCCESS
-
enum esp_spp_role_t
Values:
-
enumerator ESP_SPP_ROLE_MASTER
Role: master
-
enumerator ESP_SPP_ROLE_SLAVE
Role: slave
-
enumerator ESP_SPP_ROLE_MASTER
-
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
-
enumerator ESP_SPP_MODE_CB
-
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
-
enumerator ESP_SPP_INIT_EVT