# 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;
}