概述

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

如下图所示，Ameba 通过 UART/SPI/SDIO 等接口和主机 MCU 连接，主机 MCU 通过 AT 指令控制网络设备和传输网络数据。

../_images/at_command_4solutions.svg

AT 命令模式

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

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

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

软件环境准备

准备工作

强烈建议先学习以下章节：

AT 固件编译

  1. Menuconfig 进入 CONFIG AT CMD 配置，选择 Manual Test Mode，且勾选需要使能的 AT 命令功能模块

  2. 编译固件

备注

  • 如需使能 AT 命令中的蓝牙传输命令功能模块，需要在 Menuconfig 主页面 CONFIG BT 中打开蓝牙功能，再勾选 BLE Transfer Module 打开传输模块。

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

AT 配置修改

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

  1. 在 SDK 中找到 atcmd_config.json 文件，据需修改文件中的对应栏位

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

  3. 将 VFS 固件烧录到 Ameba 开发板对应的 Flash 的 VFS1 区域

  4. 重启模组，上电后会在 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/USB，对应的引脚请参考规格书和硬件资料文档。

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

    • 波特率：38400

    • UART_TX 管脚：PA_31

    • UART_RX 管脚：PA_30

  • UART 默认配置未启用 RTS/CTS 引脚，需硬件流控时在 atcmd_config.json 中配置对应引脚。

  • 使用 UART 执行 OTA 命令时必须启用硬件流控功能。

AT 安全证书

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

安全证书套件分为客户端证书套件和服务器证书套件，均包含 CA 证书、证书和秘钥。证书的格式是 crt，秘钥的格式是 key。安全证书套件的序号范围是 1~10。

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

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

备注

安全证书套件可以根据需要只提供部分文件。比如 HTTPS 的客户端单向认证只会使用 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 子目录

    cd {SDK}/tools/image_scripts
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 vfs_dir/CERT/
cp client_cert_1.crt vfs_dir/CERT/
cp client_key_1.key vfs_dir/CERT/
cp server_ca_1.crt vfs_dir/CERT/

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

    cp test.txt vfs_dir/AT/

  5. 使用 vfs.py 生成 LittleFS 文件系统固件（参考 VFS 章节中的 (二进制文件生成) ）

    python 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 区域（参考 VFS (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 连接线

操作步骤：

  1. 用 USB 连接线连接 Ameba 开发板的 LOGUART 端口和电脑的 USB 端口

  2. 烧录固件

  3. 用串口工具（如 Trace Tool ）按照 1.5M 波特率打开对应的串口端口

  4. 上电或重启 Ameba 开发板

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

../_images/manual_test_mode.svg

命令描述

命令格式

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

示例

AT+COMMAND=parameter1,parameter2

在这个 AT 命令中：

  • 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 消息，比如 Wi-Fi 连接被路由器主动断开，Websocket 客户端长连接突然接收到服务器发送的消息。这些 AT 消息会在消息开头增加 [$] 作为提示，以供主控应用程序解析判断。

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

模块

AT 消息

说明

AT

[$][TT]: High Watermark

TT 模式高水线提示

[$][TT]: Low Watermark

TT 模式低水线提示

Wi-Fi

[$]wifi connected

Wi-Fi 连接路由器成功

[$]wifi connect failed

Wi-Fi 连接路由器失败

[$]wifi got ip:<ip>

Wi-Fi 申请 IP 地址成功

[$]wifi got ip timeout

Wi-Fi 申请 IP 地址超时

[$]wifi disconnected

Wi-Fi 被路由器主动断开

[$]wifi reconnecting

Wi-Fi 自动重连开始

[$]wifi reconnect done

Wi-Fi 自动重连完成

[$]client connected:<sta_mac>

Wi-Fi 热点模式有 STA 连接成功

[$]client disconnected:<sta_mac>

Wi-Fi 热点模式有 STA 主动断开

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

Wi-Fi 热点模式分配 IP 地址

Socket

[$][SKT][EVENT]: A client[link_id: <link_id>,seed,tcp,dst_address:<ip>, dst_port:<port>] connected to server [link_id:<link_id>]

Socket TCP 服务器被一个 TCP 客户端连接

[$][SKT][EVENT]: A client[link_id: <link_id>,seed,tls,dst_address:<ip>, dst_port:<port>] connected to server [link_id:<link_id>]

Socket TLS 服务器被一个 TLS 客户端连接

[$][SKT][DATA][<link_id>][<length>]: <data>

Socket TCP/TLS 收到数据

[$][SKT][DATA][<link_id>][<length>] [<ip>][<port>]:<data>

Socket UDP 收到数据

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 客户端发送二进制数据。

备注

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

进入指示：

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

数据处理规则：

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

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

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

缓冲区管理：

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

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

    • 防溢出机制：

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

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

退出条件：

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

  • 主控可以通过发送连续三笔长度为 1 、内容为 < 的消息主动退出透传模式，AT 模组退出透传模式后将返回命令执行结果

备注

  • 透传模式只在主控模式下工作，一些需要用到透传模式的指令只能工作在主控模式下

  • 防溢出机制只在非 SPI 外设时才会使用，SPI 外设通过同步引脚防止溢出

  • 主控主动退出透传模式时，发送完指定消息后需停止发送其他消息，等待 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