# EMB101x系列合家亲蓝牙 AT 指令
#简介
合家亲蓝牙指令系统是由 MXCHIP 开发的,运行于 MXCHIP EMB101x系列 蓝牙BLE无线模组中的串行指令系统。用户使用该指令系统可以方便地将产品通过蓝牙与中国移动开发的“合家亲”手机APP以及家庭网关实现无线通讯,快速接入中国移动的生态体系。
整个系统的框图如下:
系统中包含的设备:
- Host:产品的主控微控制器,实现产品的功能
- Module:庆科提供的实现合家亲蓝牙 AT 指令的蓝牙模组
- Controller:中国移动开发的“合家亲”手机APP或者家庭网关。
系统中实现的通讯方法和通讯协议如下
Host和Module之间使用UART进行连接,并且以 AT指令 和 专用指令 进行通讯,其中
- AT指令格式是以"AT"开头、以回车换行“\r\n”结尾的字符串,方便用户手动输入。它的指令格式参考:指令简介 (opens new window)。并且支持大部分基础指令:基础指令 (opens new window)。用户可以使用
AT+CMD?
命令来查询支持的指令列表。这些指令主要用于快速地配置模组的参数,额外包含的AT命令,参考本文的相应章节。 - 专用指令是以16进制数据进行传输,包含特定数据帧格式。这些数据帧具有易于构建和解析的特点,方便使用程序来发送和接收。主要用于在Host和Module之间传输应用层数据。专用指令的格式和功能,参考本文相应的章节。
Controller和Module之间使用BLE无线连接,并且在BLE的GATT层上“合家亲”通讯协议。“合家亲”通讯协议请联系中国移动相关机构获取。
Module为Host提供了“合家亲”接入功能,而不需要实现蓝牙和相关协议的开发。Module在系统中实现的功能如下:
- 处理部分“合家亲”协议,例如:绑定,登录等操作。这部分交互完全不需要Host端的参与。模组处理结束后,可能会给到Host一些事件通知。
- 基于“合家亲”协议的分片重组功能,将多个蓝牙协议分片合成完整的“合家亲”协议命令,并且通过UART专用指令发送给Host。同时,也可以通过UART专用指令获取Host发送的“合家亲”协议命令,将命令进行分片后,通过蓝牙发送给Controller。
#串口通信约定
- 波特率:115200
- 数据位:8
- 奇偶校验:无
- 停止位:1
- 数据流控:无
- 供电电压:BLE模组和 MCU 主控均采用 DC 3.3V
#AT指令
请使用AT+CMD?
命令来查询支持的指令列表。下文仅介绍针对“合家亲”专用的AT命令,其他命令,参考基础指令 (opens new window)和功能指令 (opens new window)中的介绍。
#AT+CMPD
查询/设置产品信息,一种型号的产品的信息都是固定的。
#查询命令
命令:
AT+CMPD?
响应:
AT+CMPD=["id"],["token"],["vendor"],["brand"],["model],["power"]
OK
#设置命令
命令:
AT+CMPD=["id"],["token"],["vendor"],["brand"],["model],["power"]
响应:
OK
#参数
<id>:中国移动后台系统上创建时生成的产品ID号,最多8个字符。
<token>:备在开发者门户注册的产品类型Token, 最多32个字符。
<vendor>:设备制造商,最多16个字符。
<brand>:设备品牌,最多16个字符。
<model>:设备型号,最多16个字符。
<power<span class=" ne-text"="" style="color: #000000>">:供电方式如电池供电:battery、POE供电:POE、市电(220V)供电:220V(110V)、USB、其他:other,最多8个字符。
#说明
id参数用于生成蓝牙设备名称,根据中国移动的定义。加入合家亲平台的蓝牙设备的名称格式是:CMB+<CMCC_ID>+(-)+<xxxx>。其中:
- xxxx: 默认为设备Mac地址的后四位(大写)
- CMCC_ID: 本命令设置的参数值id
设备名称包含在设备的广播包的Scan Response中。
#示例
AT+CMPD="590761","sRg01hpQoylKZMJJ","Vendor","Brand","Model","Power"
OK
AT+CMPD?
+CMPD:"590761","sRg01hpQoylKZMJJ","Vendor","Brand","Model","Power"
OK
#AT+CMDEV
查询/设置设备信息,每一个单独设备的设备信息都是不同的。
#查询命令
命令:
AT+CMDEV?
响应:
+CMDEV:["sn"],["cmei"]
OK
#设置命令
命令:
AT+CMDEV=["sn"],["cmei"]
响应:
OK
#参数
<sn>:设备序列号(设备唯一标识,如没有SN则会自动使用MAC地址)。最多19个字节
<cmei>:备营销稽核唯一标识。最多15个字节
#示例
AT+CMDEV="0559059076000000003","222287230000004"
OK
AT+CMDEV?
+CMDEV:"0559059076000000003","222287230000004"
OK
#AT+CMVER
查询/设置主机的软件版本
#查询命令
命令:
AT+CMVER?
响应:
+CMVER:<"ver">
OK
#设置命令
命令:
AT+CMVER=<"ver">
响应:
OK
#参数
<ver>:软件版本(含版本名称及版本编号),多个版本可以分号间隔。最多16个字节。
#示例
AT+CMVER="1.1.0"
OK
AT+CMVER?
+CMVER:"1.1.0"
OK
#通讯专用指令
#帧格式
一个完整的串口帧长度不超过128字节。
Front | Ver | Cmd | Length | Data | Check |
帧头 | 版本 | 命令字 | 数据长度 | 数据 | 校验和 |
其中:
Section | Length | Note |
Front | 2 | 固定为 0x55aa |
Ver | 1 | 串口通信协议版本,升级扩展用 |
seq | 2 | 传输数据序列号,范围 0~0xfff0,到达 0xfff0 之后重新回到 0 |
Cmd | 1 | 具体帧类型 |
Length | 2 | 传输的有效数据长度 |
Data | 取决于具体数据 | 传输的有效数据 |
Check | 1 | 数据校验,从帧头开始按字节求和得出的结果对 256 求余 |
#命令字索引
命令字 | 说明 |
0x02 | 模组网络状态上报 |
0x03 | 配置BLE模组 |
0x04 | 下发“合家亲”协议命令 |
0x06 | 上报“合家亲”协议命令 |
#串口通信模式介绍
#Module和Host之间的命令字通信模式
通常命令字采用一发一收的同步模式,即发送方发送命令,接收方应答,如下图所示。
#Module转发“合家亲”协议命令通讯模式
模组控制命令下发采用异步模式。
- Module 下发“合家亲”协议命令
- Host主动上报“合家亲”协议命令
#命令字详解
#模组报告网络状态(0x02)
网络状态是指 BLE 模组的网络状态,当模组的网络状态发生变化,则主动下发模组网络状态至 MCU。
模组发送
字段 | 字节数 | 说明 |
帧头 | 2 | 0x55aa |
版本 | 1 | 0x03 |
序列号 | 2 | N |
命令字 | 1 | 0x02 |
数据长度 | 2 | 0x0001 + 状态数据 |
数据 | 1 | 模组网络状态:
|
校验和 | 1 | 从帧头开始按字节求和,将得出的结果对 256 求余 |
示例
55aa 03 N 02 0001 01 xx:蓝牙连接成功
55aa 03 N 02 000F 02 33 36 37 36 34 34 39 38 38 32 37 30 32 30 xx:用户登录成功,用户ID是36764498827020
MCU 返回
字段 | 字节数 | 说明 |
帧头 | 2 | 0x55aa |
版本 | 1 | 0x03 |
序列号 | 2 | N |
命令字 | 1 | 0x02 |
数据长度 | 2 | 0x0000 |
数据 | 0 | 无 |
校验和 | 1 | 从帧头开始按字节求和,将得出的结果对 256 求余 |
示例
0x55aa 03 N 02 0000 xx
#配置BLE模组(0x03)
模组发送
字段 | 字节数 | 说明 |
帧头 | 2 | 0x55aa |
版本 | 1 | 0x03 |
序列号 | 2 | N |
命令字 | 1 | 0x03 |
数据长度 | 2 | 0x0001 |
数据 | 1 |
|
校验和 | 1 | 从帧头开始按字节求和,将得出的结果对 256 求余 |
示例
重启模组: 55AA 03 N 03 0001 00 XX
恢复出厂设置:55AA 03 N 03 0001 01 XX
断开当前连接:55AA 03 N 03 0001 02 XX
停止广播:55AA 03 N 03 0001 03 XX
HOST返回
字段 | 字节数 | 说明 |
帧头 | 2 | 0x55aa |
版本 | 1 | 0x03 |
序列号 | 2 | N |
命令字 | 1 | 0x02 |
数据长度 | 2 | 0x0000 |
数据 | 0 | 无 |
校验和 | 1 | 从帧头开始按字节求和,将得出的结果对 256 求余 |
示例
55AA 03 N 03 0000 xx
#下发“合家亲”协议命令(0x04)
模组发送
字段 | 字节数 | 说明 |
帧头 | 2 | 0x55aa |
版本 | 1 | 0x03 |
序列号 | 2 | N |
命令字 | 1 | 0x04 |
数据长度 | 2 | 取决于具体数据的长度 |
数据 | 取决于传输的命令 | 参考下表 |
校验和 | 1 | 从帧头开始按字节求和,将得出的结果对 256 求余 |
数据部分的格式
各个字段的实际意义请参考中国移动提供的命令文档
字段 | 字节数 | 说明 |
CommandID | 1 | 当前帧的CommandID值 |
Key | 1 | 当前帧的Key值 |
Encrypt | 1 | 0x00或0x01,当前帧是否加密 |
Timestamp | 4 | 当前帧的时间戳(大端格式) |
Data | n | 取决于具体合家亲协议命令 |
示例
55AA 03 N 04 0007 AC 01 00 65 64 3D 4F xx:下发命令AC 01 00 65 64 3D 4F 13,其中::
- CommandID(AC)表示:设备信息命令(该接口无需绑定也能调用获取信息)
- Key(0x01)获取设备信息
- Timestamp(65 64 3D 4F)表示时间戳2023-11-27 14:55:11
- Data:不含数据
#上报“合家亲”协议命令(0x06)
HOST发送
字段 | 字节数 | 说明 |
帧头 | 2 | 0x55aa |
版本 | 1 | 0x03 |
序列号 | 2 | N |
命令字 | 1 | 0x06 |
数据长度 | 2 | 取决于具体数据的长度 |
数据 | 取决于传输的命令 | 参考下表 |
校验和 | 1 | 从帧头开始按字节求和,将得出的结果对 256 求余 |
数据部分的格式
各个字段的实际意义请参考中国移动提供的命令文档
字段 | 字节数 | 说明 |
CommandID | 1 | 当前帧的CommandID值 |
Key | 1 | 当前帧的Key值 |
Encrypt | 1 | 0x00或0x01,当前帧是否加密 |
Timestamp | 4 | 当前帧的时间戳(大端格式),如果是0x0,则模组会根据模组中记录的当前时间戳填入后,再转发给Controller |
Data | n | 取决于具体合家亲协议命令 |
示例
55AA 03 N 06 00 0C C2 01 00 00 00 00 00 00 22 02 1B 58 xx:上报命令C2 01 00 00 00 00 00 00 22 02 1B 58,其中:
- CommandID(C2):设备设置指令(上行)
- Key(0x01):设置用户信息
- Timestamp(00 00 00 00):表示由Module代为填充当前的时间戳
- Data(00 22 02 1B 58):TLV格式,根据“合家亲”协议定义,0022表示体重(单位0.01kg),02表示数据段长度,1B58是0022对应的2个字节数据
#附录
#专用指令中的校验值计算
static uint16_t _get_check_sum(uint8_t *pack, uint16_t pack_len)
{
uint16_t offset;
uint8_t check_sum = 0;
for(offset = 0; offset < pack_len; offset ++){
check_sum += *pack ++;
}
return check_sum;
}