蓝牙设备端SDK移植接口说明
更新时间：2019-07-23 19:57:49
Breeze SDK是阿里巴巴IoT事业部提供的基于蓝牙协议栈(aos组件自带的或者厂商自己的)上层提供的一套安全接入的解决方案，并支持通过蓝牙通道支持wifi辅助配网功能，本文对Breeze SDK的HAL接口进行说明，厂商对接时可以参考本文档。
Breeze目录结构
Breeze位于network/bluetooth/breeze，目录结构如下：
.
├── Config.in
├── README.md
├── aos.mk
├── api
├── core
├── hal
├── include
└── ref-impl
其中：
Config.in : 配合menuconfig的配置文件。
README.md：Breeze SDK说明文档。
aos.mk文件：Breeze SDK Makefile。
api目录：包含用户编程接口的定义和实现。
core: 源码实现。
include：Breeze SDK对接的头文件定义。
ref-impl目录：提供了在AliOS Things OS， BLE协议栈，以及内部AES和SHA256安全接口的参考实现。
HAL接口说明
Breeze SDK的HAL接口分为协议栈、OS、安全三个部分，这些接口的定义在network/bluetooth/breeze/include/目录中：
breeze_hal_ble.h
定义了蓝牙配网SDK对接到不同厂商蓝牙协议栈的接口，参考实现位于network/bluetooth/breeze/hal/ble/breeze_hal_ble.c文件；breeze_hal_os.h
定义了蓝牙配网SDK对接到不同OS系统的接口，基于AliOSThings的参考实现位于network/bluetooth/breeze/hal/ble/breeze_hal_os.c，用户如果使用AliOSThings时，该部分接口不需要对接；breeze_hal_sec.h
定义了蓝牙配网SDK对接到不同安全算法实现的接口，基于mbedtls的参考实现位于network/bluetooth/breeze/hal/ble/breeze_hal_security.c文件，用户使用AliOSThings时，该部分接口不需要对接。
蓝牙协议栈HAL列表
ble_stack_init
该接口完成对BLE协议栈的初始化。
参数
|
名称
|
类型
|
描述
|
|
ais_init
|
ais_bt_init_t
|
指定了蓝牙service和characteristics，以及他们的权限属性等相关设置。具体包括： -uuid_svc：AIS服务的uuid（type、value）信息； -rc/wc/ic/nc/ wwnrc：AIS服务的characteristic的属性信息； -on_connected:蓝牙连接时间的回调函数。
-on_disconnected：蓝牙断开连接事件的回调函数。
|
|
init_done
|
stack_init_done_t
|
协议栈初始化完成回调函数，需要在蓝牙协议栈完成之后主动调用传入成功参数AIS_ERR_SUCCESS(0)。
|
返回值
该函数成功时返回AIS_ERR_SUCCESS，错误发生时返回对应的错误编码（breeze_hal_ble.h）中。
ble_stack_deinit
该接口负责协议栈停止和资源销毁等工作。。
参数
无。
返回值
该函数成功时返回AIS_ERR_SUCCESS，错误发生时返回对应的错误编码（breeze_hal_ble.h）中。
ble_send_notification
该接口通过notify方式发送数据。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| p_data | uint8_t* | 发送数据的buffer地址。 |
| length | uint16_t | 数据长度。 |
返回值
该函数成功时返回AIS_ERR_SUCCESS，错误发生时返回对应的错误编码（breeze_hal_ble.h）中。
ble_send_indication
该接口通过indicate方式发送数据。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| p_data | uint8_t* | 发送数据的buffer地址。 |
| length | uint16_t | 数据长度。 |
| txdone | callback | 回调处理函数，由HAL实现代码在发送indication数据完毕后调用。 |
返回值
该函数成功时返回AIS_ERR_SUCCESS，错误发生时返回对应的错误编码（breeze_hal_ble.h）中。
ble_disconnect
该接口断开已有的蓝牙连接。该函数断开当前的蓝牙连接，与ble_stack_deinit的区别是，后续还可以进行连接。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| reason | uint8_t | SDK断开蓝牙连接原因，注意非蓝牙spec规定的断开原因，如Remote User Terminated Connect（0x13）、Connection Accept Timeout Exceeded（0x10）等，需要在实现中对接做一次映射。例如SDK传入AIS_BT_REASON_REMOTE_USER_TERM_CONN(0x00)，在实现的时候映射成BT_HCI_ERR_REMOTE_USER_TERM_CONN(0x13)。 |
返回值
无。
ble_advertising_start
该接口开启蓝牙广播。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| adv | ais_adv_init_t* | 输入参数adv指定了所需的广播信息，包括flag、设备名、厂商数据段内容。 |
返回值
该函数成功时返回AIS_ERR_SUCCESS，错误发生时返回对应的错误编码（breeze_hal_ble.h）中。
ble_advertising_stop
该接口停止蓝牙广播。
参数
无。
返回值
该函数成功时返回AIS_ERR_SUCCESS，错误发生时返回对应的错误编码（breeze_hal_ble.h）中。
ble_get_mac
该接口用于获取蓝牙设备的MAC地址。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| mac | uint8_t* | 用于存储获取到的蓝牙MAC地址，6字节二进制格式：0xAA，0xBB，0xCC，0xDD，0xEE，0xFF（对应MAC地址“AA:BB:CC:DD:EE:FF”） |
返回值
该函数成功退出是返回AIS_ERR_SUCCESS，错误发生时返回Breeze错误编码。
OS HAL列表
OS HAL接口提供以下功能：
定时器支持；
系统重启接口；
系统时间戳获取和睡眠接口；
Key-Value键值读取接口。
os_timer_new
该接口用于创建定时器。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| timer | os_timer_t* | 定时器指针。 |
| cb | os_timer_cb_t | 定时器超时回调处理函数。 |
| arg | void* | 回调函数函数参数。 |
| ms | int | 超时时间。 |
返回值
成功时时返回0，否则返回非0值。
os_timer_start
该接口用于启动定时器。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| timer | os_timer_t | 定时器指针。 |
返回值
成功时返回0，否则返回非0值。
os_timer_stop
该接口用于停止定时器。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| timer | os_timer_t | 定时器指针。 |
返回值
成功时返回0，否则返回非0值。
os_timer_free
该接口用于销毁定时器资源。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| timer | os_timer_t | 定时器指针。 |
返回值
成功时返回0，否则返回非0值。
os_reboot
该接口用于重启OS。
参数
无。
返回值
无。
os_msleep
该接口触发系统/进程进行睡眠。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| ms | int | 休眠时长，单位为ms。 |
返回值
无。
os_now_ms
该接口用于获取系统当前时间戳（从系统启动开始计数）。
参数
无。
返回值
系统时间戳，单位为ms。
os_kv_set
该接口用于设置永久存储Key-Value键值。。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| key | const char* | 键名（字符串）。 |
| value | const void* | 键值（任意值）。 |
| len | int | 键值长度。 |
| sync | int | 预留参数，暂时传入1 |
返回值
成功时返回0，否则返回非0值。
os_kv_get
该接口用于读取永久存储Key-Value键值。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| key | const char* | 键名（字符串）。 |
| buffer | void* | 键值（任意值）。 |
| buffer_len | int* | 键值长度指针。 |
返回值
成功时返回0，否则返回非0值。
os_kv_del
该接口用于删除永久存储Key-Value键值。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| key | const char* | 键名（字符串）。 |
返回值
成功时返回0，否则返回非0值
os_rand
该接口用于产生一个整型的随机值。
参数
无。
返回值
随机有符号整型值。
安全相关的HAL
sec_sha256_init
该接口对sha256模块进行初始化。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| ctx | SHA256_CTX | SHA256结构体指针,资源申请和销毁由调用者负责。 |
返回值
无。
sec_sha256_update
计算给定数据的SHA256值
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| ctx | SHA256_CTX | 初始化返回的SHA256结构体指针。 |
| data | const BYTE | 要进行SHA256更新的数据指针。 |
| len | size_t | 数据长度。 |
返回值
无。
sec_sha256_final
sha256模块完成SHA256计算接口。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| ctx | SHA256_CTX | 初始化返回的SHA256结构体指针。 |
| hash | BYTE | 签名输出的保存数组。 |
返回值
无。
sec_aes128_init
该接口对AES128加解密算法流程进行初始化。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| key | const uint8_t | AES128算法要求的key输入。 |
| iv | const uint8_t | AES128 CBC算法要求输入的iv值。 |
返回值void指针，指向初始化后的context，后续加解密流程中使用该返回值
sec_aes128_destroy
销毁AES128加解密算法流程，释放相关资源。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| aes | void* | 接口初始化之后返回的context。 |
返回值
成功时返回0，否则返回-1。
sec_aes128_cbc_encrypt
调用该接口进行AES128 CBC加密计算。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| aes | void* | 初始化之后返回的context。 |
| src | const void* | 指针指向需要加密的数据。 |
| block_num | size_t | 需要加密的数据块数（16字节为一块，不足16字节按一块计算）。 |
| dst | void* | 解密后数据的存储地址 |
返回值
成功时返回0，否则返回-1。
sec_aes128_cbc_decrypt
调用该接口进行AES128 CBC解密计算。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| aes | void* | 初始化之后返回的context。 |
| src | const void* | 指针指向需要加密的数据。 |
| block_num | size_t | 需要加密的数据块数（16字节为一块，不足16字节按一块计算）。 |
| dst | void* | 解密后数据的存储地址 |
返回值
成功时返回0，否则返回-1。