Overview

This section describes the modes, scenarios, usage methods, and related information of AT commands.

AT Commands Modes

Currently, two AT command modes are supported: Manual Test Mode and Host Control Mode, each suitable for different scenarios.

  • Use Cases: Single-command debugging, feature evaluation/validation, rapid testing

  • Typical Applications: Developers use serial tools to send AT commands for Wi-Fi connectivity testing, throughput testing, Bluetooth pairing tests, etc.

Software Environment Preparation

Prerequisites

It is strongly recommended to review the following sections first:

AT Image Compilation

Refer to Configuring SDK (menuconfig), navigate to CONFIG AT CMD, select Manual Test Mode, and enable relevant AT command modules.

Compile the image by following Building Code.

Note

To enable Bluetooth command modules in AT commands, enable Bluetooth in the CONFIG BT section of the Menuconfig main page fisrt.

Note

For higher Wi-Fi throughput, enable the Enable HIGH TP option in the CONFIG WIFI section of the Menuconfig main page.

AT Configuration Modification

In Host Control Mode, peripheral interfaces and their corresponding pins can be modified directly via the configuration file atcmd_config.json without updating the application image.

  • Locate atcmd_config.json in the SDK and modify fields as needed.

  • Preload atcmd_config.json to the root directory of the LittleFS virtual file system(VFS) and generate the VFS image (see Preload Example).

  • Flash the VFS image to the VFS1 region of the Ameba development board (refer to relevant documentation).

  • Reboot and LogUART will output AT command initialization information:

[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

Note

Peripheral interfaces support UART/SPI/SDIO. Refer to datasheets and hardware documentation for pin configurations.

If atcmd_config.json is not preloaded, UART default configurations will apply and default baudrate and pins are list below

  • Baud rate: 38400

  • UART_TX pin: PA_26

  • UART_RX pin: PA_27

AT Security Certificates

Some AT functionalities (e.g., connecting to Wi-Fi WPA-enterprise routers, HTTPS, WebSocket servers) may require security certificates.

Security certificate suites include client and server suites, both containing a CA certificate (.crt), a certificate (.crt), and a key (.key).

Security certificate suites are numbered from 1 to 10.

When AT commands require a security certificate suite, the optional parameter <cert_index> is used to locate and use the corresponding suite in the /CERT/ directory.

These certificate suites reside in the fixed directory /CERT/ on the LittleFS virtual file system. For preloading certificate suites, refer to Preload Example.

Note

A security certificate suite can provide only necessary files based on requirements. For instance, in HTTPS client verifies the server’s certificate using a trusted CA, only the CA certificate needs to be preloaded in the file system.

Category

Security Certificate Suite

Related AT Commands

Client

Suite 1 (filenames):

  • client_ca_1.crt

  • client_cert_1.crt

  • client_key_1.key

Suite 2 (filenames):

  • 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

Server

Suite 1 (filenames):

  • server_ca_1.crt

  • server_cert_1.crt

  • server_key_1.key

Suite 2 (filenames):

  • server_ca_2.crt

  • server_cert_2.crt

  • server_key_2.key

…

  • AT+SKTSERVE

  • AT+WSSRVSTART

Preload Example

This example demonstrates how to preload atcmd_config.json, security certificate suites and test.txt file for AT+FS cmd:

  1. Create vfs_dir and CERT subdirectory:

    mkdir vfs_dir
mkdir vfs_dir/CERT
mkdir vfs_dir/AT

  2. Copy atcmd_config.json to vfs_dir:

    cp atcmd_config.json vfs_dir/

  3. Copy certificate files to CERT:

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

  4. Copy test.txt file to AT:

    cp test.txt vfs_dir/AT/

  5. Generate LittleFS filesystem image using vfs.py (see VFS Bin File Generation):

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

    Example output:

    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 to the VFS1 region of the AT module’s flash (see VFS on Flash).

  7. Flash the boot and app image (see Image Tool).

  8. Upon reboot, check LogUART for custom configuration output. Example:

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

  9. Use the following commands to output client and server certificate suites:

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

  10. Use the following command to output the first 10 bytes of content from the test.txt file:

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

Hardware Environment Preparation

Required Materials:

  • Ameba board

  • Computer: For image flashing, sending AT commands, and observing responses

  • Type-C USB cable

Steps:

  • Connect Ameba’s LogUART port to the computer via USB.

  • Flash the image.

  • Open the corresponding serial port using a tool like Trace Tool at 1.5M baud rate.

  • Power on or reset the Ameba board.

  • Send AT commands after seeing ATCMD READY in the serial tool.

../../_images/manual_test_mode.svg

In Host Control Mode, prepare atcmd_config.json in advance (see AT Configuration Modification).

Command Description

Command Format

A complete AT command starts with two uppercase letters AT (abbreviation for Attention), followed by a + sign and the command name. If parameters are required, an = is added after the command name, followed by a parameter list, and ending with the ASCII CR-LF terminator.

Example

AT+COMMAND=parameter1,parameter2

In this example:

  • AT: Starting characters indicating a valid AT command

  • +: Separator between the start characters and the command

  • COMMAND: The command name to be executed immediately

  • Parameters: parameter1 and parameter2

In some cases, parameters can be omitted by leaving empty commas between parameters.

Example

AT+COMMAND=parameter1, ,parameter3

Here, parameter2 is omitted (using its default value) between two commas.

Command Parameters

AT command parameters follow these conventions:

  • Angle brackets < > indicate mandatory parameters

  • Square brackets [ ] indicate optional parameters

  • Parameters are separated by commas

Example

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

Here, param1 is mandatory, while param2 and param3 are optional.

Escape Characters

To include commas as part of a parameter, use the escape sequence \,. A literal backslash is represented as \\. For commands not requiring escape sequences, commas act as separators and single backslashes are treated as normal characters.

Example

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

This command has three parameters:

  • First parameter: parameter1

  • Second parameter: head,tail (comma preserved via \,)

  • Third parameter: head\tail (literal backslash via \\)

Command Length

AT commands (including AT prefix and CR-LF terminator) must not exceed specified length limits. Excess characters are ignored.

  • Host Control Mode: 2000 bytes limit

  • Manual Test Mode: 127 bytes limit

Escape sequences (e.g., \, or \\) count as 2 bytes.

Command Response

  • After receiving an AT command, the device first validates it. If invalid (not in the AT command set), it returns unknown command COMMAND. Valid commands trigger corresponding operations.

  • During command execution, various types of information may be output.

  • A successful execution typically outputs OK.

  • A failed execution outputs ERROR with an error code.

Note

Each AT command has specific error codes and meanings. Refer to individual command descriptions for details.

AT Messages

When the system is not actively executing AT commands, proactive AT messages may appear, such as when a Wi-Fi connection is actively disconnected by the router, or when a Websocket client receives messages from the server during a persistent connection.

These AT messages will be prefixed with [$] for easy identification and parsing by the host application.

The following table lists all active AT messages:

List of Active AT Messages

Module

AT Message

Description

AT

[$][TT]: High Watermark

TT mode high watermark prompt

[$][TT]: Low Watermark

TT mode low watermark prompt

Wi-Fi

[$]wifi connected

Wi-Fi successfully connected to router

[$]wifi connect failed

Wi-Fi failed to connect to router

[$]wifi got ip:<ip>

Wi-Fi successfully obtained IP address

[$]wifi got ip timeout

Wi-Fi IP address request timed out

[$]wifi disconnected

Wi-Fi actively disconnected by router

[$]wifi reconnecting

Wi-Fi auto-reconnection started

[$]wifi reconnect done

Wi-Fi auto-reconnection completed

[$]client connected:<sta_mac>

STA successfully connected in AP mode

[$]client disconnected:<sta_mac>

STA actively disconnected in AP mode

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

IP address assigned in AP mode

Socket

(To be added)

(To be added)

MQTT

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

MQTT connection successful

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

MQTT error event

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

MQTT subscription successful

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

MQTT unsubscription successful

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

MQTT publish successful

[$][MQTT][DATA][<link_id>][<topic>] [<msg_id>][<msg_len>]:<message>

MQTT message received

Websocket

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

Websocket connection successful

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

Websocket disconnected

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

Websocket PONG packet received

[$][WS][DATA][<link_id>][<data_len>]: <data>

Websocket data received

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

Websocket server connection successful

[$][WSSRV][EVENT]:linkid:<link_id>, disconnected, reason:<reason>

Websocket server disconnected

[$][WSSRV][DATA][<link_id>][<opcode>] [<data_len>]: <data>

Websocket server data received

Transparent Transmission (TT) Mode

Some AT commands will enter Transparent Transmission (TT) mode after execution, enabling high-volume data transmission or high-performance transfers from the host controller. Typical use cases include uploading large files via HTTP POST or sending binary data through Websocket client.

Entry indication:

  • Output >>> when successfully entering TT mode

Data handling:

  • Symbols such as , and \ require no escaping, all data can be transmitted directly

  • May contain ASCII CR-LF characters, these won’t be recognized as AT command terminators in TT mode

  • Data length is specified by parameters in the corresponding AT command. If unspecified, length is unrestricted

Buffer management:

  • Data <120KB: Fully bufferable, HOST can continuously send without stopping

  • Data ≥120KB: Requires flow control, HOST needs to control sending based on the following AT messages

    • Buffer overflow protection:

      • [$][TT]: High Watermark message indicates host should pause transmission

      • [$][TT]: Low Watermark message indicates host can resume transmission

Exit condition:

  • Automatically exits TT mode and returns command execution results after receiving specified data length.

Note

TT mode only works in Host Control Mode. Some AT commands requiring TT mode are exclusively supported in Host Control Mode.

AT Command List

Currently supported AT commands:

Refer to the sections above for detailed descriptions.

AT Command Version

Query the firmware’s AT command version using AT+GMR.

The version follows semantic versioning:

<major>.<minor>.<patch>

Parameter Definitions:

<major> : Major version for significant updates (e.g., new chip support, major features)

<minor> : Minor version for incremental updates (e.g., new commands, bug fixes)

<patch> : Patch version for backward-compatible fixes (no new features)

Example

Command:

AT+GMR

Response:

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