本文介绍天猫精灵BLE基础规范,包括蓝牙广播规范和蓝牙接入服务规范等。

名词解释

名词 描述
BLE Bluetooth Low Energy 蓝牙低功耗技术。
CID Company Identifier,公司标识符。阿里巴巴的标识符为0x01A8。
GATT Generic Attribute Profile蓝牙通用属性协议。
AD Advertisement广播。
VID Protocol Version Code协议版本号。
PID Product ID
FMSK Function Mask 功能使能掩码。
MAC Media AccessControl媒介访问地址。
AIS Alibaba IoT Service阿里巴巴物联网服务。
GMA 全称Genie Mobile Accessory,中文移动精灵;是天猫精灵低功耗蓝牙、经典蓝牙相关业务能力的统称。

广播规范

  • 蓝牙广播包

    蓝牙广播包格式遵循蓝牙4.0规范,由若干AD Structure组成(参见Bluetooth 4.2 Core Specification, Volume 3, Part C, Chapter 11),每一个ADStructure结构由Length、AD Type、AD Data组成。如下图所示:

    GATT广播规范
  • 广播数据包格式
    接入生活物联网平台的蓝牙设备的广播包必须包含阿里巴巴制定的厂商自定义格式(Manufacturer Specific Data,AD Type:0xFF)。阿里巴巴自定义广播格式总共由(6+n)字节组成,不同广播类型,对应不同的n值和Content。如下图所示:马上到!
    字节序 名称 说明
    0 Length 0x0F Manufacturer Specific Data Length,本文档使用基础类型,故取值为基础类型的长度
    1 Type 0xFF Manufacturer Specific Data Type
    2~3 CID 0x01A8 Company Identifiers,0x01A8为阿里巴巴公司编码
    4 VID 和Subtype 0xb5
    • bit3~0 :阿里巴巴蓝牙规范版本号,当前版本号为5,值为0b0101;
    • bit7~4 :Subtype类型;
      • 0b1000:蓝牙基础类型,mesh设备AIS广播使用此类型;
      • 0b1001:蓝牙Beacon类型;
      • 0b1010:蓝牙语音类型;
      • 0b1011:蓝牙GATT类型,接入的BLE品类设备使用此类型。
    5 FMSK 0x03 SDK提供能力Function Mask,比如安全、OTA、蓝牙版本、安全广播等
    6~n Content xx...xx 对应Subtype的内容数据
    说明 Subtype只影响广播中6~n字节的数据格式。本文档采用蓝牙GATT类型进行描述。通常一类设备只需要实现一种广播类型。

    FMSK用于表示设备具有的能力,各Bit位定义如下:

    Bit序 功能说明
    1~0 蓝牙版本,00:BLE4.0, 01:BLE4.2, 10:BLE5.0, 11:BLE5.0以上
    2 0:不支持OTA,1:支持OTA
    3 0:不进行安全认证 1:进行安全认证,详细流程参考安全认证章节
    4 0:一型一密 1:一机一密
    5 配网标识,0:未配网,1:已配网
    7~6 保留将来使用,全部填0
  • GATT类型广播格式
    GATT类型广播SubType对应0x0b,数据格式如下:基础类型广播格式
    6~15字节定义如下:
    字节序 名称 示例值 说明
    6~9 PID 0x00ef1000 产品Product ID,4字节,由生活物联网平台颁发
    10~15 MAC 0xb0b448d07882 蓝牙设备MAC地址,6字节,唯一设备地址,由生活物联网平台颁发
    说明 上述广播中的数据必须按照小端(Little-Endian)格式存储。

AIS服务规范

对于接入阿里巴巴平台的蓝牙设备,必须遵守阿里巴巴自定义的蓝牙服务AIS(Alibaba IoT Service)。

  • AIS服务声明:

    AIS服务声明为Primary Service,Service UUID为0xFEB3。

  • AIS Characteristics说明:

    AIS服务包含以下5个Characteristics:

    Characteristics Name Characteristics UUID Requirement Properties Permission
    Read Characteristics 0xFED4 Mandatory Read Read
    Write Characteristics 0xFED5 Mandatory Read /Write Write
    Indicate Characteristics 0xFED6 Mandatory Read /Indicate None
    WriteWithNoRsp Characteristics 0xFED7 Mandatory Read /Write with No Response Write
    Notify Characteristics 0xFED8 Mandatory Read /Notify None

数据传输规范

由于蓝牙4.0一次只能发送20字节的有效数据,当一包数据超过20字节时,蓝牙无法一次完成数据的传送,所以在发送长数据包时,需要发送时拆包,接收时组包。

  • 单包最大数据长度

    不同的蓝牙版本下,蓝牙在应用层可以传输长度和本规范应用数据长度如下表所示。下文用N代表规范数据长度。

    BLE版本 应用层数据长度 规范数据长度(N)
    BLE4.0 20 16
    BLE4.2 244 240
    BLE5.0 244 240
  • 数据格式
    • 每一包数据由Header,Payload组成。
    • Header长度四字节,主要包含信息指示、消息长度、序号、拆包总数等。
    • Payload 长度0~N字节。
    • 消息长度超过N字节时,分成多帧发送,接收到后按照Header描述重新组包。
    • Header占用四字节,Payload数据长度为0~N字节,整包数据长度在4~4+N字节。
    Header Payload
    4字节 0~N字节
  • 数据格式详细定义BLE数据格式
    • Header Byte 0:数据加密标示、消息ID指示等,说明如下。
      Bit序 说明 备注
      0~3 消息ID,Msg ID
      • 每发送一条消息ID加1
      • 如果消息有应答时,应答的消息ID需要和请求的消息ID匹配
      • ID超过15,自动循环到1
      4 数据加密指示 置0
      5~7 版本信息 置0
    • Header Byte 1:指令类型,蓝牙设备应用层和手机App交互的指令定义示例如下。
      分类 指令 说明
      设备主动上报 0x01 蓝牙设备主动上报的设备状态。
      Request-Response模型 0x02 手机App发出请求指令,需要设备回复,与0x03对应。
      Request-Response模型 0x03 蓝牙设备回复请求指令,与0x02对应。
      Request-Response模型 0x04 蓝牙设备发出请求指令,需要手机App,与0x05对应。
      Request-Response模型 0x05 手机App回复请求指令,与0x04对应。
      异常上报 0x0F 指令异常通知,用于蓝牙设备通知手机App,设备接收到错误的指令或流程出错。
      其他指令 - 为满足业务需求定义的其他指令,如:建立连接的指令集,参考连接建立指令集;空中升级(OTA)定义了相关的指令集,参考OTA指令集
      说明 设备主动上报、Request-Response模型指令为通用指令,Payload格式不做限制,使用方可以自行定义。蓝牙设备接收到错误的指令时,直接抛弃,并通过指令0x0F通知手机App指令错误。
    • Header Byte 2:消息帧数及帧序号,说明如下。
      Bit序 说明 备注
      0~3 帧序号 取值0~15,帧序号从0开始计数
      4~7 总拆包帧数
      • 取值0~15,故实际的总拆包帧数等于(Bit4~Bit7)的值加1
      • Payload为空时,Header中的Byte2、Byte3全为零
    • Header Byte 3:帧数据长度。

      蓝牙4.0数据长度0~16,对于蓝牙4.2及以上版本长度是0~240。

    • Payload:有效数据。

      Payload也使用小端(Little-Endian)格式传输。

    • 消息ID(MsgID):MsgID用于设备端和App端请求指令和回复指令做一一对应使用。由SDK内部维护。

      设备主动上报状态时,MsgID置0。App下发指令需要设备端应答时,设备端保存MsgID,设备的回复指令填充相同的MsgID。MsgID取值范围1~15。App每次下发需要设备端应答的指令时,MsgID加1,到15时,自动循环到1。空中升级(OTA)场景下,MsgID均置0。

  • 数据长度

    蓝牙数据拆包后,拆包数量不超过16个,蓝牙4.0每一包最长16字节,故总数据长度不超过256字节。蓝牙4.2以上,总数据长度不超过3840字节。空中升级(OTA)固件长度不受此限制。

  • 数据的接收发送规范

    蓝牙设备的数据发送、接收按照串行的方式,在SDK中维护。一条消息(表示需要拆包的完整的数据)发送完成,才能发送下一条消息,或者接收下一条消息。

安全认证

安全认证主要用于设备和手机互相校验身份,避免仿冒情况,应用于安全性要求较高的设备或场景,安全认证需要依赖云端能力。使用安全认证的设备,需要将广播的FMSK第三个Bit位置为0b1。手机在每次连接的时候,会进行安全认证流程。安全认证通过后,手机和设备的数据传输会通过密文传输。安全认证是可选实现,可以根据设备的安全性要求或实际业务场景选择使用。

算法和安全说明

  • ProductID,MAC,Secret是云端分配的数据,预先烧录在设备中。为了保证安全,Secret不进行空中传播,也不会传递到手机端。
  • 定义Random是16字节随机字符串,每次生成的Random必须不同。
  • 定义BLE Key = SHA256(Random,PID,MAC,Secret)的。即:将Random,PID,MAC,Secret四个值的字符串数据用英文逗号连接,然后进行SHA256摘要计算,取前16字节。
  • 定义Cipher = AES128 BLE Key (Random)。即:以BLE Key作为密钥,加密Random生成密文Cipher。其中加密算法使用AES128 CBC,取前16字节。
  • 安全认证通过后,数据传输使用密文形式, 加密算法使用AES128 CBC,密钥使用BLE Key。
  • 在认证过程中,云端保证设备身份的不会变化,并且是属于有效用户的合法设备。
  • 手机每次连接会请求生成新的BLE Key,每次断开连接后,设备和手机需要清除当前使用的BLE Key。
  • BLE Key计算过程参数示例如下:
    数据字段 数据格式与示例 计算使用的输入字符串
    Random 随机字符串:"drfiHgbsvomOieog" "drfiHgbsvomOieog"
    ProductID 十进制数值:168930,对应十六进制数值:0x293e2 "000293e2"
    Mac Address "AB:CD:F0:F1:F2:F3"(扫描到的蓝牙设备MAC地址) "abcdf0f1f2f3"
    Secret 字符串:"atFY1tGDCo4MQSVCGVDqtti3PvBI5WXb" "atFY1tGDCo4MQSVCGVDqtti3PvBI5WXb"
    用英文逗号连接后的字符串 "drfiHgbsvomOieog,000293e2,abcdf0f1f2f3,atFY1tGDCo4MQSVCGVDqtti3PvBI5WXb"

连接建立流程

GATT交互流程

连接建立指令集

  • CMD 0x10

    手机发起开始认证流程,下发Random到设备。

    CmdType(1字节) Total Frame & Seq(1字节) Length(1字节) Payload说明(16字节)
    0x10 0x00 0x10 16字节Random数据
    说明 Total Frame & Seq字段值为0x00表示共1帧数据且当前数据为第1帧。
  • CMD 0x11

    设备认证流程,设备生成密文Cipher并发送到手机。

    CmdType(1字节) Total Frame & Seq(1字节) Length(1字节) Payload说明(16字节)
    0x11 0x00 0x10 16字节Cipher数据
  • CMD 0x12

    手机下发校验结果到设备。

    CmdType(1字节) Total Frame & Seq(1字节) Length(1字节) Payload说明(1字节)
    0x12 0x00 0x01 0x00:成功,0x01:失败
  • CMD 0x13

    设备向手机返回BLE Key处理结果。

    CmdType(1字节) Total Frame & Seq(1字节) Length(1字节) Payload说明(1字节)
    0x13 0x00 0x01 0x00:成功,0x01:失败
    说明 0x13指令Msg ID要求与0x12指令中数据一致。
  • CMD 0x14

    手机通知设备配网成功。

    CmdType(1字节) Total Frame & Seq(1字节) Length(1字节) Payload说明(1字节)
    0x14 0x00 0x01 通知设备配网/解绑结果。0x00:解绑,0x01:配网
  • CMD 0x15

    设备回复配网成功结果。

    CmdType(1字节) Total Frame & Seq(1字节) Length(1字节) Payload说明(1字节)
    0x15 0x00 0x01 配网/解绑成功ACK 0x01
    说明 0x15指令Msg ID要求与0x14指令中数据一致。

连接建立指令与Characteristic对应关系

指令类型 说明 传输使用的Characteristic Characteristics UUID
0x0F 异常通知 Indicate Characteristics 0xFED6
0x10 下发Random Write Characteristics 0xFED5
0x11 设备上报Cipher Indicate Characteristics 0xFED6
0x12 下发校验结果 Write Characteristics 0xFED5
0x13 设备返回状态 Indicate Characteristics 0xFED6
0x14 设备解绑/配网 Write Characteristics 0xFED5
0x15 回复解绑/配网结果 Indicate Characteristics 0xFED6

参考资料

  • Bluetooth4.2 Core Specification
  • Bluetooth CoreSpecification Supplement v5