AT API Reference

Header File

• components/at/include/esp_at_core.h

Functions

bool esp_at_custom_cmd_array_register(const esp_at_cmd_t *custom_at_cmd_array, uint32_t cmd_num)

Register a custom AT command set.

参数:

• custom_at_cmd_array – Array of esp_at_cmd_t descriptors.

• cmd_num – Number of entries in the array.

返回:

true on success, false if registration failed.

void esp_at_device_ops_register(esp_at_intf_ops_t *ops)

Register the device I/O operations for the AT transport interface.

参数:

ops – Pointer to a populated esp_at_intf_ops_t.

bool esp_at_custom_net_ops_register(int32_t link_id, esp_at_net_ops_t *ops)

Register passthrough callbacks for a socket-based network link.

备注

Call this only after esp_at_module_init().

参数:

• link_id – Link identifier (0-based).

• ops – Pointer to a populated esp_at_net_ops_t.

返回:

true on success.

bool esp_at_custom_ble_ops_register(int32_t conn_index, esp_at_ble_ops_t *ops)

Register passthrough callbacks for a BLE link.

备注

Call this only after esp_at_module_init().

参数:

• conn_index – BLE connection index (0-based).

• ops – Pointer to a populated esp_at_ble_ops_t.

返回:

true on success.

void esp_at_custom_ops_register(esp_at_custom_ops_t *ops)

Register lifecycle callbacks for AT core events.

参数:

ops – Pointer to a populated esp_at_custom_ops_t.

const uint8_t *esp_at_get_current_cmd_name(void)

Return the name of the AT command currently being executed.

返回:

Pointer to a NUL-terminated command name string. Valid only during command handler execution.

const esp_partition_t *esp_at_custom_partition_find(esp_partition_type_t type, esp_partition_subtype_t subtype, const char *label)

Look up a flash partition in the secondary (user) partition table.

Searches only partitions defined in at_customize.csv (the secondary partition table), not the primary system partition table partitions_at.csv.

备注

To look up the primary partition table first and fall back to the secondary table when no match is found, use esp_partition_find_first(). In ESP-AT, this IDF API is linker-wrapped to perform that two-stage lookup.

参数:

• type – Partition type.

• subtype – Partition subtype.

• label – Partition label string.

返回:

Pointer to the matching esp_partition_t, or NULL if not found.

esp_at_para_parse_ret_t esp_at_get_para_as_digit(int32_t para_index, int32_t *value)

Parse the parameter at para_index as a signed 32-bit integer.

参数:

• para_index – Zero-based parameter position in the AT command line.

• value – Output: parsed integer value.

返回:

ESP_AT_PARA_PARSE_RET_OK, _FAIL, or _OMITTED.

esp_at_para_parse_ret_t esp_at_get_para_as_float(int32_t para_index, float *value)

Parse the parameter at para_index as a single-precision float.

参数:

• para_index – Zero-based parameter position.

• value – Output: parsed float value.

返回:

ESP_AT_PARA_PARSE_RET_OK, _FAIL, or _OMITTED.

esp_at_para_parse_ret_t esp_at_get_para_as_str(int32_t para_index, uint8_t **result)

Return a pointer to the raw string for the parameter at para_index.

The returned pointer refers to the AT core’s internal command buffer. The caller must not free or modify the pointed-to string.

参数:

• para_index – Zero-based parameter position.

• result – Output: pointer to the NUL-terminated parameter string.

返回:

ESP_AT_PARA_PARSE_RET_OK, _FAIL, or _OMITTED.

bool esp_at_port_recv_data_notify(int32_t len, uint32_t msec)

Notify the AT core that len bytes have arrived on the port (task context).

参数:

• len – Number of newly received bytes.

• msec – Maximum time to wait for the core to accept the notification (ms).

返回:

true if the notification was accepted within the timeout.

int32_t esp_at_port_read_data(uint8_t *data, int32_t len)

Read up to len bytes from the AT input port.

参数:

• data – Destination buffer.

• len – Maximum number of bytes to read.

返回:

Number of bytes actually read, or negative on error.

int32_t esp_at_port_write_data(uint8_t *data, int32_t len)

Write len bytes to the AT output port.

The output is subject to AT+SYSMSGFILTER (when filtering is enabled). The host MCU is not woken before the data is sent.

参数:

• data – Data buffer.

• len – Number of bytes to write.

返回:

Number of bytes written, or negative on error.

int32_t esp_at_port_active_write_data(uint8_t *data, int32_t len)

Write len bytes to the AT output port, waking the host MCU first.

The output is subject to AT+SYSMSGFILTER (when filtering is enabled). Before sending, the pre-write callback registered via esp_at_custom_ops_register() is invoked, which wakes the host MCU according to the AT+USERWKMCUCFG configuration.

参数:

• data – Data buffer.

• len – Number of bytes to write.

返回:

Number of bytes written, or negative on error.

int32_t esp_at_port_write_data_without_filter(uint8_t *data, int32_t len)

Write len bytes to the AT output port, bypassing AT+SYSMSGFILTER.

The output is never filtered by AT+SYSMSGFILTER. The host MCU is not woken before the data is sent.

参数:

• data – Data buffer.

• len – Number of bytes to write.

返回:

Number of bytes written, or negative on error.

int32_t esp_at_port_active_write_data_without_filter(uint8_t *data, int32_t len)

Write len bytes to the AT output port, waking the host MCU first and bypassing AT+SYSMSGFILTER.

The output is never filtered by AT+SYSMSGFILTER. Before sending, the pre-write callback registered via esp_at_custom_ops_register() is invoked, which wakes the host MCU according to the AT+USERWKMCUCFG configuration.

参数:

• data – Data buffer.

• len – Number of bytes to write.

返回:

Number of bytes written, or negative on error.

bool esp_at_port_wait_write_complete(int32_t timeout_msec)

Block until the AT output port transmit buffer is empty.

参数:

timeout_msec – Maximum wait time in milliseconds.

返回:

true if the buffer drained before the timeout.

int32_t esp_at_port_get_data_length(void)

Return the number of bytes currently pending on the AT input port.

返回:

• >= 0 : the length of the data received

• others: failure

void esp_at_port_enter_specific(esp_at_port_specific_callback_t callback)

Enter a special receive mode; callback is invoked on each data arrival.

参数:

callback – Function called when new data arrives.

void esp_at_port_exit_specific(void)

Exit the special receive mode entered by esp_at_port_enter_specific().

void esp_at_write_result(uint8_t result_code)

Output a standard result string (OK, ERROR, SEND OK, etc.) on the AT port.

This only writes the corresponding result string to the AT port; it does not change the state of the AT port receive task. Use it when, after emitting the result string, the command handler still needs to run further logic that is unrelated to receiving new data on the AT port.

备注

If the command is finished and the AT port should resume accepting new input, use esp_at_dispatch_result() instead.

参数:

result_code – One of the esp_at_rc_t values cast to uint8_t.

void esp_at_dispatch_result(esp_at_rc_t code, void *pbuf)

Output a result string and return the AT port to the ready state.

In addition to outputting the corresponding result string (like esp_at_write_result()), this dispatches the result code through any registered result handlers and brings the AT command receive task back to its idle/ready state, so that the AT port can accept and process new input.

Use it when the command handler has finished and the next step is to receive fresh data from the AT port. For example, after printing “OK” and the “>” data prompt, call this so the AT port is ready to receive the new input that the handler expects.

参数:

• code – Result code to dispatch.

• pbuf – Optional command-specific data; set it to NULL if not needed.

void esp_at_restart(void)

Restart the system with a hardware watchdog safety net.

Arms a 3-second hardware timer before calling the esp_restart() routine. If the normal restart path stalls, the watchdog forces a hard reset. No output is generated on the AT port before the restart.

void esp_at_restart_async(void)

Respond with OK on the AT port, run the pre_restart callback, then restart.

Use this variant to restart in response to an AT command so that the host receives an OK acknowledgement before the device reboots. Arms the same 3-second hardware watchdog as esp_at_restart().

bool esp_at_str_2_mac(const char *str, uint8_t mac[6])

Convert a colon-separated MAC address string to a 6-byte binary array.

Accepts the format “XX:XX:XX:XX:XX:XX” (case-insensitive hex digits).

参数:

• str – NUL-terminated MAC address string.

• mac – Output: 6-byte binary MAC address.

返回:

true on success, false if the string is malformed.

Structures

struct esp_at_cmd_t

Descriptor for a single AT command.

Register an array of these via esp_at_custom_cmd_array_register(). Set unused command-type handlers to NULL.

Public Members

char *cmd_name

Command name string, e.g. “+MYCOMMAND”

uint8_t (*test_cmd)(uint8_t *cmd_name)

Handler for AT+CMD=?

uint8_t (*query_cmd)(uint8_t *cmd_name)

Handler for AT+CMD?

uint8_t (*setup_cmd)(uint8_t para_num)

Handler for AT+CMD=<params>

uint8_t (*exe_cmd)(uint8_t *cmd_name)

Handler for AT+CMD

struct esp_at_intf_ops_t

I/O operation callbacks for the underlying AT transport device.

Pass a populated instance to esp_at_device_ops_register().

Public Members

int32_t (*read_data)(uint8_t *data, int32_t len)

Read bytes from the physical interface

int32_t (*write_data)(uint8_t *data, int32_t len)

Write bytes to the physical interface

int32_t (*get_data_length)(void)

Return the number of bytes available

bool (*wait_write_complete)(int32_t timeout_msec)

Block until the transmit buffer is drained

struct esp_at_net_ops_t

Callbacks for a socket-based passthrough (transparent-transmission) link.

Register via esp_at_custom_net_ops_register().

Public Members

int32_t (*recv_data)(uint8_t *data, int32_t len)

Invoked when data arrives on the link

void (*connect_cb)(void)

Invoked when the link is established

void (*disconnect_cb)(void)

Invoked when the link is torn down

struct esp_at_ble_ops_t

Callbacks for a BLE passthrough link.

Register via esp_at_custom_ble_ops_register().

Public Members

int32_t (*recv_data)(uint8_t *data, int32_t len)

Invoked when data arrives on the BLE link

void (*connect_cb)(void)

Invoked when the BLE link is established

void (*disconnect_cb)(void)

Invoked when the BLE link is torn down

struct esp_at_custom_ops_t

Lifecycle and status callbacks for AT core events.

Pass a populated instance to esp_at_custom_ops_register().

Public Members

void (*status_callback)(esp_at_status_t status)

Called on AT core status change

void (*pre_sleep_callback)(esp_at_sleep_mode_t mode)

Called before entering sleep

void (*pre_wakeup_callback)(void)

Called before waking from sleep

void (*pre_deepsleep_callback)(void)

Called before entering deep sleep

void (*pre_restart_callback)(void)

Called before system restart

void (*pre_active_write_data_callback)(int32_t (*write_fn)(uint8_t *data, int32_t len))

Called before an active data write

Macros

ESP_AT_ERROR_NO(subcategory, extension)

Encode an AT error code from its constituent fields.

参数:

• subcategory – Error sub-category (esp_at_errno_t).

• extension – Command-specific extension value.

返回:

Packed 32-bit error code: [module:8][sub:8][ext:16].

ESP_AT_CMD_ERROR_OK

No error

ESP_AT_CMD_ERROR_NON_FINISH

Command terminator (“\r\n”) not found

ESP_AT_CMD_ERROR_NOT_FOUND_AT

Command does not start with “AT”

ESP_AT_CMD_ERROR_PARA_LENGTH(which_para)

Parameter length mismatch (which_para: 0-based index)

ESP_AT_CMD_ERROR_PARA_TYPE(which_para)

Parameter type mismatch (which_para: 0-based index)

ESP_AT_CMD_ERROR_PARA_NUM(need, given)

Parameter count mismatch (need expected, given received)

ESP_AT_CMD_ERROR_PARA_INVALID(which_para)

Invalid parameter value (which_para: 0-based index)

ESP_AT_CMD_ERROR_PARA_PARSE_FAIL(which_para)

Failed to parse a parameter (which_para: 0-based index)

ESP_AT_CMD_ERROR_CMD_UNSUPPORT

Command not supported

ESP_AT_CMD_ERROR_CMD_EXEC_FAIL(result)

Command execution failed (result: handler-specific code)

ESP_AT_CMD_ERROR_CMD_PROCESSING

A previous command is still being processed

ESP_AT_CMD_ERROR_CMD_OP_ERROR

Unsupported command operation type

Type Definitions

typedef void (*esp_at_port_specific_callback_t)(void)

Callback invoked while the AT core is in a specific receive mode.

Enumerations

enum esp_at_status_t

Operational status of the AT core.

Values:

enumerator ESP_AT_STATUS_NORMAL

Command mode: processing AT commands

enumerator ESP_AT_STATUS_TRANSMIT

Passthrough mode: forwarding raw data

enum esp_at_sleep_mode_t

Supported sleep mode of the AT core.

Values:

enumerator ESP_AT_SLEEP_DISABLE

Sleep disabled

enumerator ESP_AT_SLEEP_MIN_MODEM

Minimum modem sleep (DTIM-based)

enumerator ESP_AT_SLEEP_LIGHT

Light sleep

enumerator ESP_AT_SLEEP_MAX_MODEM

Maximum modem sleep

enumerator ESP_AT_SLEEP_MODE_MAX

Sentinel value; not a valid mode

enum esp_at_para_parse_ret_t

Return value of the parameter-parsing helpers.

Values:

enumerator ESP_AT_PARA_PARSE_RET_FAIL

Parse failed; parameter is malformed

enumerator ESP_AT_PARA_PARSE_RET_OK

Parameter parsed successfully

enumerator ESP_AT_PARA_PARSE_RET_OMITTED

Parameter was omitted (empty field)

enum esp_at_rc_t

Result code selectors for esp_at_write_result() and esp_at_dispatch_result().

Values:

enumerator ESP_AT_RESULT_CODE_OK

OK

enumerator ESP_AT_RESULT_CODE_ERROR

ERROR

enumerator ESP_AT_RESULT_CODE_FAIL

ERROR

enumerator ESP_AT_RESULT_CODE_SEND_OK

SEND OK

enumerator ESP_AT_RESULT_CODE_SEND_FAIL

SEND FAIL

enumerator ESP_AT_RESULT_CODE_IGNORE

(no output)

enumerator ESP_AT_RESULT_CODE_PROCESS_DONE

(processing complete, no output)

enumerator ESP_AT_RESULT_CODE_OK_AND_INPUT_PROMPT

OK followed by input prompt

enumerator ESP_AT_RESULT_CODE_MAX

Sentinel; not a valid code

enum esp_at_module_t

AT core module identifier, used as the high byte of error codes.

Values:

enumerator ESP_AT_MODULE_NUM

enum esp_at_errno_t

AT command error sub-categories.

Values:

enumerator ESP_AT_SUB_OK

No error

enumerator ESP_AT_SUB_COMMON_ERROR

Generic error

enumerator ESP_AT_SUB_NO_TERMINATOR

Missing line terminator

enumerator ESP_AT_SUB_NO_AT

Missing AT prefix

enumerator ESP_AT_SUB_PARA_LENGTH_MISMATCH

Parameter length out of range

enumerator ESP_AT_SUB_PARA_TYPE_MISMATCH

Parameter type mismatch

enumerator ESP_AT_SUB_PARA_NUM_MISMATCH

Wrong number of parameters

enumerator ESP_AT_SUB_PARA_INVALID

Parameter value out of valid range

enumerator ESP_AT_SUB_PARA_PARSE_FAIL

Failed to parse parameter

enumerator ESP_AT_SUB_UNSUPPORT_CMD

Command not supported

enumerator ESP_AT_SUB_CMD_EXEC_FAIL

Command execution failed

enumerator ESP_AT_SUB_CMD_PROCESSING

A command is already in progress

enumerator ESP_AT_SUB_CMD_OP_ERROR

Wrong operation type for command

Header File

• components/at/include/esp_at.h

Functions

void esp_at_log_write(esp_log_level_t level, const char *tag, const char *format, ...)

Write a formatted message to the AT log output (weak, overridable).

Not intended to be called directly; use the ESP_AT_LOGE/W/I/D/V macros instead. Must not be called from an interrupt context. As a weak symbol, the default implementation can be overridden to redirect AT log output.

参数:

• level – Log severity level.

• tag – Log tag string.

• format – printf-style format string.

• ... – Arguments referenced by format.

const char *esp_at_get_current_module_name(void)

Return the name of the currently selected AT module.

返回:

NUL-terminated module name string.

void esp_at_ready_before(void)

Hook invoked immediately before the AT stack signals ready.

Override this weak function to: a) Execute preset AT commands via esp_at_exe_cmd(). b) Perform additional initialization using ESP-IDF or AT APIs.

esp_err_t esp_at_nvs_set_str(nvs_handle_t handle, const char *key, const char *value)

Store a NUL-terminated string in NVS (weak, overridable).

The AT core uses this helper internally to persist string data to NVS. It is a weak symbol whose default implementation simply forwards to nvs_set_str(). Override it to hook the storage path, for example to encrypt the value before it is written to flash (override esp_at_nvs_get_str() to decrypt on read).

参见

nvs_set_str

参数:

• handle – NVS handle opened with nvs_open().

• key – Key name (NUL-terminated).

• value – NUL-terminated string to store.

返回:

ESP_OK on success, or an NVS error code otherwise.

esp_err_t esp_at_nvs_get_str(nvs_handle_t handle, const char *key, char *out_value, size_t *length)

Read a NUL-terminated string from NVS (weak, overridable).

Counterpart of esp_at_nvs_set_str(): the AT core uses it internally to load string data from NVS. It is a weak symbol whose default implementation simply forwards to nvs_get_str(). Override it together with esp_at_nvs_set_str() to, for example, decrypt the value after reading it from flash.

参见

nvs_get_str

参数:

• handle – NVS handle opened with nvs_open().

• key – Key name (NUL-terminated).

• out_value – Buffer that receives the string; pass NULL to query the required length.

• length – In/out: capacity of out_value in bytes, updated with the actual length.

返回:

ESP_OK on success, or an NVS error code otherwise.

esp_err_t esp_at_nvs_set_blob(nvs_handle_t handle, const char *key, const void *value, size_t length)

Store a binary blob in NVS (weak, overridable).

The AT core uses this helper internally to persist binary data to NVS. It is a weak symbol whose default implementation simply forwards to nvs_set_blob(). Override it to hook the storage path, for example to encrypt the blob before it is written to flash (override esp_at_nvs_get_blob() to decrypt on read).

参见

nvs_set_blob

参数:

• handle – NVS handle opened with nvs_open().

• key – Key name (NUL-terminated).

• value – Pointer to the blob to store.

• length – Size of value in bytes.

返回:

ESP_OK on success, or an NVS error code otherwise.

esp_err_t esp_at_nvs_get_blob(nvs_handle_t handle, const char *key, void *out_value, size_t *length)

Read a binary blob from NVS (weak, overridable).

Counterpart of esp_at_nvs_set_blob(): the AT core uses it internally to load binary data from NVS. It is a weak symbol whose default implementation simply forwards to nvs_get_blob(). Override it together with esp_at_nvs_set_blob() to, for example, decrypt the blob after reading it from flash.

参见

nvs_get_blob

参数:

• handle – NVS handle opened with nvs_open().

• key – Key name (NUL-terminated).

• out_value – Buffer that receives the blob; pass NULL to query the required length.

• length – In/out: capacity of out_value in bytes, updated with the actual length.

返回:

ESP_OK on success, or an NVS error code otherwise.

void esp_at_yield_if_idle_timeout(uint32_t idle_timeout_ms, uint32_t yield_ticks)

Yield the current task if the FreeRTOS idle task has not run recently.

Measures the time since the last idle hook execution. If that interval exceeds idle_timeout_ms, the calling task delays for yield_ticks RTOS ticks to allow lower-priority tasks (including the idle task) to run.

Intended to prevent high-throughput tasks from starving the idle task and triggering the task watchdog timer under sustained CPU load.

备注

Must not be called from interrupt context.

参数:

• idle_timeout_ms – Threshold (ms) since last idle hook execution.

• yield_ticks – RTOS ticks to delay when a yield is triggered.

const char *esp_at_fs_get_mount_point(void)

Return the mount point of the AT filesystem partition.

返回:

NUL-terminated mount point path string (e.g. “/littlefs”).

bool esp_at_fs_mount(void)

Mount the AT filesystem partition.

返回:

true on success, false on failure.

bool esp_at_fs_unmount(void)

Unmount the AT filesystem partition.

返回:

true on success, false on failure.

esp_err_t esp_at_get_fs_info(uint32_t *out_total_bytes, uint32_t *out_free_bytes)

Query the total and free capacity of the AT filesystem.

参数:

• out_total_bytes – Output: total filesystem size in bytes.

• out_free_bytes – Output: available free space in bytes.

返回:

ESP_OK on success, or an error code.

esp_at_fs_type_t esp_at_fs_get_type(void)

Return the filesystem type in use.

返回:

The active esp_at_fs_type_t value.

Macros

ESP_AT_PORT_TX_WAIT_MS_MAX

Maximum time (ms) to wait for the AT port TX buffer to drain.

ESP_AT_BUF_ON_STACK_SIZE

Default maximum stack-allocated buffer size for AT command handlers.

esp_at_min(x, y)

Returns the smaller of two values.

esp_at_max(x, y)

Returns the larger of two values.

ESP_AT_LOG_BUFFER_HEXDUMP(tag, buffer, buff_len, level)

NULL-safe wrapper around ESP_LOG_BUFFER_HEXDUMP.

Outputs a hexadecimal buffer dump only when buffer is non-NULL.

CONFIG_AT_LOG_DEFAULT_LEVEL

Compile-time fallback for the AT log verbosity level when not set via Kconfig.

ESP_AT_LOGE(tag, format, ...)

Log at ERROR level, gated by CONFIG_AT_LOG_DEFAULT_LEVEL.

ESP_AT_LOGW(tag, format, ...)

Log at WARN level, gated by CONFIG_AT_LOG_DEFAULT_LEVEL.

ESP_AT_LOGI(tag, format, ...)

Log at INFO level, gated by CONFIG_AT_LOG_DEFAULT_LEVEL.

ESP_AT_LOGD(tag, format, ...)

Log at DEBUG level, gated by CONFIG_AT_LOG_DEFAULT_LEVEL.

ESP_AT_LOGV(tag, format, ...)

Log at VERBOSE level, gated by CONFIG_AT_LOG_DEFAULT_LEVEL.

提供有关此文档的反馈