天猫精灵IoT开放平台
1、 概况
本文为阿里巴巴为智能家居设备制定的蓝牙mesh扩展消息定义，便于更多的智能家居设备通过蓝牙mesh技术来接入天猫精灵生态。
2、 Model
由于SIG Mesh的Model目前尚未覆盖所有的家电，我们采用Vendor Model来实现智能家居设备的控制和状态上报，SIG定义其格式为4字节(其中2字节的Company ID和2字节的Vendor-assigned Model ID)，其中Alibaba的Company ID为0x01A8，如下表所示。
表1 Vendor Model ID定义格式
| Field |
Size(octets) |
Notes |
| 16-bit Company Identifier |
2 |
0x01A8 |
| 16-bit vendor-assigned model Identifier |
2 |
|
下表为两个VendorModel ID,用于消息扩展用。
表2 Vendor Model ID
| Model Name |
SIG Model ID |
| Vendor Model Server |
0x01A80000 |
| Vendor Model Client |
0x01A80001 |
IOT设备作为Vendor Model Server，天猫精灵作为Vendor Model Client。
3、扩展消息
3.1 操作码
在mesh协议中规定，操作码分为3种：1字节OpCode；2字节Opcode；3字节Opcode。
1字节Opcode的最高位为0，所以1字节Opcode的取值范围从0x00-0x7e(其中0x7f用于将来扩展用)。
2字节Opcode第一字节的最高位为1，第二位为0，所以2字节OpCode的取值范围从0x8000到0xbfff，都为SIG分配。
3字节Opcode第一字解的最高两位均为1，后两字节"z"是由SIG分配的Company ID，Company ID使用小端优先的方式传输，阿里巴巴使用的Company ID为0x01a8。’x’可由厂商定义64个opcodes。
下图为操作码的具体格式。
图1 操作码格式
阿里巴巴定义的Opcode如下表所示
表3 蓝牙mesh扩展消息Opcode
| Message Name |
Opcode |
| Vendor Message Attr Get |
0xD001A8 |
| Vendor Message Attr Set |
0xD101A8 |
| Vendor Message Attr Set Unacknowledged |
0xD201A8 |
| Vendor Message Attr Status |
0xD301A8 |
| Vendor Message Attr Indication |
0xD401A8 |
| Vendor Message Attr Confirmation |
0xD501A8 |
| Vendor Message Transparent msg |
0xCF01A8 |
3.2 消息结构
Vendor message里的数据都使用小端优先方式传输。
3.2.1 Vendor Message Attr Get
该消息用于Vendor Model Client获取Vendor Model Server的一个或多个属性值，消息格式如下
| Field |
Size |
Note |
| Opcode |
3 |
0xD001A8 |
| TID |
1 |
Transaction Identifier，每条新消息递增 |
| Attr Type |
2 |
读取的Attr类型 |
Attr Type最多可有15个。当Vendor Model Server收到Attr Get消息后，必须向Vendor Model Client回复Attr Status。如Vendor Model Client在下发该命令之后未收到Vendor Model Server返回的Attr Status，可以再次下发该指令。
3.2.2 Vendor Message Attr Set
该消息用于Vendor Model Client设置Vendor Model Server的一个或多个属性值，消息格式如下
| Field |
Size |
Note |
| Opcode |
3 |
0xD101A8 |
| TID |
1 |
Transaction Identifier，每条新消息递增 |
| Attr Type |
2 |
设置的Attr类型 |
| Attr Parameter |
N |
设置的Attr参数 |
Attr Type和Attr Parameter最多可有15个。当Vendor Model Server收到Attr Set消息后，必须向Vendor Model Client回复Attr Status。如Vendor Model Client在下发该命令之后未收到Vendor Model Server返回的Attr Status，可以再次下发该指令。
3.2.3 Vendor Message Attr Set Unacknowledged
该消息用于Vendor model Client设置Vendor Model Server的一个或多个属性值，消息格式如下
| Field |
Size |
Note |
| Opcode |
3 |
0xD201A8 |
| TID |
1 |
Transaction Identifier，每条新消息递增 |
| Attr Type |
2 |
设置的Attr类型 |
| Attr Parameter |
N |
设置的Attr参数 |
Attr Type和Attr Parameter最多可有15个。当Vendor Model Server收到Attr Set Unacknowledged消息后，不需要向Vendor Model Client发送Attr Status消息
3.2.4 Vendor Message Attr Status
该消息用于Vendor Model Server回复Attr Get和Attr Set命令或上报设备状态信息给Vendor Model Client，消息格式如下
| Field |
Size |
Note |
| Opcode |
3 |
0xD301A8 |
| TID |
1 |
Transaction Identifier，每条新消息递增 |
| Attr Type |
2 |
上报的Attr类型 |
| Attr Parameter |
N |
上报的Attr参数 |
Vendor Model Client收到Attr Status后，不需要回复消息给Vendor Model Server
3.2.5 Vendor Message Attr Indication
该消息用于Vendor Model Server发送属性给Vendor Model Client，消息格式如下
| Field |
Size |
Note |
| Opcode |
3 |
0xD401A8 |
| TID |
1 |
Transaction Identifier，每条新消息递增 |
| Attr Type |
2 |
上报的Attr类型 |
| Attr Parameter |
N |
上报的Attr参数 |
Attr Type和Attr Parameter最多可有15个。当Vendor Model Client收到Attr Indication消息后，必须向Vendor Model Server回复Attr Confirmation。如Vendor Model Server在发出该命令之后未收到Vendor Model Client回复的confirmation，可以再次发送该指令。
3.2.6 Vendor Message Attr Confirmation
该消息用于Vendor Model Client回复给Vendor Model Server，用于表示已收到Vendor Model Server发出的Indication，消息格式如下
| Field |
Size |
Note |
| Opcode |
3 |
0xD501A8 |
| TID |
1 |
Transaction Identifier，收到的Indication的TID |
Vendor Model Server收到Attr Confirmation后，不需要回复消息给Vendor Model Client
3.2.7 Vendor Message Attr Transparent Msg
该消息用于mesh设备与天猫精灵之间透传数据，后续数据格式由各厂家自己实现.
4、 智能家居设备描述
为了适配各种智能家居设备，我们将智能家居设备抽象成属性，事件和场景模式，具体定义如下
属性：包括设备具有的系统属性和物理属性，也包括设备具有的特殊功能，我们通过设置属性来改变设备的工作状态或让设备开启/关闭它的特殊功能。
事件：设备在运行过程中出现了需要用户来手动干预的特殊情况，这时候上报给用户的通知。或者是用户主动激活的某些事件，例如按键。
场景模式：设备为了完成某些特定功能而预设在设备内的一系列属性值，便于人们理解；在某一个时刻，设备只能处于一个场景模式。
注：如果属性，事件，场景模式无法满足产品开发需求，请及时与我们联系添加新的属性，事件，场景模式类型。(aligenie.iot@list.alibaba-inc.com)
4.1通用属性列表
| Category |
Attr Name |
Attr Type |
Data Struct |
Unit |
Precision |
Note |
| 系统属性 |
错误码 |
0x0000 |
uint16 Attr_Type |
- |
- |
AttrType：出错的属性类型 |
| 版本信息 |
0xFF01 |
uint32 version_number |
- |
- |
version_number:与OTA的版本一致 |
|
| Device Feature |
0xFF02 |
uint16 device_feature |
- |
- |
与Composition Data Page 0中的feature一致，最高位bit15往下是阿里自定的一些feature bit0: Relay bit1: Proxy bit2: Friend bit3: Low Power Node bit14: Low Power and Letency bit15: Multi-Attr RW support bit4~12: RFU 置1表示该功能打开，置0表示该功能关闭 |
|
| Flash总容量 |
0xFF03 |
uint32 total_flash_size |
Byte |
- |
设备Flash的总容量 |
|
| Flash已用容量 |
0xFF04 |
uint32 used_flash_size |
Byte |
- |
设备Flash的已用容量 |
|
| Flash空余容量 |
0xFF05 |
uint32 free_flash_size |
Byte |
- |
设备Flash的可用容量 |
|
| 工程模式 |
0xFF06 |
int8 Engineer_Mode |
- |
- |
1：工厂测试模式，各厂商自己定义工厂生产使用模式 2：进入debug模式，设备端log通过其他通道上传到云端 3：重启设备 4：清除设置数据 5：恢复出厂设置 6：用户诊断模式 |
|
| 通用属性 |
工作状态 |
0xF001 |
uint8 workstatus |
- |
- |
具体数值所代表含义请参看开放平台 |
| User ID |
0xF002 |
uint8 user_ID |
- |
- |
当前用户ID |
|
| 设备名 |
0xF003 |
uint8 len |
- |
- |
设备名称 |
|
| 场景模式 |
0xF004 |
uint16 mode_number |
- |
- |
设备的场景模式，与scene model关联 |
|
| 开关计划(该命令需要设备具备RTC电路和对时功能) |
0xF008 |
uint8 weekday uint16 time uint8 OnOff |
|
|
以周为周期来定时开关设备 weekday：bit0~bit6分别代表周日到周六，置1为启用，置0为禁用 time：开关的时间相对于00:00的分钟数 OnOff：开启/关闭 |
|
| 事件触发 |
0xF009 |
uint8 Event uint8 Event para[] |
- |
- |
设备发生的事件，event参见事件表，如事件带参数，则后续跟参数。 |
|
| 事件清除 |
0xF019 |
uint8 Event uint8 Event para[] |
- |
- |
如设备发生的事件引起了设备状态的改变，在设备的状态消失后，设备需要清除之前上报的事件。 例如当设备电池电量过低，设备上报低电量事件，并处于低电量状态；当用户更换电池后，设备退出低电量状态，应当上报清除低电量事件。 |
|
| 信号强度 |
0xF00A |
int8 RSSI |
dbm |
- |
设备信号强度 |
|
| 调高/调低某属性 |
0xF00B |
uint16 Attr_Type |
- |
- |
Attr_para_step为正表示增加，为负表示减少，物理量步长不带小数点 |
|
| 区域数量 |
0xF00C |
uint8 Element_num |
- |
- |
设备具有几个区域 |
|
| 属性切换 |
0xF00D |
uint8 Attr_Type uint8 switch |
- |
- |
设备具有的Attr_Type属性在他的取值范围内进行循环切换，Attr_Type为枚举或布尔型 |
|
| 受控设备地址 |
0xF00E |
uint16 Remote_Address |
- |
- |
该设备为遥控设备，该属性为这个遥控设备所控制的设备的地址，可为unicast address或者group address |
|
| 周边设备信号强度 |
0xF00F |
uint16Device_Address |
dbm |
- |
周边设备信号强度 |
|
| 定时设置某属性 |
0xF010 |
uint8 index uint32 unix_time uint16 attr_type uint8 attr_para[] |
- |
- |
该功能参数详细说明请参照定时功能文档 |
|
| 周期定时设置某属性 |
0xF011 |
uint8 index uint16 24h_timer uint8 schedule uint16 attr_type uint8 attr_para[] |
- |
- |
该功能参数详细说明请参照定时功能文档 |
|
| 删除定时 |
0xF012 |
uint8 index |
- |
- |
删除索引为index的定时 |
|
| 请求更新定时 |
0xF013 |
uint8 index |
- |
- |
请求更新索引为index的定时 |
|
| 对时设置 |
0xF01D |
uint16 period_time uint8 retry_delay uint8 retry_times |
分钟 分钟 次 |
|
每隔period_time进行一次对时请求，如果设备则过retry_delay后再次请求对时，最多重复请求retry_times（包含第一次请求） |
|
| 时区 |
0xF01E |
int8 time_zone |
|
|
取值-12～12 |
|
| Unix时间 |
0xF01F |
uint32 unix_timer |
秒 |
- |
标准Unix时间 |
|
| 断电记忆功能 |
0xF021 |
bool poweroffMemory |
- |
- |
0：关闭断电记忆 1：打开断电记忆 |
5、Sample Data
5.1 Vendor Model Client设置目标温度为22摄氏度
Vendor Model Client下发设置目标温度的Attr Set命令
| 0xD1 |
0xA8 |
0x01 |
0x01 |
0x0C |
0x01 |
0x4B |
0x73 |
| Opcode |
TID |
Attr Type |
Attr Value |
||||
| 0xD101A8 |
01 |
目标温度 (0x010C) |
目标温度值：22摄氏度(0x734B = 295.15K) |
||||
Vendor Model Server设置目标温度成功时返回的Attr Status
| 0xD3 |
0xA8 |
0x01 |
0x01 |
0x0C |
0x01 |
0x4B |
0x73 |
| Opcode |
TID |
Attr Type |
Attr Value |
||||
| 0xD301A8 |
01 |
目标温度 (0x010C) |
目标温度值：22摄氏度(0x734B = 295.15K) |
||||
Vendor Model Server设置目标温度失败时返回的Attr Status
| 0xD3 |
0xA8 |
0x01 |
0x01 |
0x00 |
0x00 |
0x0C |
0x01 |
0x80 |
| Opcode |
TID |
Error Code Type |
Attr Type |
Error Code |
||||
| 0xD301A8 |
01 |
0x0000 |
目标温度 (0x010C) |
状态码：设备未准备好(0x80) |
||||
5.2 Clinet读取前后位置，当前温度，当前湿度
Vendor Model Client发送Attr Set读取前后位置，当前温度，当前湿度的属性
| 0xD0 |
0xA8 |
0x01 |
0x01 |
0x10 |
0x01 |
0x0D |
0x01 |
0x0F |
0x01 |
| Opcode |
TID |
Attr Type |
Attr Type |
Attr Type |
|||||
| 0xD001A8 |
01 |
前后位置：(0x0110) |
当前温度：(0x010D) |
当前湿度：(0x010F) |
|||||
Vendor Model Server读取三个属性成功时返回的Attr Status
| 0xD3 |
0xA8 |
0x01 |
0x01 |
0x10 |
0x01 |
0x32 |
0x0D |
0x01 |
0x4B |
0x73 |
0x0F |
0x01 |
0x94 |
0x11 |
| Opcode |
TID |
Attr Type |
Attr Value |
Attr Type |
Atrtr Value |
Attr Type |
Atrtr Value |
|||||||
| 0xD301A8 |
01 |
前后位置：(0x0110) |
前后位置：50(0x32) |
当前温度：(0x010D) |
当前温度：22摄氏度(0x734B=295.15K) |
当前湿度：(0x010F) |
当前湿度：45%(0x1194) |
|||||||
Vendor Model Server读取温度失败时返回的Attr Status
| 0xD3 |
0xA8 |
0x01 |
0x01 |
0x10 |
0x01 |
0x32 |
0x00 |
0x00 |
0x0D |
0x01 |
0x81 |
0x0F |
0x01 |
0x94 |
0x11 |
| Opcode |
TID |
Attr Type |
Attr Value |
Error Code Type |
Attr Type |
Error Code |
Attr Type |
Atrtr Value |
|||||||
| 0xD301A8 |
01 |
前后位置 |
前后位置：50(0x32) |
0x0000 |
当前温度：(0x010D) |
错误码：不支持的属性(0x81) |
当前湿度 |
当前湿度值：45%(0x1194) |
|||||||
5.3 Vendor Model Server发送温度给Vendor Model Client
Vendor Model Server发送Attr Indication上报温度
| 0xD4 |
0xA8 |
0x01 |
0x01 |
0x0D |
0x01 |
0x4B |
0x73 |
| Opcode |
TID |
Attr Type |
Attr Value |
||||
| 0xD401A8 |
01 |
当前温度 (0x010D) |
当前温度值：22摄氏度(0x734B = 295.15K) |
||||
Vendor Modlel Client收到Attr Indication后发送Confirmation
| 0xD5 |
0xA8 |
0x01 |
0x01 |
| Opcode |
TID |
||
| 0xD501A8 |
01 |
||