# 简介
#简介
MXMesh AT 指令系统是由 MXCHIP 开发的，运行于 MXCHIP EMB101x系列 蓝牙BLE无线模组 中的串行指令系统。用户可以通过该指令系统与蓝牙模组交互，接入到 MXMesh 网络从而获取完整的 MXMesh 端/边/云三端全面的功能。从而大大缩短开发周期，实现快速上市。
通过 MXMesh AT 指令系统, 蓝牙BLE无线模组主要完成两个大的功能：
- MXMesh 物模型的构建: 根据产品功能创建 MXMesh 属性/服务/实例。MXMesh 物模型也可以通过JSON格式的配置文件直接定义，并且通过HyperPack工具与原始固件打包生成定制固件。将这个定制固件烧录到模组后, 既可以获得一个开箱即用的模组。
- MXMesh 网络通讯: 启动MXMesh 网络，然后通过对 MXMesh 物模型实例的读写实现网络通讯功能。
一般情况下，模组启动后需要先构建物模型再启动 MXMesh 网络。物模型只需要配置一次，可以通过JSON文件进行配置实现开箱即用；启动MXMesh网络也可以设置成自动。所以最简单的情况下，只要上电后就可以进行网络通讯了。
#命令类型
MXMesh AT 命令有四种类型：
类型 | 命令格式 | 说明 |
测试命令（TEST） | AT+<命令名称>=? | 查询设置命令的内部参数及其取值范围 |
查询命令（QUERY） | AT+<命令名称>? | 返回当前参数值 |
设置命令（SET） | AT+<命令名称>=<…> | 设置用户自定义的参数值，并运行命令 |
执行命令（EXE） | AT+<命令名称> | 运行无用户自定义参数的命令 |
不是每条 AT 命令都具备上述四种类型的命令。
命令里输入参数，当前只支持字符串参数和整形数字参数。
尖括号 < >内的参数不可以省略。
方括号 [ ] 内的参数可以省略, 省略时使用默认值。设置命令中, 如果省略参数, 则不对这些省略的参数进行设置, 保持之前的数值或者默认值，例如:
AT+XMUPDATE=0,"0",1,"1",2,"4332" AT+XMUPDATE=0,"0",1,"1",2,"4332",3,"-33",4,"26.9",6,"210.45 4.45 56.7"
当省略的参数后仍有参数要填写时, 必须使用逗号以示分隔, 省略几个参数添加几个逗号. 例如：
、AT+UART_DEF=115200,,1,0,3
- 使用双引号表示字符串参数, 例如：
AT+BLENAME="XBT peripheral"
特殊字符需作转义处理，如
,、"、\等。\\：转义反斜杠。\,：转义逗号，分隔参数的逗号无需转义。\"：转义双引号，表示字符串参数的双引号无需转义。\<any>：转义<any>字符，即只使用<any>字符，不使用反斜杠。
AT 命令的默认波特率为 115200。
每条 AT 命令的长度不应超过 255 字节(包含
(CR-LF))。AT 命令以新行 (CR-LF) 结束，所以串口工具应设置为“新行模式”。
使用AT+SYSLOG可以打开错误代码显示功能。AT 命令错误代码格式:
((AT_MODULE_NUM << 24) | ((subcategory) << 16) | ((extension) & 0xFFFF))，其中AT_MODULE_NUM = 1， subcategory 如下，更多信息可以参考AT工程源代码中的at_errno.h文件。
enum {
AT_SUB_OK = 0x00, /*!< OK */
AT_SUB_COMMON_ERROR = 0x01, /*!< reserved */
AT_SUB_NO_TERMINATOR = 0x02, /*!< terminator character not found ("\r\n" expected) */
AT_SUB_NO_AT = 0x03, /*!< Starting "AT" not found (or at, At or aT entered) */
AT_SUB_PARA_LENGTH_MISMATCH = 0x04, /*!< parameter length mismatch */
AT_SUB_PARA_TYPE_MISMATCH = 0x05, /*!< parameter type mismatch */
AT_SUB_PARA_NUM_MISMATCH = 0x06, /*!< parameter number mismatch */
AT_SUB_PARA_INVALID = 0x07, /*!< the parameter is invalid */
AT_SUB_PARA_PARSE_FAIL = 0x08, /*!< parse parameter fail */
AT_SUB_UNSUPPORT_CMD = 0x09, /*!< the command is not supported */
AT_SUB_CMD_EXEC_FAIL = 0x0A, /*!< the command execution failed */
AT_SUB_CMD_PROCESSING = 0x0B, /*!< processing of previous command is in progress */
AT_SUB_CMD_OP_ERROR = 0x0C, /*!< the command operation type is error */
};
- AT命令的命令头部（AT+命令名称）不区分大小写。参数中的字符串参数区分大小写，但如果用字符串表示16进制数，则是不区分大小写的
- 设备启动后，会主动发送一个
OK\r\n
参数保存在Flash中的xAT命令
以下 AT 命令的参数更改将始终保存在 flash 的KV 区域中，因此重启后，会直接使用。
- AT+UART_DEF: AT+UART_DEF=115200,8,1,0,3
其它一些命令的参数更改是否保存到 flash 可以通过 AT+SYSSTORE 命令来配置，在默认值下，都会保存在KV区域中。具体请参见命令的详细说明。
有一些配置参数是以JSON配置文件的形式直接包含在二进制文件中，这样可以保证模组在烧录后无需配置即可使用，请参考：修改默认设置 (opens new window)。
#消息返回类型
从 AT 命令端口返回的 AT 消息有两种类型：AT 响应（被动）和 AT 消息报告（主动）。
#被动响应
每个输入的 AT 命令都会返回响应，告诉发送者 AT 命令的执行结果。响应的最后一条消息必然是 OK或者ERROR。
AT 响应 | 说明 |
OK | AT 命令处理完毕，返回 OK |
ERROR | AT 命令错误或执行过程中发生错误 |
+<Command Name>:... | 详细描述 AT 命令处理结果 |
#主动响应
通过 AT 消息报告，AT 会报告系统中重要的状态变化或消息。
AT 消息报告 | 说明 |
OK | 系统启动后，会主动发送一次，仅此一次 |
+XM_PROVED | 模组已配网，可以用保存的网络参数收发消息了。 |
+XM_PROVED_NEW | 模组首次配网成功 |
+XM_PROVING | 模组进入配网模式 |
+XM_UNPROVED | 模组配网超时。如果设备保存有之前的网络参数，模组会重启恢复网络；否则模组将关闭网络功能 |
+XM_STARTED | 设备端 MXMesh 协议栈启动完成 |
+XM_GW_FOUND | 发现网关设备 |
+XM_GW_FOUND | 丢失网关设备 |
+XM_IDENTITY | 收到Identify消息，设备应执行Identify相关的动作，便于用户识别当前控制的设备。 |
+OTA_START | 模组开始进行OTA，目前只能更新模组自身的固件 |
+OTA_STOP,<result> | OTA停止，result = 1表示OTA成功，result = 0表示OTA失败。 |
+XM_WRITE_START | 收到属性写入消息，开始产生 |
+WRITE:[<ins-idx>, <"value">,...] | 收到属性实例写入消息，消息体是由<ins-idx>, <"value">" 对构成的数组。通过AT+XMEVENT命令设置。 ins-idx：数值参数，表示属性实例编号。 value：字符串参数，表示属性写入的新值。 |
+XM_WRITE_FINISHED | 收到属性写入消息，产生 |
+XM_REBOOT,<result> | 系统重启，result表示重启原因，原因类型如下： 0: 重启以进入配网模式 1：配网超时，重启以恢复之前的网络状态 2：配网失败，重启以恢复之前的网络状态 |
#修改默认配置
模组上电即可使用，如果需要修改系统默认参数，可以使用配置文件修改，并且将配置文件和固件打包在一起形成一个新的固件烧录到模组即可。部份配置参数也可以通过 AT 指令修改，则在模组工作时，动态地调整模组工作参数或者执行特定的功能。
#配置文件格式
配置文件格式是一个JSON格式的文本，跟随固件一起发布。修改配置文件可以调整 MXMesh AT指令固件的默认设置。将固件和配置文件合成的方法，参考下一章节：HyperPack配置文件打包工具。
以下是一个配置文件的示例：
{
"manufacturer": "MXCHIP", // 厂商名称，不超过32个字符
"device_name": "xMesh Node", // 设备名称，不超过32个字符
"model": "AT_NODE", // 设备型号，不超过32个字符
"fw_code": "0000.XM00.AT", // 固件编码
"module": "MX1510", // 模组型号，可选项：EMB1016，或者直接使用芯片型号，可选项：MX1510。
// 通过设置模组型号，将配置文件中的引脚编号对应到所选模组上，
// 模组引脚功能请参阅相应的数据手册。如不确定使用的模组型号，可以直接使用芯片型号。
"conf_version": "003", // 配置文件版本号,不要修改
"uart": { // 按键产品详细配置
"uart": 1,
"tx_pin": 20,
"rx_pin": 19,
"baud_rate": 115200, // 串口数据波特率
"data_width": 3, // 0: 5bits, 1: 6bits, 2: 7bits, 3: 8bits, 4: 9bits
"parity":0, // 0: 无校验， 1: 偶校验，2: 奇校验
"stop_bits": 0, // 0: 1停止位， 1：2停止位
"flow_control": 0, // 0: 无流控制， 1: CTS， 2:RTS， 3:CTSRTS
"echo": 1 // 0: AT命令无回显，1: AT命令有回显
},
"prov": { // 配网参数配置
"timeout": 5, // 超时时间, 单位：分钟
},
"sys": { // 系统配置
"auto": 0, // 上电自动启动 xmesh 系统
},
"xmesh_database": {
"ATTS": [
// =========== OPT: BITMAP ===============
// 1: READ 可以被读取，并且读取的值是有意义的
// 2: WRITE 可以被写入设备
// 4: CORE 包含在全属性应答中
// =========== UP: ENUM ==================
// 0: NONE
// 1: TRIGGER 设备值改变后，立即通过Mesh组播发送出去，通常用于触发联动
// 2: LOGGER 通过update调用后不管属性是否改变，经过随机延时，再通过单播发送给网关
// 3: PUBLISH 设备值改变后，经过随机延时，并且再次比较属性值是否改变后，再通过组播发送出去
// 4: STATE TRIGGER 调用Update后，立即通过Mesh组播发送出去，如果设备值发生变化，会将“改变位”置位，通常用于触发状态联动
// =========== F: ENUM ==================
// 0: BOOLEAN, 1: UINT8, 2: UINT16, 3: UINT32, 4: INT8, 5: INT16, 6: INT32
// 7: UINT16_1F, 8: UINT16_2F, 9: INT16_1F, 10: INT16_2F, 11: FLOAT, 12: DATA 13: STRING 14: STRUCT 255: INVALID
{ "TYPE": "0100", "OPT": 7, "UP": 3, "F": 0 }, // On
{ "TYPE": "010A", "OPT": 3, "UP": 3, "F": 1 }, // Thermostat.wind-speed
{ "TYPE": "0116", "OPT": 3, "UP": 3, "F": 2 }, // Ambient-light
{ "TYPE": "0119", "OPT": 3, "UP": 3, "F": 4 }, // vertical-tilt.target
{ "TYPE": "010E", "OPT": 3, "UP": 3, "F": 9 }, // temperature.target
{ "TYPE": "0102", "OPT": 3, "UP": 3, "F": 13, "LEN": 16}, // name
{ "TYPE": "0160", "OPT": 3, "UP": 3, "F": [8, 8, 11] } // power
],
"SVCS": [
{ "TYPE": "FF" }
],
"CHARAS": {
"INS": [ // All mxmesh characteristics, reference to attribute index
{ "ATT": 0, "SVC": 0 },
{ "ATT": 1, "SVC": 0 },
{ "ATT": 2, "SVC": 0 },
{ "ATT": 3, "SVC": 0 },
{ "ATT": 4, "SVC": 0 },
{ "ATT": 5, "SVC": 0 },
{ "ATT": 6, "SVC": 0 },
],
"PRI": 0 // characteristics instance index start from 0, in "instance" array
}
}
}
#JSON配置文件
Property | Key | JSON Type | Description |
厂商名称 | "manufacturer" | string | 厂商名称，存储在 MXMesh 属性数据库中 |
设备名称 | "device_name" | string | 设备名称，存储在 MXMesh 属性数据库中，并且显示在 MXMesh 配网广播包中 |
型号 | "model" | string | 设备型号，存储在 MXMesh 属性数据库中 |
固件编号 | "fw_code" | string | 固件编号，用于产测信息的输出，是MXCHIP生产模组时检测固件的依据 |
模组 | "module" | string | 模组型号，也可以直接选用芯片：MX1510 |
串口 | "uart" | object | AT串口默认参数，参考：AT串口默认参数 |
配网参数 | "prov" | object | 配网参数，参考：配网参数 |
系统参数 | "sys" | object | 系统参数，参考：系统参数 |
属性数据库 | "xmesh_database" | object | MXMesh属性数据库，参考：属性数据库 |
#AT串口默认参数
Property | Key | JSON Type | Description |
端口 | "uart" | number | 芯片的串口端口号 |
发送引脚 | "tx_pin" | number | MX1510芯片/模组的串口发送引脚编号 |
接收引脚 | "rx_pin" | number | MX1510芯片/模组的串口接收引脚编号 |
波特率 | "baud_rate" | number | 串口波特率 |
数据位宽度 | "data_width" | number | 0: 5bits, 1: 6bits, 2: 7bits, 3: 8bits, 4: 9bits |
奇偶校验位 | "parity" | number | 0: 无校验， 1: 偶校验，2: 奇校验 |
停止位宽度 | "stop_bits" | number | 0: 1停止位， 1：2停止位 |
串口流控制 | "flow_control" | number | 0: 无流控制， 1: CTS， 2:RTS， 3:CTSRTS |
#配网参数
Property | Key | JSON Type | Description |
配置时间 | "timeout" | number | 配网时间, 单位：分钟 |
#系统参数
Property | Key | JSON Type | Description |
自动启动 | "auto" | number | 0: 不自动启动， 1: 自动启动。启动前要确保属性数据库配置正常。 |
#属性数据库
Property | Key | JSON Type | Description |
属性列表 | "ATTS" | array | 数组，元素是属性对象，不能为空。属性对象参考：属性 |
服务列表 | "SVCS" | array | 数组，元素是服务对象，不能为空。属性对象参考：服务 |
实例描述 | "CHARAS" | object | 实例描述，参考：实例描述 |
#属性
Property | Key | JSON Type | Description |
类型 | "TYPE" | string | 属性编号 |
功能选项 | "OPT" | number | 功能选项，数字的各个BIT位表示不同的功能，功能可以多选。 BIT(0): 属性可以被读取。 BIT(1): 属性可以被写入。 BIT(2)：核心属性，读取属性时，如果不包含读取的属性类型，则在应答时用核心属性作为读取的应答。 |
自动上报 | "UP" | number | 通过AT指令更新(AT+XMUPDATE指令)属性值时，模组自动将新值发送到组播地址（D003）或者网关地址的行为定义： 0: NONE，关闭更新后自动发送属性的功能。 1: TRIGGER，立即发送到组播地址（D003），通常用于触发联动，并且更新相同的值后，可以连续触发联动。 2: LOGGER，不管属性是否改变，经过随机延时，再通过单播发送给网关。如果网关不存在，就不发送。 3: PUBLISH，经过随机延时，并且再次比较属性值是否改变后，再发送到组播地址。 4: STATE TRIGGER，如果设备值改变，立即发送到组播地址。因此和TRIGGER相比，不能连续触发相同的联动。 |
数据类型 | "F" | number | 属性数据类型，可以是以下类型的一种。数据类型定义参考 MXMesh协议。 0: BOOLEAN, 1: UINT8, 2: UINT16, 3: UINT32, 4: INT8, 5: INT16, 6: INT32 7: UINT16_1F, 8: UINT16_2F, 9: INT16_1F, 10: INT16_2F, 11: FLOAT, 12: DATA 13: STRING |
array | 由多个属性数据组成的结构体类型的属性，可以是以下类型的一种。数据类型定义参考 MXMesh协议。 0: BOOLEAN, 1: UINT8, 2: UINT16, 3: UINT32, 4: INT8, 5: INT16, 6: INT32 7: UINT16_1F, 8: UINT16_2F, 9: INT16_1F, 10: INT16_2F, 11: FLOAT, 1 | ||
数据长度 | "LEN" | number | 属性数据长度，通常数据长度由属性数据类型定义，除了以下两种情况：
|
#服务
Property | Key | JSON Type | Description |
类型 | "TYPE" | string | 服务编号 |
#实例描述
Property | Key | JSON Type | Description |
实例列表 | "INS" | array | 元素是实例对象，不能为空。实例对象参考：实例 |
主属性 | "PRI" | number | 选作为主属性的实例编号，实例编号必须位于实例列表数组范围内。 |
#实例
Property | Key | JSON Type | Description |
属性 | "ATT" | number | 属性编号，当前实例使用当前属性。属性编号必须位于属性列表数组范围内。 |
服务 | "SVC" | number | 服务编号，该服务包含当前实例。服务编号必须位于服务列表数组范围内。 |
#HyperPack 配置文件打包工具
使用庆科开发的 HyperPack工具，可以将免开发标准固件配置成适合最终产品硬件平台的标准固件。
即：产品固件 = HyperPack(标准固件，产品配置文件)。
其中标准固件从 固件发布 中获取。
#安装和使用 HyperPack
HyperPack是一套基于Python的打包工具，可以使用下面两种方式来运行它：
- 使用Docker，运行预生成的HyperPack运行环境镜像（推荐）
- 在本机安装Python环境和HyperPack的依赖项，运行HyperPack脚本
#在Docker容器下运行（推荐）
1、安装Docker，https://www.docker.com/products/docker-desktop (opens new window) 2、获取HyperPack docker运行脚本，📎pack.sh 3、在Shell中运行 ./pack.sh，pack命令格式是
Note：pack.sh脚本运行在linux上，如果在windows上运行，可以参考pack.sh脚本中的方法调用docker镜像完成打包。
Usage: pack.py [-h] -c CHIP [-o OPTION] -b BINARY -C CONF [-O OUTPUT]
Options:
-h Print usage
-c string Package tool name. (rtl87x2|bl602|mx1510)
-o string Package tool Options
For rtl87x2, parameters: select chip module (rtl8752/rtl8762)
For bl602, parameters: select module (emc3025)
-b string Input executable binary file generated by project
-C string Input configuration file
-O string Output directory
示例：运行pack脚本将标准MXMesh AT固件 xxx.bin（注意不是xxx.all.bin或者xxx.ota.bin）和配置文件 config.json 合成最终的产品固件：
$ ./pack.sh -c mx1510 -b xxx.bin -C config.json -O out
go encrypt.
...
Pack Done
脚本在当前目录下生成out文件夹，包含了所有输出。