From b3bd9fd49ba5bd174c46229a0f8f11f5f0ba5c9c Mon Sep 17 00:00:00 2001 From: Chen Wu Date: Thu, 31 Oct 2024 16:51:05 +0800 Subject: [PATCH] docs: Backported some AT command docs to esp8266 Includes the following AT commands: - AT+USERRAM - AT+USEROTA - AT+USERWKMCUCFG - AT+USERMCUSLEEP - AT+CIPSTATE - AT+CWSTATE --- docs/en/AT_Command_Set/Basic_AT_Commands.rst | 84 ----- docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst | 50 ++- docs/en/AT_Command_Set/index.rst | 1 + docs/en/AT_Command_Set/user_at_commands.rst | 297 ++++++++++++++++++ .../AT_Command_Set/Basic_AT_Commands.rst | 85 ----- .../AT_Command_Set/TCP-IP_AT_Commands.rst | 48 ++- .../AT_Command_Set/Wi-Fi_AT_Commands.rst | 45 +++ docs/zh_CN/AT_Command_Set/index.rst | 1 + .../zh_CN/AT_Command_Set/user_at_commands.rst | 297 ++++++++++++++++++ 9 files changed, 734 insertions(+), 174 deletions(-) create mode 100644 docs/en/AT_Command_Set/user_at_commands.rst create mode 100644 docs/zh_CN/AT_Command_Set/user_at_commands.rst diff --git a/docs/en/AT_Command_Set/Basic_AT_Commands.rst b/docs/en/AT_Command_Set/Basic_AT_Commands.rst index a0c11a146..d9dfbccde 100644 --- a/docs/en/AT_Command_Set/Basic_AT_Commands.rst +++ b/docs/en/AT_Command_Set/Basic_AT_Commands.rst @@ -17,7 +17,6 @@ Basic AT Commands - :ref:`AT+SLEEP `: Set the sleep mode. - :ref:`AT+SYSRAM `: Query current remaining heap size and minimum heap size. - :ref:`AT+SYSMSG `: Query/Set System Prompt Information. -- :ref:`AT+USERRAM `: Operate user's free RAM. - :ref:`AT+SYSFLASH `: Query/Set User Partitions in Flash. - [ESP32 Only] :ref:`AT+FS `: Filesystem Operations. - :ref:`AT+RFPOWER `: Query/Set RF TX Power. @@ -625,89 +624,6 @@ Example // print no prompt info when the connection status is changed AT+SYSMSG=2 -.. _cmd-USERRAM: - -:ref:`AT+USERRAM `: Operate user's free RAM ------------------------------------------------------- - -Query Command -^^^^^^^^^^^^^ - -**Function:** - -Query the current available user's RAM size. - -**Command:** - -:: - - AT+USERRAM? - -**Response:** - -:: - - +USERRAM: - OK - -Set Command -^^^^^^^^^^^ - -**Function:** - -Operate user's free RAM - -**Command:** - -:: - - AT+USERRAM=,[,] - -**Response:** - -:: - +USERRAM:, // esp-at returns this response only when the operator is ``read`` - - OK - -Parameters -^^^^^^^^^^ - -- ****: - - - 0: release user's RAM - - 1: malloc user's RAM - - 2: write user's RAM - - 3: read user's RAM - - 4: clear user's RAM - -- ****: the size to malloc/read/write -- ****: the offset to read/write. Default: 0 - -Notes -^^^^^ - -- Please malloc the RAM size before you perform any other operations. -- If the operator is ``write``, wrap return ``>`` after the write command, then you can send the data that you want to write. The length should be parameter ````. -- If the operator is ``read`` and the length is bigger than 1024, ESP-AT will reply multiple times in the same format, each reply can carry up to 1024 bytes of data, and eventually end up with ``\r\nOK\r\n``. - -Example -^^^^^^^^ - -:: - - // malloc 1 KB user's RAM - AT+USERRAM=1,1024 - - // write 500 bytes to RAM (offset: 0) - AT+USERRAM=2,500 - - // read 64 bytes from RAM offset 100 - AT+USERRAM=3,64,100 - - // free the user's RAM - AT+USERRAM=0 - .. _cmd-SYSFLASH: :ref:`AT+SYSFLASH `: Query/Set User Partitions in Flash diff --git a/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst b/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst index f2acb64d5..8964ca89f 100644 --- a/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst +++ b/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst @@ -6,7 +6,8 @@ TCP/IP AT Commands :link_to_translation:`zh_CN:[中文]` - :ref:`AT+CIPV6 `: Enable/disable the network of Internet Protocol Version 6 (IPv6). -- :ref:`AT+CIPSTATUS `: Obtain the TCP/UDP/SSL connection status and information. +- :ref:`AT+CIPSTATE `: Obtain the TCP/UDP/SSL connection information. +- :ref:`AT+CIPSTATUS (deprecated) `: Obtain the TCP/UDP/SSL connection status and information. - :ref:`AT+CIPDOMAIN `: Resolve a Domain Name. - :ref:`AT+CIPSTART `: Establish TCP connection, UDP transmission, or SSL connection. - :ref:`AT+CIPSTARTEX `: Establish TCP connection, UDP transmission, or SSL connection with an automatically assigned ID. @@ -96,11 +97,54 @@ Notes - You should enable IPv6 network before using IPv6 related upper layer AT commands (TCP/UDP/SSL/PING/DNS based on IPv6 network, also known as TCP6/UDP6/SSL6/PING6/DNS6 or TCPv6/UDPv6/SSLv6/PINGv6/DNSv6). -.. _cmd-STATUS: +.. _cmd-IPSTATE: -:ref:`AT+CIPSTATUS `: Obtain the TCP/UDP/SSL Connection Status and Information +:ref:`AT+CIPSTATE `: Obtain the TCP/UDP/SSL Connection Information ---------------------------------------------------------------------------------------- +Query Command +^^^^^^^^^^^^^^^ + +**Command:** + +:: + + AT+CIPSTATE? + +**Response:** + +When there is a connection, AT returns: + +:: + + +CIPSTATE:,<"type">,<"remote IP">,,, + + OK + +When there is no connection, AT returns: + +:: + + OK + +Parameters +^^^^^^^^^^ + +- ****: ID of the connection (0~4), used for multiple connections. +- **<"type">**: string parameter showing the type of transmission: "TCP", "TCPv6", "UDP", "UDPv6", "SSL", or "SSLv6". +- **<"remote IP">**: string parameter showing the remote IPv4 address or IPv6 address. +- ****: the remote port number. +- ****: the local port number. +- ****: + + - 0: ESP runs as a client. + - 1: ESP runs as a server. + +.. _cmd-STATUS: + +:ref:`AT+CIPSTATUS (deprecated) `: Obtain the TCP/UDP/SSL Connection Status and Information +----------------------------------------------------------------------------------------------------- + Execute Command ^^^^^^^^^^^^^^^ diff --git a/docs/en/AT_Command_Set/index.rst b/docs/en/AT_Command_Set/index.rst index 37832ac11..b007be898 100755 --- a/docs/en/AT_Command_Set/index.rst +++ b/docs/en/AT_Command_Set/index.rst @@ -20,6 +20,7 @@ Here is a list of AT commands. Some of them can only work on the ESP32 series, s [ESP8266 Only] Signaling Test AT Commands Web server AT Commands [ESP32 & ESP32S2 & ESP32-C3] Driver AT Commands + User AT Commands AT Command Set Comparison It is strongly recommended to read the following sections for some common information on AT commands before you dive into the details of each command. diff --git a/docs/en/AT_Command_Set/user_at_commands.rst b/docs/en/AT_Command_Set/user_at_commands.rst new file mode 100644 index 000000000..14b409f35 --- /dev/null +++ b/docs/en/AT_Command_Set/user_at_commands.rst @@ -0,0 +1,297 @@ +.. _User-AT: + +User AT Commands +================= + +:link_to_translation:`zh_CN:[中文]` + +- :ref:`AT+USERRAM `: Operate user's free RAM. +- :ref:`AT+USEROTA `: Upgrade the firmware according to the specified URL. +- :ref:`AT+USERWKMCUCFG `: Configure how AT wakes up MCU. +- :ref:`AT+USERMCUSLEEP `: MCU indicates its sleep state. + +.. _cmd-USERRAM: + +:ref:`AT+USERRAM `: Operate user's free RAM +------------------------------------------------------ + +Query Command +^^^^^^^^^^^^^ + +**Function:** + +Query the current available user's RAM size. + +**Command:** + +:: + + AT+USERRAM? + +**Response:** + +:: + + +USERRAM: + OK + +Set Command +^^^^^^^^^^^ + +**Function:** + +Allocate, read, write, erase, and free user's RAM + +**Command:** + +:: + + AT+USERRAM=,[,] + +**Response:** + +:: + + +USERRAM:, // esp-at returns this response only when the operator is ``read`` + + OK + +Parameters +^^^^^^^^^^ + +- ****: + + - 0: release user's RAM + - 1: malloc user's RAM + - 2: write user's RAM + - 3: read user's RAM + - 4: clear user's RAM + +- ****: the size to malloc/read/write +- ****: the offset to read/write. Default: 0 + +Notes +^^^^^ + +- Please malloc the RAM size before you perform any other operations. +- If the operator is ``write``, wrap return ``>`` after the write command, then you can send the data that you want to write. The length should be parameter ````. +- If the operator is ``read`` and the length is bigger than 1024, ESP-AT will reply multiple times in the same format, each reply can carry up to 1024 bytes of data, and eventually end up with ``\r\nOK\r\n``. + +Example +^^^^^^^^ + +:: + + // malloc 1 KB user's RAM + AT+USERRAM=1,1024 + + // write 500 bytes to RAM (offset: 0) + AT+USERRAM=2,500 + + // read 64 bytes from RAM offset 100 + AT+USERRAM=3,64,100 + + // free the user's RAM + AT+USERRAM=0 + +.. _cmd-USEROTA: + +:ref:`AT+USEROTA `: Upgrade the Firmware According to the Specified URL +----------------------------------------------------------------------------------------------------- + +ESP-AT upgrades firmware at runtime by downloading the new firmware from a specific URL. + +Set Command +^^^^^^^^^^^ + +**Function:** + +Upgrade to the firmware version specified by the URL. + +**Command:** + +:: + + AT+USEROTA= + +**Response:** + +:: + + OK + + > + +This response indicates that AT is ready for receiving URL. You should enter the URL, and when the URL length reaches the ```` value, the system returns: + +:: + + Recv bytes + +After AT outputs the above information, the upgrade process starts. If the upgrade process is complete, the system returns: + +:: + + OK + +If the parameter is wrong or firmware upgrades fails, the system returns: + +:: + + ERROR + +Parameters +^^^^^^^^^^ + +- ****: URL length. Maximum: 8192 bytes. + +Note +^^^^^ + +- You can `Download AT firmware from GitHub Actions `_, or you can generate OTA firmware from :doc:`Compile ESP-AT Project <../Compile_and_Develop/How_to_clone_project_and_compile_it>` as well. +- OTA firmware is ``build/esp-at.bin``. +- The speed of the upgrade depends on the network status. +- If the upgrade fails due to unfavorable network conditions, AT will return ``ERROR``. Please wait for some time before retrying. +- Downgrading to an older version is not recommended due to potential compatibility issues and the risk of operational failure. If you still prefer downgrading to an older version, please test and verify the functionality based on your product. +- After you upgrade the AT firmware, you are suggested to call the command :ref:`AT+RESTORE ` to restore the factory default settings. +- ``AT+USEROTA`` only supports ``HTTP``. +- After AT outputs the ``>`` character, the special characters in the URL does not need to be escaped through the escape character, and it does not need to end with a new line (CR-LF). +- Please refer to :doc:`../Compile_and_Develop/How_to_implement_OTA_update` for more OTA commands. + +Example +^^^^^^^^ + +:: + + AT+USEROTA=36 + + OK + + > + Recv 36 bytes + + OK + +.. _cmd-USERWKMCUCFG: + +:ref:`AT+USERWKMCUCFG `: Configure How AT Wakes up MCU +--------------------------------------------------------------- + +Set Command +^^^^^^^^^^^ + +**Function:** + +This command configures how AT checks whether MCU is in awake state and how to wake it up. + +- If MCU is in awake state, AT will directly send the data to it without waking it up. +- If MCU is in sleep state and AT is ready to actively send the data to MCU (the data sent actively is the same as defined in `ESP-AT Message Reports `_), AT will first send wake signals to MCU and then send the data. The wake signals will be cleared after MCU wakes up or times out. + +**Command:** + +:: + + AT+USERWKMCUCFG=,,,,[,] + +**Response:** + +:: + + OK + +Parameters +^^^^^^^^^^ + +- ****: Enable or disable wake-up configuration. + + - 0: Disable wake-up configuration + - 1: Enable wake-up configuration + +- ****: Wake mode. + + - 1: GPIO wake-up + - 2: UART wake-up + +- ****: It means differently depending on the parameter ````. + + - If ```` is 1, ```` represents GPIO number for wake-up. You need to ensure that the configured GPIO wake-up pin is not used for other purposes. Otherwise, you need to perform compatibility processing. + - If ```` is 2, ```` represents UART number. Currently, only 1 is supported for ````, which means only UART1 can wake up MCU. + +- ****: It means differently depending on the parameter ````. + + - If ```` is 1, ```` represents wake-up level. + + - 0: Low level + - 1: High level + + - If ```` is 2, ```` represents wake-up byte. Range: [0,255]. + +- ****: Maximum waiting time. Unit: milliseconds. Range: [0,60000]. It means differently depending on the parameter ````. + + - If ```` is 1, the ```` level will be held on during the ````. After the ```` is reached, the ```` level is reversed. + - If ```` is 2, AT will send ```` byte immediately and wait until timeout. + +- ****: AT checks whether MCU is in awake state. + + - Bit 0: Whether to enable :ref:`AT+USERMCUSLEEP ` command linkage. Enabled by default. That is, when receiving AT+USERMCUSLEEP=0 command from MCU, AT knows that MCU is in awake state; when receiving AT+USERMCUSLEEP=1 command, AT knows that MCU is in sleep. + - Bit 1: Whether to enable :ref:`AT+SLEEP=0/1/2/3 ` command linkage. Disabled by default. That is, when receiving AT+SLEEP=0 command, AT knows that MCU is in awake state; when receiving AT+SLEEP=1/2/3 command, AT knows that MCU is in sleep. + - Bit 2: Whether to enable the function of indicating MCU state after ```` timeout. Disabled by default. That is, when disabled, it indicates that MCU is in sleep after ````; when enabled, it indicates that MCU is in awake state after ````. + - Bit 3 (not implemented yet): Whether to enable the function of indicating MCU state via GPIO. Unsupported by default. + +Notes +^^^^^ + +- This command needs to be configured only once. +- Each time before the AT actively sends data to MCU, it will send a wake-up signal first and then enter the waiting time. When ```` is reached, it will directly send data. This wait timeout will reduce the transmission efficiency with MCU. +- If AT receives any wake-up event in ```` before ````, it will immediately clear the wake-up state; otherwise, the wake-up state will be cleared automatically after the ```` timeout. + +Example +^^^^^^^ + +:: + + // Enable wake-up MCU configuration. Before each time the AT sends data to the MCU, it will first use the GPIO18 pin of the Wi-Fi module to wake up the MCU at a high level and hold on the high level for 10 seconds. + AT+USERWKMCUCFG=1,1,18,1,10000,3 + + // Enable wake-up configuration + AT+USERWKMCUCFG=0 + +.. _cmd-USERMCUSLEEP: + +:ref:`AT+USERMCUSLEEP `: MCU Indicates Its Sleep State +--------------------------------------------------------------- + +Set Command +^^^^^^^^^^^ + +**Function:** + +This command can only take effect after the ```` Bit 0 of the :ref:`AT+USERWKMCUCFG ` command is configured. It informs AT of the current MCU sleep state. + +**Command:** + +:: + + AT+USERMCUSLEEP= + +**Response:** + +:: + + OK + +Parameters +^^^^^^^^^^ + +- ****: + + - 0: Indicates that MCU is in awake state. + - 1: Indicates that MCU is in sleep state. + +Example +^^^^^^^ + +:: + + // MCU tells AT that the current MCU is in awake state + AT+USERMCUSLEEP=0 diff --git a/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst index 2a9586894..c6f799782 100644 --- a/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst @@ -17,7 +17,6 @@ - :ref:`AT+SLEEP `：设置 sleep 模式 - :ref:`AT+SYSRAM `：查询当前剩余堆空间和最小堆空间 - :ref:`AT+SYSMSG `：查询/设置系统提示信息 -- :ref:`AT+USERRAM `：操作用户的空闲 RAM - :ref:`AT+SYSFLASH `：查询或读写 flash 用户分区 - [ESP32 Only] :ref:`AT+FS `：文件系统操作 - :ref:`AT+RFPOWER `：查询/设置 RF TX Power @@ -613,90 +612,6 @@ // 连接状态发生改变时不打印信息 AT+SYSMSG=2 -.. _cmd-USERRAM: - -:ref:`AT+USERRAM `: 操作用户的空闲 RAM ----------------------------------------------------------- -查询命令 -^^^^^^^^ - -**功能：** - -查询用户当前可用的空闲 RAM 大小 - -**命令：** - -:: - - AT+USERRAM? - -**响应：** - -:: - - +USERRAM: - - OK - -设置命令 -^^^^^^^^ - -**功能：** - -分配、读、写、擦除、释放用户 RAM 空间 - -**命令：** - -:: - - AT+USERRAM=,[,] - -**响应：** - -:: - - +USERRAM:, // 只有是读操作时，才会有这个回复 - - OK - -参数 -^^^^ - -- ****： - - - 0：释放用户 RAM 空间 - - 1：分配用户 RAM 空间 - - 2：向用户 RAM 写数据 - - 3：从用户 RAM 读数据 - - 4：清除用户 RAM 上的数据 - -- ****: 分配/读/写的用户 RAM 大小 -- ****: 读/写 RAM 的偏移量。默认：0 - -说明 -^^^^ - -- 请在执行任何其他操作之前分配用户 RAM 空间。 -- 当 ```` 为 ``write`` 时，系统收到此命令后先换行返回 ``>``，此时您可以输入要写的数据，数据长度应与 ```` 一致。 -- 当 ```` 为 ``read`` 时并且长度大于 1024，ESP-AT 会以同样格式多次回复，每次回复最多携带 1024 字节数据，最终以 ``\r\nOK\r\n`` 结束。 - -示例 -^^^^ - -:: - - // 分配 1 KB 用户 RAM 空间 - AT+USERRAM=1,1024 - - // 向 RAM 空间开始位置写入 500 字节数据 - AT+USERRAM=2,500 - - // 从 RAM 空间偏移 100 位置读取 64 字节数据 - AT+USERRAM=3,64,100 - - // 释放用户 RAM 空间 - AT+USERRAM=0 - .. _cmd-SYSFLASH: :ref:`AT+SYSFLASH `：查询或读写 flash 用户分区 diff --git a/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst index 1d79a77db..ddc7cf23d 100644 --- a/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst @@ -6,7 +6,8 @@ TCP/IP AT 命令 :link_to_translation:`en:[English]` - :ref:`AT+CIPV6 `: 启用/禁用 IPv6 网络 (IPv6) -- :ref:`AT+CIPSTATUS `：查询 TCP/UDP/SSL 连接状态和信息 +- :ref:`AT+CIPSTATE `：查询 TCP/UDP/SSL 连接信息 +- :ref:`AT+CIPSTATUS (弃用) `：查询 TCP/UDP/SSL 连接状态和信息 - :ref:`AT+CIPDOMAIN `：域名解析 - :ref:`AT+CIPSTART `：建立 TCP 连接、UDP 传输或 SSL 连接 - :ref:`AT+CIPSTARTEX `：建立自动分配 ID 的 TCP 连接、UDP 传输或 SSL 连接 @@ -96,9 +97,52 @@ TCP/IP AT 命令 - 在使用基于 IPv6 网络的上层应用前，需要先启用 IPv6 网络。（例如：基于 IPv6 网络使用 TCP/UDP/SSL/PING/DNS，也称为 TCP6/UDP6/SSL6/PING6/DNS6 或 TCPv6/UDPv6/SSLv6/PINGv6/DNSv6） +.. _cmd-IPSTATE: + +:ref:`AT+CIPSTATE `：查询 TCP/UDP/SSL 连接信息 +----------------------------------------------------------------------------------------- + +查询命令 +^^^^^^^^ + +**命令：** + +:: + + AT+CIPSTATE? + +**响应：** + +当有连接时，AT 返回： + +:: + + +CIPSTATE:,<"type">,<"remote IP">,,, + + OK + +当没有连接时，AT 返回： + +:: + + OK + +参数 +^^^^ + +- ****：网络连接 ID (0 ~ 4)，用于多连接的情况 +- **<"type">**：字符串参数，表示传输类型："TCP"、"UDP"、"SSL"、"TCPv6"、"UDPv6" 或 "SSLv6" +- **<"remote IP">**：字符串参数，表示远端 IPv4 地址或 IPv6 地址 +- ****：远端端口值 +- ****：本地端口值 +- ****: + + - 0: ESP 设备作为客户端 + - 1: ESP 设备作为服务器 + .. _cmd-STATUS: -:ref:`AT+CIPSTATUS `：查询 TCP/UDP/SSL 连接状态和信息 +:ref:`AT+CIPSTATUS (弃用) `：查询 TCP/UDP/SSL 连接状态和信息 ----------------------------------------------------------------------------------------- 执行命令 diff --git a/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst index e66069286..4df9b02a0 100644 --- a/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst @@ -6,6 +6,7 @@ Wi-Fi AT 命令集 :link_to_translation:`en:[English]` - :ref:`AT+CWMODE `：查询/设置 Wi-Fi 模式 (Station/SoftAP/Station+SoftAP) +- :ref:`AT+CWSTATE `：查询 Wi-Fi 状态和 Wi-Fi 信息 - :ref:`AT+CWJAP `：连接 AP - :ref:`AT+CWRECONNCFG `：查询/设置 Wi-Fi 重连配置 - :ref:`AT+CWLAPOPT `：设置 :ref:`AT+CWLAP ` 命令扫描结果的属性 @@ -102,6 +103,50 @@ Wi-Fi AT 命令集 AT+CWMODE=3 +.. _cmd-WSTATE: + +:ref:`AT+CWSTATE `：查询 Wi-Fi 状态和 Wi-Fi 信息 +------------------------------------------------------------- + +查询命令 +^^^^^^^^ + +**功能：** + +查询 ESP 设备的 Wi-Fi 状态和 Wi-Fi 信息 + +**命令：** + +:: + + AT+CWSTATE? + +**响应：** + +:: + + +CWSTATE:,<"ssid"> + + OK + +参数 +^^^^ + +- ****：当前 Wi-Fi 状态 + + - 0: ESP station 尚未进行任何 Wi-Fi 连接 + - 1: ESP station 已经连接上 AP，但尚未获取到 IPv4 地址 + - 2: ESP station 已经连接上 AP，并已经获取到 IPv4 地址 + - 3: ESP station 正在进行 Wi-Fi 连接或 Wi-Fi 重连 + - 4: ESP station 处于 Wi-Fi 断开状态 + +- **<"ssid">**：目标 AP 的 SSID + +说明 +^^^^ + +- 当 ESP station 没有连接上 AP 时，推荐使用此命令查询 Wi-Fi 信息；当 ESP station 已连接上 AP 后，推荐使用 :ref:`AT+CWJAP ` 命令查询 Wi-Fi 信息 + .. _cmd-JAP: :ref:`AT+CWJAP `：连接 AP diff --git a/docs/zh_CN/AT_Command_Set/index.rst b/docs/zh_CN/AT_Command_Set/index.rst index d81600375..6ceebdbec 100755 --- a/docs/zh_CN/AT_Command_Set/index.rst +++ b/docs/zh_CN/AT_Command_Set/index.rst @@ -20,6 +20,7 @@ AT 命令集 [ESP8266 Only] 信令测试 AT 命令集 [ESP32 & ESP32-S2 & ESP32-C3] 驱动 AT 命令集 web 服务器 AT 命令集 + 用户 AT 命令集 AT 命令集对比 强烈建议在使用命令之前先阅读以下内容，了解 AT 命令的一些基本信息。 diff --git a/docs/zh_CN/AT_Command_Set/user_at_commands.rst b/docs/zh_CN/AT_Command_Set/user_at_commands.rst new file mode 100644 index 000000000..0a319a0bf --- /dev/null +++ b/docs/zh_CN/AT_Command_Set/user_at_commands.rst @@ -0,0 +1,297 @@ +.. _User-AT: + +用户 AT 命令 +================= + +:link_to_translation:`en:[English]` + +- :ref:`AT+USERRAM `：操作用户的空闲 RAM +- :ref:`AT+USEROTA `：根据指定 URL 升级固件 +- :ref:`AT+USERWKMCUCFG `：设置 AT 唤醒 MCU 的配置 +- :ref:`AT+USERMCUSLEEP `：MCU 指示自己睡眠状态 + +.. _cmd-USERRAM: + +:ref:`AT+USERRAM `: 操作用户的空闲 RAM +---------------------------------------------------------- +查询命令 +^^^^^^^^ + +**功能：** + +查询用户当前可用的 RAM 大小 + +**命令：** + +:: + + AT+USERRAM? + +**响应：** + +:: + + +USERRAM: + + OK + +设置命令 +^^^^^^^^ + +**功能：** + +分配、读、写、擦除、释放用户 RAM 空间 + +**命令：** + +:: + + AT+USERRAM=,[,] + +**响应：** + +:: + + +USERRAM:, // 只有是读操作时，才会有这个回复 + + OK + +参数 +^^^^ + +- ****： + + - 0：释放用户 RAM 空间 + - 1：分配用户 RAM 空间 + - 2：向用户 RAM 写数据 + - 3：从用户 RAM 读数据 + - 4：清除用户 RAM 上的数据 + +- ****: 分配/读/写的用户 RAM 大小 +- ****: 读/写 RAM 的偏移量。默认值：0 + +说明 +^^^^ + +- 请在执行任何其他操作之前分配用户 RAM 空间。 +- 当 ```` 为 ``write`` 时，系统收到此命令后先换行返回 ``>``，此时您可以输入要写的数据，数据长度应与 ```` 一致。 +- 当 ```` 为 ``read`` 时并且长度大于 1024，ESP-AT 会以同样格式多次回复，每次回复最多携带 1024 字节数据，最终以 ``\r\nOK\r\n`` 结束。 + +示例 +^^^^ + +:: + + // 分配 1 KB 用户 RAM 空间 + AT+USERRAM=1,1024 + + // 向 RAM 空间开始位置写入 500 字节数据 + AT+USERRAM=2,500 + + // 从 RAM 空间偏移 100 位置读取 64 字节数据 + AT+USERRAM=3,64,100 + + // 释放用户 RAM 空间 + AT+USERRAM=0 + +.. _cmd-USEROTA: + +:ref:`AT+USEROTA `：根据指定 URL 升级固件 +--------------------------------------------------------------------- + +ESP-AT 在运行时，通过从指定 URL 下载新固件进行升级。 + +设置命令 +^^^^^^^^ + +**功能：** + +升级到 URL 指定版本的固件 + +**命令：** + +:: + + AT+USEROTA= + +**响应：** + +:: + + OK + + > + +上述响应表示 AT 已准备好接收 URL，此时您可以输入 URL，当 AT 接收到的 URL 长度达到 ```` 后，返回： + +:: + + Recv bytes + +AT 输出上述信息之后，升级过程开始。如果升级完成，返回： + +:: + + OK + +如果参数错误或者固件升级失败，返回： + +:: + + ERROR + +参数 +^^^^ + +- ****：URL 长度。最大值：8192 字节 + +说明 +^^^^ + +- 您可以 `从 GitHub Actions 里下载 `_ 所需要的 OTA 固件，也可以自行 :doc:`编译 ESP-AT 工程 <../Compile_and_Develop/How_to_clone_project_and_compile_it>` 生成所需要的 OTA 固件。 +- OTA 固件为 ``build/esp-at.bin``。 +- 升级速度取决于网络状况。 +- 如果网络条件不佳导致升级失败，AT 将返回 ``ERROR``，请等待一段时间再试。 +- 不建议降级到旧版本。降到旧版本可能会出现兼容性问题和无法运行的风险。如果您坚持要降级到旧版本，请根据您的产品自行测试验证功能。 +- 建议升级 AT 固件后，调用 :ref:`AT+RESTORE ` 恢复出厂设置。 +- ``AT+USEROTA`` 仅支持 ``HTTP``。 +- AT 输出 ``>`` 字符后，数据中的特殊字符不需要转义字符进行转义，也不需要以新行结尾 (CR-LF)。 +- 请参考 :doc:`../Compile_and_Develop/How_to_implement_OTA_update` 获取更多 OTA 命令。 + +示例 +^^^^ + +:: + + AT+USEROTA=36 + + OK + + > + Recv 36 bytes + + OK + +.. _cmd-USERWKMCUCFG: + +:ref:`AT+USERWKMCUCFG `：设置 AT 唤醒 MCU 的配置 +--------------------------------------------------------------------- + +设置命令 +^^^^^^^^ + +**功能：** + +此命令配置 AT 如何检查 MCU 的唤醒状态，以及 AT 如何唤醒 MCU。 + +- 当 MCU 是醒来的状态，AT 将直接向 MCU 发送数据，不会发送唤醒信号。 +- 当 MCU 是睡眠的状态，AT 准备向 MCU 主动发送数据时（主动发送的数据和 `ESP-AT 消息报告 `_ 中定义的相同），AT 会先发送唤醒信号再发送数据。MCU 被唤醒或者超时后会清除唤醒信号。 + +**命令：** + +:: + + AT+USERWKMCUCFG=,,,,[,] + +**响应：** + +:: + + OK + +参数 +^^^^ + +- ****：启用或禁用唤醒配置。 + + - 0：禁用唤醒 MCU 配置 + - 1：使能唤醒 MCU 配置 + +- ****：唤醒模式。 + + - 1：GPIO 唤醒 + - 2：UART 唤醒 + +- ****：该参数的意义取决于 ```` 的值。 + + - 如果 ```` 是 1，```` 代表唤醒管脚 GPIO 编号。用户需要保证配置的唤醒管脚没有用作其它用途，否则需要用户做兼容性处理。 + - 如果 ```` 是 2，```` 代表唤醒 UART 编号。当前只支持 1，即支持 UART1 唤醒 MCU。 + +- ****：该参数的意义取决于 ```` 的值。 + + - 如果 ```` 是 1，```` 代表唤醒电平。 + + - 0：低电平 + - 1：高电平 + + - 如果 ```` 是 2，```` 代表唤醒字节。范围：[0,255]。 + +- ****：最长等待时间。单位：毫秒。范围：[0,60000]。该参数的意义取决于 ```` 的值。 + + - 如果 ```` 是 1，则在 ```` 期间内，将一直保持 ```` 电平。```` 到后，则反转 ```` 电平。 + - 如果 ```` 是 2，则立即发送 ```` 字节，进入等待直到超时。 + +- ****：AT 检查 MCU 是否处于醒来的状态。 + + - Bit 0：是否开启与 :ref:`AT+USERMCUSLEEP ` 命令的关联。默认开启。即：收到 AT+USERMCUSLEEP=0 命令，指示 MCU 醒来；收到 AT+USERMCUSLEEP=1 命令，指示 MCU 睡眠。 + - Bit 1：是否开启与 :ref:`AT+SLEEP=0/1/2/3 ` 命令的关联。默认禁用。即：收到 AT+SLEEP=0 命令，指示 MCU 醒来；收到 AT+SLEEP=1/2/3 命令，指示 MCU 睡眠。 + - Bit 2：是否开启 ```` 超时后指示 MCU 醒来功能。默认禁用。即：禁用时，delay time 后，指示 MCU 睡眠；使能时，delay time 后，指示 MCU 醒来。 + - Bit 3（暂未实现）：是否开启 GPIO 指示 MCU 醒来功能。默认不支持。 + +说明 +^^^^ + +- 此命令只需要配置一次。 +- 每次 AT 向 MCU 主动发送数据前，会先发送唤醒信号再进入等待，```` 时间到了之后直接发送数据。此超时会降低与 MCU 间的传输效率。 +- 如果在 ```` 毫秒之前，AT 收到 ```` 里的任意唤醒事件，则立即清除唤醒状态；否则会等待 ```` 超时后，会自动清除唤醒状态。 + +示例 +^^^^ + +:: + + // 使能唤醒 MCU 配置。每次 AT 向 MCU 发送数据前，会先使用 Wi-Fi 模块的 GPIO18 管脚，高电平唤醒 MCU，同时保持高电平 10 秒。 + AT+USERWKMCUCFG=1,1,18,1,10000,3 + + // 禁用唤醒 MCU 配置 + AT+USERWKMCUCFG=0 + +.. _cmd-USERMCUSLEEP: + +:ref:`AT+USERMCUSLEEP `：MCU 指示自己睡眠状态 +----------------------------------------------------------- + +设置命令 +^^^^^^^^ + +**功能：** + +在 :ref:`AT+USERWKMCUCFG ` 命令的 ```` Bit 0 配置情况下，此命令才会生效。用于告知 AT 当前 MCU 的睡眠状态。 + +**命令：** + +:: + + AT+USERMCUSLEEP= + +**响应：** + +:: + + OK + +参数 +^^^^ + +- ****： + + - 0：指示 MCU 醒来。 + - 1：指示 MCU 睡眠。 + +示例 +^^^^ + +:: + + // MCU 告知 AT 当前 MCU 醒来 + AT+USERMCUSLEEP=0