AT API Reference

Header File

Functions

void esp_at_module_init(const uint8_t *custom_version)

This function should be called only once.

Parameters:

custom_version – version information by custom

esp_at_para_parse_result_type esp_at_get_para_as_digit(int32_t para_index, int32_t *value)

Parse digit parameter from command string.

Parameters:

  • para_index – the index of parameter

  • value – the value parsed

Returns:

  • ESP_AT_PARA_PARSE_RESULT_OK : succeed

  • ESP_AT_PARA_PARSE_RESULT_FAIL : fail

  • ESP_AT_PARA_PARSE_RESULT_OMITTED : this parameter is OMITTED

esp_at_para_parse_result_type esp_at_get_para_as_float(int32_t para_index, float *value)

Parse float parameter from command string.

Parameters:

  • para_index – the index of parameter

  • value – the value parsed

Returns:

  • ESP_AT_PARA_PARSE_RESULT_OK : succeed

  • ESP_AT_PARA_PARSE_RESULT_FAIL : fail

  • ESP_AT_PARA_PARSE_RESULT_OMITTED : this parameter is OMITTED

esp_at_para_parse_result_type esp_at_get_para_as_str(int32_t para_index, uint8_t **result)

Parse string parameter from command string.

Parameters:

  • para_index – the index of parameter

  • result – the pointer that point to the result.

Returns:

  • ESP_AT_PARA_PARSE_RESULT_OK : succeed

  • ESP_AT_PARA_PARSE_RESULT_FAIL : fail

  • ESP_AT_PARA_PARSE_RESULT_OMITTED : this parameter is OMITTED

void esp_at_port_recv_data_notify_from_isr(int32_t len)

Calling the esp_at_port_recv_data_notify_from_isr to notify at module that at port received data. When received this notice,at task will get data by calling get_data_length and read_data in esp_at_device_ops. This function MUST be used in isr.

Parameters:

len – data length

bool esp_at_port_recv_data_notify(int32_t len, uint32_t msec)

Calling the esp_at_port_recv_data_notify to notify at module that at port received data. When received this notice,at task will get data by calling get_data_length and read_data in esp_at_device_ops. This function MUST NOT be used in isr.

Parameters:

  • len – data length

  • msec – timeout time,The unit is millisecond. It waits forever,if msec is portMAX_DELAY.

Returns:

  • true : succeed

  • false : fail

void esp_at_transmit_terminal_from_isr(void)

terminal transparent transmit mode,This function MUST be used in isr.

void esp_at_transmit_terminal(void)

terminal transparent transmit mode,This function MUST NOT be used in isr.

bool esp_at_custom_cmd_array_regist(const esp_at_cmd_struct *custom_at_cmd_array, uint32_t cmd_num)

register at command set, which defined by custom,

Parameters:

  • custom_at_cmd_array – at command set

  • cmd_num – command number

void esp_at_device_ops_regist(esp_at_device_ops_struct *ops)

register device operate functions set,

Parameters:

ops – device operate functions set

bool esp_at_custom_net_ops_regist(int32_t link_id, esp_at_custom_net_ops_struct *ops)
bool esp_at_custom_ble_ops_regist(int32_t conn_index, esp_at_custom_ble_ops_struct *ops)
void esp_at_custom_ops_regist(esp_at_custom_ops_struct *ops)

register custom operate functions set interacting with AT,

Parameters:

ops – custom operate functions set

uint32_t esp_at_get_version(void)

get at module version number,

Returns:

at version bit31~bit24: at main version bit23~bit16: at sub version bit15~bit8 : at test version bit7~bit0 : at custom version

void esp_at_response_result(uint8_t result_code)

response AT process result,

Parameters:

result_code – see esp_at_result_code_string_index

int32_t esp_at_port_write_data(uint8_t *data, int32_t len)

write data into device,

Parameters:

  • data – data buffer to be written

  • len – data length

Returns:

  • >= 0 : the real length of the data written

  • others : fail.

int32_t esp_at_port_active_write_data(uint8_t *data, int32_t len)

call pre_active_write_data_callback() first and then write data into device,

Parameters:

  • data – data buffer to be written

  • len – data length

Returns:

  • >= 0 : the real length of the data written

  • others : fail.

int32_t esp_at_port_read_data(uint8_t *data, int32_t len)

read data from device,

Parameters:

  • data – data buffer

  • len – data length

Returns:

  • >= 0 : the real length of the data read from device

  • others : fail

bool esp_at_port_wait_write_complete(int32_t timeout_msec)

wait for transmitting data completely to peer device,

Parameters:

timeout_msec – timeout time,The unit is millisecond.

Returns:

  • true : succeed,transmit data completely

  • false : fail

int32_t esp_at_port_get_data_length(void)

get the length of the data received,

Returns:

  • >= 0 : the length of the data received

  • others : fail

bool esp_at_custom_cmd_line_terminator_set(uint8_t *terminator)

Set AT command terminator, by default, the terminator is “\r\n” You can change it by calling this function, but it just supports one character now.

Parameters:

terminator – the line terminator

Returns:

  • true : succeed,transmit data completely

  • false : fail

uint8_t *esp_at_custom_cmd_line_terminator_get(void)

Get AT command line terminator,by default, the return string is “\r\n”.

Returns:

the command line terminator

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

Find the partition which is defined in at_customize.csv.

Parameters:

  • type – the type of the partition

  • subtype – the subtype of the partition

  • label – Partition label

Returns:

pointer to esp_partition_t structure, or NULL if no partition is found. This pointer is valid for the lifetime of the application

void esp_at_port_enter_specific(esp_at_port_specific_callback_t callback)

Set AT core as specific status, it will call callback if receiving data. for example: 

static void wait_data_callback (void)
{
    xSemaphoreGive(sync_sema);
}

void process_task(void* para)
{
    vSemaphoreCreateBinary(sync_sema);
    xSemaphoreTake(sync_sema,portMAX_DELAY);
    esp_at_port_write_data((uint8_t *)">",strlen(">"));
    esp_at_port_enter_specific(wait_data_callback);
    while(xSemaphoreTake(sync_sema,portMAX_DELAY)) {
        len = esp_at_port_read_data(data, data_len);
        // TODO:
    }
}

Parameters:

callback – which will be called when received data from AT port

void esp_at_port_exit_specific(void)

Exit AT core as specific status.

const uint8_t *esp_at_get_current_cmd_name(void)

Get current AT command name.

int32_t esp_at_get_core_version(char *buffer, uint32_t size)

Get the version of the AT core library.

Parameters:

  • buffer – buffer to store the version string

  • size – size of the buffer

Returns:

  • > 0 : the real length of the version string

  • others : fail

bool at_fatfs_mount(void)

Mount FATFS partition.

Note

if you want to use FATFS, you should enable “AT FS command support” in menuconfig first.

Note

esp-at uses a fixed partition for the filesystem, which defined in esp-at/module_config/$your_module_config/at_customize.csv, and uses a fixed mount point “/fatfs”.

Note

when using FATFS, you should call this function to mount the partition first, and call at_fatfs_unmount() to unmount the partition when you don’t need it.

Returns:

  • true : succeed

  • false : fail

bool at_fatfs_unmount(void)

Unmount FATFS partition.

Returns:

  • true : succeed

  • false : fail

bool at_str_is_null(uint8_t *str)

Check if the string is NULL.

Parameters:

str – the string to be checked

Returns:

  • true : the string is NULL

  • false : the string is not NULL

void at_handle_result_code(esp_at_result_code_string_index code, void *pbuf)

Structures

struct esp_at_cmd_struct

esp_at_cmd_struct used for define at command

Public Members

char *at_cmdName

at command name

uint8_t (*at_testCmd)(uint8_t *cmd_name)

Test Command function pointer

uint8_t (*at_queryCmd)(uint8_t *cmd_name)

Query Command function pointer

uint8_t (*at_setupCmd)(uint8_t para_num)

Setup Command function pointer

uint8_t (*at_exeCmd)(uint8_t *cmd_name)

Execute Command function pointer

struct esp_at_device_ops_struct

esp_at_device_ops_struct device operate functions struct for AT

Public Members

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

read data from device

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

write data into device

int32_t (*get_data_length)(void)

get the length of data received

bool (*wait_write_complete)(int32_t timeout_msec)

wait write finish

struct esp_at_custom_net_ops_struct

esp_at_custom_net_ops_struct custom socket callback for AT

Public Members

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

callback when socket received data

void (*connect_cb)(void)

callback when socket connection is built

void (*disconnect_cb)(void)

callback when socket connection is disconnected

struct esp_at_custom_ble_ops_struct

esp_at_custom_ble_ops_struct custom ble callback for AT

Public Members

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

callback when ble received data

void (*connect_cb)(void)

callback when ble connection is built

void (*disconnect_cb)(void)

callback when ble connection is disconnected

struct esp_at_custom_ops_struct

esp_at_ops_struct some custom function interacting with AT

Public Members

void (*status_callback)(esp_at_status_type status)

callback when AT status changes

void (*pre_sleep_callback)(at_sleep_mode_t mode)

callback before entering light sleep

void (*pre_wakeup_callback)(void)

callback before waking up from light sleep

void (*pre_deepsleep_callback)(void)

callback before enter deep sleep

void (*pre_restart_callback)(void)

callback before restart

void (*pre_active_write_data_callback)(at_write_data_fn_t)

callback before write data

Macros

at_min(x, y)
at_max(x, y)
ESP_AT_ERROR_NO(subcategory, extension)
ESP_AT_CMD_ERROR_OK

No Error

ESP_AT_CMD_ERROR_NON_FINISH

terminator character not found (“\r\n” expected)

ESP_AT_CMD_ERROR_NOT_FOUND_AT

Starting “AT” not found (or at, At or aT entered)

ESP_AT_CMD_ERROR_PARA_LENGTH(which_para)

parameter length mismatch

ESP_AT_CMD_ERROR_PARA_TYPE(which_para)

parameter type mismatch

ESP_AT_CMD_ERROR_PARA_NUM(need, given)

parameter number mismatch

ESP_AT_CMD_ERROR_PARA_INVALID(which_para)

the parameter is invalid

ESP_AT_CMD_ERROR_PARA_PARSE_FAIL(which_para)

parse parameter fail

ESP_AT_CMD_ERROR_CMD_UNSUPPORT

the command is not supported

ESP_AT_CMD_ERROR_CMD_EXEC_FAIL(result)

the command execution failed

ESP_AT_CMD_ERROR_CMD_PROCESSING

processing of previous command is in progress

ESP_AT_CMD_ERROR_CMD_OP_ERROR

the command operation type is error

Type Definitions

typedef int32_t (*at_read_data_fn_t)(uint8_t *data, int32_t len)
typedef int32_t (*at_write_data_fn_t)(uint8_t *data, int32_t len)
typedef int32_t (*at_get_data_len_fn_t)(void)
typedef void (*esp_at_port_specific_callback_t)(void)

AT specific callback type.

Enumerations

enum esp_at_status_type

esp_at_status some custom function interacting with AT

Values:

enumerator ESP_AT_STATUS_NORMAL

Normal mode.Now mcu can send AT command

enumerator ESP_AT_STATUS_TRANSMIT

Transparent Transmission mode

enum at_sleep_mode_t

Values:

enumerator AT_DISABLE_SLEEP
enumerator AT_MIN_MODEM_SLEEP
enumerator AT_LIGHT_SLEEP
enumerator AT_MAX_MODEM_SLEEP
enumerator AT_SLEEP_MAX
enum esp_at_module

module number,Now just AT module

Values:

enumerator ESP_AT_MODULE_NUM

AT module

enum esp_at_error_code

subcategory number

Values:

enumerator ESP_AT_SUB_OK

OK

enumerator ESP_AT_SUB_COMMON_ERROR

reserved

enumerator ESP_AT_SUB_NO_TERMINATOR

terminator character not found (“\r\n” expected)

enumerator ESP_AT_SUB_NO_AT

Starting “AT” not found (or at, At or aT entered)

enumerator ESP_AT_SUB_PARA_LENGTH_MISMATCH

parameter length mismatch

enumerator ESP_AT_SUB_PARA_TYPE_MISMATCH

parameter type mismatch

enumerator ESP_AT_SUB_PARA_NUM_MISMATCH

parameter number mismatch

enumerator ESP_AT_SUB_PARA_INVALID

the parameter is invalid

enumerator ESP_AT_SUB_PARA_PARSE_FAIL

parse parameter fail

enumerator ESP_AT_SUB_UNSUPPORT_CMD

the command is not supported

enumerator ESP_AT_SUB_CMD_EXEC_FAIL

the command execution failed

enumerator ESP_AT_SUB_CMD_PROCESSING

processing of previous command is in progress

enumerator ESP_AT_SUB_CMD_OP_ERROR

the command operation type is error

enum esp_at_para_parse_result_type

the result of AT parse

Values:

enumerator ESP_AT_PARA_PARSE_RESULT_FAIL

parse fail,Maybe the type of parameter is mismatched,or out of range

enumerator ESP_AT_PARA_PARSE_RESULT_OK

Successful

enumerator ESP_AT_PARA_PARSE_RESULT_OMITTED

the parameter is OMITTED.

enum esp_at_result_code_string_index

the result code of AT command processing

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

response nothing, just change internal status

enumerator ESP_AT_RESULT_CODE_PROCESS_DONE

response nothing, just change internal status

enumerator ESP_AT_RESULT_CODE_OK_AND_INPUT_PROMPT
enumerator ESP_AT_RESULT_CODE_MAX

Header File

Functions

const char *esp_at_get_current_module_name(void)

get current module name

const char *esp_at_get_module_name_by_id(uint32_t id)

get module name by index

uint32_t esp_at_get_module_id(void)

get current module id

void esp_at_set_module_id(uint32_t id)

Set current module id.

Parameters:

id – [in] the module id to set

void esp_at_set_module_id_by_str(const char *buffer)

Get module id by module name.

Parameters:

buffer – [in] pointer to a module name string

void esp_at_main_preprocess(void)

some workarounds for esp-at project

at_mfg_params_storage_mode_t at_get_mfg_params_storage_mode(void)

get storage mode of mfg parameters

Returns:

at_mfg_params_storage_mode_t

void esp_at_ready_before(void)

Do some things before esp-at is ready.

Note

This function can be overridden with custom implementation. For example, you can override this function to: a) execute some preset AT commands by calling at_exe_cmd() API. b) do some initializations by calling APIs from esp-idf or esp-at.

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

Write message into the log.

This function is not intended to be used directly. Instead, use one of ESP_AT_LOGE, ESP_AT_LOGW, ESP_AT_LOGI, ESP_AT_LOGD, ESP_AT_LOGV macros.

This function or these macros should not be used from an interrupt.

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

NVS operations for string and blob.

See also

nvs_set_str,nvs_get_str,nvs_set_blob,nvs_get_blob

Note

These functions can be overridden with custom implementations. For example: you can override these functions to encrypt the data before writing to NVS (decrypt the data after reading from NVS).

esp_err_t esp_at_nvs_get_str(nvs_handle_t handle, const char *key, char *out_value, size_t *length)
esp_err_t esp_at_nvs_set_blob(nvs_handle_t handle, const char *key, const void *value, size_t length)
esp_err_t esp_at_nvs_get_blob(nvs_handle_t handle, const char *key, void *out_value, size_t *length)
void esp_at_yield_if_idle_timeout(uint32_t idle_timeout_ms, uint32_t yield_ticks)

Yield the current task if the system has not recently executed the idle task.

This function measures the elapsed time since the last execution of the FreeRTOS idle hook. If that duration exceeds the specified threshold, the current task voluntarily delays for a given number of RTOS ticks to allow lower-priority tasks (including the idle task) to run.

This mechanism is intended to prevent long-running tasks from monopolizing the CPU under high workload conditions (e.g., heavy RX traffic), which may otherwise trigger the task watchdog.

Note

This function must not be called from ISR context.

Parameters:

  • idle_timeout_ms – [in] Threshold in milliseconds. If the time since the last idle hook execution exceeds this value, a yield is performed.

  • yield_ticks – [in] Number of RTOS ticks to delay when yielding.

Macros

ESP_AT_PORT_TX_WAIT_MS_MAX
AT_BUFFER_ON_STACK_SIZE
ESP_AT_LOG_BUFFER_HEXDUMP(tag, buffer, buff_len, level)

Same to ESP_LOG_BUFFER_HEXDUMP, but only output when buffer is not NULL.

CONFIG_AT_LOG_DEFAULT_LEVEL
ESP_AT_LOGE(tag, format, ...)

runtime macro to output logs at a specified level.

See also

printf

Parameters:

  • tag – tag of the log, which can be used to change the log level by esp_log_level_set at runtime.

  • format – format of the output log. See printf

  • ... – variables to be replaced into the log. See printf

ESP_AT_LOGW(tag, format, ...)
ESP_AT_LOGI(tag, format, ...)
ESP_AT_LOGD(tag, format, ...)
ESP_AT_LOGV(tag, format, ...)

Enumerations

enum at_mfg_params_storage_mode_t

Values:

enumerator AT_PARAMS_NONE
enumerator AT_PARAMS_IN_MFG_NVS
enumerator AT_PARAMS_IN_PARTITION

Provide feedback about this document