AT API Reference

Header File

• components/at/include/esp_at_core.h

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)

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

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

regist 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 Transmition 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

• components/at/include/esp_at.h

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)

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