SPP

SPP（Serial Port Profile）基于经典蓝牙 RFCOMM 协议实现串口透传。管理 SPP 连接/断开、写入数据和回调注册。

上位机通过蓝牙虚拟串口与 WS63 数据交互，透明传输任意二进制数据。适用蓝牙串口调试、无线数据采集等需要串口替代的场景。

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

接口清单

接口名称功能简述

spp_server_create 创建SPP Server监听socket

spp_server_accept 等待远端设备连接此Server

spp_server_close 关闭Server并释放相关资源

spp_connect 连接远端设备

spp_disconnect 断开连接并释放相关资源

is_spp_connected 获取指定SPP socket的连接状态

spp_get_remote_addr 获取SPP socket对应远端设备的地址

spp_write 向SPP socket写入数据

spp_register_callbacks 注册SPP回调函数

Functions

spp_server_create

int spp_server_create(spp_create_socket_para_t *socket_para, const char *name, unsigned int len)

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

功能说明

基于服务记录创建SPP Server监听socket
创建成功后返回有效的Server ID，用于后续accept/close操作
返回的Server ID用于标识当前Server socket

前置条件

模块初始化状态：蓝牙协议栈已通过enable_bt_stack()初始化完成
参数合法性要求：socket_para不为NULL且指向有效内存，name不为NULL且指向以'\0'结尾的字符串，len取值为strlen(name) + 1

入参

名称参数类型详细说明约束取值范围

socket_para spp_create_socket_para_t * SPP Server创建参数不为NULL

name const char * SPP Server名称不为NULL，以'\0'结尾的字符串

len unsigned int SPP Server名称长度取值为strlen(name) + 1

返回值

返回类型：int

返回值文字含义触发场景

SPP_INVALID_ID(-1) 创建Server失败创建失败

其他正整数创建Server成功，返回Server ID 创建成功

spp_server_accept

int spp_server_accept(int server_id)

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

功能说明

等待远端设备来连接此Server，返回一个Client ID用于与远端设备进行数据收发
这是一个同步接口，调用后将阻塞等待远端连接
返回的Client ID可用于spp_disconnect、is_spp_connected、spp_get_remote_addr、spp_write操作

前置条件

模块初始化状态：已通过spp_server_create()成功创建Server并获得有效Server ID
参数合法性要求：server_id为spp_server_create()返回的有效Server ID

入参

名称参数类型详细说明约束取值范围

server_id int 标识当前Server socket的ID spp_server_create()返回的有效Server ID

返回值

返回类型：int

返回值文字含义触发场景

SPP_INVALID_ID(-1) 等待失败 Accept失败

其他正整数等待成功，返回有效的Client ID Accept成功

spp_server_close

int spp_server_close(int server_id)

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

功能说明

关闭Server socket并释放相关资源
这是一个同步接口
关闭后对应的Server ID不再有效

前置条件

模块初始化状态：已通过spp_server_create()成功创建Server并获得有效Server ID
参数合法性要求：server_id为spp_server_create()返回的有效Server ID

入参

名称参数类型详细说明约束取值范围

server_id int 标识当前Server socket的ID spp_server_create()返回的有效Server ID

返回值

返回类型：int

返回值文字含义触发场景

ERRCODE_BT_SUCCESS(0x00) 执行成功关闭成功

Other 其他错误码，参考errcode_bt_t 执行失败

spp_connect

int spp_connect(spp_create_socket_para_t *socket_para, const bd_addr_t *bd_addr)

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

功能说明

创建Client socket并连接远端设备
这是一个同步接口
连接成功后返回有效的Client ID，用于后续数据收发操作

前置条件

模块初始化状态：蓝牙协议栈已通过enable_bt_stack()初始化完成
参数合法性要求：socket_para不为NULL且指向有效内存，bd_addr不为NULL且指向有效蓝牙地址

入参

名称参数类型详细说明约束取值范围

socket_para spp_create_socket_para_t * 创建Client socket并连接远端设备的参数不为NULL

bd_addr const bd_addr_t * 远端设备的蓝牙地址不为NULL

返回值

返回类型：int

返回值文字含义触发场景

SPP_INVALID_ID(-1) 连接失败连接失败

其他正整数连接成功，返回有效Client ID 连接成功

spp_disconnect

int spp_disconnect(int client_id)

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

功能说明

断开连接并释放相关资源
这是一个同步接口
断开后对应的Client ID不再有效

前置条件

模块初始化状态：已通过spp_server_accept()或spp_connect()获得有效Client ID
参数合法性要求：client_id为有效的Client ID

入参

名称参数类型详细说明约束取值范围

client_id int 标识当前Client socket的ID spp_server_accept()或spp_connect()返回的有效Client ID

返回值

返回类型：int

返回值文字含义触发场景

ERRCODE_BT_SUCCESS(0x00) 执行成功断开成功

Other 其他错误码，参考errcode_bt_t 执行失败

is_spp_connected

bool is_spp_connected(int client_id)

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

功能说明

获取指定SPP socket的连接状态
返回true表示已连接，false表示未连接
可在spp_server_accept()或spp_connect()之后调用

前置条件

模块初始化状态：已通过spp_server_accept()或spp_connect()获得有效Client ID
参数合法性要求：client_id为有效的Client ID

入参

名称参数类型详细说明约束取值范围

client_id int 标识当前Client socket的ID spp_server_accept()或spp_connect()返回的有效Client ID

返回值

返回类型：bool

返回值文字含义触发场景

true 已连接 SPP socket处于连接状态

false 未连接 SPP socket处于未连接状态

spp_get_remote_addr

int spp_get_remote_addr(int client_id, bd_addr_t *remote_addr)

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

功能说明

获取SPP socket对应远端设备的蓝牙地址
远端地址由调用者分配内存存储
可在spp_server_accept()或spp_connect()之后调用

前置条件

模块初始化状态：已通过spp_server_accept()或spp_connect()获得有效Client ID
参数合法性要求：client_id为有效的Client ID，remote_addr不为NULL且指向已分配的内存空间

入参

名称参数类型详细说明约束取值范围

client_id int 标识当前Client socket的ID spp_server_accept()或spp_connect()返回的有效Client ID

remote_addr bd_addr_t * 远端设备的地址（由调用者分配内存）不为NULL

出参

名称数据类型输出说明

remote_addr bd_addr_t 远端设备的蓝牙地址

返回值

返回类型：int

返回值文字含义触发场景

ERRCODE_BT_SUCCESS(0x00) 执行成功获取地址成功

Other 其他错误码，参考errcode_bt_t 执行失败

spp_write

int spp_write(int client_id, const char *data, const unsigned int len)

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

功能说明

向SPP socket写入数据
操作成功时返回实际写入的字节数
操作失败时返回SPP_WRITE_FAILED

前置条件

模块初始化状态：已通过spp_server_accept()或spp_connect()获得有效Client ID，且SPP socket处于已连接状态
参数合法性要求：client_id为有效的Client ID，data不为NULL且指向有效数据缓冲区，len不超过数据缓冲区实际长度

入参

名称参数类型详细说明约束取值范围

client_id int 标识当前Client socket的ID spp_server_accept()或spp_connect()返回的有效Client ID

data const char * 存储待写入数据的缓冲区不为NULL

len const unsigned int 待写入数据的长度不超过data缓冲区实际长度

返回值

返回类型：int

返回值文字含义触发场景

SPP_WRITE_FAILED(-1) 写入失败操作失败

其他正整数实际写入长度（单位字节）写入成功

spp_register_callbacks

int spp_register_callbacks(spp_callbacks_t *func)

头文件清单

#include "include/middleware/services/bts/br/bts_spp.h"

功能说明

注册SPP回调函数，用于接收连接状态变化和接收数据事件
回调函数运行于bts线程，不能阻塞或长时间等待
devices内存由bts申请和释放，回调中不应释放

前置条件

模块初始化状态：蓝牙协议栈已通过enable_bt_stack()初始化完成
参数合法性要求：func不为NULL且指向有效的回调函数结构体

入参

名称参数类型详细说明约束取值范围

func spp_callbacks_t * 指向回调函数接口定义的指针不为NULL

返回值

返回类型：int

返回值文字含义触发场景

ERRCODE_BT_SUCCESS(0x00) 执行成功注册成功

Other 其他错误码，参考errcode_bt_t 执行失败

Enumerations

spp_socket_type_t

typedef enum {
    SPP_SOCKET_RFCOMM = 0x0,    /*!< RFCOMM */
} spp_socket_type_t;

枚举成员取值描述

SPP_SOCKET_RFCOMM 0x0 RFCOMM socket类型

errcode_bt_t

typedef enum {
    ERRCODE_BT_SUCCESS = 0x00,                /*!< 执行成功错误码 */
    ERRCODE_BT_FAIL = ERRCODE_BT_COMMON_BASE, /*!< 执行失败错误码 */
    ERRCODE_BT_NOT_READY,                     /*!< 执行状态未就绪错误码 */
    ERRCODE_BT_MALLOC_FAIL,                   /*!< 内存不足错误码 */
    ERRCODE_BT_MEMCPY_FAIL,                   /*!< 内存拷贝错误错误码 */
    ERRCODE_BT_BUSY,                          /*!< 繁忙无法响应错误码 */
    ERRCODE_BT_DONE,                          /*!< 执行完成错误码 */
    ERRCODE_BT_UNSUPPORTED,                   /*!< 不支持错误码 */
    ERRCODE_BT_PARAM_ERR,                     /*!< 无效参数错误码 */
    ERRCODE_BT_STATE_ERR,                     /*!< 状态错误 */
    ERRCODE_BT_UNHANDLED,                     /*!< 未处理错误码 */
    ERRCODE_BT_AUTH_FAIL,                     /*!< 鉴权失败错误码 */
    ERRCODE_BT_RMT_DEV_DOWN,                  /*!< 远端设备关闭错误码 */
    ERRCODE_BT_AUTH_REJECTED,                 /*!< 鉴权被拒错误码 */
    ERRCODE_BT_MAX = ERRCODE_BT_COMMON_END    /*!< 蓝牙错误码最大值 */
} errcode_bt_t;

枚举成员取值描述

ERRCODE_BT_SUCCESS 0x00 执行成功

ERRCODE_BT_FAIL 0x80006000 执行失败

ERRCODE_BT_NOT_READY 0x80006001 执行状态未就绪

ERRCODE_BT_MALLOC_FAIL 0x80006002 内存不足

ERRCODE_BT_MEMCPY_FAIL 0x80006003 内存拷贝错误

ERRCODE_BT_BUSY 0x80006004 繁忙无法响应

ERRCODE_BT_DONE 0x80006005 执行完成

ERRCODE_BT_UNSUPPORTED 0x80006006 不支持

ERRCODE_BT_PARAM_ERR 0x80006007 无效参数

ERRCODE_BT_STATE_ERR 0x80006008 状态错误

ERRCODE_BT_UNHANDLED 0x80006009 未处理

ERRCODE_BT_AUTH_FAIL 0x8000600A 鉴权失败

ERRCODE_BT_RMT_DEV_DOWN 0x8000600B 远端设备关闭

ERRCODE_BT_AUTH_REJECTED 0x8000600C 鉴权被拒

ERRCODE_BT_MAX 0x800067FF 蓝牙错误码最大值

uuid_type_t

typedef enum {
    UUID_TYPE_NULL = 0x00, /*!< 空uuid */
    UUID_TYPE_16_BIT,      /*!< 16bit长度的uuid */
    UUID_TYPE_32_BIT,      /*!< 32bit长度的uuid */
    UUID_TYPE_128_BIT,     /*!< 128bit长度的uuid */
} uuid_type_t;

枚举成员取值描述

UUID_TYPE_NULL 0x00 空UUID

UUID_TYPE_16_BIT 0x01 16位UUID

UUID_TYPE_32_BIT 0x02 32位UUID

UUID_TYPE_128_BIT 0x03 128位UUID

bt_addr_type

typedef enum {
    BT_ADDRESS_TYPE_PUBLIC_DEVICE_ADDRESS          =  0x00, /*!< 蓝牙公有地址 */
    BT_ADDRESS_TYPE_RANDOM_DEVICE_ADDRESS          =  0x01, /*!< 蓝牙随机地址 */
} bt_addr_type;

枚举成员取值描述

BT_ADDRESS_TYPE_PUBLIC_DEVICE_ADDRESS 0x00 蓝牙公有地址

BT_ADDRESS_TYPE_RANDOM_DEVICE_ADDRESS 0x01 蓝牙随机地址

profile_connect_state_t

typedef enum {
    PROFILE_STATE_CONNECTING = 0x01,    /*!< 正在连接 */
    PROFILE_STATE_CONNECTED = 0x02,     /*!< 已连接 */
    PROFILE_STATE_DISCONNECTING = 0x03, /*!< 正在断连 */
    PROFILE_STATE_DISCONNECTED = 0x04   /*!< 已断连 */
} profile_connect_state_t;

枚举成员取值描述

PROFILE_STATE_CONNECTING 0x01 正在连接

PROFILE_STATE_CONNECTED 0x02 已连接

PROFILE_STATE_DISCONNECTING 0x03 正在断连

PROFILE_STATE_DISCONNECTED 0x04 已断连

Structures

spp_create_socket_para_t

typedef struct {
    bt_uuid_t uuid;                /*!< SPP socket对应的服务UUID */
    spp_socket_type_t socket_type; /*!< SPP socket类型 */
    bool is_encrypt;               /*!< 是否加密（目前此参数未使用，默认加密） */
} spp_create_socket_para_t;

成员说明：

成员名称数据类型描述

uuid bt_uuid_t SPP socket对应的服务UUID

socket_type spp_socket_type_t SPP socket类型，取值参见spp_socket_type_t枚举

is_encrypt bool 是否加密（目前此参数未使用，默认加密）

bd_addr_t

typedef struct {
    uint8_t addr[BD_ADDR_LEN];     /*!< 蓝牙地址 */
    uint8_t type;                  /*!< 蓝牙地址类型，参考bt_addr_type */
} bd_addr_t;

成员说明：

成员名称数据类型描述

addr uint8_t[6] 蓝牙设备地址，长度为BD_ADDR_LEN(6)字节

type uint8_t 蓝牙地址类型，取值参见bt_addr_type

bt_uuid_t

typedef struct {
    uint8_t uuid_len;               /*!< UUID长度 */
    uint8_t uuid[BT_UUID_MAX_LEN]; /*!< UUID字段 */
} bt_uuid_t;

成员说明：

成员名称数据类型描述

uuid_len uint8_t UUID长度，取值参见uuid_type_t

uuid uint8_t[16] UUID字段，最大长度为BT_UUID_MAX_LEN(16)字节

spp_callbacks_t

typedef struct {
    spp_receive_data_callback receive_data_cb;
    spp_conn_state_changed_callback conn_state_changed_cb;
} spp_callbacks_t;

成员说明：

成员名称数据类型描述

receive_data_cb spp_receive_data_callback 接收数据回调函数

conn_state_changed_cb spp_conn_state_changed_callback 连接状态变化回调函数

Type definitions

spp_conn_state_changed_callback

typedef void (*spp_conn_state_changed_callback)(uint8_t client_id, profile_connect_state_t state);

使用说明：在spp_callbacks_t结构体中作为conn_state_changed_cb成员使用，用于上报SPP连接状态变化事件。

spp_receive_data_callback

typedef void (*spp_receive_data_callback)(uint8_t client_id, uint8_t *data, uint32_t data_len);

使用说明：在spp_callbacks_t结构体中作为receive_data_cb成员使用，用于上报接收到的SPP数据。

接口名称	功能简述
spp_server_create	创建SPP Server监听socket
spp_server_accept	等待远端设备连接此Server
spp_server_close	关闭Server并释放相关资源
spp_connect	连接远端设备
spp_disconnect	断开连接并释放相关资源
is_spp_connected	获取指定SPP socket的连接状态
spp_get_remote_addr	获取SPP socket对应远端设备的地址
spp_write	向SPP socket写入数据
spp_register_callbacks	注册SPP回调函数

名称	参数类型	详细说明	约束取值范围
socket_para	spp_create_socket_para_t *	SPP Server创建参数	不为NULL
name	const char *	SPP Server名称	不为NULL，以'\0'结尾的字符串
len	unsigned int	SPP Server名称长度	取值为strlen(name) + 1

返回值	文字含义	触发场景
SPP_INVALID_ID(-1)	创建Server失败	创建失败
其他正整数	创建Server成功，返回Server ID	创建成功

返回值	文字含义	触发场景
SPP_INVALID_ID(-1)	等待失败	Accept失败
其他正整数	等待成功，返回有效的Client ID	Accept成功

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	关闭成功
Other	其他错误码，参考errcode_bt_t	执行失败

名称	参数类型	详细说明	约束取值范围
socket_para	spp_create_socket_para_t *	创建Client socket并连接远端设备的参数	不为NULL
bd_addr	const bd_addr_t *	远端设备的蓝牙地址	不为NULL

返回值	文字含义	触发场景
SPP_INVALID_ID(-1)	连接失败	连接失败
其他正整数	连接成功，返回有效Client ID	连接成功

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	断开成功
Other	其他错误码，参考errcode_bt_t	执行失败

返回值	文字含义	触发场景
true	已连接	SPP socket处于连接状态
false	未连接	SPP socket处于未连接状态

名称	参数类型	详细说明	约束取值范围
client_id	int	标识当前Client socket的ID	spp_server_accept()或spp_connect()返回的有效Client ID
remote_addr	bd_addr_t *	远端设备的地址（由调用者分配内存）	不为NULL

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	获取地址成功
Other	其他错误码，参考errcode_bt_t	执行失败

返回值	文字含义	触发场景
SPP_WRITE_FAILED(-1)	写入失败	操作失败
其他正整数	实际写入长度（单位字节）	写入成功

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	注册成功
Other	其他错误码，参考errcode_bt_t	执行失败

枚举成员	取值	描述
ERRCODE_BT_SUCCESS	0x00	执行成功
ERRCODE_BT_FAIL	0x80006000	执行失败
ERRCODE_BT_NOT_READY	0x80006001	执行状态未就绪
ERRCODE_BT_MALLOC_FAIL	0x80006002	内存不足
ERRCODE_BT_MEMCPY_FAIL	0x80006003	内存拷贝错误
ERRCODE_BT_BUSY	0x80006004	繁忙无法响应
ERRCODE_BT_DONE	0x80006005	执行完成
ERRCODE_BT_UNSUPPORTED	0x80006006	不支持
ERRCODE_BT_PARAM_ERR	0x80006007	无效参数
ERRCODE_BT_STATE_ERR	0x80006008	状态错误
ERRCODE_BT_UNHANDLED	0x80006009	未处理
ERRCODE_BT_AUTH_FAIL	0x8000600A	鉴权失败
ERRCODE_BT_RMT_DEV_DOWN	0x8000600B	远端设备关闭
ERRCODE_BT_AUTH_REJECTED	0x8000600C	鉴权被拒
ERRCODE_BT_MAX	0x800067FF	蓝牙错误码最大值

枚举成员	取值	描述
UUID_TYPE_NULL	0x00	空UUID
UUID_TYPE_16_BIT	0x01	16位UUID
UUID_TYPE_32_BIT	0x02	32位UUID
UUID_TYPE_128_BIT	0x03	128位UUID

枚举成员	取值	描述
BT_ADDRESS_TYPE_PUBLIC_DEVICE_ADDRESS	0x00	蓝牙公有地址
BT_ADDRESS_TYPE_RANDOM_DEVICE_ADDRESS	0x01	蓝牙随机地址

枚举成员	取值	描述
PROFILE_STATE_CONNECTING	0x01	正在连接
PROFILE_STATE_CONNECTED	0x02	已连接
PROFILE_STATE_DISCONNECTING	0x03	正在断连
PROFILE_STATE_DISCONNECTED	0x04	已断连

成员名称	数据类型	描述
uuid	bt_uuid_t	SPP socket对应的服务UUID
socket_type	spp_socket_type_t	SPP socket类型，取值参见spp_socket_type_t枚举
is_encrypt	bool	是否加密（目前此参数未使用，默认加密）

成员名称	数据类型	描述
addr	uint8_t[6]	蓝牙设备地址，长度为BD_ADDR_LEN(6)字节
type	uint8_t	蓝牙地址类型，取值参见bt_addr_type

成员名称	数据类型	描述
uuid_len	uint8_t	UUID长度，取值参见uuid_type_t
uuid	uint8_t[16]	UUID字段，最大长度为BT_UUID_MAX_LEN(16)字节

成员名称	数据类型	描述
receive_data_cb	spp_receive_data_callback	接收数据回调函数
conn_state_changed_cb	spp_conn_state_changed_callback	连接状态变化回调函数