# 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

- components/bt/host/bluedroid/api/include/api/esp_spp_api.h

- 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 on `bt`, 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.

  参数

    callback -- [in] pointer to the init callback function.

  返回

    - 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.

  参数

    mode -- [in] Choose the mode of SPP, ESP_SPP_MODE_CB or ESP_SPP_MODE_VFS.

  返回

    - 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.

  备注

  The member variable enable_l2cap_etrm in esp_spp_cfg_t can affect all L2CAP channel configurations of the upper layer RFCOMM protocol.

  参数

    cfg -- [in] SPP configuration.

  返回

    - 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.

  返回

    - 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().

  参数

    bd_addr -- [in] Remote device bluetooth device address.

  返回

    - 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().

  参数

    - 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.

  返回

    - 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().

  参数

    handle -- [in] The connection handle.

  返回

    - 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().

  参数

    - 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.

  返回

    - 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().

  返回

    - 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().

  参数

    scn -- [in] Server channel number.

  返回

    - 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.

  参数

    - handle -- [in] The connection handle.

    - len -- [in] The length of the data written.

    - p_data -- [in] The data written.

  返回

    - 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().

  返回

    - 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().

  返回

    - 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

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。