Bluetooth® SPP API
Overview
SPP (Serial Port Profile) enables serial communication between Bluetooth devices, allowing them to exchange data over a virtual serial link. SPP API provides functionality to create both SPP initiators (clients) and acceptors (servers), enabling operation under different security requirements.
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
btcomponent. 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_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. tx_buffer_size 0 is replaced with ESP_SPP_DEFAULT_TX_BUFFER_SIZE and a warning is logged. Any other value outside ESP_SPP_MIN_TX_BUFFER_SIZE to ESP_SPP_MAX_TX_BUFFER_SIZE is rejected.
- 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_enhanced_init() completes successfully.
- Returns:
ESP_OK: success
other: failed
-
esp_err_t esp_spp_start_discovery(esp_bd_addr_t bd_addr)
Perform 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_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_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
ESP_ERR_INVALID_ARG: peer address is NULL, remote SCN is out of range, or role is invalid
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_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_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
ESP_ERR_INVALID_ARG: server name is invalid, local SCN is out of range, or role is invalid
other: failed
-
esp_err_t esp_spp_start_srv_with_cfg(const esp_spp_start_srv_cfg_t *cfg)
This function is similar to
esp_spp_start_srv. The only difference is that it adds a parameter to specify whether to create the SPP record.Note
If the SPP record is not created, it is suggested to use it together with the SDP API.
- Parameters:
cfg -- [in] Configuration parameters for starting the server.
- Returns:
ESP_OK: success
ESP_ERR_INVALID_ARG: if cfg is NULL, or name/SCN/role is invalid
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_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_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)
Write data on an SPP connection, only for ESP_SPP_MODE_CB. The whole buffer is copied into the transmit buffer and the call returns immediately. Waking the stack to send does not block on the BTC task queue. ESP_OK means the data is queued, not that it has been sent. The buffer size is tx_buffer_size passed to esp_spp_enhanced_init(). If len can never fit in that buffer, ESP_ERR_INVALID_SIZE is returned and nothing is queued. For ESP_ERR_INVALID_SIZE, waiting for ESP_SPP_CONG_EVT does not help because the buffer never shrinks. If len can fit but free space is less than len, ESP_ERR_NO_MEM is returned and nothing is queued. Retry only after ESP_SPP_CONG_EVT with cong equal to false. Queued data is sent in chunks of at most the peer MTU. ESP_SPP_WRITE_EVT reports each chunk after it has been submitted to RFCOMM. write.cong still reports TX buffer congestion, so the next packet can wait for cong equal to false. That pacing still works, but is not recommended. Prefer the return value and ESP_SPP_CONG_EVT. This function must be called after the connection 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: data queued in the transmit buffer
ESP_ERR_INVALID_SIZE: len can never be queued
ESP_ERR_NO_MEM: not enough free space
ESP_ERR_INVALID_ARG: invalid len or p_data
ESP_ERR_INVALID_STATE: SPP is not ready, or the connection is not open
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_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
-
esp_err_t esp_spp_get_profile_status(esp_spp_profile_status_t *profile_status)
This function is used to get the status of SPP.
- Parameters:
profile_status -- [out] - SPP status
- 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
Always FALSE. This event is only the TX buffer uncongest edge
-
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 spp_write_evt_param
- #include <esp_spp_api.h>
ESP_SPP_WRITE_EVT.
Public Members
-
esp_spp_status_t status
Always ESP_SPP_SUCCESS. Sent only after the chunk is submitted to RFCOMM
-
uint32_t handle
The connection handle
-
int len
The length of the data submitted to RFCOMM.
-
bool cong
TRUE when the TX buffer is congested, not RFCOMM congestion. Sending the next packet after this event reports cong equal to false still works, but is not recommended. Prefer the esp_spp_write() return value and ESP_SPP_CONG_EVT.
-
esp_spp_status_t status
-
struct esp_spp_cb_param_t::spp_init_evt_param init
Structures
-
struct esp_spp_cfg_t
SPP initialization 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. 0 uses ESP_SPP_DEFAULT_TX_BUFFER_SIZE. Any other value must be from ESP_SPP_MIN_TX_BUFFER_SIZE to ESP_SPP_MAX_TX_BUFFER_SIZE.
-
esp_spp_mode_t mode
-
struct esp_spp_start_srv_cfg_t
SPP start server configuration parameters.
Public Members
-
uint8_t local_scn
The specific channel you want to get. If channel is 0, means get any channel.
-
bool create_spp_record
Specifies whether to create the SPP record
-
esp_spp_sec_t sec_mask
Security Setting Mask. Suggest to use ESP_SPP_SEC_NONE, ESP_SPP_SEC_AUTHORIZE or ESP_SPP_SEC_AUTHENTICATE only
-
esp_spp_role_t role
Master or slave.
-
const char *name
Server's name.
-
uint8_t local_scn
-
struct esp_spp_profile_status_t
SPP profile status parameters.
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
-
ESP_SPP_DEFAULT_TX_BUFFER_SIZE
SPP default tx buffer size
-
BT_SPP_DEFAULT_CONFIG()
SPP default configuration.
-
BT_SPP_CB_MODE_DEFAULT_CONFIG()
SPP default configuration for callback mode.
-
ESP_SPP_SEC_NONE
No security.
-
ESP_SPP_SEC_AUTHORIZE
Authorization required (only needed for out going connection )
-
ESP_SPP_SEC_AUTHENTICATE
Authentication required.
-
ESP_SPP_SEC_ENCRYPT
Encryption required.
-
ESP_SPP_SEC_MODE4_LEVEL4
Mode 4 level 4 service, i.e. incoming/outgoing MITM and P-256 encryption.
-
ESP_SPP_SEC_MITM
Man-In-The-Middle protection.
-
ESP_SPP_SEC_IN_16_DIGITS
Min 16 digit for pin code.
Type Definitions
-
typedef uint16_t esp_spp_sec_t
SPP security type
-
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
SPP status type.
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
SPP role type.
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
SPP mode type.
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 TX buffer becomes uncongested, the event comes, only for ESP_SPP_MODE_CB
-
enumerator ESP_SPP_WRITE_EVT
When SPP has submitted a chunk to RFCOMM, 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