SPP

The Serial Port Profile (SPP) can be used to emulate a serial port connection using Radio Frequency Communication(RFCOMM) protocol between two peer devices. More...

Overview

The Serial Port Profile (SPP) can be used to emulate a serial port connection using Radio Frequency Communication(RFCOMM) protocol between two peer devices.

It supports server and client roles. The SPP server is implemented for a server side connection (Acceptor). It can wait for another device to take initiative to connect. The SPP client is implemented for a client side connection (Initiator) to initiate a connection with another device.

Terms and Acronyms

Terms	Details
UUID	A Universally Unique Identifier. For more information, please refer to Wikipedia.
SPP	Serial Port Profile. For more information, please refer to Wikipedia.
RFCOMM	The Radio Frequency Communication. For more information, please refer to Wikipedia.
SDP	Service Discovery Protocol. For more information, please refer to Wikipedia.

How to use this module

• SPP connection in server mode, as shown in the figure titled as "SPP connection establishment message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  • Step 1. Mandatory, implement bt_sdps_get_customized_record() to add SDP records of SPP Servers. The SPP's SDP record contains five attributes: the service class ID list, the protocol description list, the public browse group, the language list and the service name. In general, user needs to customize the service class ID list, the protocol description list and the service name, while the other two attributes are constant. In the service class ID list, user needs to fill the 128-bit UUID to identify the SPP server. User can assign their own unique and private UUID for the purpose of customization. In the protocol description list, user needs to fill the SPP server ID with the value between the BT_SPP_SERVER_ID_START and the BT_SPP_SERVER_ID_END. It is noted that each SPP record must be assigned with a unique server ID. In the service name, user can assign a name to the SPP server. For more information about the SDP record, please refer to SDP.
• Sample code:

  #define BT_SPP_UUID    0x00,0x00,0x11,0x01,0x00,0x00,0x10,0x00,0x80,0x00,0x00,0x80,0x5F,0x9B,0x34,0xFB
  static const uint8_t bt_spp_service_class_id_pattern[] =
  {
      BT_SPP_SDP_ATTRIBUTE_UUID_LENGTH,
      BT_SPP_SDP_ATTRIBUTE_UUID(BT_SPP_STANDARD_UUID)
  };
  static const uint8_t bt_spp_protocol_descriptor_list_pattern[] =
  {
      BT_SPP_SDP_ATTRIBUTE_PROTOCOL_DESCRIPTOR(BT_SPP_SERVER_ID_START)
  };
  static const uint8_t bt_spp_browse_group_pattern[] =
  {
      BT_SPP_SDP_ATTRIBUTE_PUBLIC_BROWSE_GROUP
  };
  static const uint8_t bt_spp_language_pattern[] =
  {
      BT_SPP_SDP_ATTRIBUTE_LANGUAGE
  };
  static const uint8_t bt_spp_service_name_pattern[] =
  {
      BT_SPP_SDP_ATTRIBUTE_SIZE_OF_SERVICE_NAME(11),
      'S', 'e', 'r', 'i', 'a', 'l', ' ', 'P', 'o', 'r', 't'
  };
  static const bt_sdps_attribute_t bt_spp_sdp_attributes_pattern[] =
  {
      BT_SPP_SDP_ATTRIBUTE_SERVICE_CLASS_ID_LIST(bt_spp_service_class_id_pattern),
      BT_SPP_SDP_ATTRIBUTE_PROTOCOL_DESC_LIST(bt_spp_protocol_descriptor_list_pattern),
      BT_SPP_SDP_ATTRIBUTE_BROWSE_GROUP_LIST(bt_spp_browse_group_pattern),
      BT_SPP_SDP_ATTRIBUTE_LANGUAGE_BASE_LIST(bt_spp_language_pattern),
      BT_SPP_SDP_ATTRIBUTE_SERVICE_NAME(bt_spp_service_name_pattern)
  };
  static const bt_sdps_record_t bt_spp_sdp_record_pattern = 
  {
      .attribute_list_length = sizeof(bt_spp_sdp_attributes_pattern),
      .attribute_list = bt_spp_sdp_attributes_pattern,
  };
  static const bt_sdps_record_t *sdps_spp_record[]= {
      &bt_spp_sdp_record_pattern,
      //&bt_spp_sdp_record_custom, user can add multiple SPP servers here.
  };
  uint8_t bt_sdps_get_customized_record(const bt_sdps_record_t *** record_list)
  {
      *record_list = sdps_spp_record;
      return sizeof(sdps_spp_record)/sizeof(bt_sdps_record_t*);
  }

  • Step 2. If a remote SPP client initiates a connection to the SPP server, the BT_SPP_CONNECT_IND event notifies the function bt_app_event_callback().
  • Step 3. Call the function bt_spp_connect_response() to accept or reject this connection request from a remote SPP client.
  • Step 4. The BT_SPP_CONNECT_CNF event notifies the function bt_app_event_callback() if the device is connected successfully or not.
    • Sample code:

      bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
      {
          switch (msg) {
              case BT_SPP_CONNECT_IND:
                   bt_spp_connect_ind_t* conn_ind_p = (bt_spp_connect_ind_t*) buff;
                   bt_spp_connect_response(conn_ind_p->handle, true);
                   break;
              case BT_SPP_CONNECT_CNF:
                   bt_spp_connect_cnf_t* conn_cnf_p = (bt_spp_connect_cnf_t*) buff;
                   break;
              default:
                  break;
          }
      }

• SPP connection in client mode, as shown in the figure titled as "SPP connection establishment message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  • Step 1. Call the function bt_spp_connect() to initiate a connection to a remote server.
    • Sample code:

      static const uint8_t spp_uuid[16] = {0x00,0x00,0x11,0x01,0x00,0x00,0x10,0x00,0x80,0x00,0x00,0x80,0x5F,0x9B,0x34,0xFB};
      bt_bd_addr_t remote_addr = {0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC};
      uint32_t spp_handle = BT_SPP_INVALID_HANDLE;
      bt_spp_connect(&(spp_handle), &remote_addr, spp_uuid);

  • Step 2. The BT_SPP_CONNECT_CNF event notifies the function bt_app_event_callback() if the device is connected successfully or not.
• Send data, as shown in the figure titled as "SPP data transfer message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  • Step 1. Call the function bt_spp_send() to send application data to the remote device. If returned value is BT_STATUS_SPP_TX_NOT_AVAILABLE, the application must wait for the BT_SPP_READY_TO_SEND_IND event before the next send operation.
    • Sample code:

      uint8_t app_send_data_buffer[100] = {0};
      bt_status_t result = bt_spp_send(spp_handle, app_send_data_buffer, 100);

  • Step 2. If the application received BT_SPP_READY_TO_SEND_IND event, it can continue to write the rest of application data.
    • Sample code:

      bt_status_t result = bt_spp_send(spp_handle, app_send_data_buffer, 100);

• Received data, as shown in the figure titled as "SPP data transfer message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  • Step 1. The BT_SPP_DATA_RECEIVED_IND event notifies the function bt_app_event_callback() if the device received data from the remote.
    • Sample code:

      uint8_t app_receive_data_buffer[900] = {0};
       bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
       {
           switch (msg) {
               case BT_SPP_DATA_RECEIVED_IND:
                   bt_spp_data_received_ind_t* data_ind_p = (bt_spp_data_received_ind_t*) buff;
                   memcpy(app_receive_data_buffer, data_ind_p->packet, data_ind_p->packet_length);
               default:
                   break;
           }
       }

  • Step 2. If there is no buffer for the application to save the SPP packet from the BT_SPP_DATA_RECEIVED_IND, call the function bt_spp_hold_data() to hold the packet in the Bluetooth RX buffer.
    • Sample code:

      bt_spp_data_received_ind_t saved_data = {0};
      bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
      {
          switch (msg) {
              case BT_SPP_DATA_RECEIVED_IND:
                  bt_spp_data_received_ind_t* data_ind_p = (bt_spp_data_received_ind_t*) buff;
                  bt_spp_hold_data(data_ind_p->packet);
                  saved_data.packet = data_ind_p->packet;
                  saved_data.packet_length = data_ind_p->packet_length
              default:
                  break;
          }
      }

  • Step 3. Release the SPP packet after it is stored in the application by calling the function bt_spp_release_data(). If not released, the Bluetooth RX buffer may be exhausted and the application cannot receive data from a remote device.
    • Sample code:

      uint8_t app_new_data_buffer[900] = {0};
      bt_spp_data_received_ind_t* data_p = &saved_data;
      memcpy(app_new_data_buffer, data_p->packet, data_p->packet_length);
      bt_spp_release_data(saved_data.packet);

• Disconnect the SPP connection, as shown in the figure titled as "SPP connection release message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  • Step 1. Call the function bt_spp_disconnect() to disconnect the SPP connection from a remote device.
    • Sample code:

      bt_status_t result = bt_spp_disconnect(spp_handle);

  • Step 2. The BT_SPP_DISCONNECT_IND event will notify the function bt_app_event_callback() to indicate the SPP connection has been released.
    • Sample code:

      bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
      {
          switch (msg) {
              case BT_SPP_DISCONNECT_IND:
                 bt_spp_disconnect_ind_t* disc_ind_p = (bt_spp_disconnect_ind_t*)buff;
              default:
                  break;
          }
      }

Functions
bt_status_t	bt_spp_connect (uint32_t *handle, const bt_bd_addr_t *address, const uint8_t *uuid128)
	This function is for the SPP client to connect to a remote server, the BT_SPP_CONNECT_CNF event is reported to indicate the result of the connection. More...
bt_status_t	bt_spp_connect_response (uint32_t handle, bool accept)
	This function is for the SPP server to accept or reject connection from a remote client, the BT_SPP_CONNECT_CNF event is reported to indicate the result of the response. More...
bt_status_t	bt_spp_send (uint32_t handle, uint8_t *packet, uint16_t packet_length)
	This function sends data to a remote device. More...
bt_status_t	bt_spp_disconnect (uint32_t handle)
	This function disconnects an existing connection, the BT_SPP_DISCONNECT_IND event is reported to indicate the result of the disconnection. More...
void	bt_spp_hold_data (uint8_t *data)
	This function holds the SPP packet until it is fully consumed. More...
void	bt_spp_release_data (uint8_t *data)
	This function releases the SPP packet after it is consumed. More...

Modules
	Define
	This section defines the macros for the SPP.
	Struct
	This section defines the structures for the SPP.

Function Documentation

bt_status_t bt_spp_connect	(	uint32_t *	handle,
		const bt_bd_addr_t *	address,
		const uint8_t *	uuid128
	)

This function is for the SPP client to connect to a remote server, the BT_SPP_CONNECT_CNF event is reported to indicate the result of the connection.

Note that this API can only be used by an SPP client.

Parameters

[out]	handle	is the SPP handle of the current connection.
[in]	address	is the Bluetooth address of a remote device.
[in]	uuid128	is a 128-bit UUID of remote server, such as {0x00,0x00,0x11,0x01,0x00,0x00, 0x10,0x00,0x80,0x00,0x00,0x80,0x5F,0x9B,0x34,0xFB}.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_spp_connect_response	(	uint32_t	handle,
		bool	accept
	)

This function is for the SPP server to accept or reject connection from a remote client, the BT_SPP_CONNECT_CNF event is reported to indicate the result of the response.

Note that this API can only be used by the SPP server.

Parameters

[in]	handle	is the SPP handle of the current connection.
[in]	accept	defines whether the connection is accepted.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed.

bt_status_t bt_spp_disconnect

(

uint32_t

handle

)

This function disconnects an existing connection, the BT_SPP_DISCONNECT_IND event is reported to indicate the result of the disconnection.

Parameters

[in]

handle

is the SPP handle of the current connection.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed.

void bt_spp_hold_data

(

uint8_t *

data

)

This function holds the SPP packet until it is fully consumed.

Parameters

[in]

data

is the initialization parameter. The value is provided once it is called by the SPP.

Returns

None.

void bt_spp_release_data

(

uint8_t *

data

)

This function releases the SPP packet after it is consumed.

Parameters

[in]

data

is the initialization parameter. The value is provided once it is called by the SPP.

Returns

None.

bt_status_t bt_spp_send	(	uint32_t	handle,
		uint8_t *	packet,
		uint16_t	packet_length
	)

This function sends data to a remote device.

Parameters

[in]	handle	is the SPP handle of the current connection.
[in]	packet	is a pointer to the packet to send to a remote device.
[in]	packet_length	is the length of a packet to send.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_SPP_TX_NOT_AVAILABLE, if the TX buffer in the local device or the RX buffer in the remote device has no space available. The application should wait for the BT_SPP_READY_TO_SEND_IND event before the next send operation.