boards: esp32-based: update documentation

This PR updates all Espressif board names to meet its original value. It also update reference links, re-organize entries and removes unused content. This also fixes bootloader information regarding a few boards. IDF Bootloader was removed and these boards kept that info. This updated it accordingly with the Simpleboot Bootloader. Signed-off-by: Sylvio Alves <[email protected]>
renesas · Sep 11, 2024 · 6654c2a · 6654c2a
1 parent c8161dc
commit 6654c2a
Show file tree

Hide file tree

Showing 25 changed files with 313 additions and 273 deletions.
diff --git a/boards/espressif/esp32_devkitc_wroom/doc/index.rst b/boards/espressif/esp32_devkitc_wroom/doc/index.rst
@@ -1,17 +1,17 @@
 .. _esp32_devkitc_wroom:
 
-ESP32-DEVKITC-WROOM
+ESP32-DevKitC-WROOM
 ###################
 
 Overview
 ********
 
-ESP32-DEVKITC-WROOM is a series of low cost, low power system on a chip microcontrollers
-with integrated Wi-Fi & dual-mode Bluetooth.  The ESP32 series employs a
+ESP32 is a series of low cost, low power system on a chip microcontrollers
+with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a
 Tensilica Xtensa LX6 microprocessor in both dual-core and single-core
-variations.  ESP32-WROOM is created and developed by Espressif Systems, a
+variations. ESP32 is created and developed by Espressif Systems, a
 Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm
-process. [1]_
+process. For more information, check `ESP32-DevKitC-WROOM`_.
 
 The features include the following:
 
@@ -43,20 +43,23 @@ The features include the following:
 
 .. figure:: img/esp32_devkitc_wroom.jpg
     :align: center
-    :alt: ESP32-DEVKITC-WROOM
+    :alt: ESP32-DevKitC-WROOM
 
     ESP32-DevKitC-WROOM-32D DK
 
+For more information, check the datasheet at `ESP32 Datasheet`_ or the technical reference
+manual at `ESP32 Technical Reference Manual`_.
+
 Asymmetric Multiprocessing (AMP)
 ********************************
 
-ESP32-DEVKITC-WROOM allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
+ESP32-DevKitC-WROOM allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
 and/or exchanging data over OpenAMP framework. See :ref:`ipc_samples` folder as code reference.
 
 Supported Features
 ==================
 
-Current Zephyr's ESP32-WROOM board supports the following features:
+Current Zephyr's ESP32-DevKitC-WROOM board supports the following features:
 
 +------------+------------+-------------------------------------+
 | Interface  | Controller | Driver/Component                    |
@@ -235,10 +238,9 @@ message in the monitor:
 Debugging
 *********
 
-ESP32-DEVKITC-WROOM support on OpenOCD is available upstream as of version 0.12.0.
-Download and install OpenOCD from `OpenOCD`_.
+ESP32 support on OpenOCD is available at `OpenOCD ESP32`_.
 
-On the ESP-WROOM-32 DevKitC board, the JTAG pins are not run to a
+On the ESP32-DevKitC-WROOM board, the JTAG pins are not run to a
 standard connector (e.g. ARM 20-pin) and need to be manually connected
 to the external programmer (e.g. a Flyswatter2):
 
@@ -260,8 +262,7 @@ to the external programmer (e.g. a Flyswatter2):
 | IO15       | TDO       |
 +------------+-----------+
 
-Further documentation can be obtained from the SoC vendor in `JTAG debugging
-for ESP32`_.
+Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32`_.
 
 Here is an example for building the :ref:`hello_world` application.
 
@@ -288,12 +289,11 @@ GDB stub is enabled on ESP32.
   This does not work as the code is on flash which cannot be randomly
   accessed for modification.
 
-.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
-.. _`OpenOCD`: https://github.com/openocd-org/openocd
-
 References
 **********
 
-.. [1] https://en.wikipedia.org/wiki/ESP32
-.. _ESP32 Technical Reference Manual: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
-.. _Hardware Reference: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html
+.. _`ESP32-DevKitC-WROOM`: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/hw-reference/esp32/get-started-devkitc.html#
+.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
+.. _`ESP32 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
+.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
+.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
diff --git a/boards/espressif/esp32_devkitc_wrover/doc/index.rst b/boards/espressif/esp32_devkitc_wrover/doc/index.rst
@@ -1,17 +1,17 @@
 .. _esp32_devkitc_wrover:
 
-ESP32-DEVKITC-WROVER
+ESP32-DevKitC-WROVER
 ####################
 
 Overview
 ********
 
 ESP32 is a series of low cost, low power system on a chip microcontrollers
-with integrated Wi-Fi & dual-mode Bluetooth.  The ESP32 series employs a
+with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a
 Tensilica Xtensa LX6 microprocessor in both dual-core and single-core
-variations.  ESP32 is created and developed by Espressif Systems, a
+variations. ESP32 is created and developed by Espressif Systems, a
 Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm
-process. [1]_
+process. For more information, check `ESP32-DevKitC-WROVER`_.
 
 The features include the following:
 
@@ -43,20 +43,23 @@ The features include the following:
 
 .. figure:: img/esp32_devkitc_wrover.jpg
     :align: center
-    :alt: ESP32-DEVKITC-WROVER
+    :alt: ESP32-DevKitC-WROVER
 
     ESP32-DevKitC-WROVER-IE
 
+For more information, check the datasheet at `ESP32 Datasheet`_ or the technical reference
+manual at `ESP32 Technical Reference Manual`_.
+
 Asymmetric Multiprocessing (AMP)
 ********************************
 
-ESP32-DEVKITC-WROVER allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
+ESP32-DevKitC-WROVER allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
 and/or exchanging data over OpenAMP framework. See :ref:`ipc_samples` folder as code reference.
 
 Supported Features
 ==================
 
-Current Zephyr's ESP32-devkitc board supports the following features:
+Current Zephyr's ESP32-DevKitC-WROVER board supports the following features:
 
 +------------+------------+-------------------------------------+
 | Interface  | Controller | Driver/Component                    |
@@ -235,10 +238,9 @@ message in the monitor:
 Debugging
 *********
 
-ESP32 support on OpenOCD is available upstream as of version 0.12.0.
-Download and install OpenOCD from `OpenOCD`_.
+ESP32 support on OpenOCD is available at `OpenOCD ESP32`_.
 
-On the ESP-WROOM-32 DevKitC board, the JTAG pins are not run to a
+On the ESP32-DevKitC-WROVER board, the JTAG pins are not run to a
 standard connector (e.g. ARM 20-pin) and need to be manually connected
 to the external programmer (e.g. a Flyswatter2):
 
@@ -260,8 +262,7 @@ to the external programmer (e.g. a Flyswatter2):
 | IO15       | TDO       |
 +------------+-----------+
 
-Further documentation can be obtained from the SoC vendor in `JTAG debugging
-for ESP32`_.
+Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32`_.
 
 Here is an example for building the :ref:`hello_world` application.
 
@@ -288,12 +289,11 @@ GDB stub is enabled on ESP32.
   This does not work as the code is on flash which cannot be randomly
   accessed for modification.
 
-.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
-.. _`OpenOCD`: https://github.com/openocd-org/openocd
-
 References
 **********
 
-.. [1] https://en.wikipedia.org/wiki/ESP32
-.. _ESP32 Technical Reference Manual: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
-.. _Hardware Reference: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html
+.. _`ESP32-DevKitC-WROVER`: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/hw-reference/esp32/get-started-devkitc.html#
+.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
+.. _`ESP32 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
+.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
+.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
diff --git a/boards/espressif/esp32_ethernet_kit/doc/index.rst b/boards/espressif/esp32_ethernet_kit/doc/index.rst
@@ -1,8 +1,11 @@
 .. _esp32_ethernet_kit:
 
-ESP32-ETHERNET-KIT
+ESP32-Ethernet-Kit
 ##################
 
+Overview
+********
+
 The ESP32-Ethernet-Kit is an Ethernet-to-Wi-Fi development board that enables
 Ethernet devices to be interconnected over Wi-Fi. At the same time, to provide
 more flexible power supply options, the ESP32-Ethernet-Kit also supports power
@@ -17,16 +20,13 @@ over Ethernet (PoE).
 
     ESP32-Ethernet-Kit V1.2 Overview
 
-Overview
-********
-
-ESP32-Ethernet-Kit is an ESP32-based development board produced by
-`Espressif <https://espressif.com>`_.
+ESP32-Ethernet-Kit is an ESP32-WROVER-E based development.
+For more information, check the datasheet at `ESP32-WROVER-E Datasheet`_.
 
-It consists of two development boards, the Ethernet board A and the PoE
-board B. The `Ethernet board (A)`_ contains Bluetooth/Wi-Fi dual-mode
+It consists of two development boards, the Ethernet Board A and the PoE
+board B. The `Ethernet Board (A)`_ contains Bluetooth/Wi-Fi dual-mode
 ESP32-WROVER-E module and IP101GRI, a Single Port 10/100 Fast Ethernet
-Transceiver (PHY). The `PoE board (B)`_ provides power over Ethernet
+Transceiver (PHY). The `PoE Board (B)`_ provides power over Ethernet
 functionality. The A board can work independently, without the board B
 installed.
 
@@ -39,7 +39,7 @@ installed.
 
     ESP32-Ethernet-Kit V1.2
 
-For the application loading and monitoring, the Ethernet board (A) also
+For the application loading and monitoring, the Ethernet Board (A) also
 features FTDI FT2232H chip - an advanced multi-interface USB bridge.
 This chip enables to use JTAG for direct debugging of ESP32 through the
 USB interface without a separate JTAG debugger.
@@ -76,7 +76,7 @@ Ethernet Board (A)
     :alt: ESP32-Ethernet-Kit V1.2
     :figclass: align-center
 
-    ESP32-Ethernet-Kit - Ethernet board (A) layout
+    ESP32-Ethernet-Kit - Ethernet Board (A) layout
 
 The table below provides description starting from the picture's top right
 corner and going clockwise.
@@ -104,8 +104,7 @@ corner and going clockwise.
       ESP32. FT2232H also features USB-to-JTAG interface which is available
       on channel A of the chip, while USB-to-serial is on channel B.
       The FT2232H chip enhances user-friendliness in terms of application
-      development and debugging. See
-      `ESP32-Ethernet-Kit V1.2 Ethernet board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_.
+      development and debugging. See `ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`_
   * - USB Port
     - USB interface. Power supply for the board as well as the communication
       interface between a computer and the board.
@@ -121,7 +120,7 @@ corner and going clockwise.
   * - DC/DC Converter
     - Provided DC 5 V to 3.3 V conversion, output current up to 2 A.
   * - Board B Connectors
-    - A pair male and female header pins for mounting the `PoE board (B)`_
+    - A pair male and female header pins for mounting the `PoE Board (B)`_
   * - IP101GRI (PHY)
     - The physical layer (PHY) connection to the Ethernet cable is
       implemented using the
@@ -155,39 +154,39 @@ PoE Board (B)
 ^^^^^^^^^^^^^
 
 This board coverts power delivered over the Ethernet cable (PoE) to provide a
-power supply for the Ethernet board (A). The main components of the PoE board
+power supply for the Ethernet Board (A). The main components of the PoE Board
 (B) are shown on the block diagram under `Functionality Overview`_.
 
-The PoE board (B) has the following features:
+The PoE Board (B) has the following features:
 
 * Support for IEEE 802.3at
 * Power output: 5 V, 1.4 A
 
 To take advantage of the PoE functionality the **RJ45 Port** of the Ethernet
 board (A) should be connected with an Ethernet cable to a switch that supports
-PoE. When the Ethernet board (A) detects 5 V power output from the PoE board
+PoE. When the Ethernet Board (A) detects 5 V power output from the PoE Board
 (B), the USB power will be automatically cut off.
 
 .. figure:: img/esp32-ethernet-kit-b-v1.0-layout.jpg
     :align: center
-    :alt: ESP32-Ethernet-Kit - PoE board (B)
+    :alt: ESP32-Ethernet-Kit - PoE Board (B)
     :figclass: align-center
 
-    ESP32-Ethernet-Kit - PoE board (B) layout
+    ESP32-Ethernet-Kit - PoE Board (B) layout
 
-.. list-table:: Table  PoE board (B)
+.. list-table:: Table  PoE Board (B)
   :widths: 40 150
   :header-rows: 1
 
   * - Key Component
     - Description
   * - Board A Connector
     - Four female (left) and four male (right) header pins for connecting the
-      PoE board (B) to `Ethernet board (A)`_. The pins on the left accept
+      PoE Board (B) to `Ethernet Board (A)`_. The pins on the left accept
       power coming from a PoE switch. The pins on the right deliver 5 V power
-      supply to the Ethernet board (A).
+      supply to the Ethernet Board (A).
   * - External Power Terminals
-    - Optional power supply (26.6 ~ 54 V) to the PoE board (B).
+    - Optional power supply (26.6 ~ 54 V) to the PoE Board (B).
 
 .. _get-started-esp32-ethernet-kit-v1.2-setup-options:
 
@@ -225,9 +224,7 @@ or generated from internal ESP32 APLL (not recommended).
 .. note::
 
     For additional information on the RMII clock selection, please refer to
-    `ESP32-Ethernet-Kit V1.2 Ethernet board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_,
-    sheet 2, location D2.
-
+    `ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`_, sheet 2, location D2.
 
 RMII Clock Sourced Externally by PHY
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -267,7 +264,7 @@ for transmission line delay, and then supplied to the PHY.
 
 To implement this option, users need to remove or add some RC components on
 the board. For details please refer to
-`ESP32-Ethernet-Kit V1.2 Ethernet board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_,
+`ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`_,
 sheet 2, location D2. Please note that if the APLL is already used for other
 purposes (e.g. I2S peripheral), then you have no choice but use an external
 RMII clock.
@@ -411,7 +408,7 @@ GPIO Allocation Summary
        module that can be disabled/enabled externally. Similarly like when
        using RESET_N, the oscillator module should be disabled by default and
        turned on by ESP32 after power-up. For a reference design please see
-       `ESP32-Ethernet-Kit V1.2 Ethernet board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_.
+       `ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`_.
 
     2. The ESP32 pins GPIO16 and GPIO17 are not broken out to the
        ESP32-WROVER-E module and therefore not available for use. If you need
@@ -560,7 +557,7 @@ Debugging
 
 As with much custom hardware, the ESP32 modules require patches to
 OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
-the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_
+the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_.
 
 The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
 ``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
@@ -615,13 +612,9 @@ Board Init
 RESET_N (GPIO5) is automatically set high to enable the Ethernet PHY
 during board initialization (board_init.c)
 
-Related Documents
-*****************
+References
+**********
 
-* `ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_ (PDF)
-* `ESP32-Ethernet-Kit PoE Board (B) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_B_V1.0_20190517.pdf>`_ (PDF)
-* `ESP32-Ethernet-Kit V1.2 Ethernet Board (A) PCB Layout <https://dl.espressif.com/dl/schematics/PCB_ESP32-Ethernet-Kit_A_V1_2_20190829.pdf>`_ (PDF)
-* `ESP32-Ethernet-Kit PoE Board (B) PCB Layout <https://dl.espressif.com/dl/schematics/PCB_ESP32-Ethernet-Kit_B_V1_0_20190306.pdf>`_ (PDF)
-* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
-* `ESP32-WROVER-E Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf>`_ (PDF)
-* `OpenOCD ESP32 <https://github.com/espressif/openocd-esp32/releases>`_
+.. _`ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`: https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf
+.. _`ESP32-WROVER-E Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf
+.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases