本文介绍天猫精灵音箱、App和BLE设备行为和具体协议规范。
背景信息
本规范基于蓝牙BLE基础规范。
基础规范使用
- 广播规范
将Subtype置为0b1011。
如上图所示，Manufacturer Specific Data在基本类型的定义上扩展出2个字节（16bit）的Ext字段，用来标识一些额外的信息。Ext字段各bit位定义如下。
Bit序 功能说明 0 是否有数据进行上报，0：没有数据；1：有数据上报 1～15 保留位数，后续启用，全部配置为0。 - 数据传输规范
BLE数据传输使用基础规范定义的数据格式和规则。具体介绍，请参见数据传输规范。
- Payload业务规范
- Flag标识业务数据的特征，占用bit7～6。
bit位 说明 bit7 - 消息为上行消息时表示云端还是天猫精灵音箱或App本地处理，0为云端处理，1为本地处理。
- 消息为下行消息时表示消息来自云端还是天猫精灵音箱或App本地，0为来自云端，1为来自本地。
bit6 当前置0，后续可扩展。 - DataType标识业务数据的类型，占用bit5～0：默认取值0x01。适用于当前使用场景，后续可做扩展。
- Flag标识业务数据的特征，占用bit7～6。
接入设备类型
接入的BLE产品必须符合标准的BLE GATT协议。由于GATT和Mesh协议不同，是基于连接的协议，也就是传输数据之前必须先进行连接，而天猫精灵和App同时连接的BLE 设备是有限的，所以和天猫精灵连接的BLE设备，只有在需要传输数据的时候才建立GATT的连接，数据传输完成之后，GATT连接就需要断开。由于这种差异性，根据产品业务不同，将接入的产品主要分为数据上报型设备和数据下发上报型设备。
数据上报型设备
此类设备以上传数据给天猫精灵或App为主要业务场景，天猫精灵或App侧没有主动下发命令的需求。体脂秤是典型的数据上报型设备，体脂秤都是主动将采集到的体脂信息主动上报到天猫精灵或App，天猫精灵或App在连接还没有建立的情况下，没有主动下发命令的场景。此类设备只在需要上报数据的时候，向外发送BLE 广播包，天猫精灵和App扫描到此广播包后就主动连接此设备，连接建立之后，设备主动上报数据到天猫精灵端或App端，在连接没有断开之前，天猫精灵端或App 端可以下发命令。当设备和天猫精灵在2分钟内没有数据传输的话，精灵需要主动断开和设备的连接。同时也允许设备为了功耗的考虑，在完成数据传输后立刻主动断开和天猫精灵的连接。
数据交互指令集
CMD对应数据格式Header中的CmdType字段。
- 设备主动上报
CMD 0x01：蓝牙设备主动上报的设备状态。
- Request-Response模型（App或音箱发起）
- CMD 0x02 ：手机App或音箱发出请求指令，需要蓝牙设备回复，与CMD 0x03对应。
- CMD 0x03 ：蓝牙设备回复请求指令，与CMD 0x02对应。
- Request-Response模型（设备发起）
- CMD 0x04 ：蓝牙设备发出请求指令，需要手机App或音箱回复，与CMD 0x05对应。
- CMD 0x05 ：手机App或音箱回复请求指令，与CMD 0x04对应。
- 命令下发
CMD 0x06：手机App或音箱发送指令，无需对方回复。
- 异常上报
CMD 0x0F：指令异常通知，用于蓝牙设备通知手机App，设备接收到错误的指令或流程出错。
数据Data格式选项
根据BLE设备的不同，Data可以有两个选项。
- 厂商自定义格式
如果厂商选用自定义私有格式，设备端的改动较小，但需到云端配置脚本数据转换。
- 使用阿里定义的格式
如果选用阿里定义的格式，则需要设备端实现阿里的数据规范，将opcode缩减为1字节。更多介绍，请参见蓝牙Mesh设备扩展协议。缩减后的opcode如下表所示。
Message Name Opcode Vendor Message Attr Get 0xD0 Vendor Message Attr Set 0xD1 Vendor Message Attr Set Unacknowledged 0xD2 Vendor Message Attr Status 0xD3 Vendor Message Attr Indication 0xD4 Vendor Message Attr Confirmation 0xD5 Vendor Message Attr Indication To TmallGenie 0xDE Vendor Message Attr Confirmation From TmallGenie 0xDF Vendor Message Transparent msg（厂商自定义格式） 0xCF
体脂秤属性示例
体脂秤属性定义示例如下。
| 属性名称 | Vendor model Attr | Vendor Model Attr Parameter | 备注 |
|---|---|---|---|
| 体重 | 0x0200 | uint16 weight | 精度0.01公斤 |
| 体脂 | 0x0201 | uint32 impedance | 欧姆（Ω），精度为0.1 |
| 称重时间 | 0x0103 | uint8 unix_time[6] | unix时间戳 |
| 单位 | 0x010B | uint8 unit |
|
| 开始称重 | 0xF009 | uint8 Event | 0x1D ： 开始测量 |
| 低电告警 | 0xF009 | uint8 Event | 0x01 |
| 电量 | 0x0104 | uint8 power_percent | 电池电量百分比 |
| 故障上报 | 0xF009 | uint8 Event | 设备发生的事件，详细定义，请参见设备事件表。如事件带参数，则后续跟参数。 例如0x82表示不支持操作；0x84表示设备状态错误；0x91表示传感器故障。 |
体脂秤场景交互
如下所示，其中开始称重和设置单位是可选的，当设备有低电量情况下，主动上报低电量告警。
体脂秤数据示例
- 开始称重
- 该消息使用Vendor Message Attr Indication，消息格式如下。
字段 字节数 说明 Opcode 1 0xD4 TID 1 Transaction Identifier，每条新消息递增，回复控制命令的TID为下发消息的TID。 Attr Type 2 0xF009 Attr Parameter 1 0x1D - 天猫精灵或App使用Vendor Message Attr Confirmation回复，消息格式如下。
字段 字节数 说明 Opcode 1 0xD5 TID 1 Transaction Identifier，收到的Indication的TID。
- 该消息使用Vendor Message Attr Indication，消息格式如下。
- 设置单位
该消息使用Vendor Message Attr Set Unacknowledged，消息格式如下。
字段 字节数 说明 Opcode 1 0xD2 TID 1 Transaction Identifier，每条新消息递增。 Attr Type 2 0x010B Attr Parameter 1 0x02：中国单位（市斤） - 上报体重体脂数据（使用Vendor Message Attr Status）
上报体重体脂数据可以使用Vendor Message Attr Status ，此消息天猫精灵或者App无需回复，消息格式如下。
字段 字节数 说明 Opcode 1 0xD3 TID 1 Transaction Identifier，每条新消息递增。 Attr Type 2 0x0200 Attr Parameter 2 体重值 Attr Type 2 0x0201 Attr Parameter 2 体脂值 - 上报体重体脂数据（使用Vendor Message Attr Indication）
- 上报体重体脂数据可以使用Vendor Message Attr Indication，消息格式如下。
字段 字节数 说明 Opcode 1 0xD4 TID 1 Transaction Identifier，每条新消息递增。 Attr Type 2 0x0200 Attr Parameter 2 体重值 Attr Type 2 0x0201 Attr Parameter 2 体脂值 - 天猫精灵或者App使用Vendor Message Attr Confirmation回复，消息格式如下。
字段 字节数 说明 Opcode 1 0xD5 TID 1 Transaction Identifier，收到的Indication的TID。
- 上报体重体脂数据可以使用Vendor Message Attr Indication，消息格式如下。
- 低电量告警
该消息使用Vendor Message Attr Status ，此消息天猫精灵或者App无需回复，消息格式如下。
字段 字节数 说明 Opcode 1 0xD3 TID 1 Transaction Identifier，每条新消息递增。 Attr Type 2 0xF009 Attr Parameter 1 0x01