AT API Reference

esp_at_core.h

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.

Parameters:

custom_at_cmd_array – Array of esp_at_cmd_t descriptors.
cmd_num – Number of entries in the array.

Returns:

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.

Parameters:: 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.

Note

Call this only after esp_at_module_init().

Parameters:

link_id – Link identifier (0-based).
ops – Pointer to a populated esp_at_net_ops_t.

Returns:

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.

Note

Call this only after esp_at_module_init().

Parameters:

conn_index – BLE connection index (0-based).
ops – Pointer to a populated esp_at_ble_ops_t.

Returns:

true on success.

void esp_at_custom_ops_register(esp_at_custom_ops_t *ops)

Register lifecycle callbacks for AT core events.

Parameters:: 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.

Returns:: 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.

Note

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.

Parameters:

type – Partition type.
subtype – Partition subtype.
label – Partition label string.

Returns:

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.

Parameters:

para_index – Zero-based parameter position in the AT command line.
value – Output: parsed integer value.

Returns:

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.

Parameters:

para_index – Zero-based parameter position.
value – Output: parsed float value.

Returns:

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.

Parameters:

para_index – Zero-based parameter position.
result – Output: pointer to the NUL-terminated parameter string.

Returns:

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).

Parameters:

len – Number of newly received bytes.
msec – Maximum time to wait for the core to accept the notification (ms).

Returns:

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.

Parameters:

data – Destination buffer.
len – Maximum number of bytes to read.

Returns:

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.

Parameters:

data – Data buffer.
len – Number of bytes to write.

Returns:

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.

Parameters:

data – Data buffer.
len – Number of bytes to write.

Returns:

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.

Parameters:

data – Data buffer.
len – Number of bytes to write.

Returns:

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.

Parameters:

data – Data buffer.
len – Number of bytes to write.

Returns:

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.

Parameters:: timeout_msec – Maximum wait time in milliseconds.
Returns:: 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.

Returns:

>= 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.

Parameters:: 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.

Note

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

Parameters:: 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.

Parameters:

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).

Parameters:

str – NUL-terminated MAC address string.
mac – Output: 6-byte binary MAC address.

Returns:

true on success, false if the string is malformed.

esp_err_t esp_at_wifi_connect(void)

Same as esp_wifi_connect(), but also compatible with the AT Wi-Fi command set.

Note

Use this instead of esp_wifi_connect() to start a Wi-Fi connection.

Returns:: ESP_OK on success, or a Wi-Fi stack error code.

esp_err_t esp_at_wifi_disconnect(void)

Same as esp_wifi_disconnect(), but also compatible with the AT Wi-Fi command set.

Note

Use this instead of esp_wifi_disconnect() to stop a Wi-Fi connection.

Returns:: ESP_OK on success, or a Wi-Fi stack error code.

void esp_at_wifi_reconnect_init(bool force)

Initialize the Wi-Fi reconnect state machine before a connection attempt.

Must be called before esp_at_wifi_connect(). If the connection drops or the initial connect fails, the AT core automatically attempts to reconnect according to the selected policy.

Parameters:: force – true — reconnect unconditionally until esp_at_wifi_reconnect_stop() is called explicitly. false — reconnect using the interval and count configured via AT+CWRECONNCFG.

void esp_at_wifi_reconnect_stop(void)

Stop an active Wi-Fi reconnect sequence.

If an IP address has already been acquired, the existing connection is preserved and not torn down.

esp_err_t esp_at_wifi_scan_start(const wifi_scan_config_t *config, bool block)

Start a Wi-Fi scan using the AT command calling convention.

If a reconnect sequence is in progress, it is suspended for the duration of the scan and then automatically resumed on completion.

Parameters:

config – Scan configuration, or NULL for a default full passive scan.
block – true to block until the scan completes.

Returns:

ESP_OK on success, or a Wi-Fi stack error code.

int esp_at_connect(int fd, const struct sockaddr *name, socklen_t namelen, int timeout_ms)

Connect a socket with an explicit timeout.

Behaves like POSIX connect() with the following differences:

Configurable timeout via timeout_ms.
Requires approximately 2 KB of additional heap memory.
The file descriptor lifecycle is managed internally; do not close it manually after calling this function.

Additional error codes not returned by connect():

ESP_ERR_INVALID_ARG — invalid argument
ESP_ERR_NO_MEM — memory allocation failed
ESP_ERR_TIMEOUT — connection timed out

Parameters:

fd – Socket file descriptor.
name – Destination address structure.
namelen – Size of the address structure.
timeout_ms – Connection timeout in milliseconds; must be greater than 0.

Returns:

0 on success, or a negative error code.

int32_t esp_at_get_socket_by_link_id(uint8_t link_id)

Return the socket file descriptor associated with a TCP/UDP/SSL link ID.

Parameters:: link_id – AT connection link identifier (0-based).
Returns:: Socket file descriptor, or a negative value if the link ID is invalid.

esp_at_netif_t esp_at_get_netif_by_socket(int fd)

Return the network interface type associated with a socket.

Parameters:: fd – Socket file descriptor.
Returns:: The corresponding esp_at_netif_t, or ESP_AT_NETIF_NONE if unknown.

int32_t esp_at_write_data_to_link_id(uint8_t link_id, const void *data, size_t size)

Send data on a TCP/UDP/SSL connection identified by link ID.

The connection must already have been established with AT+CIPSTART or AT+CIPSTARTEX. This helper writes payload data to the socket associated with link_id.

Parameters:

link_id – AT connection link identifier (0-based).
data – Payload buffer to send.
size – Number of bytes to send.

Returns:

Number of bytes written, or a negative error code.

esp_err_t esp_at_hostname_to_ipaddr(const char *hostname, esp_at_ip_proto_t ip_proto, ip_addr_t *target_addr, uint32_t timeout_ms)

Resolve a hostname to a single IP address with timeout control.

Note

hostname may also be an IPv4/IPv6 address literal string.

Note

When timeout_ms > 0, the call uses approximately 2 KB of additional heap memory. When timeout_ms == 0, no extra 2 KB is used and the timeout is controlled internally by lwIP.

Parameters:

hostname – NUL-terminated hostname or IPv4/IPv6 address string.
ip_proto – Address family preference.
target_addr – Output: resolved IP address.
timeout_ms – Resolution timeout in milliseconds.

Returns:

ESP_OK — resolved successfully
ESP_ERR_NOT_FOUND — hostname not found
ESP_ERR_TIMEOUT — resolution timed out
ESP_ERR_NO_MEM — memory allocation failed
Other esp_err_t codes from the underlying DNS stack

esp_err_t esp_at_hostname_to_addrinfo(const char *hostname, esp_at_ip_proto_t ip_proto, ip_addr_t *target_addr, struct addrinfo **res, uint32_t timeout_ms)

Resolve a hostname to a linked list of addrinfo structures.

Returns detailed address information and supports multiple resolved addresses for a single hostname. The caller is responsible for freeing res with freeaddrinfo().

Note

hostname may also be an IPv4/IPv6 address literal string. The timeout and heap-usage behavior is the same as esp_at_hostname_to_ipaddr().

Parameters:

hostname – NUL-terminated hostname or IPv4/IPv6 address string.
ip_proto – Address family preference.
target_addr – Output: first resolved IP address (may be NULL).
res – Output: head of the resolved addrinfo linked list.
timeout_ms – Resolution timeout in milliseconds.

Returns:

Same error codes as esp_at_hostname_to_ipaddr().

esp_err_t esp_at_http_set_pki_if_config(esp_http_client_config_t *config)

Apply PKI configuration from AT+HTTPCFG to an HTTP client config struct.

Call this before creating the HTTP client handle. The function copies the certificate and key material configured via AT+HTTPCFG into config.

Parameters:: config – HTTP client configuration to populate.
Returns:: ESP_OK on success, or an error code.

void esp_at_http_free_pki_if_config(esp_http_client_config_t *config)

Release PKI resources previously applied by esp_at_http_set_pki_if_config().

Parameters:: config – HTTP client configuration whose PKI fields are to be freed.

esp_err_t esp_at_http_set_header_if_config(esp_http_client_handle_t handle)

Apply request headers from AT+HTTPCHEAD to an HTTP client handle.

Call this after creating the client handle and before initiating the request.

Parameters:: handle – HTTP client handle.
Returns:: ESP_OK on success, or an error code.

void esp_at_http_set_sni_if_config(esp_http_client_config_t *config)

Reuse the global SNI previously set by AT+HTTPCSNI.

If AT+HTTPCSNI has already configured a global SNI, call this API in a custom AT command to apply that same setting. The function assigns the stored SNI pointer to config (it does not copy the string). Call it before creating the HTTP client handle.

Parameters:: config – HTTP client configuration to populate.

esp_err_t esp_at_http_clear_header(void)

Clear all request headers previously configured via AT+HTTPCHEAD.

Returns:: ESP_OK on success.

esp_websocket_client_handle_t esp_at_get_ws_client_handle_by_link_id(uint8_t link_id)

Return the WebSocket client handle associated with a link ID.

Parameters:: link_id – AT connection link identifier (0-2).
Returns:: WebSocket client handle, or NULL if the link ID is invalid or inactive.

int esp_at_websocket_client_send_by_opcode_fin(esp_websocket_client_handle_t handle, ws_transport_opcodes_t opcode, bool fin, const char *data, int length, TickType_t timeout)

Send data over a WebSocket connection with explicit opcode and FIN flag.

Parameters:

handle – WebSocket client handle.
opcode – WebSocket frame opcode (e.g. WS_TRANSPORT_OPCODES_TEXT).
fin – true to mark the last frame; false for continuation frames.
data – Payload data buffer.
length – Payload length in bytes.
timeout – Maximum time to wait for the send to complete.

Returns:

Number of bytes sent, or negative on error.

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.

Parameters:

subcategory – Error sub-category (esp_at_errno_t).
extension – Command-specific extension value.

Returns:

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

enum esp_at_ip_proto_t

IP protocol family preference for DNS resolution.

Values:

enumerator ESP_AT_IPPROTO_UNSPEC: No preference; use the system default

enumerator ESP_AT_IPPROTO_IPV4_IPV6: Accept both IPv4 and IPv6 addresses

enumerator ESP_AT_IPPROTO_IPV4_ONLY: Resolve IPv4 addresses only

enumerator ESP_AT_IPPROTO_IPV6_ONLY: Resolve IPv6 addresses only

enum esp_at_netif_t

Network interface type associated with a socket or connection.

Values:

enumerator ESP_AT_NETIF_NONE: No network interface

enumerator ESP_AT_NETIF_STA: Wi-Fi station interface

enumerator ESP_AT_NETIF_AP: Wi-Fi soft-AP interface

enumerator ESP_AT_NETIF_ETH: Ethernet interface

enumerator ESP_AT_NETIF_MAX: Sentinel value

esp_at.h

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.

Parameters:

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.

Returns:: 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_exe_cmd(const char *cmd, const char *expected_response, uint32_t timeout_ms)

Execute an AT command from firmware and wait for the expected response.

Allows the firmware itself to send AT commands through the AT engine without a physical or virtual host interface. Intended for executing preset commands during initialization, before the AT stack is fully ready.

Note

Do not call this function from within an AT command handler (test, query, set, or execute handler). To invoke AT commands from a handler, dispatch via a separate task and queue instead.

Parameters:

cmd – AT command string to execute.
expected_response – NUL-terminated expected response substring.
timeout_ms – Timeout in milliseconds.

Returns:

ESP_OK if the expected response was received within the timeout, or an error code otherwise.

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).

See also

nvs_set_str

Parameters:

handle – NVS handle opened with nvs_open().
key – Key name (NUL-terminated).
value – NUL-terminated string to store.

Returns:

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.

See also

nvs_get_str

Parameters:

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.

Returns:

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).

See also

nvs_set_blob

Parameters:

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.

Returns:

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.

See also

nvs_get_blob

Parameters:

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.

Returns:

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.

Note

Must not be called from interrupt context.

Parameters:

idle_timeout_ms – Threshold (ms) since last idle hook execution.
yield_ticks – RTOS ticks to delay when a yield is triggered.

bool esp_at_mem_check(const char *tag, int value)

Check task stack high watermarks and heap integrity.

Dumps each task’s stack high watermark (minimum remaining free stack since task creation), warns when remaining stack is below the configured risk threshold, and runs heap_caps_check_integrity_all().

Only available when AT memory debug mode is not None (CONFIG_AT_MEM_MONITOR_DEBUG). Without IDF heap poisoning, integrity checks mainly validate heap metadata.

For source-location tracing, pass FILE(or func) and LINE, or use ESP_AT_MEM_CHECK(). Place the macro between two calls to help locate where heap corruption first appears.

Parameters:

tag – Optional label included in logs (may be NULL).
value – Optional numeric value included in logs (e.g. a counter or ID).

Returns:

true if healthy, false on stack overflow risk or heap corruption.

const char *esp_at_fs_get_mount_point(void)

Return the mount point of the AT filesystem partition.

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

bool esp_at_fs_mount(void)

Mount the AT filesystem partition.

Returns:: true on success, false on failure.

bool esp_at_fs_unmount(void)

Unmount the AT filesystem partition.

Returns:: 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.

Parameters:

out_total_bytes – Output: total filesystem size in bytes.
out_free_bytes – Output: available free space in bytes.

Returns:

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.

Returns:: 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.

ESP_AT_MEM_CHECK(): Run esp_at_mem_check() with the current source location.

Provide feedback about this document