boards: Update all vendors documentation related with Espressif SoCs

Update the documentation of ESP32 related boards:

* use included sections
* fix the `References` links if applicable.

Signed-off-by: Marek Matej <[email protected]>

Author: Marek Matej

boards/01space/esp32c3_042_oled/doc/index.rst

@@ -31,11 +31,6 @@ It features:
    The ESP32-C3 does not have native USB, it has an on-chip USB-serial converter
    instead.
 
-Supported Features
-==================
-
-.. zephyr:board-supported-hw::
-
 Connections and IOs
 ===================
 
@@ -50,11 +45,11 @@ See the following image:
 It also features a 0.42 inch OLED display, driven by a SSD1306-compatible chip.
 It is connected over I2C: SDA on GPIO5, SCL on GPIO6.
 
-Prerequisites
-=============
+System requirements
+*******************
 
-Espressif HAL requires WiFi and Bluetooth binary blobs. Run the command below to
-retrieve those files.
+Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
+below to retrieve those files.
 
 .. code-block:: console
 
@@ -69,68 +64,17 @@ Programming and Debugging
 
 .. zephyr:board-supported-runners::
 
-Standalone application
-======================
-
-The board can be loaded using a single binary image, without 2nd stage bootloader.
-It is the default option when building the application without additional configuration.
-
-.. note::
-
-   This mode does not provide any security features nor OTA updates.
-
-Use the following command to build a sample hello_world application:
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: esp32c3_042_oled
-   :goals: build
-
-Sysbuild
-========
-
-:ref:`sysbuild` makes it possible to build and flash all necessary images needed to
-bootstrap the board.
-
-By default, the ESP32 sysbuild configuration creates bootloader (MCUboot) and
-application images.
+.. include:: ../../../espressif/common/building-flashing.rst
+   :start-after: espressif-building-flashing
 
-To build the sample application using sysbuild, use this command:
+.. include:: ../../../espressif/common/board-variants.rst
+   :start-after: espressif-board-variants
 
-.. zephyr-app-commands::
-   :tool: west
-   :zephyr-app: samples/hello_world
-   :board: esp32c3_042_oled
-   :goals: build
-   :west-args: --sysbuild
-   :compact:
-
-Flashing
-========
-
-For the :code:`Hello, world!` application, follow the instructions below.
-Assuming the board is connected to ``/dev/ttyACM0`` on Linux.
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: esp32c3_042_oled
-   :goals: flash
-   :flash-args: --esp-device /dev/ttyACM0
-
-Since the Zephyr console is by default on the ``usb_serial`` device, we use
-the espressif monitor utility to connect to the console.
-
-.. code-block:: console
-
-   $ west espressif monitor -p /dev/ttyACM0
-
-After the board has automatically reset and booted, you should see the following
-message in the monitor:
-
-.. code-block:: console
+Debugging
+=========
 
-   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
-   Hello World! esp32c3_042_oled
+.. include:: ../../../espressif/common/openocd-debugging.rst
+   :start-after: espressif-openocd-debugging
 
 References
 **********

boards/adafruit/feather_esp32/doc/index.rst

@@ -25,9 +25,6 @@ Supported Features
 System requirements
 ===================
 
-Prerequisites
--------------
-
 Espressif HAL requires WiFi and Bluetooth binary blobs in order to work. Run
 the commands below to retrieve the files.
 
@@ -36,26 +33,22 @@ the commands below to retrieve the files.
    west update
    west blobs fetch hal_espressif
 
-Building & flashing
--------------------
-
-Use the standard build and flash process for this board. See
-:ref:`build_an_application` and :ref:`application_run` for more details.
+Programming and Debugging
+*************************
 
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: adafruit_feather_esp32/esp32/procpu
-   :goals: build flash
+.. zephyr:board-supported-runners::
 
-The baud rate of 921600bps is set by default. If experiencing issues when flashing,
-try using different values by using ``--esp-baud-rate <BAUD>`` option during
-``west flash`` (e.g. ``west flash --esp-baud-rate 115200``).
+.. include:: ../../../espressif/common/building-flashing.rst
+   :start-after: espressif-building-flashing
 
-After flashing, view the serial monitor with the espressif monitor command.
+.. include:: ../../../espressif/common/board-variants.rst
+   :start-after: espressif-board-variants
 
-.. code-block:: shell
+Debugging
+=========
 
-   west espressif monitor
+.. include:: ../../../espressif/common/openocd-debugging.rst
+   :start-after: espressif-openocd-debugging
 
 Testing
 =======
@@ -106,8 +99,11 @@ Test ESP32 Wi-Fi functionality using the Wi-Fi shell module.
 
 References
 **********
-- `Adafruit ESP32 Feather V2 <https://www.adafruit.com/product/5400>`_
-- `Adafruit ESP32 Feather V2 Pinouts <https://learn.adafruit.com/adafruit-esp32-feather-v2/pinouts>`_
-- `Adafruit ESP32 Feather V2 Schematic <https://learn.adafruit.com/adafruit-esp32-feather-v2/downloads#schematic-and-fab-print-3112284>`_
-- `ESP32-PICO-MINI-02 Datasheet <https://cdn-learn.adafruit.com/assets/assets/000/109/588/original/esp32-pico-mini-02_datasheet_en.pdf?1646852017>`_ (PDF)
-- `STEMMA QT <https://learn.adafruit.com/introducing-adafruit-stemma-qt>`_
+
+.. target-notes::
+
+- _`Adafruit ESP32 Feather V2`: https://www.adafruit.com/product/5400
+- _`Adafruit ESP32 Feather V2 Pinouts`: https://learn.adafruit.com/adafruit-esp32-feather-v2/pinouts
+- _`Adafruit ESP32 Feather V2 Schematic`: https://learn.adafruit.com/adafruit-esp32-feather-v2/downloads#schematic-and-fab-print-3112284
+- _`ESP32-PICO-MINI-02 Datasheet`: https://cdn-learn.adafruit.com/assets/assets/000/109/588/original/esp32-pico-mini-02_datasheet_en.pdf?1646852017
+- _`STEMMA QT`: https://learn.adafruit.com/introducing-adafruit-stemma-qt

boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2.rst

@@ -56,13 +56,8 @@ pinouts and the schematic.
 - `Adafruit ESP32-S2 Feather Pinouts`_
 - `Adafruit ESP32-S2 Feather Schematic`_
 
-Programming and Debugging
-*************************
-
-.. zephyr:board-supported-runners::
-
-Prerequisites
-=============
+System requirements
+*******************
 
 Espressif HAL requires WiFi binary blobs in order work. Run the command below
 to retrieve those files.
@@ -72,195 +67,22 @@ to retrieve those files.
    west update
    west blobs fetch hal_espressif
 
-Building & Flashing
-*******************
-
-Simple boot
-===========
-
-The board could be loaded using the single binary image, without 2nd stage
-bootloader. It is the default option when building the application without
-additional configuration.
-
-.. note::
-
-   Simple boot does not provide any security features nor OTA updates.
-
-MCUboot bootloader
-==================
-
-User may choose to use MCUboot bootloader instead. In that case the bootloader
-must be built (and flashed) at least once.
-
-There are two options to be used when building an application:
-
-1. Sysbuild
-2. Manual build
-
-.. note::
-
-   User can select the MCUboot bootloader by adding the following line
-   to the board default configuration file.
-
-   .. code:: cfg
-
-      CONFIG_BOOTLOADER_MCUBOOT=y
-
-Sysbuild
-========
-
-The sysbuild makes possible to build and flash all necessary images needed to
-bootstrap the board with the ESP32 SoC.
-
-To build the sample application using sysbuild use the command:
-
-**Rev B**
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: adafruit_feather_esp32s2@B
-   :goals: build
-   :west-args: --sysbuild
-   :compact:
-
-**Rev C**
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: adafruit_feather_esp32s2@C
-   :goals: build
-   :west-args: --sysbuild
-   :compact:
-
-By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
-images. But it can be configured to create other kind of images.
-
-Build directory structure created by sysbuild is different from traditional
-Zephyr build. Output is structured by the domain subdirectories:
-
-.. code-block::
-
-   build/
-   ├── hello_world
-   │   └── zephyr
-   │       ├── zephyr.elf
-   │       └── zephyr.bin
-   ├── mcuboot
-   │    └── zephyr
-   │       ├── zephyr.elf
-   │       └── zephyr.bin
-   └── domains.yaml
-
-.. note::
-
-   With ``--sysbuild`` option the bootloader will be re-build and re-flash
-   every time the pristine build is used.
-
-For more information about the system build please read the :ref:`sysbuild` documentation.
-
-Manual build
-============
-
-During the development cycle, it is intended to build & flash as quickly possible.
-For that reason, images can be built one at a time using traditional build.
-
-The instructions following are relevant for both manual build and sysbuild.
-The only difference is the structure of the build directory.
-
-.. note::
-
-   Remember that bootloader (MCUboot) needs to be flash at least once.
-
-Build and flash applications as usual:
-
-**Rev B**
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: adafruit_feather_esp32s2@B
-   :goals: build
-
-**Rev C**
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: adafruit_feather_esp32s2@C
-   :goals: build
-
-The usual ``flash`` target will work. Here is an example for the :zephyr:code-sample:`hello_world`
-application.
-
-To enter ROM bootloader mode, hold down ``boot-button`` while clicking reset button.
-When in the ROM bootloader, you can upload code and query the chip using ``west flash``.
-
-
-**Rev B**
-
-   .. zephyr-app-commands::
-      :zephyr-app: samples/hello_world
-      :board: adafruit_feather_esp32s2@B
-      :goals: flash
-
-**Rev C**
-
-   .. zephyr-app-commands::
-      :zephyr-app: samples/hello_world
-      :board: adafruit_feather_esp32s2@C
-      :goals: flash
-
-After the flashing you will receive most likely this Error:
-
-.. code-block:: console
-
-   WARNING: ESP32-S2FNR2 (revision v0.0) chip was placed into download mode using GPIO0.
-   esptool.py can not exit the download mode over USB. To run the app, reset the chip manually.
-   To suppress this note, set --after option to 'no_reset'.
-   FATAL ERROR: command exited with status 1: ...
-
-As stated in the Warning-Message ``esptool`` can't reset the board by itself and this message
-can be ignored and the board needs to be reseted via the Reset-Button manually.
-
-Open the serial monitor using the following command:
-
-.. code-block:: shell
-
-   west espressif monitor
+Programming and Debugging
+*************************
 
-After the board has been manually reseted and booted, you should see the following
-message in the monitor:
+.. zephyr:board-supported-runners::
 
-.. code-block:: console
+.. include:: ../../../espressif/common/building-flashing.rst
+   :start-after: espressif-building-flashing
 
-   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
-   Hello World! adafruit_feather_esp32s2
+.. include:: ../../../espressif/common/board-variants.rst
+   :start-after: espressif-board-variants
 
 Debugging
-*********
-
-ESP32-S2 support on OpenOCD is available at `OpenOCD`_.
+=========
 
-ESP32-S2 has a built-in JTAG circuitry and can be debugged without any
-additional chip. Only an USB cable connected to the D+/D- pins is necessary.
-
-Further documentation can be obtained from the SoC vendor
-in `JTAG debugging for ESP32-S2`_.
-
-You can debug an application in the usual way. Here is an example for
-the :zephyr:code-sample:`hello_world` application.
-
-**Rev B**
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: adafruit_feather_esp32s2@B
-   :goals: debug
-
-**Rev C**
-
-.. zephyr-app-commands::
-   :zephyr-app: samples/hello_world
-   :board: adafruit_feather_esp32s2@C
-   :goals: debug
+.. include:: ../../../espressif/common/openocd-debugging.rst
+   :start-after: espressif-openocd-debugging
 
 Testing the On-Board-LED
 ************************