Breeze SDK是阿里巴巴IoT提供的基于低功耗蓝牙协议栈上层提供的一套安全接入的解决方案,并可通过蓝牙通道支持WiFi辅助配网功能,本文对Breeze SDK的HAL接口进行说明,厂商对接时可以参考本文档。

HAL接口说明

Breeze SDK的HAL接口分为协议栈、OS、安全三个部分,这些接口的定义在$(SDK Src)/framework/bluetooth/breeze/hal目录下。

  • breeze_hal_ble.h

    定义了蓝牙配网SDK对接到不同厂商蓝牙协议栈的接口,参考实现见breeze_hal_ble.c文件。

  • breeze_hal_os.h

    定义了蓝牙配网SDK对接到不同OS系统的接口,基于AliOS Things的参考实现见breeze_hal_os.c,用户如果使用AliOS Things时,该部分接口不需要对接。

  • breeze_hal_sec.h

    定义了蓝牙配网SDK对接到不同安全算法实现的接口,基于mbedtls的参考实现见breeze_hal_security.c文件,用户使用AliOS Things时,该部分接口不需要对接。

蓝牙协议栈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 HAL接口如下。
  • 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_msleep

    该接口触发系统/进程进行睡眠。

    参数

    名称 类型 描述
    ms int 休眠时长,单位为ms。

    返回值

  • os_reboot

    该接口用于重启OS。

    参数

    返回值

  • os_now_ms

    该接口用于获取系统当前时间戳(从系统启动开始计数)。

    参数

    返回值

    系统时间戳,单位为ms。

  • 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

  • ais_aes128_init

    该接口对AES128加解密算法context进行初始化。

    参数

    名称 类型 描述
    key const uint8_t* AES128算法要求的key输入。
    iv const uint8_t* AES128 CBC算法要求输入的iv值。

    返回值

    void指针,指向初始化后的context,后续加解密流程中使用该返回值

  • ais_aes128_destroy

    销毁AES128加解密算法context,释放相关资源。

    参数

    名称 类型 描述
    aes void* 接口初始化之后返回的context。

    返回值

    成功返回0,否则返回-1

  • ais_aes128_cbc_encrypt

    调用该接口进行AES128 CBC加密计算。

    参数

    名称 类型 描述
    aes void* 接口初始化之后返回的context。
    src const void* 指针指向需要加密的数据。
    block_num size_t 需要加密的数据块数(16字节为一块,不足16字节按一块计算)。
    dst void* 解密后数据的存储地址。

    返回值

    成功返回0,否则返回-1

  • ais_aes128_cbc_decrypt

    调用该接口进行AES128 CBC解密计算。

    参数

    名称 类型 描述
    aes void* 接口初始化之后返回的context。
    src const void* 指针指向需要加密的数据。
    block_num size_t 需要加密的数据块数(16字节为一块,不足16字节按一块计算)。
    dst void* 解密后数据的存储地址。

    返回值

    成功返回0,否则返回-1