Merge branch 'docs/update_at_commands_description' into 'master'

docs: update AT commands description See merge request application/esp-at!1029
espressif · Dec 24, 2021 · 9ff1373 · 9ff1373
2 parents dcb5ce1 + 4bb1239
commit 9ff1373
Show file tree

Hide file tree

Showing 6 changed files with 273 additions and 138 deletions.
diff --git a/docs/en/AT_Command_Set/BLE_AT_Commands.rst b/docs/en/AT_Command_Set/BLE_AT_Commands.rst
@@ -118,6 +118,7 @@ Parameter
 Notes
 ^^^^^
 
+-  When using Bluetooth LE function, if you do not need to use SoftAP mode, it is recommended that you can disable the mode through :ref:`AT+CWMODE <cmd-MODE>`.
 -  The file "at_customize.bin" has to be downloaded, so that the relevant commands can be used. Please refer to :doc:`../Compile_and_Develop/How_to_customize_BLE_services` for more details.
 -  Before using other Bluetooth LE AT commands, you should run this command first to trigger the initialization process.
 -  After the initialization, the Bluetooth LE role cannot be changed unless you run :ref:`AT+RST <cmd-RST>` to restart the system first and then re-initialize the Bluetooth LE role.
@@ -1834,8 +1835,7 @@ Notes
 
 -  In Bluetooth LE client, the property of tx characteristic must be ``write with response`` or ``write without response``, and the property of rx characteristic must be ``indicate`` or ``notify``.
 -  In Bluetooth LE server, the property of tx characteristic must be ``indicate`` or ``notify``, and the property of rx characteristic must be ``write with response`` or ``write without response``.
--  If the automatic reconnection function is disabled, when the connection is disconnected, a disconnection message is displayed (depending on AT+SYSMSG), customer need to send the connection command again. 
--  If the automatic reconnection function is enabled, the connection will be automatically reconnected after disconnection, and the MCU side will not be aware of the disconnection. If the MAC of the peer end changes, the connection will fail.
+-  If the automatic reconnection function is disabled, when the connection is disconnected, a disconnection message is displayed (depending on AT+SYSMSG), you need to send the connection command again; If this function is enabled, the connection will be automatically reconnected after disconnection, and the MCU side will not be aware of the disconnection. If the MAC of the peer end changes, the connection will fail.
 
 Example
 ^^^^^^^^

diff --git a/docs/en/AT_Command_Set/Driver_AT_Commands.rst b/docs/en/AT_Command_Set/Driver_AT_Commands.rst
@@ -37,34 +37,99 @@ Set Command
 ::
 
     +DRVADC:<raw data>
+
     OK
 
 Parameters
 ^^^^^^^^^^
 
--  **<channel>**: ADC1 channel. Range: 0 ~ 7. See datasheets for corresponding pins.
+-  **<channel>**: ADC1 channel.
+
+   - For ESP32 devices, the range is [0,7].
+
+     .. list-table::
+      :header-rows: 1
+
+      * - CHANNEL
+        - GPIO
+      * - 0
+        - GPIO36
+      * - 1
+        - GPIO37
+      * - 2
+        - GPIO38
+      * - 3
+        - GPIO39
+      * - 4
+        - GPIO32
+      * - 5
+        - GPIO33
+      * - 6
+        - GPIO34
+      * - 7
+        - GPIO35
+
+   - For ESP32-C3 devices, the range is [0,4].
+
+     .. list-table::
+      :header-rows: 1
+
+      * - CHANNEL
+        - GPIO
+      * - 0
+        - GPIO0
+      * - 1
+        - GPIO1
+      * - 2
+        - GPIO2
+      * - 3
+        - GPIO3
+      * - 4
+        - GPIO4
+
 -  **<atten>**: attenuation.
 
-   -  0: 0 dB attenuation gives full-scale voltage 1.1 V.
-   -  1: 2.5 dB attenuation gives full-scale voltage 1.5 V.
-   -  2: 6 dB attenuation gives full-scale voltage 2.2 V.
-   -  3: 11 dB attenuation gives full-scale voltage 3.9 V.
+   - For ESP32 devices:
+
+     -  0: 0 dB attenuation, effective measurement range is [100, 950] mV.
+     -  1: 2.5 dB attenuation, effective measurement range is [100, 1250] mV.
+     -  2: 6 dB attenuation, effective measurement range is [150, 1750] mV.
+     -  3: 11 dB attenuation, effective measurement range is [150, 2450] mV.
+
+   - For ESP32-C3 devices:
+
+     -  0: 0 dB attenuation, effective measurement range is [0, 750] mV.
+     -  1: 2.5 dB attenuation, effective measurement range is [0, 1050] mV.
+     -  2: 6 dB attenuation, effective measurement range is [0, 1300] mV.
+     -  3: 11 dB attenuation, effective measurement range is [0, 2500] mV.
 
-- **<raw data>**: ADC channel value. The voltage value is raw_data/2 :sup:`width` * atten.
+- **<raw data>**: ADC channel value. 
 
 Notes
 ^^^^^
 
 -  ESP-AT only supports ADC1.
 -  ESP32 and ESP32-C3 support 12-bit width.
+-  For details on how to convert the channel value into voltage, please refer to `ADC Conversion <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/adc.html#adc-conversion>`__ for ESP32 devices and `ADC Conversion <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-reference/peripherals/adc.html#adc-conversion>`__ for ESP32-C3 devices.
 
 Example
 ^^^^^^^^
 
 ::
 
-    AT+DRVADC=0,0   // ADC1 0 channel, voltage: 0 ~ 1.1 V
-    +DRVADC:2048    // For ESP32 and ESP32-C3, the voltage is 2048 / 4096 * 1.1 = 0.55 
+    // For ESP32, 0 dB attenuation, effective measurement range is [100, 950] mV
+    // The returned 2048 means the voltage is 2048 / 4095 * 950 = 475.12 mV
+    AT+DRVADC=0,0
+    +DRVADC:2048
+
+    OK
+
+::
+
+    // For ESP32-C3, 0 dB attenuation, effective measurement range is [0, 750] mV
+    // The returned 2048 means the voltage is 2048 / 4095 * 750 = 375.09 mV
+    AT+DRVADC=0,0
+    +DRVADC:2048
 
     OK
 

diff --git a/docs/en/Compile_and_Develop/how_to_generate_pki_files.rst b/docs/en/Compile_and_Develop/how_to_generate_pki_files.rst
@@ -135,106 +135,108 @@ Download or Update Certificate Bin Files
 
 The script ``AtPKI.py`` is only responsible for converting the certificate files to bin files. You can download bin files to the corresponding flash partition in one of the following ways:
 
-1. Download certificate bin files with tools
+Download with Tools
+^^^^^^^^^^^^^^^^^^^
 
-  #. Windows
+- Windows
 
-     Please download `Flash Download Tools for Windows <https://www.espressif.com/en/support/download/other-tools>`_.
+  Please download `Flash Download Tools for Windows <https://www.espressif.com/en/support/download/other-tools>`_.
 
-     For more details about the Tools, please see ``readme.pdf`` or the ``doc`` folder in the zip folder.
+  For more details about the Tools, please see ``readme.pdf`` or the ``doc`` folder in the zip folder.
 
-  #. Linux or macOS
+- Linux or macOS
 
-     Please use `esptool.py <https://github.com/espressif/esptool>`_.
+  Please use `esptool.py <https://github.com/espressif/esptool>`_.
 
-     You can execute the following command in the root directory of ESP-AT to download bin files.
+  You can execute the following command in the root directory of ESP-AT to download bin files.
 
-     .. code-block:: none
+  .. code-block:: none
 
-       esptool.py --chip auto --port PORTNAME --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB ADDRESS FILEDIRECTORY
+    esptool.py --chip auto --port PORTNAME --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB ADDRESS FILEDIRECTORY
 
-     Replace ``PORTNAME`` with your port name. Replace ``ADDRESS`` with the the download address. Replace ``FILEDIRECTORY`` with the file directory of the bin.
+  Replace ``PORTNAME`` with your port name. Replace ``ADDRESS`` with the the download address. Replace ``FILEDIRECTORY`` with the file directory of the bin.
 
-2. Update certificate bin files with commands
+Update with Commands
+^^^^^^^^^^^^^^^^^^^^
 
-  #. :ref:`AT+SYSFLASH <cmd-SYSFLASH>`
+- :ref:`AT+SYSFLASH <cmd-SYSFLASH>`
 
-     Taking ``ESP32`` module as an example, you can execute the following command to upgrade the ``client_cert`` partition. Please refer to :ref:`AT+SYSFLASH <cmd-SYSFLASH>` for more details.
+  Taking ``ESP32`` module as an example, you can execute the following command to upgrade the ``client_cert`` partition. Please refer to :ref:`AT+SYSFLASH <cmd-SYSFLASH>` for more details.
 
-     1. Query user partitions in flash
+  1. Query user partitions in flash
 
-       Command:
+    Command:
 
-       .. code-block:: none
+    .. code-block:: none
 
-         AT+SYSFLASH?
+      AT+SYSFLASH?
 
-       Response:
+    Response:
 
-       .. code-block:: none
+    .. code-block:: none
 
-         +SYSFLASH:"ble_data",64,1,0x21000,0x3000
-         +SYSFLASH:"server_cert",64,2,0x24000,0x2000
-         +SYSFLASH:"server_key",64,3,0x26000,0x2000
-         +SYSFLASH:"server_ca",64,4,0x28000,0x2000
-         +SYSFLASH:"client_cert",64,5,0x2a000,0x2000
-         +SYSFLASH:"client_key",64,6,0x2c000,0x2000
-         +SYSFLASH:"client_ca",64,7,0x2e000,0x2000
-         +SYSFLASH:"factory_param",64,8,0x30000,0x1000
-         +SYSFLASH:"wpa2_cert",64,9,0x31000,0x2000
-         +SYSFLASH:"wpa2_key",64,10,0x33000,0x2000
-         +SYSFLASH:"wpa2_ca",64,11,0x35000,0x2000
-         +SYSFLASH:"mqtt_cert",64,12,0x37000,0x2000
-         +SYSFLASH:"mqtt_key",64,13,0x39000,0x2000
-         +SYSFLASH:"mqtt_ca",64,14,0x3b000,0x2000
-         +SYSFLASH:"fatfs",1,129,0x70000,0x90000
+      +SYSFLASH:"ble_data",64,1,0x21000,0x3000
+      +SYSFLASH:"server_cert",64,2,0x24000,0x2000
+      +SYSFLASH:"server_key",64,3,0x26000,0x2000
+      +SYSFLASH:"server_ca",64,4,0x28000,0x2000
+      +SYSFLASH:"client_cert",64,5,0x2a000,0x2000
+      +SYSFLASH:"client_key",64,6,0x2c000,0x2000
+      +SYSFLASH:"client_ca",64,7,0x2e000,0x2000
+      +SYSFLASH:"factory_param",64,8,0x30000,0x1000
+      +SYSFLASH:"wpa2_cert",64,9,0x31000,0x2000
+      +SYSFLASH:"wpa2_key",64,10,0x33000,0x2000
+      +SYSFLASH:"wpa2_ca",64,11,0x35000,0x2000
+      +SYSFLASH:"mqtt_cert",64,12,0x37000,0x2000
+      +SYSFLASH:"mqtt_key",64,13,0x39000,0x2000
+      +SYSFLASH:"mqtt_ca",64,14,0x3b000,0x2000
+      +SYSFLASH:"fatfs",1,129,0x70000,0x90000
 
-         OK
+      OK
 
-     2. Erase ``client_cert`` sector
+  2. Erase ``client_cert`` sector
 
-       Command:
+    Command:
 
-       .. code-block:: none
+    .. code-block:: none
 
-         AT+SYSFLASH=0,"client_cert"
+      AT+SYSFLASH=0,"client_cert"
 
-       Response:
+    Response:
 
-       .. code-block:: none
+    .. code-block:: none
 
-         OK
+      OK
 
-     3. Update ``client_cert`` sector
+  3. Update ``client_cert`` sector
 
-       Command:
+    Command:
 
-       .. code-block:: none
+    .. code-block:: none
 
-         AT+SYSFLASH=1,"client_cert",0,2344
+      AT+SYSFLASH=1,"client_cert",0,2344
 
-       Response:
+    Response:
 
-       .. code-block:: none
+    .. code-block:: none
 
-         >
+      >
 
-       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 ``<length>``. When the write operation is completed, the system will prompt the following information.
+    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 ``<length>``. When the write operation is completed, the system will prompt the following information.
 
-       .. code-block:: none
+    .. code-block:: none
 
-         OK
+      OK
 
-  #. :ref:`AT+CIUPDATE <cmd-UPDATE>`
+- :ref:`AT+CIUPDATE <cmd-UPDATE>`
 
-     For example, you can execute the following command to upgrade the ``client_ca`` partition. Please refer to :ref:`AT+CIUPDATE <cmd-UPDATE>` for more details.
+  For example, you can execute the following command to upgrade the ``client_ca`` partition. Please refer to :ref:`AT+CIUPDATE <cmd-UPDATE>` for more details.
 
-     .. Important::
-       If you want to update the ``client_ca`` partition in this way, you must implement your own OTA device, please refer to :doc:`How_to_implement_OTA_update`.
+  .. Important::
+    If you want to update the ``client_ca`` partition in this way, you must implement your own OTA device, please refer to :doc:`How_to_implement_OTA_update`.
 
-     .. code-block:: none
+  .. code-block:: none
 
-       AT+CIUPDATE=1,"v2.2.0.0","client_ca"
+    AT+CIUPDATE=1,"v2.2.0.0","client_ca"
 
 .. note::
 

diff --git a/docs/zh_CN/AT_Command_Set/BLE_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/BLE_AT_Commands.rst
@@ -118,6 +118,7 @@ Bluetooth® Low Energy AT 命令集
 说明
 ^^^^
 
+-  使用 Bluetooth LE 功能时，如果您无需使用 SoftAP 模式，则建议您可以通过 :ref:`AT+CWMODE <cmd-MODE>` 禁用 SoftAP 模式。
 -  使用相关命令之前，请先下载 "at_customize.bin" 文件，详情请见 :doc:`../Compile_and_Develop/How_to_customize_BLE_services`。
 -  使用其它 Bluetooth LE 命令之前，请先调用本命令，初始化 Bluetooth LE 角色。
 -  Bluetooth LE 角色初始化后，不能直接切换。如需切换角色，需要先调用 :ref:`AT+RST <cmd-RST>` 命令重启系统，再重新初始化 Bluetooth LE 角色。