Merge branch 'docs/add_at_cmd_support_notes' into 'master'

docs: Added the command set support note See merge request application/esp-at!1390
espressif · Jun 2, 2023 · 97b1fa9 · 97b1fa9
2 parents 204a181 + 1e87b74
commit 97b1fa9
Show file tree

Hide file tree

Showing 32 changed files with 675 additions and 259 deletions.
diff --git a/docs/en/AT_Command_Set/BLE_AT_Commands.rst b/docs/en/AT_Command_Set/BLE_AT_Commands.rst
@@ -5,26 +5,9 @@ Bluetooth® Low Energy AT Commands
 
 :link_to_translation:`zh_CN:[中文]`
 
- .. only:: esp32
-
-  Currently, AT firmware for {IDF_TARGET_NAME} series supports `Bluetooth® Core Specification Version 4.2 <https://www.bluetooth.com/specifications/specs/core-specification-4-2/>`_.
-
- .. only:: esp32c3
-
-  Currently, AT firmware for {IDF_TARGET_NAME} supports `Bluetooth® Core Specification Version 5.0 <https://www.bluetooth.com/specifications/specs/core-specification-5/>`_.
-
-.. only:: esp32c2
-
-  Currently, AT firmware for {IDF_TARGET_NAME} supports `Bluetooth® Core Specification Version 5.0 <https://www.bluetooth.com/specifications/specs/core-specification-5/>`_.
-
-    .. attention::
-        **{IDF_TARGET_CFG_PREFIX}-4MB AT firmware supports BluFi, but {IDF_TARGET_CFG_PREFIX}-2MB AT firmware does not**. If you need the firmware with BluFi support on {IDF_TARGET_CFG_PREFIX}-2MB, please compile it on your own by following :doc:`Compile ESP-AT Project <../Compile_and_Develop/How_to_clone_project_and_compile_it>` and choosing the following configurations in the Step 5. Configure:
-
-        - ``Component config`` -> ``Bluetooth`` -> ``Bluetooth`` -> ``Host`` -> ``NimBLE`` - ``BLE only``
-        - ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Enable blufi functionality``
-
 .. list::
 
+    :esp32 or esp32c3 or esp32c2: - :ref:`Introduction <cmd-ble-intro>`
     :esp32 or esp32c3 or esp32c2: - :ref:`AT+BLEINIT <cmd-BINIT>`: Bluetooth LE initialization.
     :esp32 or esp32c3 or esp32c2: - :ref:`AT+BLEADDR <cmd-BADDR>`: Query/Set Bluetooth LE device address.
     :esp32 or esp32c3 or esp32c2: - :ref:`AT+BLENAME <cmd-BNAME>`: Query/Set Bluetooth LE device name.
@@ -80,6 +63,59 @@ Bluetooth® Low Energy AT Commands
     :esp32c3 or esp32c2: - :ref:`AT+BLEREADPHY <cmd-BLERDPHY>`: Query the current transmitter PHY.
     :esp32c3 or esp32c2: - :ref:`AT+BLESETPHY <cmd-BLESETPHY>`: Set the current transmitter PHY.
 
+.. _cmd-ble-intro:
+
+Introduction
+------------
+
+ .. only:: esp32
+
+  Currently, AT firmware for {IDF_TARGET_NAME} series supports `Bluetooth® Core Specification Version 4.2 <https://www.bluetooth.com/specifications/specs/core-specification-4-2/>`_.
+
+ .. only:: esp32c2 or esp32c3
+
+  Currently, AT firmware for {IDF_TARGET_NAME} supports `Bluetooth® Core Specification Version 5.0 <https://www.bluetooth.com/specifications/specs/core-specification-5/>`_.
+
+.. only:: esp32 or esp32c3
+
+  .. important::
+    The default AT firmware supports all the AT commands mentioned on this page. If you need to modify the commands supported by {IDF_TARGET_NAME} by default, please compile the ESP-AT project by following the steps in :doc:`Compile ESP-AT Project Locally <../Compile_and_Develop/How_to_clone_project_and_compile_it>` documentation. In the project configuration during the fifth step, make the following selections:
+
+    - Disable BluFi commands: ``Component config`` -> ``AT`` -> ``AT blufi command support``
+    - Disable Bluetooth LE commands: ``Component config`` -> ``AT`` -> ``AT ble command support``
+    - Disable Bluetooth LE HID commands: ``Component config`` -> ``AT`` -> ``AT ble hid command support``
+
+.. only:: esp32c2
+
+  .. important::
+    The default {IDF_TARGET_CFG_PREFIX}-4MB AT firmware supports BluFi functionality, while the {IDF_TARGET_CFG_PREFIX}-2MB AT firmware does not. If you need BluFi functionality for {IDF_TARGET_CFG_PREFIX}-2MB, please refer to the :doc:`Compile ESP-AT Project Locally <../Compile_and_Develop/How_to_clone_project_and_compile_it>` documentation and follow the steps below in the project configuration (Step 5):
+
+    - Enable ``Component config`` -> ``Bluetooth``
+    - Enable ``Component config`` -> ``Bluetooth`` -> ``Bluetooth`` -> ``Host`` -> ``NimBLE`` - ``BLE only``
+    - Enable ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Enable blufi functionality``
+    - Enable ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Enable BLE 5 feature`` -> ``Enable extended advertising``
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Maximum number of concurrent connections`` -> 1
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Memory Settings`` -> ``MSYS_1_Block Count`` -> 10
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Memory Settings`` -> ``MSYS_1_Block Size`` -> 100
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Memory Settings`` -> ``MSYS_2_Block Count`` -> 4
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Memory Settings`` -> ``ACL Buffer Count`` -> 5
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Memory Settings`` -> ``High Priority HCI Event Buffer count`` -> 5
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Memory Settings`` -> ``Low Priority HCI Event Buffer count`` -> 3
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``BLE white list size`` -> 1
+    - Set ``Component config`` -> ``Bluetooth`` -> ``Controller Options`` -> ``BLE LL Resolving list size`` -> 1
+    - Set ``Component config`` -> ``Bluetooth`` -> ``Controller Options`` -> ``BLE duplicate scan list count`` -> 1
+
+  .. important::
+    The default {IDF_TARGET_CFG_PREFIX}-4MB AT firmware and {IDF_TARGET_CFG_PREFIX}-2MB AT firmware do not support Bluetooth LE functionality. If you need to enable Bluetooth LE functionality, please refer to the :doc:`Compile ESP-AT Project Locally <../Compile_and_Develop/How_to_clone_project_and_compile_it>` documentation and follow the steps of above BluFi functionality in the project configuration (Step 5), and then follow the steps below:
+
+    - Enable Bluetooth LE commands: ``Component config`` -> ``AT`` -> ``AT ble command support``
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Maximum length of BLE device name in octets`` -> 32
+    - Set ``Component config`` -> ``Bluetooth`` -> ``NimBLE Options`` -> ``Preferred MTU size in octets`` -> 203
+
+    If you encounter an error similar to ``Part 'ota_0' 0/16 @ 0xd0000 size 0x130000 (overflow 0x59a0)``, you need to disable unnecessary features in ``Component config`` -> ``AT`` according to your application requirements to reduce the firmware size.
+
+    Due to limited memory, it is recommended to disable the Wi-Fi protocol stack by sending the command :ref:`AT+CWINIT=0 <cmd-INIT>` before using Bluetooth LE functionality. This will free up memory for Bluetooth operations.
+
 .. only:: esp32 or esp32c3 or esp32c2
 
     .. _cmd-BINIT:

diff --git a/docs/en/AT_Command_Set/BT_AT_Commands.rst b/docs/en/AT_Command_Set/BT_AT_Commands.rst
@@ -5,8 +5,7 @@
 
 :link_to_translation:`zh_CN:[中文]`
 
-{IDF_TARGET_NAME} AT firmware supports `Bluetooth® Core Specification Version 4.2 <https://www.bluetooth.com/specifications/archived-specifications/>`_.
-
+- :ref:`Introduction <cmd-bt-intro>`
 - :ref:`AT+BTINIT <cmd-BTINIT>`: Classic Bluetooth initialization.
 - :ref:`AT+BTNAME <cmd-BTNAME>`: Query/Set Classic Bluetooth device name.
 - :ref:`AT+BTSCANMODE <cmd-BTSCANMODE>`: Set Classic Bluetooth scan mode.
@@ -30,6 +29,20 @@
 - :ref:`AT+BTCOD <cmd-BTCOD>`: Set class of devices.
 - :ref:`AT+BTPOWER <cmd-BTPWR>`: Query/Set power of Classic Bluetooth.
 
+.. _cmd-bt-intro:
+
+Introduction
+------------
+
+{IDF_TARGET_NAME} AT firmware supports `Bluetooth® Core Specification Version 4.2 <https://www.bluetooth.com/specifications/archived-specifications/>`_.
+
+.. important::
+  The default AT firmware does not support the AT commands listed on this page. If you need {IDF_TARGET_NAME} to support Classic Bluetooth commands, you can compile the ESP-AT project by following the steps in :doc:`Compile ESP-AT Project Locally <../Compile_and_Develop/How_to_clone_project_and_compile_it>` documentation. In the project configuration during the fifth step, make the following selections:
+
+  - Enable Generic Bluetooth commands: ``Component config`` -> ``AT`` -> ``AT bt command support``
+  - Enable SPP commands: ``Component config`` -> ``AT`` -> ``AT bt command support`` -> ``AT bt spp command support``
+  - Enable A2DP commands:``Component config`` -> ``AT`` -> ``AT bt command support`` -> ``AT bt a2dp command support``
+
 .. _cmd-BTINIT:
 
 :ref:`AT+BTINIT <BT-AT>`: Classic Bluetooth Initialization

diff --git a/docs/en/AT_Command_Set/Basic_AT_Commands.rst b/docs/en/AT_Command_Set/Basic_AT_Commands.rst
@@ -7,6 +7,7 @@ Basic AT Commands
 
 .. list::
 
+  - :ref:`Introduction <cmd-basic-intro>`
   - :ref:`AT <cmd-AT>`: Test AT startup.
   - :ref:`AT+RST <cmd-RST>`: Restart a module.
   - :ref:`AT+GMR <cmd-GMR>`: Check version information.
@@ -25,8 +26,6 @@ Basic AT Commands
   - :ref:`AT+SYSMSGFILTERCFG <cmd-SYSMSGFILTERCFG>`: Query/Set the :term:`system message` filters.
   - :ref:`AT+SYSFLASH <cmd-SYSFLASH>`: Query/Set User Partitions in Flash.
   - :ref:`AT+SYSMFG <cmd-SYSMFG>`: Query/Set :term:`manufacturing nvs` User Partitions.
-  - :ref:`AT+FS <cmd-FS>`: Filesystem Operations.
-  - :ref:`AT+FSMOUNT <cmd-FSMOUNT>`: Mount/Unmount Filesystem.
   - :ref:`AT+RFPOWER <cmd-RFPOWER>`: Query/Set RF TX Power.
   - :ref:`AT+SYSROLLBACK <cmd-SYSROLLBACK>`: Roll back to the previous firmware.
   - :ref:`AT+SYSTIMESTAMP <cmd-SETTIME>`: Query/Set local time stamp.
@@ -36,6 +35,14 @@ Basic AT Commands
   - :ref:`AT+SYSREG <cmd-SYSREG>`: Read/write the register.
   :esp32c3: - :ref:`AT+SYSTEMP <cmd-SYSTEMP>`: Read the internal chip Celsius temperature value.
 
+.. _cmd-basic-intro:
+
+Introduction
+------------
+
+.. important::
+  The default AT firmware supports all the AT commands mentioned on this page.
+
 .. _cmd-AT:
 
 :ref:`AT <Basic-AT>`: Test AT Startup
@@ -1521,113 +1528,6 @@ Example
 
     // Wait until AT command port returns ``>``, and then write 1164 bytes
 
-.. _cmd-FS:
-
-:ref:`AT+FS <Basic-AT>`: Filesystem Operations
----------------------------------------------------------------
-
-Set Command
-^^^^^^^^^^^
-
-**Command:**
-
-::
-
-    AT+FS=<type>,<operation>,<filename>,<offset>,<length>
-
-**Response:**
-
-::
-
-    OK  
-
-Parameters
-^^^^^^^^^^
-
--  **<type>**: only FATFS is currently supported.
-
-   -  0: FATFS
-
--  **<operation>**:
-
-   -  0: delete file.
-   -  1: write file.
-   -  2: read file.
-   -  3: query the size of the file.
-   -  4: list files in a specific directory. Only root directory is currently supported.
-
--  **<offset>**: apply to writing and reading operations only.
--  **<length>**: data length, applying to writing and reading operations only.
-
-Notes
-^^^^^
-
--  This command will automatically mount the filesystem. After the :ref:`AT+FS <cmd-FS>` filesystem operation is all done, it is strongly recommended to use the :ref:`AT+FSMOUNT=0 <cmd-FSMOUNT>` command to unmount the filesystem to free a large amount of RAM space.
--  Please make sure that you have downloaded at_customize.bin before using this command. For more details, refer to `ESP-IDF Partition Tables <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/api-guides/partition-tables.html>`_ and :doc:`../Compile_and_Develop/How_to_customize_partitions`.
--  If the length of the read data is greater than the actual file length, only the actual data length of the file will be returned.
--  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>``.
-
-Example
-^^^^^^^^
-
-::
-
-    // delete a file.
-    AT+FS=0,0,"filename"
-
-    // write 10 bytes to offset 100 of a file.
-    AT+FS=0,1,"filename",100,10
-
-    // read 100 bytes from offset 0 of a file.
-    AT+FS=0,2,"filename",0,100
-
-    // list all files in the root directory.
-    AT+FS=0,4,"."
-
-.. _cmd-FSMOUNT:
-
-:ref:`AT+FSMOUNT <Basic-AT>`: Mount/Unmount Filesystem
-------------------------------------------------------
-
-Set Command
-^^^^^^^^^^^
-
-**Command:**
-
-::
-
-    AT+FSMOUNT=<mount>
-
-**Response:**
-
-::
-
-    OK
-
-Parameters
-^^^^^^^^^^
-
--  **<mount>**:
-
-   -  0: Unmount filesystem
-   -  1: Mount filesystem
-
-Notes
-^^^^^
-
--  After the :ref:`AT+FS <cmd-FS>` filesystem operation is all done, it is strongly recommended to use the :ref:`AT+FSMOUNT=0 <cmd-FSMOUNT>` command to unmount the filesystem to free a large amount of RAM space.
-
-Example
-^^^^^^^^
-
-::
-
-    // unmount the filesystem manually
-    AT+FSMOUNT=0
-
-    // mount the filesystem manually
-    AT+FSMOUNT=1
-
 .. _cmd-RFPOWER:
 
 :ref:`AT+RFPOWER <Basic-AT>`: Query/Set RF TX Power

diff --git a/docs/en/AT_Command_Set/Driver_AT_Commands.rst b/docs/en/AT_Command_Set/Driver_AT_Commands.rst
@@ -5,6 +5,7 @@ Driver AT Commands
 
 :link_to_translation:`zh_CN:[中文]`
 
+- :ref:`Introduction <cmd-driver-intro>`
 -  :ref:`AT+DRVADC <cmd-DRVADC>`: Read ADC channel value.
 -  :ref:`AT+DRVPWMINIT <cmd-DRVPWMINIT>`: Initialize PWM driver.
 -  :ref:`AT+DRVPWMDUTY <cmd-DRVPWMDUTY>`: Set PWM duty.
@@ -18,6 +19,16 @@ Driver AT Commands
 -  :ref:`AT+DRVSPIRD <cmd-DRVSPIRD>`: Read SPI data.
 -  :ref:`AT+DRVSPIWR <cmd-DRVSPIWR>`: Write SPI data.
 
+.. _cmd-driver-intro:
+
+Introduction
+------------
+
+.. important::
+  The default AT firmware does not support the AT commands listed on this page. If you need {IDF_TARGET_NAME} to support driver commands, you can compile the ESP-AT project by following the steps in :doc:`Compile ESP-AT Project Locally <../Compile_and_Develop/How_to_clone_project_and_compile_it>` documentation. In the project configuration during the fifth step, make the following selections:
+
+  - Enable ``Component config`` -> ``AT`` -> ``AT driver command support``
+
 .. _cmd-DRVADC:
 
 :ref:`AT+DRVADC <Driver-AT>`: Read ADC Channel Value

diff --git a/docs/en/AT_Command_Set/Ethernet_AT_Commands.rst b/docs/en/AT_Command_Set/Ethernet_AT_Commands.rst
@@ -7,10 +7,19 @@
 
 :link_to_translation:`zh_CN:[中文]`
 
+- :ref:`Introduction <cmd-eth-intro>`
 - :ref:`Prerequisite <cmd-ETHPRE>`
 - :ref:`AT+CIPETHMAC <cmd-ETHMAC>`: Query/Set the MAC address of the {IDF_TARGET_NAME} Ethernet.
 - :ref:`AT+CIPETH <cmd-ETHIP>`: Query/Set the IP address of the {IDF_TARGET_NAME} Ethernet.
 
+.. _cmd-eth-intro:
+
+Introduction
+------------
+
+.. important::
+  The default AT firmware does not support the AT commands listed on this page. If you need {IDF_TARGET_NAME} to support Ethernet commands, please refer to :doc:`../Compile_and_Develop/How_to_enable_ESP_AT_Ethernet` documentation and :doc:`Compile ESP-AT Project Locally <../Compile_and_Develop/How_to_clone_project_and_compile_it>`.
+
 .. _cmd-ETHPRE:
 
 :ref:`Prerequisite <ETH-AT>`