概述

本节描述AT命令的模式,使用场景,使用方法等相关信息。

AT命令的模式

当前支持的AT命令模式分为两种： 手动测试模式 与 主控控制模式，分别适合不同的场景。

  • 适用场景：单命令调试, 功能评估验证, 快速测试

  • 典型应用：开发人员通过串口工具发送AT命令进行wifi的连线和吞吐量测试，蓝牙配对测试等

软件环境准备

准备工作

强烈建议先学习了解如下章节：

AT固件编译

参考 配置 SDK (menuconfig) 进入 CONFIG AT CMD 配置，选择 Manual Test Mode 并且勾选需要使能的相关AT命令功能模块

参考 编译代码 进行固件编译

备注

如需使能AT命令中的蓝牙命令功能模块，需要在Menuconfig主页面 CONFIG BT 中打开蓝牙功能。

备注

如需更高的wifi吞吐量，需要在Menuconfig主页面 CONFIG WIFI 中打开 Enable HIGH TP 选项。

AT配置修改

主控控制模式下，可以在不修改更新应用固件的情况下，直接通过配置文件 atcmd_config.json 来修改外设接口以及其对应的管脚等信息。

  • 在SDK中找到 atcmd_config.json 文件，根据需要来修改该文件中的对应栏位

  • 将 atcmd_config.json 文件提前预置到LittleFS虚拟文件系统（VFS）的根目录下，并且制作VFS固件（参考 提前预置示例 ）

  • 将VFS固件烧录到Ameba开发板对应的flash的VFS1区域 （参考）

  • 重启模组，上电后会在LogUART输出AT命令初始化相关信息

[AT-I] ATCMD Host Control Mode : SPI, mosi:PA_27, miso:PA_28, clk:PA_26,cs:PA_12, master_sync_pin:PB_30, slave_sync_pin:PB_31

备注

外设接口支持UART/SPI/SDIO, 相关对应的管脚请参考规格书以及硬件资料文档。

如果未预置 atcmd_config.json 文件，将使用UART的默认配置,默认的波特率和管脚如下：

  • 波特率：38400

  • UART_TX管脚： PA_26

  • UART_RX管脚： PA_27

AT安全证书

一些AT功能组件可能需要使用安全证书，比如连接Wifi企业级路由器，HTTPS，WebSocket服务器功能等。

安全证书套件分为客户端证书套件和服务器证书套件，均包含CA证书，证书和秘钥，证书的格式是crt，秘钥格式是key。

安全证书套件的序号范围是1-10。

AT命令在需要使用安全证书时，会以 <cert_index> 的可选参数作为序号从文件系统 /CERT/ 目录中查找和使用对应的安全证书套件。

安全证书套件存放于LittleFS的虚拟文件系统上的固定路径 /CERT/ 下， 如何提前预置安全证书请参考 提前预置示例。

备注

安全证书套件可以根据需要只提供部分文件，比如HTTPS的client单向认证只会使用CA证书进行认证服务器合法性，只需要在文件系统提前预置对应序号的客户端CA证书即可。

分类

安全证书套件

相关AT命令

客户端

安全证书套件1 文件名：

  • client_ca_1.crt

  • client_cert_1.crt

  • client_key_1.key

安全证书套件2 文件名：

  • client_ca_2.crt

  • client_cert_2.crt

  • client_key_2.key

…

  • AT+HTTPGET

  • AT+HTTPPOST

  • AT+HTTPPUT

  • AT+HTTPDEL

  • AT+MQTTCONN

  • AT+SKTCLIENT

  • AT+WSCONN

服务器

安全证书套件1 文件名：

  • server_ca_1.crt

  • server_cert_1.crt

  • server_key_1.key

安全证书套件2 文件名：

  • server_ca_2.crt

  • server_cert_2.crt

  • server_key_2.key

…

  • AT+SKTSERVE

  • AT+WSSRVSTART

提前预置示例

本节演示如何提前预置 atcmd_config.json 和安全证书文件和 AT+FS 命令使用的test.txt文件，以及如何使用：

  1. 创建 vfs_dir 目录和 CERT 子目录：

    mkdir vfs_dir
mkdir vfs_dir/CERT
mkdir vfs_dir/AT

  2. 将 atcmd_config.json 文件复制到 vfs_dir 目录：

    cp atcmd_config.json vfs_dir/

  3. 将安全证书文件复制到 CERT 子目录：

    cp client_ca_1.crt client_cert_1.crt client_key_1.key server_ca_1.crt vfs_dir/CERT/

  4. 将test.txt文件复制到 AT 子目录：

    cp test.txt vfs_dir/AT/

  5. 使用 vfs.py 生成 LittleFS 文件系统固件（参考：VFS 二进制文件生成）：

    ./vfs.py -t LITTLEFS -dir vfs_dir -out vfs.bin

    输出示例：

    vfs.bin has been successfully generated.
block_size: 4096, block_count: 32, image_size: 131072, source_directory: vfs_dir, output_image: vfs.bin

  6. 根据 Flash 布局，将生成的 vfs.bin 文件烧录到 AT 模块 Flash 的 VFS1 区域（参考：Flash中的VFS）。

  7. 烧录boot和app固件（参考：Image Tool）。

  8. Ameba 开发板上电后，如果在 LOGUART 端口观察到自定义配置的打印输出，则表明配置已生效。例如：

    [AT-I] ATCMD HOST Control Mode : UART, tx:PA26, rx:PA27, baudrate:115200

  9. 使用以下命令输出 1 号客户端安全证书套件和 1 号服务器安全证书套件：

    AT+CERT=0,1
AT+CERT=1,1

  10. 使用以下命令输出test.txt文件前10个字节内容：

AT+FS=3,test.txt,0,10

硬件环境准备

所需材料：

  • Ameba开发板

  • 电脑： 用于烧录固件， 输入AT命令，观察AT命令的响应

  • Type-C USB连接线

操作步骤：

  • 用USB连接线连接Ameba开发板的LogUART端口和电脑的USB端口

  • 烧录固件

  • 用串口工具(如 Trace Tool)按照1.5M波特率打开对应的串口端口

  • 上电或者重启Ameba开发板

  • 串口工具看到``ATCMD READY``消息即可开始收发AT命令

../../_images/manual_test_mode.svg

在主控控制模式下，用户需要提前准备 atcmd_config.json 文件（参考 AT配置修改）。

命令描述

命令格式

一条完整的AT命令的格式以两个大写字母 AT （Attention的缩写）开头，称为起始字符；后接一个 + 号；之后是命令名称。如果有多个参数，则在命令名称后接一个 =，再接参数列表，最后是结束符ASCII码 CR-LF 。

示例

AT+COMMAND=parameter1,parameter2

在这个示例中：

  • AT：起始字符，表示当前字符串可以被识别为AT命令

  • +：用于分隔起始字符和后续命令

  • COMMAND：具体的命令名称，需要立即执行

  • 参数： parameter1 和 parameter2

某些情况下，在AT命令中可以省略某些参数，此时参数之间应输入一个或多个逗号。

示例

AT+COMMAND=parameter1, ,parameter3

在这个AT命令中，两个逗号之间存在一个被省略的 parameter2，此时使用默认值。

命令参数

AT命令的参数列表遵循以下约定：

  • 尖括号< >表示 必选 参数

  • 方括号[ ]表示 可选 参数

  • 不同的参数之间用逗号分隔

示例

AT+COMMAND=<param1>[,<param2>,<param3>]

在这个AT命令中，第一个参数 param1 是必须的，第二个参数 param2 和第三个参数 param3 是可选的。

转义字符

在某些AT命令中，如果确实需要将逗号作为参数的一部分，建议使用转义字符 \,。反斜杠本身用转义字符表示为 \\。 对于其他不需要使用转义字符的AT命令，逗号通常被视为分隔符，单个反斜杠可作为普通字符使用。

示例

AT+COMMAND=parameter1,head\,tail,head\\tail

在这个AT命令中，总共有三个参数：

  • 第一个参数 parameter1。

  • 第二个参数 head,tail 是一个包含逗号的字符串。其中的逗号被反斜杠转义（ \, ），因此不会被解析为参数分隔符，而是字符串的一部分。

  • 第三个参数 head\\tail 是一个包含反斜杠的字符串。单个反斜杠（如 \ ）是非法的，必须使用双反斜杠（ \\ ）表示字面意义上的单个反斜杠。

命令长度

每个AT命令包含 AT 开头和 CR-LF 结束符，必须不超过指定的长度限制，否则，多余的部分将被忽略。

  • 手动测试模式 的长度限制为127字节。

  • 主控控制模式 的长度限制为2000字节。

在使用转义字符的AT命令中，转义字符（如 \, 或 \\）应被视为占用2个字节。

命令响应

  • 在接收到AT命令后，从机首先判断其是否为有效命令。如果被视为无效命令（不在AT命令集内），将显示 unknown command COMMAND。否则，将根据输入的命令及参数执行相应操作。

  • 当命令执行期间，可能会有各类信息输出。

  • 当命令执行成功时，通常最后会输出 OK 。

  • 当命令执行失败时，通常最后会输出 ERROR ，并附加一个错误代码。

备注

每个AT命令都有其对应的错误代码编号和意义,具体请参考各AT命令的介绍说明。

AT消息

在非AT命令执行期间，也可能有主动的AT消息，比如wifi连接被路由器主动断开，Websocket client长连接突然接收到服务器发送的消息。

这些AT消息会在消息会在消息开头增加 [$] 作为提示，以供主控应用程序解析判断。

下表列出了所有的主动AT消息

主动AT消息列表

模块

AT消息

说明

AT

[$][TT]: High Watermark

TT模式高水线提示

[$][TT]: Low Watermark

TT模式低水线提示

Wi-Fi

[$]wifi connected

wifi连接路由器成功

[$]wifi connect failed

wifi连接路由器失败

[$]wifi got ip:<ip>

wifi申请IP地址成功

[$]wifi got ip timeout

wifi申请IP地址超时

[$]wifi disconnected

wifi被路由器主动断开

[$]wifi reconnecting

wifi自动重连开始

[$]wifi reconnect done

wifi自动重连完成

[$]client connected:<sta_mac>

wifi热点模式有sta连接成功

[$]client disconnected:<sta_mac>

wifi热点模式有sta主动断开

[$]assign client ip:<sta_ip>, hwaddr:<sta_mac>

wifi热点模式分配IP地址

Socket

（待添加）

（待添加）

MQTT

[$][MQTT][EVENT]:linkid:<link_id>, connected

MQTT连接成功

[$][MQTT][EVENT]:linkid:<link_id>, ERROR:<err_no>

MQTT异常事件

[$][MQTT][EVENT]:linkid:<link_id>, subscribed

MQTT订阅成功

[$][MQTT][EVENT]:linkid:<link_id>, unsubscribed

MQTT取消订阅成功

[$][MQTT][EVENT]:linkid:<link_id>, published

MQTT发布成功

[$][MQTT][DATA][<link_id>][<topic>] [<消息ID>][<消息长度>]:<消息>

MQTT收到消息

Websocket

[$][WS][EVENT]:linkid:<link_id>, connected

Websocket连接成功

[$][WS][EVENT]:linkid:<link_id>, disconnect

Websocket连接断开

[$][WS][EVENT]:linkid:%d, pong

Websocket收到PONG包

[$][WS][DATA][<link_id>][<数据长度>]: <数据>

Websocket收到数据

[$][WSSRV][EVENT]:linkid:<link_id>, connected

Websocket服务器连接成功

[$][WSSRV][EVENT]:linkid:<link_id>, disconnected, reason:<断开原因>

Websocket服务器连接断开

[$][WSSRV][DATA][<link_id>][<opcode>] [<数据长度>]: <数据>

Websocket服务器收到数据

透传（TT）模式

部分AT命令执行后会进入透传（TT）模式，用于主控端进行超大数据量或高性能传输。典型场景包括通过HTTP POST上传大文件或通过Websocket客户端发送二进制数据。

进入指示：

  • 成功进入透传模式时会输出 >>> 消息

数据处理规则：

  • , , \ 等无需转义，所有数据可直接发送

  • 可包含ASCII CR-LF 字符，透传模式下不会被识别为AT命令终止符

  • 数据长度由对应AT命令参数指定，未明确时长度不受限制

缓冲区管理：

  • 数据量 <120KB：支持完整缓存，主控可以持续不停的发送

  • 数据量 ≥120KB：无法全部缓存，主控需要根据下列AT消息来控制发送

    • 防溢出机制：

      • [$][TT]: High Watermark 消息提示主控需要暂停发送

      • [$][TT]: Low Watermark 消息提示主控可以恢复发送

退出条件：

  • 收到指定长度数据后自动退出透传模式并返回命令执行结果

备注

透传模式仅在 主控控制模式 下生效，因此涉及透传模式的AT命令仅支持在 主控控制模式 中使用。

AT命令列表

以下是目前支持的AT命令集：

请参考以上章节获取不同AT命令的详细信息。

AT命令版本

用户可以通过执行 AT+GMR 命令查询当前固件的AT命令版本信息。

版本号采用语义化版本系统，其格式如下：

<major>.<minor>.<patch>

参数说明：

<major> : 主版本号，代表重大更新，通常包括对于新芯片的支持、新功能的引入等

<minor> : 次版本号，代表重要更新，通常包括新命令的添加、bug修复等

<patch> : 修订版本号，表示修复了一些问题，但没有新增任何功能

示例

命令：

AT+GMR

响应：

AT+GMR
AMEBA-RTOS SDK VERSION: 1.1.0
ATCMD VERSION: 2.2.0
amebasmart: e1ffe0ff2504cc5383c030d6ffffff28
COMPILE TIME: 2025-03-03 16:48:37
COMPILE USER: user@linux
COMPILE ENV : arm-none-eabi-gcc

OK