IoT开放平台
开发指南

天猫精灵蓝牙mesh软件基础规范


一.目的

定义BLE Mesh通用的模组软件规范,指导模组厂家软件设计并接入天猫精灵。

 

二.mesh模组软件基本要求

蓝牙mesh设备必须具备mesh协议里定义的Relay、Proxy功能,LPN和Friend功能可选。低功耗设备采用精灵低功耗(GLP)方案,LPN方案可选。特殊产品会如果仅需支持部分功能将在产品软件规范中明确说明具体需要支持的功能。

蓝牙mesh设备要求至少支持2个NetKey,总计10个AppKey。

 

三.BLE Mesh通用模块软件规范

1. 名词解释

蓝牙mesh

蓝牙网状网络连接技术

三元组

阿里巴巴颁发的一组数据,包括MAC地址,Product ID, Secret,用于设备鉴权。开发者可在天猫精灵开发者网站申请

CID

Company Identifier,公司标识符。阿里巴巴的标识符为0x01A8

GLP

精灵低功耗方案

 

2. 广播包

mesh广播包

蓝牙mesh设备上电后如处于未配网状态,需要广播Unprovisioned Device Beacon,每次广播时长40ms,广播间隔100ms,广播持续时间默认10分钟,具体产品的广播启动方式和广播持续时间以产品需求为准。超时后仍未被配网则进入静默广播状态(请参见3.2.1.2 ),低功耗设备不需要进入静默广播状态。

 

广播包中的Device UUID是识别设备的关键信息,阿里巴巴对Device UUID的定义如下表所示,UUID中各字段采用小端模式进行存储。

Field

Size(Octets)

Notes

CID

2

公司ID,设置为0x01A8:Taobao

PID

1

Bit0-3 蓝牙广播包版本号,目前是0x01

bit4为1:一机一密

bit5为1:支持OTA

bit6~7:   00:BLE4.0

                 01:BLE4.2

                 10:BLE5.0

                 11:BLE5.0以上

ProductID

4

阿里巴巴平台颁发,一型一号

MAC地址

6

阿里巴巴平台颁发,一机一号

FeatureFlag

1

bit7-1:uuid版本号,目前版本为1

bit0  0:处于未配网广播状态

        1:处于静默广播状态

RFU

2

0x00 Reserved for future use

表1:Device UUID格式

 

Feature Flag

目前UUID版本号及其对应的特性如下表:

UUID版本号

特性

名字待定

0b0000000

1.该版本配网流程遵循蓝牙mesh标准规范

V1.0

0b0000001

1.该版本优化了配网流程,具体参见3.3.4

2.该版本需要支持vendor model V2.0(参见《蓝牙mesh扩展协议》)

V2.0

表2:UUID版本号说明

 

静默广播

    静默广播区别于未配网广播,当设备处于静默广播状态时,设备在收到Provisioner发出的配网消息时不进行响应,Provisioner设备在收到静默广播报文后,应当提示用户重置设备进入未配网广播状态进行配网。

    设备在进入静默广播状态时,需要首先修改自身UUID,然后开始广播Unprovisioned Device Beacon,每次广播时长120ms,广播间隔60s。

 

广播未配网广播示例

未配网广播数据示例:

0x14

0x2B

0x00

A8 01 71 81 02 00 00 55 43 CB 07 DA 78 02 00 00

0x00

0x00


Mesh Beacon

Unprovisioned Device beacon

Device UUID

OOB Information

Length

Type

Beacon Type

Beacon Data

advertising data header

adversiting data payload

静默广播数据示例:

0x14

0x2B

0x00

A8 01 71 81 02 00 00 55 43 CB 07 DA 78 03 00 00

0x00

0x00


Mesh Beacon

Unprovisioned Device beacon

Device UUID(静默广播数据位为1)

OOB Information

Length

Type

Beacon Type

Beacon Data

advertising data header

adversiting data payload

 

PB-GATT广播包

不支持PB-ADV的设备,如蓝牙4.0手机,则需要通过和节点建立GATT连接,并通过Mesh Provisioning Service通信。因此建立GATT连接之前,节点需要广播PB-GATT的广播包。综上所述,节点需要交叉广播Unprovisioned Device Beacon广播包和PB-GATT的广播包。设备上电后,PB-GATT的广播包每次广播时长是40ms,广播间隔是1s。

GATT广播包中的UUID参照3.2.1 mesh广播包中的UUID定义。

 

3. mesh设备配网流程

蓝牙mesh设备配网流程遵循蓝牙mesh标准的Provisioning流程,其中几个使用自定义数据的步骤描述如下:

 

Provisioning Capabilities阶段

mesh设备在Provisioning Capabilities阶段提供OOB方式,要求唯一支持Static OOB方式,其中的AuthValue计算过程如下:

AuthValue = SHA256(Product ID,MAC,Secret)。

即:将ProductID,MAC,Secret三元组通过字符串用英文逗号连接,然后进行SHA256摘要计算,取前16字节。注:这里用于计算SHA256的英文字母全部为小写

三元组在开发者平台注册产品时会生成调试用的三元组,量产三元组请走开发者平台量产流程。

表6 SHA256计算示例

数据字段

数据格式与示例

计算使用的输入字符串

Product ID

十进制数值:168930,对应十六进制数值:0x293e2

"000293e2"

Mac Address

"AB:CD:F0:F1:F2:F3"(扫描到的蓝牙设备MAC地址)

"abcdf0f1f2f3"

Secret

"53daed805bc534a4a93c825ed20a7063"

"53daed805bc534a4a93c825ed20a7063"

连接后字符串

"000293e2,abcdf0f1f2f3,53daed805bc534a4a93c825ed20a7063"

SHA256结果输出(HEX)

c1 c7 67 41 55 32 36 fb 7d a0 a5 86 e6 22 98 c2 31 da c2 88 5e 73 5f eb a6 b8 b441 7c 7d 9e 72

AuthValue(HEX)

c1 c7 67 41 55 32 36 fb 7d a0 a5 86 e6 22 98 c2

 

Provisioning Confirmation

这个阶段,天猫精灵和mesh设备会使用Static OOB方式来做认证,如果天猫精灵和mesh设备两边计算得到的Confirmation值不相同,则认证失败,结束流程。

mesh协议在此阶段中有一个步骤是设备端生成一个随机数并发送给天猫精灵,天猫精灵会把这个随机数发送给云端鉴权,云端会保存设备端每次发送的随机数,如果设备端发送的随机数是之前使用过的,则云端将会拒绝该设备配网,所以务必保证每次生成的随机数都不重复。

 

Provisioning Data阶段

对于多Element设备,天猫精灵在该阶段只会下发Pirmery Element的Unicast Address。其余Element的Unicast Address则根据上一Element的地址自行增加1。

 

Provision完成配置阶段

天猫精灵在Provisioning Complete之后,会下发AppKey。其余配置根据UUID版本有以下区别:

UUID版本

配置方式

0

天猫精灵会下发一次主element的Config_Model_App_bind,设备需要返回成功的status,否则会配网失败;剩余model需要自行绑定appkey。

天猫精灵会下发一次主element的Config_Model_Subscription_Add,设备需要返回成功的status,否则会配网失败;剩余model需要自行绑定Subscription Address。

1

天猫精灵不会下发Config_model_app_bind和Config_Model_Subscrption_Add消息。IOT设备需要自行给所有Element的所有model绑定下发的AppKey,并根据产品类型为各个model订阅相应的组播地址(具体品类组播地址请参阅各产品软件规范)。蓝牙mesh设备完成配网后需要进行消息上报,上报消息包括该设备所有支持的可上报的属性。

 

4. mesh数据发送和接收

通常情况下,我们建议设备端的scan window/interval/period分别为10ms/10ms/100ms,advertising interval/period分别为5ms/100ms。

设备在状态改变的时候需要用vendor model向天猫精灵订阅地址(0xF000)发送状态改变的Indication;

 

5. IV Index Update

为保证天猫精灵智能家居设备能够长时间稳定运行,我们对于mesh spec1.0中的IV index update过程中做了如下要求:

(1)模组在seq number达到0xB0E500的时候开始进行IV Index Update流程

(2)由于很多低功耗设备会一直处于睡眠或断电状态,无法进行计时,所以我们要求忽略协议里规定的入网96小时之后才能进行IV index update和Recovery的时间限制

(3)要求如果设备在返回网络后收到第一个secure network beacon的IV index等于当前设备的IV index+1且IV Update Flag为0,应选择直接进行IV Index update,而不应忽略Secure Network Beacon。

(4)对于需要长时间休眠的低功耗设备,为了防止无法接收到IV更新信息,要求设备至少每48小时唤醒一次,且进行至少15秒及以上的连续扫描。

 

 

6. 设备上电规范

蓝牙mesh设备上电后需要延迟随机0~10秒后使用vendor model indication进行消息上报,上报消息包括该设备所有支持的可上报的属性(包含上电消息),上电消息示例如下表所示。

0xD4

0xA8

0x01

0x01

0x09

0xF0

0x03

Opcode

TID

Attr Name

Event

0xD401A8

0x01

事件上报

设备上电


7. 设备同步规范

蓝牙mesh设备在接收到天猫精灵发送的同步消息之后,需要延迟随机0~10秒后使用vendor model indication进行消息上报,上报消息包括该设备所有支持的可上报的属性,天猫精灵下发的同步消息如下表所示。

0xD2

0xA8

0x01

0x01

0x09

0xF0

0x12

Opcode

TID

Attr Name

Event

0xD201A8

0x01

事件

设备联网


8. 设备状态改变上报规范

蓝牙mesh设备的状态改变后,需要通过该状态关联的Model和Vendor model的属性都上报给天猫精灵。例如灯的亮度被改变后,需要用Light Lightness Server的Light Lightness Status和Vendor Model的indication消息(D401A8)上报亮度(0x0121)属性这两种方式将灯当前亮度值上报给天猫精灵。

 

9. 设备重启规范

蓝牙mesh设备重启规范参照设备上电规范,将设备重启视作设备上电。

 

10. 设备复位规范

软件复位(解除配网)

蓝牙mesh设备需要支持通过Config Node Reset的软复位的方法来移除Node,当设备进行软件复位的时候需要移除设备上保存的网络配置信息,设备能够再次被配网,同时根据各产品特性决定是否删除设备配置信息。具体请参阅各产品技术规范。

如果在软件复位过程中需要重启设备,则要求此时不能影响设备正常工作。

 

硬件复位(恢复出厂设置)

蓝牙mesh设备通过硬复位恢复模块出厂设置时,需要移除设备上保存的网络配置信息,设备恢复出厂设置后能够再次被配网,同时根据各产品特性决定是否删除设备配置信息,具体产品的硬复位方法请参看各产品的规格书。

 

注意:硬复位后seq number不能被清零。


11. OTA升级

模组需要根据自身产品形态支持mesh OTA和GATT OTA两种升级方式。具体请参看《天猫精灵智能家居设备OTA升级规范》。

 

12. 精灵低功耗(GLP)

如果模组要应用于下行数据接收的低延时低功耗设备(例如单火开关,电池供电的窗帘电机)时,可以采用精灵低功耗(Genie Low Power)方案,在开放平台上创建产品时在属性里选择精灵低功耗,这样精灵在给这个设备发送数据的时候,会在1.2s的时间内持续不断地发送数据。所以设备只需要每1.2s醒来60ms,可以在低功耗的情况下能及时接收到精灵下发的数据。