ESP-AT 用户指南 Choose target... Choose version... 入门 AT Binary 列表 AT 命令集 AT 命令示例 AT 版本简介 编译和开发 第三方开放云平台定制化 AT FAQ 缩写词索引 特别声明 关于 ESP-AT ESP-AT 用户指南 ESP-AT 用户指南 在 GitHub 上编辑 ESP-AT 用户指南 [English] 这里是乐鑫 ESP-AT 开发框架的文档中心。ESP-AT 作为由 Espressif Systems 发起和提供技术支持的官方项目，适用于 Windows、Linux、macOS 上的 ESP32、ESP32-C2、ESP32-C3、ESP32-C5、ESP32-C6、ESP32-C61、和 ESP32-S2 系列芯片。 本文档仅包含针对 ESP32 芯片的 ESP-AT 使用。如需了解其他芯片，请在页面左上方的下拉菜单中选择你的目标芯片。 入门 AT Binary 列表 AT 命令集 AT 命令示例 编译和开发 第三方定制化 AT 命令和固件 索引 提供有关此文档的反馈 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-AT 用户指南 Choose target... Choose version... 入门 AT Binary 列表 AT 命令集 AT 命令示例 AT 版本简介 编译和开发 如何本地编译 AT 工程 如何在 GitHub 网页上编译 AT 工程 如何修改 AT 管脚 如何添加自定义 AT 命令 如何提高 ESP-AT 吞吐性能 如何更新 mfg_nvs 分区 如何更新出厂参数 如何更新 PKI 配置 如何自定义低功耗蓝牙服务 如何自定义分区 如何使能 ESP32-AT 以太网 如何增加一个新的模组支持 如何实现 SDIO AT 如何基于乐鑫服务器实现自己的 OTA 管理 如何更新 ESP-IDF 版本 ESP-AT 固件差异 如何从 GitHub 下载最新临时版本 AT 固件 at.py 工具 ESP-AT API 参考 Header File Functions Structures Macros Type Definitions Enumerations Header File Functions Macros 如何配置 silence mode 如何启用更多 AT 调试日志 第三方开放云平台定制化 AT FAQ 缩写词索引 特别声明 关于 ESP-AT ESP-AT 用户指南 如何编译和开发自己的 AT 工程 AT API Reference 在 GitHub 上编辑 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 f