第三方蓝牙通信插件适配指南
更新时间：2019-04-28 19:16:37
概述
蓝牙通信框图如下所示，由于各家蓝牙应用层协议千差万别，为了将不同的蓝牙应用层协议接入到统一框架，势必需要有一个适配层来抹平各个协议的差异。如阿里巴巴IoT就定义了一套应用层的通信协议：Breeze。
一般说来，各家的蓝牙应用层协议都会定义如下几部分功能：
1、蓝牙广播：广播设备相关信息，如厂家信息，设备型号信息，设备Mac地址等
2、数据通信，包括数据分段，组包等功能
基于此，阿里云IoT在蓝牙接入框架中引入了蓝牙通信插件管理系统，即 'Link protocol bridge system'，简称 'LPBS'。
蓝牙通信插件管理系统简介
蓝牙通信插件管理系统定义了一套抽象的接口，不同的蓝牙应用协议实现此套抽象接口后，即可以将不同的蓝牙协议设备接入到蓝牙设备接入统一框架中，从而可以按阿里云IoT定义的物模型对蓝牙设备进行控制以及感知。
每一个具体实现我们这里叫做一个 '插件'。
具体的抽象接口定义可以参见文章末尾的头文件下载链接。
关于阿里云IoT物模型
在开发之前，开发者有必要了解一下'物模型'概念。
对于一个设备，阿里云IoT平台会使用物模型来描述设备的功能。物模型采用TSL(Thing Specification Language)来定义一个设备的方方面面的能力。
再具体一点物模型将设备的能力抽象成三个部分：
1、属性
属性可以读取，可以设置，如灯的开关可以是一个属性
2、事件
事件一般而言包含设备需要被外部感知和处理的通知信息，如设备告警。事件可以 subscribe以及post
3、服务
可被外部调用的能力或方法
关于物模型可以参见 物模型TSL
开发流程
飞燕后台相关操作
智能设备需要在阿里云IoT平台获得一个身份后，才能将某个智能设备归属到某一个用户账号下，进一步地可以实现设备数据的上下云以及设备地相关控制。在阿里云IoT平台，设备身份由以下二者确定：
1、productKey（简称PK），一串随机字符串，可以理解为设备的产品型号，在飞燕后台注册产品时由阿里云IoT平台颁发
2、deviceName （简称DN），可以理解为阿里云IoT平台特有的设备的id。跟productKey一起唯一确定一个IoT平台的设备。deviceName可以是阿里云IoT平台生成的一串随机字符串，也可以是厂家在阿里云IoT平台录入设备时指定的字符串，在这里我们采用后者作为设备的deviceName。
而一个智能设备在出厂时，厂家会给设备颁发一个全球唯一的id来标识一个设备。此 id一般由两部分组成
1、productModel，产品型号，如某冰箱型号: BCD-320WGPZM。
2、deviceId，设备 id，一般为 Mac或者SN。
如上所述，智能设备在接入阿里云IoT平台时需要完成私有id跟阿里云IoT平台颁发的id的映射。
后台操作时有两个阶段需要注意：
一、注册产品
在飞燕后台，厂家（或ISV）可以新增一个产品，在注册产品时阿里云IoT平台会给该产品颁发一个productKey来标识此产品。
需要注意的是注册产品时配置参数"数据格式"需要配成"透传/自定义格式"，如下图所示：
二、设备id录入
产品注册后，厂家（或ISV）可以将该产品下的设备批量录入deviceId。这样阿里云IoT平台会为该批次设备颁发设备身份，以便完成后续设备的操作。同时阿里云IoT平台会以录入的deviceId作为设备的deviceName使用。
如何在阿里云IoT后台注册产品以及设备id如何录入，其具体流程可以参见 快速入门。由于第三方蓝牙设备不需要使用阿里云IoT提供的模组或者SDK，设备开发调试那部分可以略过。
数据格式转换脚本
如前述，对于设备的功能，阿里云IoT使用物模型来描述，物模型同时也定义了使用设备功能时收发消息的数据格式。而由于第三方蓝牙设备开发时并没有按物模型来定义设备的功能。这样如果将按物模型约定的格式封装的消息发给蓝牙设备，蓝牙设备会无法识别。如以开灯这一场景举例，按物模型封装的消息格式如下所示：
{
"id":123,
"version":"1.0.0",
"method":"thing.service.property.set",
"params":{
"LightSwitch":1
},
}
此时需要翻译成蓝牙设备能够理解的数据格式，从而可以在蓝牙设备接收到数据后去正确执行开灯的响应。
飞燕平台控制台可以通过编辑产品的JS脚本来完成这个翻译。如下图所示：
编辑脚本时，可以参考其中的示例代码。
蓝牙通信插件管理系统 插件开发
通信插件抽象接口分为三个部分：
1、蓝牙设备发现接口
对于蓝牙通信，蓝牙设备会不停的做蓝牙广播，而手机APP则会从广播中提取到蓝牙设备的相关信息，如产品型号(productModel)以及设备 id（一般为Mac地址）。不过这里要注意，在通信插件开发时，开发者需要将广播中的productModel转换成产品注册时拿到的productKey，Mac地址可以直接当做deviceName使用，需要在飞燕控制台‘量产管理’购买激活码时选择‘激活码生成方式’为‘批量上传’，同时上传的deviceName使用Mac地址。
2、设备连接接口
在手机发现蓝牙设备后，手机可以根据蓝牙广播里的设备信息与蓝牙设备建立连接。
这个接口需要实现手机(即蓝牙Central）跟蓝牙设备(即蓝牙Peripheral)建立连接的过程。一旦连接建立，后续就会有业务数据在手机跟蓝牙设备之间通信。
3、数据发送/接收接口
插件开发者需要完成将业务数据发送到蓝牙设备，同时需要将蓝牙设备的响应数据返回给上层的蓝牙接入框架。
同时还需要实现事件订阅功能，可以订阅蓝牙设备的事件，在蓝牙设备事件发生时，APP侧可以接收到事件。
蓝牙设备的绑定以及控制
在插件实现后，第三方蓝牙设备的后续流程跟阿里云IoT蓝牙设备是一样的，蓝牙设备的绑定以及控制等流程可以参见 移动端 SDK 介绍： iOS开发文档，Android开发文档
相关代码
iOS端：
插件抽象接口头文件
基于阿里蓝牙协议（Breeze）实现的通信插件，可以参考代码 BreezeBridgeSample，下载本代码将默认您同意本软件许可协议
android端：
插件抽象接口头文件