# 指令简介

#简介

xAT 指令系统是由 MXCHIP 开发的，运行于 MXCHIP EMB101x系列 蓝牙BLE无线模组 中的串行指令系统。

通过该指令系统，用户可以快速地为设备增加无线蓝牙通信功能，大大缩短开发周期，实现快速上市。

#命令类型

xAT 命令有四种类型：

类型

命令格式

说明

测试命令（TEST）

AT+<命令名称>=?

查询设置命令的内部参数及其取值范围

查询命令（QUERY）

AT+<命令名称>?

返回当前参数值

设置命令（SET）

AT+<命令名称>=<…>

设置用户自定义的参数值，并运行命令

执行命令（EXE）

AT+<命令名称>

运行无用户自定义参数的命令

  1. 不是每条 AT 命令都具备上述四种类型的命令。

  2. 命令里输入参数，当前只支持字符串参数和整形数字参数。

  3. 尖括号 < >内的参数不可以省略。

  4. 方括号 [ ] 内的参数可以省略，省略时使用默认值。设置命令中，如果省略参数，则不对这些省略的参数进行设置，保持之前的数值或者默认值，例如：

    AT+BLEADVDATAEX="12345678",1, AT+BLEADVDATAEX="12345678",1,"FFF0"

  5. 当省略的参数后仍有参数要填写时，必须使用逗号以示分隔，例如：

AT+BLEADVDATAEX="12345678",,"FFF0"
  1. 使用双引号表示字符串参数，例如：
AT+BLENAME="XBT peripheral"

  1. 特殊字符需作转义处理，如 ,、"、\ 等。

    • \\：转义反斜杠。

    • \,：转义逗号，分隔参数的逗号无需转义。

    • \"：转义双引号，表示字符串参数的双引号无需转义。

    • \<any>：转义 <any>字符，即只使用 <any>字符，不使用反斜杠。

  2. 只有 AT 命令 中的特殊字符需要转义，其它地方无需转义。例如，AT 命令口打印 > 等待输入数据时，该数据不需要转义。

AT+BLENAME="\"XBT\" peripheral"
  1. AT 命令的默认波特率为 115200。
  2. 每条 AT 命令的长度不应超过 255 字节(包含 (CR-LF) )。
  3. AT 命令以新行 (CR-LF) 结束，所以串口工具应设置为“新行模式”。
  4. 使用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 */
};
  1. AT命令的命令头部（AT+命令名称）不区分大小写。参数中的字符串参数区分大小写，但如果用字符串表示16进制数，则是不区分大小写的
  2. 设备启动后，会主动发送一个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)。

#消息返回类型

从 xAT 命令端口返回的 xAT 消息有两种类型：xAT 响应（被动）和 xAT 消息报告（主动）。

#被动响应

每个输入的xAT 命令都会返回响应，告诉发送者 xAT 命令的执行结果。响应的最后一条消息必然是 OK或者ERROR。

AT 响应

说明

OK

AT 命令处理完毕，返回 OK

ERROR

AT 命令错误或执行过程中发生错误

+<Command Name>:...

详细描述 AT 命令处理结果

#主动响应

通过 xAT 消息报告，xAT 会报告系统中重要的状态变化或消息。大部分主动消息可以使用AT+SYSMSG和 AT+CIPMODE命令来进行屏蔽，

xAT 消息报告

说明

OK

系统启动后，会主动发送一次，仅此一次

>

xAT 正在等待用户输入数据

+BLECONN

Bluetooth LE 连接已建立

+BLEDISCONN

Bluetooth LE 连接已断开

+SEND_OK

AT指令模式下，串口数据接收完成，并且已经已发送到协议栈，但不代表数据已经发到对端

+SEND_FAIL

AT指令模式下，向协议栈发送数据时发生错误

+SEND_CANCELED

AT指令模式下，向协议栈发送数据已取消

+NOTIFY_ENABLED

Client已经开启监听Sever发送透传notify消息

+NOTIFY_DISABLED

Client已经停止监听Server发送透传notify消息

+WRITE,<xxx>

通过 Bluetooth LE 进行写入操作， 写入<xxx>字节

+PASSKEY_DISPLAY

生成用于配对的PASSKEY

+PASSKEY_WAIT_INPUT

等待用户输入PASSKEY

+PASSKEY_WAIT_CONFIRM

等待用户确认显示的PASSKEY是否正确

+PAIR_CANCELED

当前配对流程取消

+PAIR_CONFIRM

配对已确认

+PAIR_FAILED

配对失败

+PAIR_COMPLETE

配对完成

#工作模式切换

模组在启动后模组立即开始广播，等待 BLE Central 设备的连接，同时串口驱动直接进入预设的工作模式。

预设值可以在config.json中修改，并且烧录到Flash中的配置分区即可，详情可参考：修改默认设置 (opens new window)。

同时在AT模式下，可以使用命令进行工作模式的切换。

模组启动后的默认的广播包内容如下，可以使用AT指令灵活修改和控制。

  1. Type：0x01（BT_DATA_FLAGS）；Data：BT_LE_AD_GENERAL | BT_LE_AD_NO_BREDR

  2. 根据Transparent服务使用的UUID类型，选择对应的Type：

    • Type：0x03（BT_DATA_UUID16_ALL），Data：Transparent服务的UUID。
    • Type：0x05（BT_DATA_UUID32_ALL），Data：Transparent服务的UUID。
    • Type：0x07（BT_DATA_UUID128_ALL），Data：Transparent服务的UUID。

  3. Type：0xFF（BT_DATA_MANUFACTURER_DATA）；Data：[0x22, 0x09, 0x00, XX, XX]，其中 XX XX是模组MAC地址的最低2个字节。

  4. Type：0x09（BT_DATA_NAME_COMPLETE）；Data是"GAP名称"+"_XXXX" 其中 XX XX是模组MAC地址的最低2个字节。

Transparent 服务，Data In特性和Data Out特性的UUID可以在配置文件中修改，默认值分别是0xFE00，0xFE01和0xFF02。

串口处理数据的工作模式有以下几种：

#RAW DATA模式

Raw data模式也是常说的透传模式，即将串口数据不加修改发送到网络协议栈。

  • 模组从串口接收数据：

    串口接收数据，将收到的数据组成一个数据帧，将数据帧发送到BLE的Transparent 服务的Data Out特性。如果

  1. 设备和Central设备连接建立

  2. Data Out特性的CCCD的Notification的标志打开

    那么这些数据就可以被发送到Central 设备上。

    串口接收的数据根据以下两个条件组成数据帧，参数可以在配置文件中调整：

  3. 长度打包：收到的数据达到设定的最大长度。默认是256字节。

  4. 超时打包：在收到一个数据后，在一定时间内没有收到新的数据，则已经收到的数据进行打包。默认值是50毫秒。

  • 模组向串口发送数据：

    以下数据会发送到串口上

  1. 同样的的Central设备可以向Transparent service的Data In特性写入数据，收到的网络数据帧的负载也直接发送到串口上。
  2. 在产生事件时，会在串口上输出事件消息。该功能使用配置文件中的msg_flag进行设置。这些事件可以参考 BLE AT命令集的“主动响应”章节。

#AT模式

按照AT命令的格式解析数据（以AT开始，CR-LF结束），发送给AT子系统处理。在该模式下，自动启动AT指令的回显功能，同时也不会对串口的输入做超时处理，这样可以方便用户在终端上手动输入AT指令。

在AT模式下，可以通过AT指令修改系统对串口数据的处理方式：

  • 对模组从网络接收数据的处理，使用AT+CIPMODE命令：

    • CIPMODE=0（默认）时，收到的网络数据通过AT事件的格式输出到串口，即：+WRITE, <xxx>:<raw data>
    • CIPMODE=1时，收到的网络数据直接传输到串口，和RAW Data模式下的处理方式一致。这种模式可以成为网络数据旁路模式。

  • 对模组从串口获取数据的处理方式，使用AT+BLEGATTSNTFY命令。在串口输出>字符后，临时进入串口数据透传模式。即将串口接收的数据直接发送到网络。当接收到特定长度的数据，或者连续三个+字符后，自动退出该模式。

以下是状态切换图：

#AUTO模式（默认）

AUTO模式结合了RAW DATA模式和AT模式。对串口数据的处理方式如下：

  • 对模组从串口获取数据的处理方式：

    自动检测是否符合AT指令格式：在一个数据包中以AT开头，同时检测到CRLF，则将从AT到CRLF部分的数据提取出来，按照AT模式进行处理，否则以Raw Data模式处理。同时，由于需要在RAW DATA模式和AT模式之间切换，与单AT模式下处理的AT指令处理有一些区别：

  1. AT指令没有回显功能
  2. 检测数据包时，有和Raw Data模式下一样的超时打包机制。所以在输入AT指令时，每个字节的输入就间隔必须小于间隔时间（默认50毫秒）。再使用串口终端时，不能以单个字符一个个地输入，而是应该将一个完整的AT指令一次性输入到串口上。
  3. 输入AT指令时，应确保AT在头部。即在发送Raw data后，应至少等待50毫秒。
  • 对模组从网络接收数据的处理，将收到的网络数据直接传输到串口。串口上同样会输出AT系统的事件信息，并且可以通过AT+SYSMSG来进行配置。

#修改默认配置

xAT系统上电即可使用，如果需要修改系统默认参数，可以使用配置文件修改，并且将配置文件和固件打包在一起形成一个新的固件烧录到模组即可。而是用AT指令，则可以在模组工作时，动态的模组工作参数或者执行特定的功能。

配置文件格式是一个JSON格式的文本，跟随固件一起发布： xAT固件发布。

将应用固件和配置文件合成的方法，请参考 HyperPack工具使用。

可配置项和说明如下：

{
  "module": "MX1510",                 // 模组型号，或者直接使用芯片型号MX1510。
                                      // 通过设置模组型号，将配置文件中的引脚编号对应到所选模组上，
                                      // 模组引脚功能请参阅相应的数据手册。如不确定使用的模组型号，可以直接使用芯片型号。
  "device_name": "XAT",               // 设备默认名称,广播包中会额外增加MAC地址后两个字节作为后缀
  "conf_version": "001",              // 配置文件版本号，不要修改
  "uart": {
    "pack_mode": 2,                 // UART数据打包处理方式：0: 透传，1: AT指令，2: 自动
    "raw_packet_max_length": 256,   // 透传数据包最大长度，不得超过256字节
    "raw_packet_gap_time": 50,      // 透传数据包封包时间间隔，单位ms。即在收到一个字节后，如在设定的时间内没有收到额外数据，则将之前的数据打包处理
    "msg_flag": 5,                  // BIT0: 退出透明接收模式，打印“+QUITT”，BIT1: 打印详细事件信息，BIT2: 打印事件信息
    "uart": 1,                      // UART 端口号
    "tx_pin": 20,                   // tx 引脚编号，参考"module"所选模组或芯片
    "rx_pin": 19,                   // rx 引脚编号，参考"module"所选模组或芯片
    "cts_pin": -1,                  // cts 引脚编号，参考"module"所选模组或芯片
    "rts_pin": -1,                  // rts 引脚编号，参考"module"所选模组或芯片
    "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      
  },
  "transparent": {                    // GATT 透传服务配置
    "service_uuid": "FE00",         // 透传服务UUID，如: "1234", "12345678", "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"
    "data_out_uuid": "FE01",        // 透传数据发送属性(notify)UUID，如: "1234", "12345678", "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"
    "data_in_uuid": "FE02"          // 透传数据接收属性(write without response)UUID，如: "1234", "12345678", "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"
  }
}

#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运行脚本， 3、在Shell中运行 ./pack.sh，pack命令格式是

Usage: pack.py [-h] -c CHIP [-o OPTION] -b BINARY -C CONF [-O OUTPUT]

Options:

-h                    Print usage
-c string             Package tool name. (rtl87x2|tg7100c)
-o string             Package tool parameters
For rtl87x2，parameters：select chip module (rtl8752/rtl8762)
-b string             Input executable binary file generated by project
-C string             Input configuration file
-O string             Output directory

示例，pack脚本当前目录下的基于RTL8752芯片的免开发方案固件light.bin和产品硬件配置文件config.json合成最终的产品固件：

$ ./pack.sh -c rtl87x2 -o rtl8752 -b light.bin -C config.json -O out
go encrypt.
...
Pack Done

脚本在当前目录下生成out文件夹，包含了所有输出，其中的READ.md文件指明了各个文件的用处。

# 在本机原生环境下直接运行

1、安装python3，https://www.python.org/downloads/ (opens new window)； 2、从仓库https://code.aliyun.com/mxos/pack (opens new window)上获取完整的HyperPack脚本； 3、在脚本目录下，执行 pip3 install -r requirments.txt安装依赖项目； 4、填写适当的参数，执行pack脚本。

$ python3 pack.py --help
usage: pack.py [-h] -c CHIP [-o OPTION] -b BINARY -C CONF [-O OUTPUT]
Pack Image of MXCHIP Modules.
optional arguments:
  -h, --help            show this help message and exit
  -c CHIP, --chip CHIP  Chip
  -o OPTION, --option OPTION
                        Options of chip
  -b BINARY, --binary BINARY
                        Application Binary
  -C CONF, --conf CONF  Configuration JSON
  -O OUTPUT, --output OUTPUT
                        Output Directory

更新时间: 2023/11/29 13:52:34

← 基础指令 →