蓝牙设备端开发指南

更新时间：2018-10-19 11:29:34

本方案作为一个蓝牙通用方案，包括了蓝牙广播定制、连接管理、设备认证、数据安全、数据通信、固件OTA等功能，提供用户统一接口，方便用户快速接入。此章节中涉及的设备端SDK，需要和客户端的Breeze SDK配套使用。

1. 设备端开发流程

1.1 获取SDK

在产品开发时，需要使用推荐列表中已经通过认证的SDK。 如果推荐列表中目前还没有您所使用的芯片，请联系我们。

1.2 产品注册信息与SDK关联

在商家后台完成产品注册之后，需要获取相关的设备注册信息。然后将相关信息在初始化时设置到结构体struct device_config中的product_key、device_key、secret部分。

1.3 设备端应用开发

在更新完成产品相关信息之后，使用蓝牙SDK提供的API，可以进行设备端应用的开发。 此环节主要由产品方开发。

• 注1：蓝牙SDK具有配置蓝牙广播数据的能力。针对不同的应用场景，客户在调用SDK初始化时，可以开启或者禁用安全、OTA等功能。

• 注2：设备上电后，必须要上报一条完整的设备属性到云端，否则APP无法展示设备状态，并且无法控制。

• 注3：关于设备端的OTA功能说明：此部分功能在芯片原厂进行接口适配时已经完成，所以对于产品方不需要额外的开发。

2. 设备端接口说明

蓝牙SDK实现了安全可靠的数据通信通道，提供统一的接口，供用户开发时调用。

2.1 数据结构

device_config，设备的基本配置：

struct device_config {
    uint8_t bd_addr[BD_ADDR_LEN];               /**< Bluetooth Device Address. */
    char model[STR_MODEL_LEN];                  /**< reserved. */
    uint32_t product_id;
    char product_key[STR_PROD_KEY_LEN];
    uint8_t product_key_len;
    char device_key[STR_DEV_KEY_LEN];
    uint8_t device_key_len;
    char secret[STR_SEC_LEN];
    uint8_t secret_len;
    char version[STR_VER_LEN];
    bool enable_ota;
    bool enable_auth;
    ali_auth_type_t auth_type;
    dev_status_changed_cb status_changed_cb;
    set_dev_status_cb set_cb;
    get_dev_status_cb get_cb;
};

其中：
bd_addr是BLE设备的地址。
product_id、product_key、device_key、secret是在后台注册产品时生成，每个产品不同。
version是开发者应用的版本号，格式类似1.0.1。
enable_ota、enable_auth分别是OTA和使能标志，其使能与否由用户开发时决定。
status_changed_cb、set_cb、get_cb为用户注册的回调函数，status_changed_cb在BLE状态发生变化时会被调用，set_cb在用户设置设备状态时调用，get_cb在用户获取设备状态时调用。

alink_event_t为通过status_changed_cb上报的事件类型，定义了一些用户关心的蓝牙事件，比如蓝牙建立连接、断开连接、认证通过、发送完成等，会在BLE设备底层状态发生改变时通过回调的方式通知到应用层：

typedef enum {
    CONNECTED,     //connect with phone success
    DISCONNECTED,  //lost connection with phone
    AUTHENTICATED, //success authentication
    TX_DONE,       //send data complete
    NONE
} alink_event_t;

ali_auth_type_t为认证时使用的秘钥类型，可选Product secret（用于“一型一密”）和Device secret（用于“一机一密”）方式：

typedef enum
{
    ALI_AUTH_BY_PRODUCT_SECRET,     /**< Authentication by product secret. */
    ALI_AUTH_BY_DEVICE_SECRET,      /**< Authentication by device secret. */
} ali_auth_type_t;

2.2 接口定义

1. typedef void (*dev_status_changed_cb) (alink_event_t event);

返回值：无
说明：回调函数的原型申明，本函数在蓝牙设备发生状态变化时被SDK调用，如蓝牙建立连接，或者断开连接等

2. typedef void (*set_dev_status_cb) (uint8_t *buffer, uint32_t length);

返回值：无
说明：回调函数的原型申明，当手机APP有控制指令下发给蓝牙设备时，SDK会调用此函数

3. typedef void (*get_dev_status_cb) (uint8_t *buffer, uint32_t length);

返回值：无
说明：回调函数原型申明，当手机APP有查询指令下发给蓝牙设备时，SDK会调用此函数

4. int alink_start(struct device_config *dev_conf);

返回值：0表示调用成功 -1表示调用失败
说明：启动SDK的服务，由客户代码调用

5. int alink_end();

返回值：无
说明：停止SDK的服务，由客户代码调用

6. void alink_post(uint8_t *buffer, uint32_t length);

返回值：无
说明：一旦蓝牙设备有数据更新，需要调用此函数将蓝牙设备最新状态发送给手机App，在Callback 函数status_changed_cb中通知调用结果，蓝牙采用indicate的方式post数据，非阻塞

7. void alink_post_fast(uint8_t *buffer, uint32_t length);

返回值：无
说明：一旦蓝牙设备有数据更新，需要调用此函数将蓝牙设备最新状态发送给手机App，在Callback 函数status_changed_cb中通知调用结果，蓝牙采用notify的方式post数据，非阻塞

3. 芯片推荐列表

更新日期：2018-05-24

如果贵司开发的产品，使用的蓝牙芯片包含在上述列表中，请直接联系厂商获取设备端SDK。
否则，则属于未认证的芯片，开发前请先联系我们。