微信蓝牙外设协议104pdf

微信蓝牙外设协议Project BlueShadow

V1.0.4

Tencent Confidential

文档变更日志

目录

概要 (5)

整体架构 (5)

主要功能 (5)

蓝牙BLE模拟成流 (6)

协议 (7)

1前提 (7)

2设备和广播 (8)

3绑定 (9)

扫码绑定 (9)

厂商服务器绑定 (9)

4扫描和连接 (10)

5 流 (10)

6 包 (10)

7 包结构 (11)

8 定长包头 (11)

9 变长包体 (12)

10加密的身份验证 (13)

11 不加密的身份验证 (15)

12 会话约定 (16)

13 时序 (17)

14 Read Characteristics (17)

15 其他 (17)

微信的Protobuf协议 (17)

1 概述 (17)

2 命令列表 (18)

3 错误码 (19)

4 JSAPI (20)

概述 (20)

用户场景 (21)

接口 (21)

附录 (22)

1 ProtoBuf协议介绍 (22)

2 蓝牙硬件一些规定 (22)

3 Ios BLE设备的截图 (23)

4 包的二进制例子 (25)

5 包的数据流图 (26)

6 包的时序图 (27)

7 加解密字段 (28)

8 Md5DeviceTypeAndDeviceId的例子 (29)

9 CBC例子 (30)

10 CRC32例子 (31)

11 微信蓝牙外设proto文件 (31)

12 微信公众平台proto文件 (36)

概要

该文档规范了蓝牙设备和手机上的微信的通信协议

协议支持经典蓝牙和4.0 BLE蓝牙，目前支持ios和andriod两个系统，后续会扩展到其他系统。

整体架构

厂商服务器和外设，由厂商开发完成。

微信会提供服务器的接口以对接厂商的服务器，会提供手机的接口（如本文规定的蓝牙协议）以对接厂商的外设。

主要功能

该协议打通了设备和厂商服务器之间的数据链路，也就是支持将设备上的数据发送到厂商的

服务器上，也支持将厂商的数据发送到设备。

厂商的数据对于微信来说，是黑盒，微信不对设备数据做分析。

该协议也打通了设备和微信服务器之间的数据链路。

设备和微信服务器之间的数据格式由微信规定，例如登录，新消息通知等。

蓝牙BLE模拟成流

微信支持蓝牙BLE。

微信规定了蓝牙BLE设备需要先模拟成流(即stream，输入输出流)。经典蓝牙的RFCOMM，就是一个流。流具有的特性有：

a.可以传输无限长度的数据

b.双工，读写可以并发，互不干扰。

显然，蓝牙BLE无法传输无限长度的数据，为了实现这个目的，需要定义一个规范。

蓝牙设备需暴露两个特征值（Characteristics）：Write特征值，Indication特征值。蓝牙设备从Write特征值接受数据，从Indication特征值发送数据。

Indication特征值类型是bytes。

这里我们约定，把一个特征值一次传输的数据，称为一帧（不同类型的特征值一次传输的数据长度是不一样的）。

注意：应用层上的数据包（例如1k大小），会分散成许多帧来传输。

蓝牙设备写过程：

1.分帧：假设蓝牙手环上有1k数据，要发给手机微信。由于一个特征值长度有限（如

20个字节），显然需要分多次才能传输完成。1k数据，要分成1024字节/ 20字节=51 个帧。剩下的4个字节，不足一帧（20个字节），需补齐为一帧并对剩下的16个字节赋0。总共是52帧。

2.发送第一个帧：把第一个帧的内容放入特征值里面。然后通知手机读取数据，通知

有两种方式，Indication 和notify，这里使用Indication方式，即带响应的通知。

当通知完成的时候，可以认为手机已经读完数据。这就完成了发送第一个帧。

3.按照2的步骤，依次发送剩下的帧。

蓝牙设备读过程：

当蓝牙设备发现读特征值收到数据的时候，就接收数据，并追加到设备的buf里。

注意：蓝牙设备必须等微信app订阅了Characteristics之后，才能indicate数据，否者会造成设备发送数据丢失的问题。

协议

1前提

厂商需先开通微信公众平台的硬件号功能。

厂商需先在公众平台上注册设备（具体api见服务器端的微信公众平台的硬件功能文档）。

2设备和广播

为了和微信能够通信，设备的广播包需符合以下的格式：

低功耗蓝牙（android&ios）设备需要广播：

a.微信规定的service uuid（具体见附录）。

b.厂商自定义字段里，包含MAC地址（具体见附录）。

c.包含指定的Characteristics（具体见附录）。

Andriod经典蓝牙设备需要广播：

a.暴露一个指定uuid的rfcomm服务（具体见附录）。

b.厂商自定义字段里，包含MAC地址（具体见附录）。

Ios经典蓝牙需要通过mfi认证，并且SerialNumber需为MAC地址（字符串形式）。

设备可分为两种：

可确认设备：如有按钮，或者可以双击，或者有可检测翻转等传感器，可与人交互

的设备。大部分设备属于可确认设备。

无法确认的设备：即没有按钮等传感器，无法与人交互的设备。这种设备很少。

目前的市面上设备，有很多是要设备做出确认之后（如长按某个按钮，或者靠近手机），才会进行设备和用户的绑定。

相应的，广播包有两种：

普通包：我们把设备正常情况下无时无刻广播的包成称为普通包

确认包：当用户进行设备确认时（如双击手环，或者按按钮），广播的特殊的包称

为确认包。微信规定了微信认识的普通包和确认包的格式：通过manufature data

来区别（具体见附录）。

3绑定

用户绑定设备有两种方式：扫码绑定，厂商服务器绑定

这两种方式都需要先向微信公众平台注册授权设备（具体api参见公众平台文档）。

扫码绑定

用户通过扫描设备二维码绑定设备（获取二维码的方法见公众平台文档）。

用户场景：用户打开扫一扫界面，扫码设备二维码，出现公众号页面。用户点击关注，进行绑定设备。

扫码绑定并不需要设备在身边。

厂商服务器绑定

厂商可通过微信公众平台提供的接口，绑定厂商指定的用户和设备。

该功能给厂商比较大的自由，可自定义绑定的流程和界面（通过html5）。

该功能目前需要通过本协议的jsapi来实现。

绑定的用户场景和技术细节详见本文档jsapi一章。

4扫描和连接

进入特定界面后(如具有硬件功能的公众号界面)，微信会开始扫描设备。当设备广播符合微信定义的广播包时，则微信可以扫描到设备。

扫描到设备后，微信会连接设备（Ios经典蓝牙需要用户手动在设置界面里面连接上设备）。

当连上设备之后，微信和设备之间开始传输数据。数据的具体格式见下面章节。

5 流

经典蓝牙使用RFCOMM通信（是个流），蓝牙BLE也模拟成流。

6 包

流之上运载的是一个紧接着一个的业务逻辑的数据包。

数据包的发送方和接受方：设备<->厂商服务器，或者设备<->微信服务器。

把设备->厂商服务器/微信服务器的请求称为Req，回包称为Resp。一个请求，对应着一个回包。

把厂商服务器/微信服务器->设备的请求称为PushReq，没有回包（即没有PushResp

这样的包）。

7 包结构

由定长包头和变长包体组成。

包的二进制例子见附录。

8 定长包头

9 变长包体

为Protobuf（protobuf的介绍见附录）打包的结构。例如AuthReq。

一个包体里面只有一个Req，或者一个Resp，或者一个PushReq。

每个Req/Resp/PushReq都有对应的EmCmdId，例如AuthReq的命令号为ECI_req_auth。

具体的定义见附录。

10加密的身份验证

微信支持身份验证和加密，以使得厂商的数据更加安全。

加密算法选用aes 128位，并使用cbc模式，pkcs7填充。初始向量为密钥。

具体验证和加密的步骤如下：

a.设备需要烧一个Key（128位）到硬件上，微信服务器也要记录下这个Key。一个

设备（deiveId+deviceType唯一确定一个设备），对应一个Key。

key要保护好（类似用户密码，银行卡账号密码），千万不要印刷出来或者打印出来。

另外有一个MD5(deviceType+deviceId)，如果设备算MD5很麻烦的话，建议先算好，直接烧进设备里面。该MD5类似于用户名。

b.对于设备来说，手机和服务器可看成一个黑盒。设备和手机服务器之间，通过Auth

命令，使用key，最终，把sessionKey下发给到设备。

Auth的步骤为：

设备发送AuthReq，里面的字段有MD5(deviceType+deviceId)，另一个字段为AES加密的一段buffer（具体字段细节在附录描叙）。

微信发送回包AuthResp，里面的字段有用AES加密的含有sessionkey的一段buffer（具体字段细节在附录描叙）。设备解密这段buffer可得到SessionKey。

c.设备和手机之间，就通过sessionKey来加解密包。

AuthReq，AuthResp之后的所有命令，例如InitReq, InitResponse，SendDataRequest，SendDataResponse，RecvDataPush等都需要加解密。

d.加密只针对变长包体，不需要加密定长包头。

e.为了提高安全性，设备可再进一步的验证手机是否可信。

设备在InitReq里填入Challeange（一个4字节的随机数random4），手机将在InitResp里面返回ChalleangeAnswer（一个4字节的数，值为crc32(random4)）。

设备验证ChalleangeAnswer是否正确。如果是，说明手机是可信的。

身份验证和加解密大体的流程图为：

另外有一些细节：

a.当sessionKey过期，手机对设备的所有请求都返回错误码EEC_sessionTimeout，要

求设备重做一次auth。

b.当发现解密设备的包失败时，返回EEC_decode。这种情况下，通常是sessionkey过

期，或者是设备程序有问题。

11 不加密的身份验证

微信客户端同时支持不加密的方式，以降低设备厂商的接入难度，加快开发产品的进程。

不加密的方式下，设备和微信之间的通信的安全级别，将与设备和系统原生的蓝牙api 之间的通信的安全级别一样。为了确保厂商设备和服务器的数据安全，厂商需自行实现安全机制。

不加密有两种方式：

1.MD5认证：使用MD5(deviceType+deviceId)和微信认证，如果设备算MD5

很麻烦的话，建议先算好，直接烧进设备里面。该MD5类似于用户名。这种

方法要求产线上对不同的设备需要烧写不同的MD5。

2.MAC地址认证：使用MAC地址和微信认证。Mac地址类似于用户名。这种

方法不需要产线上对设备烧写额外的东西（MAC地址在原来的产线上本来就是

要烧进设备的）。该方法减低了产线的难度，但安全性不如MD5认证。

步骤如下：

将AuthReq里的AesSign字段付空。

如果是用MD5登录，则赋值Md5DeviceTypeAndDeviceId字段，且AuthMethod= EAM_md5，如果是MAC地址登录，则赋值MacAddress字段，且AuthMethod=EAM_macNoEncrypt。

发送AuthReq。

收到AuthResp之后，忽略掉AesSessionKey字段。

将InitReq里的Challeange字段随便付一个值。发送InitReq。

收到InitResp，忽略掉ChalleangeAnswer字段。

随后的包都不需要加解密。

12 会话约定

a.设备连上微信之后，需要发送AuthReq，等收到成功的回包之后，接着还要发送

InitReq，并收到成功的回包之后，才能正常发送数据。如果设备没有auth，手机对设备的所有请求都返回错误码EEC_needAuth。

b.当出现解包异常的时候，直接断开连接。

c.Push类的包seq永远为0。Req类和Resp类的包的seq永不为0。

d.服务器可随时发送Push包。

e.厂商服务器发送的Push包（注意Push包是没有回包的，即没有PushResp），如

果需要设备的回包，需要由厂商自己实现。

具体方法如：厂商发送RecvDataPush给设备，设备收到push后，向厂商服务器发送一个SendDataRequest。这时厂商服务器可知道设备收到了push，并且可以从Req里取得设备的回应数据。

13 时序

时序图请见附录。

14 Read Characteristics

为了支持同一手机上一个app连接了设备后，微信还能搜素并连接到设备的情况，设备需要在微信的service下面，暴露一个read character，内容为6字节的MAC地址。

当ios上的其他app连接上设备时，设备不会再广播，微信会读取该特征值，以确定是否要连接该设备。

15 其他

目前规定了一些基础的协议，更多的协议等待补充。

微信的Protobuf协议

1 概述

变长包体部分，使用的是Protobuf定义的协议。Protobuf文件见附录。

里面规定了设备和微信客户端之间的命令。

2 命令列表

3 错误码Proto里的错误码