本文介绍天猫精灵音箱、App和BLE设备行为和具体协议规范。

背景信息

本规范基于蓝牙BLE基础规范

基础规范使用

  • 广播规范
    将Subtype置为0b1011。GATT_MSD_扩展如上图所示,Manufacturer Specific Data在基本类型的定义上扩展出2个字节(16bit)的Ext字段,用来标识一些额外的信息。Ext字段各bit位定义如下。
    Bit序 功能说明
    0 是否有数据进行上报,0:没有数据,1:有数据上报
    1~15 保留将来使用,全部填0
  • 数据传输规范

    BLE数据传输使用基础规范定义的数据格式和规则。参考数据传输规范

  • Payload业务规范BLEPayload
    • Flag标识业务数据的特征,占用bit7~6。
      bit位 说明
      bit7
      • 消息为上行消息时表示云端还是天猫精灵音箱/App本地处理,0为云端处理,1为本地处理。
      • 消息为下行消息时表示消息来自云端还是天猫精灵音箱/App本地,0为来自云端,1为来自本地。
      bit6 当前置0,后续可扩展。
    • DataType标识业务数据的类型,占用bit5~0:默认取值0x01。适用于当前使用场景,后续可做扩展。

接入设备类型

接入的BLE产品必须符合标准的BLE GATT协议。由于GATT和Mesh协议不同,是基于连接的协议,也就是传输数据之前必须先进行连接,而天猫精灵和App同时连接的BLE 设备是有限的,所以和天猫精灵连接的BLE设备,只有在需要传输数据的时候才建立GATT的连接,数据传输完成之后,GATT连接就需要断开。由于这种差异性,根据产品业务不同,将接入的产品主要分为数据上报型设备和数据下发上报型设备。

数据上报型设备

此类设备以上传数据给天猫精灵或App为主要业务场景,天猫精灵或App侧没有主动下发命令的需求。体脂秤是典型的数据上报型设备,体脂秤都是主动将采集到的体脂信息主动上报到天猫精灵或App,天猫精灵或App在连接还没有建立的情况下,没有主动下发命令的场景。此类设备只在需要上报数据的时候,向外发送BLE 广播包,天猫精灵和App扫描到此广播包后就主动连接此设备,连接建立之后,设备主动上报数据到天猫精灵端或App端,在连接没有断开之前,天猫精灵端或App 端可以下发命令。当设备和天猫精灵在2分钟内没有数据传输的话,精灵需要主动断开和设备的连接。同时也允许设备为了功耗的考虑,在完成数据传输后立刻主动断开和天猫精灵的连接。

数据上报型设备

数据下发上报型设备

此类设备除了上传数据给天猫精灵的业务场景之外,还有天猫精灵主动推送命令给设备的业务场景。此类设备要求此设备一直处在可被连接的状态。天猫精灵或App需要主动推送命令的时候,先主动连接此设备,然后发送命令。

数据下发上报型设备

数据交互指令集

CMD对应数据格式Header中的CmdType字段。

  • 设备主动上报:

    CMD 0x01:蓝牙设备主动上报的设备状态。

    CMD01
  • Request-Response模型(App/音箱发起):
    • CMD 0x02 :手机App/音箱发出请求指令,需要蓝牙设备回复,与CMD 0x03对应。
    • CMD 0x03 :蓝牙设备回复请求指令,与CMD 0x02对应。
    CMD0203
  • Request-Response模型(设备发起):
    • CMD 0x04 :蓝牙设备发出请求指令,需要手机App/音箱回复,与CMD 0x05对应。
    • CMD 0x05 :手机App/音箱回复请求指令,与CMD 0x04对应。
    CMD0405
  • 下发命令:

    CMD 0x06:手机App/音箱发送指令,无需对方回复。

    CMD06
  • 异常上报:
    CMD 0x0F :指令异常通知,用于蓝牙设备通知手机App,设备接收到错误的指令或流程出错。CMD0F

数据Payload格式选项

根据BLE 设备的不同,Payload可以有两个选项。

  • 厂商自定义格式

    如果厂商选用自定义私有格式,设备端的改动较小,但需到云端配置脚本数据转换。

  • 使用阿里定义的格式
    如果选用阿里定义的格式,则需要设备端实现阿里的数据规范。参考蓝牙Mesh设备扩展协议,将opcode缩减为1字节,缩减后的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
  • 0:公制(公斤,米,摄氏度)
  • 1:英制(磅,英尺,华氏度)
  • 2:中国单位(市斤,尺)
开始称重 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 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 Status ,此消息天猫精灵或者App无需回复,消息格式如下。
    字段 字节数 说明
    Opcode 1 0xD3
    TID 1 Transaction Identifier,每条新消息递增。
    Attr Type 2 0xF009
    Attr Parameter 1 0x01