diff --git a/boards/01space/esp32c3_042_oled/doc/index.rst b/boards/01space/esp32c3_042_oled/doc/index.rst index 801e8651cfa67..f51a329b605f1 100644 --- a/boards/01space/esp32c3_042_oled/doc/index.rst +++ b/boards/01space/esp32c3_042_oled/doc/index.rst @@ -3,7 +3,7 @@ Overview ******** -ESP32C3 0.42 OLED is a mini development board based on the `Espressif ESP32-C3`_ +ESP32-C3 0.42 OLED is a mini development board based on the `Espressif ESP32-C3`_ RISC-V WiFi/Bluetooth dual-mode chip. For more details see the `01space ESP32C3 0.42 OLED`_ Github repo. @@ -31,10 +31,8 @@ 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:: +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features Connections and IOs =================== @@ -50,87 +48,28 @@ 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 -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs. Run the command below to -retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: +System Requirements +******************* - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements 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. - -To build the sample application using sysbuild, use this command: - -.. 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 +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -After the board has automatically reset and booted, you should see the following -message in the monitor: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -.. 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 ********** diff --git a/boards/adafruit/feather_esp32/doc/index.rst b/boards/adafruit/feather_esp32/doc/index.rst index 9c6141ae0d7e9..a9c6928367b3d 100644 --- a/boards/adafruit/feather_esp32/doc/index.rst +++ b/boards/adafruit/feather_esp32/doc/index.rst @@ -6,6 +6,9 @@ Overview The Adafruit ESP32 Feather is an ESP32-based development board using the Feather standard layout. +Hardware +******** + It features the following integrated components: - ESP32-PICO-V3-02 chip (240MHz dual core, Wi-Fi + BLE) @@ -17,51 +20,42 @@ It features the following integrated components: - Reset and user buttons - STEMMA QT I2C connector +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features ================== .. zephyr:board-supported-hw:: -System requirements -=================== - -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order to work. Run -the commands below to retrieve the files. - -.. code-block:: shell +System Requirements +******************* - west update - west blobs fetch hal_espressif +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -Building & flashing -------------------- +Programming and Debugging +************************* -Use the standard build and flash process for this board. See -:ref:`build_an_application` and :ref:`application_run` for more details. +.. zephyr:board-supported-runners:: -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32/esp32/procpu - :goals: build flash +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -The baud rate of 921600bps is set by default. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -After flashing, view the serial monitor with the espressif monitor command. +Debugging +========= -.. code-block:: shell - - west espressif monitor +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging Testing -======= +******* On-board LED ------------- +============ Test the functionality of the user LED connected to pin 13 with the blinky sample program. @@ -72,7 +66,7 @@ sample program. :goals: build flash NeoPixel --------- +======== Test the on-board NeoPixel using the led_strip sample program. @@ -82,7 +76,7 @@ Test the on-board NeoPixel using the led_strip sample program. :goals: build flash User button ------------ +=========== Test the button labeled SW38 using the button input sample program. @@ -92,7 +86,7 @@ Test the button labeled SW38 using the button input sample program. :goals: build flash Wi-Fi ------ +===== Test ESP32 Wi-Fi functionality using the Wi-Fi shell module. @@ -106,8 +100,11 @@ Test ESP32 Wi-Fi functionality using the Wi-Fi shell module. References ********** -- `Adafruit ESP32 Feather V2 `_ -- `Adafruit ESP32 Feather V2 Pinouts `_ -- `Adafruit ESP32 Feather V2 Schematic `_ -- `ESP32-PICO-MINI-02 Datasheet `_ (PDF) -- `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 diff --git a/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2.rst b/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2.rst index 00779bc87e3f0..2fdf91d664e8c 100644 --- a/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2.rst +++ b/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2.rst @@ -38,6 +38,9 @@ Hardware NeoPixel and I2C QT port on ``rev B`` boards ``GPIO7`` (``i2c_reg``) needs to be set to LOW and on ``rev C`` boards it needs to be set HIGH. +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features ================== @@ -56,211 +59,28 @@ pinouts and the schematic. - `Adafruit ESP32-S2 Feather Pinouts`_ - `Adafruit ESP32-S2 Feather Schematic`_ -Programming and Debugging -************************* - -.. zephyr:board-supported-runners:: - -Prerequisites -============= - -Espressif HAL requires WiFi binary blobs in order work. Run the command below -to retrieve those files. - -.. code-block:: console - - west update - west blobs fetch hal_espressif - -Building & Flashing +System Requirements ******************* -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 -======== +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -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 ************************ diff --git a/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2_tft.rst b/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2_tft.rst index 6629b57feee6d..8cec7304031bd 100644 --- a/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2_tft.rst +++ b/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2_tft.rst @@ -31,6 +31,9 @@ Hardware - For the MAX17048 and LC709203F a driver in zephyr exists and is supported, but needs to be added via a devicetree overlay. +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features ================== @@ -49,183 +52,28 @@ pinouts and the schematic. - `Adafruit ESP32-S2 TFT Feather Pinouts`_ - `Adafruit ESP32-S2 TFT Feather Schematic`_ -Programming and Debugging -************************* - -.. zephyr:board-supported-runners:: - -Prerequisites -============= - -Espressif HAL requires WiFi binary blobs in order work. Run the command below -to retrieve those files. - -.. code-block:: console - - west update - west blobs fetch hal_espressif - -Building & Flashing +System Requirements ******************* -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: - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s2_tft - :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. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -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: - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s2_tft - :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``. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s2_tft - :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_tft +.. 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. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s2_tft - :goals: debug - -Testing the On-Board-LED -************************ - -There is a sample available to verify that the LEDs on the board are -functioning correctly with Zephyr: - -.. zephyr-app-commands:: - :zephyr-app: samples/basic/blinky - :board: adafruit_feather_esp32s2_tft - :goals: build flash +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging Testing the NeoPixel ******************** diff --git a/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2_tft_reverse.rst b/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2_tft_reverse.rst index ad90a07858204..9e7915745b16b 100644 --- a/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2_tft_reverse.rst +++ b/boards/adafruit/feather_esp32s2/doc/adafruit_feather_esp32s2_tft_reverse.rst @@ -27,6 +27,9 @@ Hardware - For the MAX17048 a driver in zephyr exists and is supported, but needs to be added via a devicetree overlay. +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features ================== @@ -45,172 +48,28 @@ including pinouts and the schematic. - `Adafruit ESP32-S2 Reverse TFT Feather Pinouts`_ - `Adafruit ESP32-S2 Reverse TFT Feather Schematic`_ -Programming and Debugging -************************* - -.. zephyr:board-supported-runners:: - -Prerequisites -============= - -Espressif HAL requires WiFi binary blobs in order work. Run the command below -to retrieve those files. - -.. code-block:: console - - west update - west blobs fetch hal_espressif - -Building & Flashing +System Requirements ******************* -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: - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s2_tft_reverse - :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 +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. 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: - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s2_tft_reverse - :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``. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s2_tft_reverse - :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_tft_reverse +.. 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. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s2_tft_reverse - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging Testing the On-Board-LED ************************ diff --git a/boards/adafruit/feather_esp32s3/doc/index.rst b/boards/adafruit/feather_esp32s3/doc/index.rst index 17332ba68fab6..f79c285de03c5 100644 --- a/boards/adafruit/feather_esp32s3/doc/index.rst +++ b/boards/adafruit/feather_esp32s3/doc/index.rst @@ -23,59 +23,13 @@ Hardware - Built-in NeoPixel indicator RGB LED - STEMMA QT connector for I2C devices, with switchable power for low-power mode -Asymmetric Multiprocessing (AMP) -================================ - -The ESP32-S3 SoC allows 2 different applications to be executed in asymmetric -multiprocessing. 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 :zephyr:code-sample-category:`ipc` folder as code reference. - -For more information, check the datasheet at `ESP32-S3 Datasheet`_. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features Supported Features ================== -The current ``adafruit_feather_esp32s3`` board supports the following hardware -features: - -+------------+------------+-------------------------------------+ -| Interface | Controller | Driver/Component | -+============+============+=====================================+ -| UART | on-chip | serial port | -+------------+------------+-------------------------------------+ -| GPIO | on-chip | gpio | -+------------+------------+-------------------------------------+ -| PINMUX | on-chip | pinmux | -+------------+------------+-------------------------------------+ -| USB-JTAG | on-chip | hardware interface | -+------------+------------+-------------------------------------+ -| SPI Master | on-chip | spi | -+------------+------------+-------------------------------------+ -| TWAI/CAN | on-chip | can | -+------------+------------+-------------------------------------+ -| ADC | on-chip | adc | -+------------+------------+-------------------------------------+ -| Timers | on-chip | counter | -+------------+------------+-------------------------------------+ -| Watchdog | on-chip | watchdog | -+------------+------------+-------------------------------------+ -| TRNG | on-chip | entropy | -+------------+------------+-------------------------------------+ -| LEDC | on-chip | pwm | -+------------+------------+-------------------------------------+ -| MCPWM | on-chip | pwm | -+------------+------------+-------------------------------------+ -| PCNT | on-chip | qdec | -+------------+------------+-------------------------------------+ -| GDMA | on-chip | dma | -+------------+------------+-------------------------------------+ -| USB-CDC | on-chip | serial | -+------------+------------+-------------------------------------+ -| Wi-Fi | on-chip | | -+------------+------------+-------------------------------------+ -| Bluetooth | on-chip | | -+------------+------------+-------------------------------------+ +.. zephyr:board-supported-hw:: Connections and IOs =================== @@ -83,173 +37,28 @@ Connections and IOs The `Adafruit Feather ESP32-S3 User Guide`_ has detailed information about the board including `pinouts`_ and the `schematic`_. +System Requirements +******************* + +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements + Programming and Debugging ************************* .. zephyr:board-supported-runners:: -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the -command below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -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 build (and flash) 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-S3 SoC. - -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3/esp32s3/procpu - :goals: build - :west-args: --sysbuild - :compact: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -By default, the ESP32-S3 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 build 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``adafruit_feather_esp32s3`` board -. Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3/esp32s3/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! adafruit_feather_esp32s3 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ========= -ESP32-S3 support on OpenOCD is available upstream as of version 0.12.0. Download -and install OpenOCD from `OpenOCD`_. - -ESP32-S3 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-S3`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3/esp32s3/procpu - :goals: build flash - -You can debug an application in the usual way. Here is an example for the -:zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3/esp32s3/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/adafruit/feather_esp32s3_tft/doc/index.rst b/boards/adafruit/feather_esp32s3_tft/doc/index.rst index 7324debe849da..b0a357afcc1d3 100644 --- a/boards/adafruit/feather_esp32s3_tft/doc/index.rst +++ b/boards/adafruit/feather_esp32s3_tft/doc/index.rst @@ -85,173 +85,28 @@ Connections and IOs The `Adafruit Feather ESP32-S3 TFT User Guide`_ has detailed information about the board including `pinouts`_ and the `schematic`_. +System Requirements +******************* + +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements + Programming and Debugging ************************* .. zephyr:board-supported-runners:: -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the -command below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -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 build (and flash) 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-S3 SoC. - -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3_tft/esp32s3/procpu - :goals: build - :west-args: --sysbuild - :compact: - -By default, the ESP32-S3 sysbuild creates bootloader (MCUboot) and application -images. But it can be configured to create other kind of images. +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -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 build 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3_tft/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``adafruit_feather_esp32s3_tft`` -board. Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3_tft/esp32s3/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! adafruit_feather_esp32s3_tft +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ========= -ESP32-S3 support on OpenOCD is available upstream as of version 0.12.0. Download -and install OpenOCD from `OpenOCD`_. - -ESP32-S3 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-S3`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3_tft/esp32s3/procpu - :goals: build flash - -You can debug an application in the usual way. Here is an example for the -:zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3_tft/esp32s3/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/adafruit/feather_esp32s3_tft_reverse/doc/index.rst b/boards/adafruit/feather_esp32s3_tft_reverse/doc/index.rst index 98135629d74b2..587a024b17824 100644 --- a/boards/adafruit/feather_esp32s3_tft_reverse/doc/index.rst +++ b/boards/adafruit/feather_esp32s3_tft_reverse/doc/index.rst @@ -29,16 +29,8 @@ Hardware - Three User Tactile buttons - D0, D1, and D2. D0/BOOT0 is also used for entering ROM bootloader mode if necessary. - -Asymmetric Multiprocessing (AMP) -================================ - -The ESP32-S3 SoC allows 2 different applications to be executed in asymmetric -multiprocessing. 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 :zephyr:code-sample-category:`ipc` folder as code reference. - -For more information, check the datasheet at `ESP32-S3 Datasheet`_. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features Supported Features ================== @@ -51,173 +43,28 @@ Connections and IOs The `Adafruit ESP32-S3 Reverse TFT Feather User Guide`_ has detailed information about the board including `pinouts`_ and the `schematic`_. +System Requirements +******************* + +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements + Programming and Debugging ************************* .. zephyr:board-supported-runners:: -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the -command below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -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 build (and flash) 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-S3 SoC. - -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3_tft_reverse/esp32s3/procpu - :goals: build - :west-args: --sysbuild - :compact: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -By default, the ESP32-S3 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 build 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: :board: adafruit_feather_esp32s3_tft_reverse/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``adafruit_feather_esp32s3_tft_reverse`` -board. Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3_tft_reverse/esp32s3/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! adafruit_feather_esp32s3_tft_reverse/esp32s3/procpu +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ========= -ESP32-S3 support on OpenOCD is available upstream as of version 0.12.0. Download -and install OpenOCD from `OpenOCD`_. - -ESP32-S3 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-S3`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3_tft_reverse/esp32s3/procpu - :goals: build flash - -You can debug an application in the usual way. Here is an example for the -:zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_feather_esp32s3_tft_reverse/esp32s3/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/adafruit/qt_py_esp32s3/doc/index.rst b/boards/adafruit/qt_py_esp32s3/doc/index.rst index 8ad715a673c0d..01bb7f108bf21 100644 --- a/boards/adafruit/qt_py_esp32s3/doc/index.rst +++ b/boards/adafruit/qt_py_esp32s3/doc/index.rst @@ -23,222 +23,36 @@ bootloader or user input. Like many other Adafruit boards, it has a `SparkFun Qwiic`_-compatible `STEMMA QT`_ connector for the I2C bus so you don't even need to solder. -ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated -2.4 GHz Wi-Fi and Bluetooth® Low Energy (Bluetooth LE). It consists of -high-performance dual-core microprocessor (Xtensa® 32-bit LX7), a low power -coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband, RF module, and -numerous peripherals. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features Supported Features ================== .. zephyr:board-supported-hw:: -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the -command below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: adafruit_qt_py_esp32s3 - :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. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -The instructions following are relevant for both manual build and sysbuild. -The only difference is the structure of the build directory. +Programming and Debugging +************************* -.. note:: - - Remember that bootloader (MCUboot) needs to be flash at least once. - -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. tabs:: - - .. group-tab:: QT Py ESP32S3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_qt_py_esp32s3/esp32s3/procpu - :goals: build - - .. group-tab:: QT Py ESP32S3 with PSRAM - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_qt_py_esp32s3@psram/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``adafruit_qt_py_esp32s3`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. tabs:: - - .. group-tab:: QT Py ESP32S3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_qt_py_esp32s3/esp32s3/procpu - :goals: flash - - .. group-tab:: QT Py ESP32S3 with PSRAM - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_qt_py_esp32s3@psram/esp32s3/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset 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_qt_py_esp32s3/esp32s3/procpu +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_. - -ESP32-S3 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-S3`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. tabs:: - - .. group-tab:: QT Py ESP32S3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_qt_py_esp32s3/esp32s3/procpu - :goals: debug - - .. group-tab:: QT Py ESP32S3 with PSRAM - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_qt_py_esp32s3@psram/esp32s3/procpu - :goals: debug - -You can debug an application in the usual way. Here is an example for -the :zephyr:code-sample:`hello_world` application. - -.. tabs:: - - .. group-tab:: QT Py ESP32S3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_qt_py_esp32s3/esp32s3/procpu - :goals: debug - - .. group-tab:: QT Py ESP32S3 with PSRAM +========= - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: adafruit_qt_py_esp32s3@psram/esp32s3/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/aithinker/esp32_cam/doc/index.rst b/boards/aithinker/esp32_cam/doc/index.rst index 4e6efe50e34da..ed6faa8115b10 100644 --- a/boards/aithinker/esp32_cam/doc/index.rst +++ b/boards/aithinker/esp32_cam/doc/index.rst @@ -5,6 +5,9 @@ Overview Ai-Thinker ESP32-CAM is an ESP32-based development board produced by `Ai-Thinker `_. +Hardware +******** + ESP32-CAM features the following components: - ESP32S module @@ -17,27 +20,19 @@ ESP32-CAM features the following components: ESP32's GPIO4 on the ESP32 is shared between the MicroSD data pin and the onboard flash LED. -For more information, check the datasheet at `ESP32 Datasheet`_ or the technical reference -manual at `ESP32 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features Supported Features -****************** +================== .. zephyr:board-supported-hw:: -System requirements +System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* @@ -50,22 +45,12 @@ Programming and Debugging .. include:: ../../../espressif/common/board-variants.rst :start-after: espressif-board-variants -Applications for the ``esp32_cam`` board can be built and flashed in the usual way -(see :ref:`build_an_application` and :ref:`application_run` for more details); -however, an external FTDI USB to TTL Serial Adapter is required since the board -does not have any on-board debug IC. - -The following pins of the Serial Adapter must be connected to the header pins: - -* VTref = VCC -* GND = GND -* TXD = U0TXD -* RXD = U0RXD -* Boot = GPIO0 (Must be low at boot) - Debugging ========= +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging + ESP32 support on OpenOCD is available at `OpenOCD ESP32`_. +------------+-----------+ @@ -84,14 +69,22 @@ ESP32 support on OpenOCD is available at `OpenOCD ESP32`_. | IO15 | TDO | +------------+-----------+ +Sample Applications +******************* + Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32`_. +Applications for the ``esp32_cam`` board can be built and flashed in the usual way +(see :ref:`build_an_application` and :ref:`application_run` for more details); +however, an external FTDI USB to TTL Serial Adapter is required since the board +does not have any on-board debug IC. -Here is an example for building the :zephyr:code-sample:`hello_world` application. +The following pins of the Serial Adapter must be connected to the header pins: -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32_cam/esp32/procpu - :goals: build flash +* VTref = VCC +* GND = GND +* TXD = U0TXD +* RXD = U0RXD +* Boot = GPIO0 (Must be low at boot) References ********** diff --git a/boards/dptechnics/walter/doc/index.rst b/boards/dptechnics/walter/doc/index.rst index eb5dc5e3d50f2..1b12c6facaf48 100644 --- a/boards/dptechnics/walter/doc/index.rst +++ b/boards/dptechnics/walter/doc/index.rst @@ -55,168 +55,36 @@ Form factor - Pin and footprint compatible with EOL Pycom GPy - Breadboard friendly +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features ================== .. zephyr:board-supported-hw:: -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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 build (and flash) 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-S3 SoC. - -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :app: samples/hello_world - :board: walter/esp32s3/procpu - :goals: build - :west-args: --sysbuild - :compact: +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -By default, the ESP32 sysbuild creates bootloader (MCUboot) and application -images. But it can be configured to create other kind of images. +Programming and Debugging +************************* -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 build 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: walter/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``walter`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: walter/esp32s3/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset 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! walter/esp32s3/procpu +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_. - -ESP32-S3 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-S3`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: walter/esp32s3/procpu - :goals: build flash - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: walter/esp32s3/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/espressif/common/board-variants.rst b/boards/espressif/common/board-variants.rst index b04cdc57b5f0a..0fffde9c64602 100644 --- a/boards/espressif/common/board-variants.rst +++ b/boards/espressif/common/board-variants.rst @@ -42,4 +42,9 @@ To apply a board variant, use the ``-S`` flag with west build: :snippets: flash-32M,psram-4M :compact: -**Note:** These snippets are applicable to boards with compatible hardware support for the selected flash/PSRAM configuration. +.. note:: + + These snippets are applicable to boards with compatible hardware support for the selected flash/PSRAM configuration. + + - If no FLASH snippet is used, the board default flash size will be used. + - If no PSRAM snippet is used, the board default psram size will be used. diff --git a/boards/espressif/common/soc-esp32-features.rst b/boards/espressif/common/soc-esp32-features.rst new file mode 100644 index 0000000000000..f2825bd044f9a --- /dev/null +++ b/boards/espressif/common/soc-esp32-features.rst @@ -0,0 +1,40 @@ +:orphan: + +.. espressif-soc-esp32-features + +ESP32 Features +============== + +- Dual core Xtensa microprocessor (LX6), running at 160 or 240MHz +- 520KB of SRAM +- 802.11b/g/n/e/i +- Bluetooth v4.2 BR/EDR and BLE +- Various peripherals: + + - 12-bit ADC with up to 18 channels + - 2x 8-bit DACs + - 10x touch sensors + - Temperature sensor + - 4x SPI + - 2x I2S + - 2x I2C + - 3x UART + - SD/SDIO/MMC host + - Slave (SDIO/SPI) + - Ethernet MAC + - CAN bus 2.0 + - IR (RX/TX) + - Motor PWM + - LED PWM with up to 16 channels + - Hall effect sensor + +- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) +- 5uA deep sleep current + +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 +and/or exchanging data over OpenAMP framework. See :zephyr:code-sample-category:`ipc` folder as code reference. + +For more information, check the `ESP32 Datasheet`_ or the `ESP32 Technical Reference Manual`_. diff --git a/boards/espressif/common/soc-esp32c2-features.rst b/boards/espressif/common/soc-esp32c2-features.rst new file mode 100644 index 0000000000000..b904e9ebc0fa5 --- /dev/null +++ b/boards/espressif/common/soc-esp32c2-features.rst @@ -0,0 +1,39 @@ +:orphan: + +.. espressif-soc-esp32c2-features + +ESP32-C2 Features +================= + +ESP32-C2 (ESP8684 core) is a low-cost, Wi-Fi 4 & Bluetooth 5 (LE) chip. Its unique design +makes the chip smaller and yet more powerful than ESP8266. ESP32-C2 is built around a RISC-V +32-bit, single-core processor, with 272 KB of SRAM (16 KB dedicated to cache) and 576 KB of ROM. +ESP32-C2 has been designed to target simple, high-volume, and low-data-rate IoT applications, +such as smart plugs and smart light bulbs. ESP32-C2 offers easy and robust wireless connectivity, +which makes it the go-to solution for developing simple, user-friendly and reliable +smart-home devices. + +Features include the following: + +- 32-bit core RISC-V microcontroller with a maximum clock speed of 120 MHz +- 2 MB or 4 MB in chip (ESP8684) or in package (ESP32-C2) flash +- 272 KB of internal RAM +- 802.11b/g/n +- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh +- Various peripherals: + + - 14 programmable GPIOs + - 3 SPI + - 2 UART + - 1 I2C Master + - LED PWM controller, with up to 6 channels + - General DMA controller (GDMA) + - 1 12-bit SAR ADC, up to 5 channels + - 1 temperature sensor + - 1 54-bit general-purpose timer + - 2 watchdog timers + - 1 52-bit system timer + +- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) + +For detailed information check the `ESP8684 Datasheet`_ or the `ESP8684 Technical Reference Manual`_. diff --git a/boards/espressif/common/soc-esp32c3-features.rst b/boards/espressif/common/soc-esp32c3-features.rst new file mode 100644 index 0000000000000..db763329e1d17 --- /dev/null +++ b/boards/espressif/common/soc-esp32c3-features.rst @@ -0,0 +1,43 @@ +:orphan: + +.. espressif-soc-esp32c3-features + +ESP32-C3 Features +================= + +ESP32-C3 is a single-core Wi-Fi and Bluetooth 5 (LE) microcontroller SoC, +based on the open-source RISC-V architecture. It strikes the right balance of power, +I/O capabilities and security, thus offering the optimal cost-effective +solution for connected devices. +The availability of Wi-Fi and Bluetooth 5 (LE) connectivity not only makes the device configuration easy, +but it also facilitates a variety of use-cases based on dual connectivity. + +The features include the following: + +- 32-bit core RISC-V microcontroller with a maximum clock speed of 160 MHz +- 802.11b/g/n/ +- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh +- 384 KB ROM +- 400 KB SRAM (16 KB for cache) +- 8 KB SRAM in RTC +- 22 x programmable GPIOs +- Various peripherals: + + - Full-speed USB Serial/JTAG controller + - TWAI® compatible with CAN bus 2.0 + - General DMA controller (GDMA) + - 2x 12-bit SAR ADC with up to 6 channels + - 3x SPI + - 2x UART + - 1x I2S + - 1x I2C + - 2 x 54-bit general-purpose timers + - 3 x watchdog timers + - 1 x 52-bit system timer + - Remote Control Peripheral (RMT) + - LED PWM controller (LEDC) with up to 6 channels + - Temperature sensor + +- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) + +For more information, check the `ESP32-C3 Datasheet`_ or the `ESP32-C3 Technical Reference Manual`_. diff --git a/boards/espressif/common/soc-esp32c6-features.rst b/boards/espressif/common/soc-esp32c6-features.rst new file mode 100644 index 0000000000000..d27e77a82b1fe --- /dev/null +++ b/boards/espressif/common/soc-esp32c6-features.rst @@ -0,0 +1,90 @@ +:orphan: + +.. espressif-soc-esp32c6-features + +ESP32-C6 Features +================= + +ESP32-C6 is Espressif's first Wi-Fi 6 SoC integrating 2.4 GHz Wi-Fi 6, Bluetooth 5.3 (LE) and the +802.15.4 protocol. ESP32-C6 achieves an industry-leading RF performance, with reliable security +features and multiple memory resources for IoT products. +It consists of a high-performance (HP) 32-bit RISC-V processor, which can be clocked up to 160 MHz, +and a low-power (LP) 32-bit RISC-V processor, which can be clocked up to 20 MHz. +It has a 320KB ROM, a 512KB SRAM, and works with external flash. + +ESP32-C6 includes the following features: + +- 32-bit core RISC-V microcontroller with a clock speed of up to 160 MHz +- 400 KB of internal RAM +- WiFi 802.11 ax 2.4GHz +- Fully compatible with IEEE 802.11b/g/n protocol +- Bluetooth LE: Bluetooth 5.3 certified +- Internal co-existence mechanism between Wi-Fi and Bluetooth to share the same antenna +- IEEE 802.15.4 (Zigbee and Thread) + +Digital interfaces: + +- 30x GPIOs (QFN40), or 22x GPIOs (QFN32) +- 2x UART +- 1x Low-power (LP) UART +- 1x General purpose SPI +- 1x I2C +- 1x Low-power (LP) I2C +- 1x I2S +- 1x Pulse counter +- 1x USB Serial/JTAG controller +- 1x TWAI® controller, compatible with ISO 11898-1 (CAN Specification 2.0) +- 1x SDIO 2.0 slave controller +- LED PWM controller, up to 6 channels +- 1x Motor control PWM (MCPWM) +- 1x Remote control peripehral +- 1x Parallel IO interface (PARLIO) +- General DMA controller (GDMA), with 3 transmit channels and 3 receive channels +- Event task matrix (ETM) + +Analog interfaces: + +- 1x 12-bit SAR ADCs, up to 7 channels +- 1x temperature sensor + +Timers: + +- 1x 52-bit system timer +- 1x 54-bit general-purpose timers +- 3x Watchdog timers +- 1x Analog watchdog timer + +Low Power: + +- Four power modes designed for typical scenarios: Active, Modem-sleep, Light-sleep, Deep-sleep + +Security: + +- Secure boot +- Flash encryption +- 4-Kbit OTP, up to 1792 bits for users +- Cryptographic hardware acceleration: (AES-128/256, ECC, HMAC, RSA, SHA, Digital signature, Hash) +- Random number generator (RNG) + +Low-Power CPU (LP CORE) +======================= + +The ESP32-C6 SoC has two RISC-V cores: the High-Performance Core (HP CORE) and the Low-Power Core (LP CORE). +The LP Core features ultra low power consumption, an interrupt controller, a debug module and a system bus +interface for memory and peripheral access. + +The LP Core is in sleep mode by default. It has two application scenarios: + +- Power insensitive scenario: When the High-Performance CPU (HP Core) is active, the LP Core can assist the HP CPU with some speed and efficiency-insensitive controls and computations. +- Power sensitive scenario: When the HP CPU is in the power-down state to save power, the LP Core can be woken up to handle some external wake-up events. + +The LP Core support is fully integrated with :ref:`sysbuild`. The user can enable the LP Core by adding +the following configuration to the project: + +.. code:: cfg + + CONFIG_ULP_COPROC_ENABLED=y + +See :zephyr:code-sample-category:`lp-core` folder as code reference. + +For more information, check the `ESP32-C6 Datasheet`_ or the `ESP32-C6 Technical Reference Manual`_. diff --git a/boards/espressif/common/soc-esp32h2-features.rst b/boards/espressif/common/soc-esp32h2-features.rst new file mode 100644 index 0000000000000..d566c5015afd2 --- /dev/null +++ b/boards/espressif/common/soc-esp32h2-features.rst @@ -0,0 +1,65 @@ +:orphan: + +.. espressif-soc-esp32h2-features + +ESP32-H2 Features +================= + +ESP32-H2 combines IEEE 802.15.4 connectivity with Bluetooth 5 (LE). The SoC is powered by +a single-core, 32-bit RISC-V microcontroller that can be clocked up to 96 MHz. The ESP32-H2 has +been designed to ensure low power consumption and security for connected devices. ESP32-H2 has +320 KB of SRAM with 16 KB of Cache, 128 KB of ROM, 4 KB LP of memory, and a built-in 2 MB or 4 MB +SiP flash. It has 19 programmable GPIOs with support for ADC, SPI, UART, I2C, I2S, RMT, GDMA +and LED PWM. + +ESP32-H2 main features: + +- RISC-V 32-bit single-core microprocessor +- 320 KB of internal RAM +- 4 KB LP Memory +- Bluetooth LE: Bluetooth 5.3 certified +- IEEE 802.15.4 (Zigbee and Thread) +- 19 programmable GPIOs +- Numerous peripherals (details below) + +Digital interfaces: + +- 19x GPIOs +- 2x UART +- 2x I2C +- 1x General-purpose SPI +- 1x I2S +- 1x Pulse counter +- 1x USB Serial/JTAG controller +- 1x TWAI® controller, compatible with ISO 11898-1 (CAN Specification 2.0) +- 1x LED PWM controller, up to 6 channels +- 1x Motor Control PWM (MCPWM) +- 1x Remote Control peripheral (RMT), with up to 2 TX and 2 RX channels +- 1x Parallel IO interface (PARLIO) +- General DMA controller (GDMA), with 3 transmit channels and 3 receive channels +- Event Task Matrix (ETM) + +Analog interfaces: + +- 1x 12-bit SAR ADCs, up to 5 channels +- 1x Temperature sensor (die) + +Timers: + +- 1x 52-bit system timer +- 2x 54-bit general-purpose timers +- 3x Watchdog timers + +Low Power: + +- Four power modes designed for typical scenarios: Active, Modem-sleep, Light-sleep, Deep-sleep + +Security: + +- Secure boot +- Flash encryption +- 4-Kbit OTP, up to 1792 bits for users +- Cryptographic hardware acceleration: (AES-128/256, ECC, HMAC, RSA, SHA, Digital signature, Hash) +- Random number generator (RNG) + +For detailed information, check the `ESP32-H2 Datasheet`_ or the `ESP32-H2 Technical Reference Manual`_. diff --git a/boards/espressif/common/soc-esp32s2-features.rst b/boards/espressif/common/soc-esp32s2-features.rst new file mode 100644 index 0000000000000..1496c57cdacdb --- /dev/null +++ b/boards/espressif/common/soc-esp32s2-features.rst @@ -0,0 +1,32 @@ +:orphan: + +.. espressif-soc-esp32s2-features + +ESP32-S2 Features +================= + +ESP32-S2 is a highly integrated, low-power, single-core Wi-Fi Microcontroller SoC, designed to be secure and +cost-effective, with a high performance and a rich set of IO capabilities. + +The features include the following: + +- RSA-3072-based secure boot +- AES-XTS-256-based flash encryption +- Protected private key and device secrets from software access +- Cryptographic accelerators for enhanced performance +- Protection against physical fault injection attacks +- Various peripherals: + + - 43x programmable GPIOs + - 14x configurable capacitive touch GPIOs + - USB OTG + - LCD interface + - camera interface + - SPI + - I2S + - UART + - ADC + - DAC + - LED PWM with up to 8 channels + +For more information, check the `ESP32-S2 Datasheet`_ or the `ESP32-S2 Technical Reference Manual`_. diff --git a/boards/espressif/common/soc-esp32s3-features.rst b/boards/espressif/common/soc-esp32s3-features.rst new file mode 100644 index 0000000000000..db7631d16d9ba --- /dev/null +++ b/boards/espressif/common/soc-esp32s3-features.rst @@ -0,0 +1,73 @@ +:orphan: + +.. espressif-soc-esp32s3-features + +ESP32-S3 Features +================= + +ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated 2.4 GHz Wi-Fi +and Bluetooth® Low Energy (Bluetooth LE). It consists of high-performance dual-core microprocessor +(Xtensa® 32-bit LX7), a low power coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband, +RF module, and numerous peripherals. + +ESP32-S3 SoC includes the following features: + +- Dual core 32-bit Xtensa Microprocessor (Tensilica LX7), running up to 240MHz +- Additional vector instructions support for AI acceleration +- 512KB of SRAM +- 384KB of ROM +- Wi-Fi 802.11b/g/n +- Bluetooth LE 5.0 with long-range support and up to 2Mbps data rate + +Digital interfaces: + +- 45 programmable GPIOs +- 4x SPI +- 1x LCD interface (8-bit ~16-bit parallel RGB, I8080 and MOTO6800), supporting conversion between RGB565, YUV422, YUV420 and YUV411 +- 1x DVP 8-bit ~16-bit camera interface +- 3x UART +- 2x I2C +- 2x I2S +- 1x RMT (TX/RX) +- 1x pulse counter +- LED PWM controller, up to 8 channels +- 1x full-speed USB OTG +- 1x USB Serial/JTAG controller +- 2x MCPWM +- 1x SDIO host controller with 2 slots +- General DMA controller (GDMA), with 5 transmit channels and 5 receive channels +- 1x TWAI® controller, compatible with ISO 11898-1 (CAN Specification 2.0) +- Addressable RGB LED, driven by GPIO38. + +Analog interfaces: + +- 2x 12-bit SAR ADCs, up to 20 channels +- 1x temperature sensor +- 14x touch sensing IOs + +Timers: + +- 4x 54-bit general-purpose timers +- 1x 52-bit system timer +- 3x watchdog timers + +Low Power: + +- Power Management Unit with five power modes +- Ultra-Low-Power (ULP) coprocessors: ULP-RISC-V and ULP-FSM + +Security: + +- Secure boot +- Flash encryption +- 4-Kbit OTP, up to 1792 bits for users +- Cryptographic hardware acceleration: (AES-128/256, Hash, RSA, RNG, HMAC, Digital signature) + +Asymmetric Multiprocessing (AMP) +================================ + +Boards featuring the ESP32-S3 SoC allows 2 different applications to be executed. 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 :zephyr:code-sample-category:`ipc` folder as code reference. + +For more information, check the `ESP32-S3 Datasheet` or the `ESP32-S3 Technical Reference Manual`_. diff --git a/boards/espressif/common/system-requirements.rst b/boards/espressif/common/system-requirements.rst new file mode 100644 index 0000000000000..b0fd19d139031 --- /dev/null +++ b/boards/espressif/common/system-requirements.rst @@ -0,0 +1,17 @@ +:orphan: + +.. espressif-system-requirements + +Binary Blobs +============ + +Espressif HAL requires RF binary blobs in order work. Run the command +below to retrieve those files. + +.. code-block:: console + + west blobs fetch hal_espressif + +.. note:: + + It is recommended running the command above after :file:`west update`. diff --git a/boards/espressif/esp32_devkitc/doc/index.rst b/boards/espressif/esp32_devkitc/doc/index.rst index 48c1a4496a8cc..c494d112f51d5 100644 --- a/boards/espressif/esp32_devkitc/doc/index.rst +++ b/boards/espressif/esp32_devkitc/doc/index.rst @@ -12,59 +12,22 @@ process. For more information, check `ESP32-DevKitC`_. The features include the following: -- Dual core Xtensa microprocessor (LX6), running at 160 or 240MHz -- 520KB of SRAM -- 802.11b/g/n/e/i -- Bluetooth v4.2 BR/EDR and BLE -- Various peripherals: - - - 12-bit ADC with up to 18 channels - - 2x 8-bit DACs - - 10x touch sensors - - Temperature sensor - - 4x SPI - - 2x I2S - - 2x I2C - - 3x UART - - SD/SDIO/MMC host - - Slave (SDIO/SPI) - - Ethernet MAC - - CAN bus 2.0 - - IR (RX/TX) - - Motor PWM - - LED PWM with up to 16 channels - - Hall effect sensor - -- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) -- 5uA deep sleep current - -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 -and/or exchanging data over OpenAMP framework. See :zephyr:code-sample-category:`ipc` folder as code reference. +Hardware +******** + +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features Supported Features -****************** +================== .. zephyr:board-supported-hw:: System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp32_ethernet_kit/doc/index.rst b/boards/espressif/esp32_ethernet_kit/doc/index.rst index 5c58a64e06822..d2a554a61a8f7 100644 --- a/boards/espressif/esp32_ethernet_kit/doc/index.rst +++ b/boards/espressif/esp32_ethernet_kit/doc/index.rst @@ -37,13 +37,16 @@ USB interface without a separate JTAG debugger. Hardware ******** +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features -****************** +================== .. zephyr:board-supported-hw:: Functionality Overview -********************** +====================== The block diagram below shows the main components of ESP32-Ethernet-Kit and their interconnections. @@ -55,7 +58,6 @@ and their interconnections. ESP32-Ethernet-Kit block diagram - Functional Description ====================== @@ -64,7 +66,6 @@ and controls of the ESP32-Ethernet-Kit. .. _get-started-esp32-ethernet-kit-a-v1.2-layout: - Ethernet Board (A) ------------------ @@ -187,9 +188,8 @@ PoE. When the Ethernet Board (A) detects 5 V power output from the PoE Board .. _get-started-esp32-ethernet-kit-v1.2-setup-options: - Setup Options -************* +============= This section describes options to configure the ESP32-Ethernet-Kit hardware. @@ -211,7 +211,6 @@ DIP SW GPIO Pin 4 GPIO14 ======= ================ - RMII Clock Selection ==================== @@ -267,14 +266,12 @@ 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. - GPIO Allocation -*************** +=============== This section describes allocation of ESP32 GPIOs to specific interfaces or functions of the ESP32-Ethernet-Kit. - IP101GRI (PHY) Interface ======================== @@ -312,7 +309,6 @@ No. ESP32 Pin (MAC) IP101GRI (PHY) be selected from GPIO0, GPIO16 or GPIO17 and it can not be changed through GPIO Matrix. - GPIO Header 1 ============= @@ -330,7 +326,6 @@ No. ESP32 Pin 6 GPIO39 ==== ================ - GPIO Header 2 ============= @@ -413,22 +408,8 @@ GPIO Allocation Summary to use these pins, please solder a module without PSRAM memory inside, e.g. the ESP32-WROOM-32D or ESP32-SOLO-1. -System Requirements -******************* - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - Enabling Ethernet -***************** +================= Enable Ethernet MAC, PHY and MDIO; add these to your device tree overlay: @@ -455,11 +436,17 @@ Enable Ethernet in KConfig: CONFIG_NET_L2_ETHERNET=y Board Init -********** +========== RESET_N (GPIO5) is automatically set high to enable the Ethernet PHY during board initialization (board_init.c) +System Requirements +******************* + +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements + Programming and Debugging ************************* diff --git a/boards/espressif/esp32c3_devkitc/doc/index.rst b/boards/espressif/esp32c3_devkitc/doc/index.rst index 6ba73a120c847..1aaf0d533ec81 100644 --- a/boards/espressif/esp32c3_devkitc/doc/index.rst +++ b/boards/espressif/esp32c3_devkitc/doc/index.rst @@ -10,34 +10,8 @@ For more information, check `ESP32-C3-DevKitC`_. Hardware ******** -ESP32-C3 is a single-core Wi-Fi and Bluetooth 5 (LE) microcontroller SoC, -based on the open-source RISC-V architecture. It strikes the right balance of power, -I/O capabilities and security, thus offering the optimal cost-effective -solution for connected devices. -The availability of Wi-Fi and Bluetooth 5 (LE) connectivity not only makes the device configuration easy, -but it also facilitates a variety of use-cases based on dual connectivity. - -The features include the following: - -- 32-bit core RISC-V microcontroller with a maximum clock speed of 160 MHz -- 400 KB of internal RAM -- 802.11b/g/n/e/i -- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh -- Various peripherals: - - - 12-bit ADC with up to 6 channels - - TWAI compatible with CAN bus 2.0 - - Temperature sensor - - 3x SPI - - 1x I2S - - 1x I2C - - 2x UART - - LED PWM with up to 6 channels - -- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) - -For more information, check the datasheet at `ESP32-C3 Datasheet`_ or the technical reference -manual at `ESP32-C3 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features Supported Features ================== @@ -47,16 +21,8 @@ Supported Features System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp32c3_devkitm/doc/index.rst b/boards/espressif/esp32c3_devkitm/doc/index.rst index c1319966e44b8..df51f88b7bb57 100644 --- a/boards/espressif/esp32c3_devkitm/doc/index.rst +++ b/boards/espressif/esp32c3_devkitm/doc/index.rst @@ -10,34 +10,8 @@ For more information, check `ESP32-C3-DevKitM`_. Hardware ******** -ESP32-C3 is a single-core Wi-Fi and Bluetooth 5 (LE) microcontroller SoC, -based on the open-source RISC-V architecture. It strikes the right balance of power, -I/O capabilities and security, thus offering the optimal cost-effective -solution for connected devices. -The availability of Wi-Fi and Bluetooth 5 (LE) connectivity not only makes the device configuration easy, -but it also facilitates a variety of use-cases based on dual connectivity. - -The features include the following: - -- 32-bit core RISC-V microcontroller with a maximum clock speed of 160 MHz -- 400 KB of internal RAM -- 802.11b/g/n/e/i -- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh -- Various peripherals: - - - 12-bit ADC with up to 6 channels - - TWAI compatible with CAN bus 2.0 - - Temperature sensor - - 3x SPI - - 1x I2S - - 1x I2C - - 2x UART - - LED PWM with up to 6 channels - -- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) - -For more information, check the datasheet at `ESP32-C3 Datasheet`_ or the technical reference -manual at `ESP32-C3 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features Supported Features ================== @@ -47,16 +21,8 @@ Supported Features System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp32c3_rust/doc/index.rst b/boards/espressif/esp32c3_rust/doc/index.rst index 2ab911aab84b0..870d76267c946 100644 --- a/boards/espressif/esp32c3_rust/doc/index.rst +++ b/boards/espressif/esp32c3_rust/doc/index.rst @@ -12,32 +12,8 @@ For more information, check `ESP32-C3-DevKit-RUST`_. Hardware ******** -SoC Features: - -- IEEE 802.11 b/g/n-compliant -- Bluetooth 5, Bluetooth mesh -- 32-bit RISC-V single-core processor, up to 160MHz -- 384 KB ROM -- 400 KB SRAM (16 KB for cache) -- 8 KB SRAM in RTC -- 22 x programmable GPIOs -- 3 x SPI -- 2 x UART -- 1 x I2C -- 1 x I2S -- 2 x 54-bit general-purpose timers -- 3 x watchdog timers -- 1 x 52-bit system timer -- Remote Control Peripheral (RMT) -- LED PWM controller (LEDC) -- Full-speed USB Serial/JTAG controller -- General DMA controller (GDMA) -- 1 x TWAI® -- 2 x 12-bit SAR ADCs, up to 6 channels -- 1 x temperature sensor - -For more information, check the datasheet at `ESP32-C3 Datasheet`_ or the technical reference -manual at `ESP32-C3 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features Supported Features ================== @@ -92,16 +68,8 @@ Power System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp32c6_devkitc/doc/index.rst b/boards/espressif/esp32c6_devkitc/doc/index.rst index 3477165463f24..65e0c038658f5 100644 --- a/boards/espressif/esp32c6_devkitc/doc/index.rst +++ b/boards/espressif/esp32c6_devkitc/doc/index.rst @@ -10,13 +10,6 @@ Bluetooth LE, Zigbee, and Thread functions. For more information, check `ESP32-C Hardware ******** -ESP32-C6 is Espressif's first Wi-Fi 6 SoC integrating 2.4 GHz Wi-Fi 6, Bluetooth 5.3 (LE) and the -802.15.4 protocol. ESP32-C6 achieves an industry-leading RF performance, with reliable security -features and multiple memory resources for IoT products. -It consists of a high-performance (HP) 32-bit RISC-V processor, which can be clocked up to 160 MHz, -and a low-power (LP) 32-bit RISC-V processor, which can be clocked up to 20 MHz. -It has a 320KB ROM, a 512KB SRAM, and works with external flash. - ESP32-C6-DevKitC is an entry-level development board based on ESP32-C6-WROOM-1(U), a general-purpose module with a 8 MB SPI flash. @@ -24,62 +17,8 @@ Most of the I/O pins are broken out to the pin headers on both sides for easy in Developers can either connect peripherals with jumper wires or mount ESP32-C6-DevKitC on a breadboard. -ESP32-C6 includes the following features: - -- 32-bit core RISC-V microcontroller with a clock speed of up to 160 MHz -- 400 KB of internal RAM -- WiFi 802.11 ax 2.4GHz -- Fully compatible with IEEE 802.11b/g/n protocol -- Bluetooth LE: Bluetooth 5.3 certified -- Internal co-existence mechanism between Wi-Fi and Bluetooth to share the same antenna -- IEEE 802.15.4 (Zigbee and Thread) - -Digital interfaces: - -- 30x GPIOs (QFN40), or 22x GPIOs (QFN32) -- 2x UART -- 1x Low-power (LP) UART -- 1x General purpose SPI -- 1x I2C -- 1x Low-power (LP) I2C -- 1x I2S -- 1x Pulse counter -- 1x USB Serial/JTAG controller -- 1x TWAI® controller, compatible with ISO 11898-1 (CAN Specification 2.0) -- 1x SDIO 2.0 slave controller -- LED PWM controller, up to 6 channels -- 1x Motor control PWM (MCPWM) -- 1x Remote control peripehral -- 1x Parallel IO interface (PARLIO) -- General DMA controller (GDMA), with 3 transmit channels and 3 receive channels -- Event task matrix (ETM) - -Analog interfaces: - -- 1x 12-bit SAR ADCs, up to 7 channels -- 1x temperature sensor - -Timers: - -- 1x 52-bit system timer -- 1x 54-bit general-purpose timers -- 3x Watchdog timers -- 1x Analog watchdog timer - -Low Power: - -- Four power modes designed for typical scenarios: Active, Modem-sleep, Light-sleep, Deep-sleep - -Security: - -- Secure boot -- Flash encryption -- 4-Kbit OTP, up to 1792 bits for users -- Cryptographic hardware acceleration: (AES-128/256, ECC, HMAC, RSA, SHA, Digital signature, Hash) -- Random number generator (RNG) - -For more information, check the datasheet at `ESP32-C6 Datasheet`_ or the technical reference -manual at `ESP32-C6 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32c6-features.rst + :start-after: espressif-soc-esp32c6-features Supported Features ================== @@ -89,16 +28,8 @@ Supported Features System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* @@ -117,30 +48,6 @@ Debugging .. include:: ../../../espressif/common/openocd-debugging.rst :start-after: espressif-openocd-debugging -Low-Power CPU (LP CORE) -*********************** - -The ESP32-C6 SoC has two RISC-V cores: the High-Performance Core (HP CORE) and the Low-Power Core (LP CORE). -The LP Core features ultra low power consumption, an interrupt controller, a debug module and a system bus -interface for memory and peripheral access. - -The LP Core is in sleep mode by default. It has two application scenarios: - -- Power insensitive scenario: When the High-Performance CPU (HP Core) is active, the LP Core can assist the HP CPU with some speed and efficiency-insensitive controls and computations. -- Power sensitive scenario: When the HP CPU is in the power-down state to save power, the LP Core can be woken up to handle some external wake-up events. - -For more information, check the datasheet at `ESP32-C6 Datasheet`_ or the technical reference -manual at `ESP32-C6 Technical Reference Manual`_. - -The LP Core support is fully integrated with :ref:`sysbuild`. The user can enable the LP Core by adding -the following configuration to the project: - -.. code:: cfg - - CONFIG_ULP_COPROC_ENABLED=y - -See :zephyr:code-sample-category:`lp-core` folder as code reference. - References ********** diff --git a/boards/espressif/esp32h2_devkitm/doc/index.rst b/boards/espressif/esp32h2_devkitm/doc/index.rst index f1f64f7cd2c48..04e707d6166ec 100644 --- a/boards/espressif/esp32h2_devkitm/doc/index.rst +++ b/boards/espressif/esp32h2_devkitm/doc/index.rst @@ -14,69 +14,8 @@ For details on getting started, check `ESP32-H2-DevKitM-1`_. Hardware ******** -ESP32-H2 combines IEEE 802.15.4 connectivity with Bluetooth 5 (LE). The SoC is powered by -a single-core, 32-bit RISC-V microcontroller that can be clocked up to 96 MHz. The ESP32-H2 has -been designed to ensure low power consumption and security for connected devices. ESP32-H2 has -320 KB of SRAM with 16 KB of Cache, 128 KB of ROM, 4 KB LP of memory, and a built-in 2 MB or 4 MB -SiP flash. It has 19 programmable GPIOs with support for ADC, SPI, UART, I2C, I2S, RMT, GDMA -and LED PWM. - -Most of ESP32-H2-DevKitM-1's I/O pins are broken out to the pin headers on both sides for easy -interfacing. Developers can either connect peripherals with jumper wires or mount the board -on a breadboard. - -ESP32-H2 main features: - -- RISC-V 32-bit single-core microprocessor -- 320 KB of internal RAM -- 4 KB LP Memory -- Bluetooth LE: Bluetooth 5.3 certified -- IEEE 802.15.4 (Zigbee and Thread) -- 19 programmable GPIOs -- Numerous peripherals (details below) - -Digital interfaces: - -- 19x GPIOs -- 2x UART -- 2x I2C -- 1x General-purpose SPI -- 1x I2S -- 1x Pulse counter -- 1x USB Serial/JTAG controller -- 1x TWAI® controller, compatible with ISO 11898-1 (CAN Specification 2.0) -- 1x LED PWM controller, up to 6 channels -- 1x Motor Control PWM (MCPWM) -- 1x Remote Control peripheral (RMT), with up to 2 TX and 2 RX channels -- 1x Parallel IO interface (PARLIO) -- General DMA controller (GDMA), with 3 transmit channels and 3 receive channels -- Event Task Matrix (ETM) - -Analog interfaces: - -- 1x 12-bit SAR ADCs, up to 5 channels -- 1x Temperature sensor (die) - -Timers: - -- 1x 52-bit system timer -- 2x 54-bit general-purpose timers -- 3x Watchdog timers - -Low Power: - -- Four power modes designed for typical scenarios: Active, Modem-sleep, Light-sleep, Deep-sleep - -Security: - -- Secure boot -- Flash encryption -- 4-Kbit OTP, up to 1792 bits for users -- Cryptographic hardware acceleration: (AES-128/256, ECC, HMAC, RSA, SHA, Digital signature, Hash) -- Random number generator (RNG) - -For detailed information, check the datasheet at `ESP32-H2 Datasheet`_ or the Technical Reference -Manual at `ESP32-H2 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32h2-features.rst + :start-after: espressif-soc-esp32h2-features Supported Features ================== @@ -86,16 +25,8 @@ Supported Features System Requirements ******************* -Espressif HAL requires Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp32s2_devkitc/doc/index.rst b/boards/espressif/esp32s2_devkitc/doc/index.rst index b3bef993a45f7..5a7c903da8617 100644 --- a/boards/espressif/esp32s2_devkitc/doc/index.rst +++ b/boards/espressif/esp32s2_devkitc/doc/index.rst @@ -11,32 +11,8 @@ For more information, check `ESP32-S2-DevKitC`_. Hardware ******** -ESP32-S2 is a highly integrated, low-power, single-core Wi-Fi Microcontroller SoC, designed to be secure and -cost-effective, with a high performance and a rich set of IO capabilities. - -The features include the following: - -- RSA-3072-based secure boot -- AES-XTS-256-based flash encryption -- Protected private key and device secrets from software access -- Cryptographic accelerators for enhanced performance -- Protection against physical fault injection attacks -- Various peripherals: - - - 43x programmable GPIOs - - 14x configurable capacitive touch GPIOs - - USB OTG - - LCD interface - - camera interface - - SPI - - I2S - - UART - - ADC - - DAC - - LED PWM with up to 8 channels - -For more information, check the datasheet at `ESP32-S2 Datasheet`_ or the technical reference -manual at `ESP32-S2 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32s2-features.rst + :start-after: espressif-soc-esp32s2-features Supported Features ================== @@ -46,16 +22,8 @@ Supported Features System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp32s2_saola/doc/index.rst b/boards/espressif/esp32s2_saola/doc/index.rst index 418fde8cba778..bc5c8788a214d 100644 --- a/boards/espressif/esp32s2_saola/doc/index.rst +++ b/boards/espressif/esp32s2_saola/doc/index.rst @@ -11,32 +11,8 @@ For more information, check `ESP32-S3-DevKitC`_. Hardware ******** -ESP32-S2 is a highly integrated, low-power, single-core Wi-Fi Microcontroller SoC, designed to be secure and -cost-effective, with a high performance and a rich set of IO capabilities. - -The features include the following: - -- RSA-3072-based secure boot -- AES-XTS-256-based flash encryption -- Protected private key and device secrets from software access -- Cryptographic accelerators for enhanced performance -- Protection against physical fault injection attacks -- Various peripherals: - - - 43x programmable GPIOs - - 14x configurable capacitive touch GPIOs - - USB OTG - - LCD interface - - camera interface - - SPI - - I2S - - UART - - ADC - - DAC - - LED PWM with up to 8 channels - -For more information, check the datasheet at `ESP32-S2 Datasheet`_ or the technical reference -manual at `ESP32-S2 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32s2-features.rst + :start-after: espressif-soc-esp32s2-features Supported Features ================== @@ -46,16 +22,8 @@ Supported Features System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp32s3_devkitc/doc/index.rst b/boards/espressif/esp32s3_devkitc/doc/index.rst index 6fce1233a6894..6398b99a932d3 100644 --- a/boards/espressif/esp32s3_devkitc/doc/index.rst +++ b/boards/espressif/esp32s3_devkitc/doc/index.rst @@ -10,73 +10,8 @@ and Bluetooth Low Energy functions. For more information, check `ESP32-S3-DevKit Hardware ******** -ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated 2.4 GHz Wi-Fi -and Bluetooth® Low Energy (Bluetooth LE). It consists of high-performance dual-core microprocessor -(Xtensa® 32-bit LX7), a low power coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband, -RF module, and numerous peripherals. - -ESP32-S3-DevKitC includes the following features: - -- Dual core 32-bit Xtensa Microprocessor (Tensilica LX7), running up to 240MHz -- Additional vector instructions support for AI acceleration -- 512KB of SRAM -- 384KB of ROM -- Wi-Fi 802.11b/g/n -- Bluetooth LE 5.0 with long-range support and up to 2Mbps data rate - -Digital interfaces: - -- 45 programmable GPIOs -- 4x SPI -- 1x LCD interface (8-bit ~16-bit parallel RGB, I8080 and MOTO6800), supporting conversion between RGB565, YUV422, YUV420 and YUV411 -- 1x DVP 8-bit ~16-bit camera interface -- 3x UART -- 2x I2C -- 2x I2S -- 1x RMT (TX/RX) -- 1x pulse counter -- LED PWM controller, up to 8 channels -- 1x full-speed USB OTG -- 1x USB Serial/JTAG controller -- 2x MCPWM -- 1x SDIO host controller with 2 slots -- General DMA controller (GDMA), with 5 transmit channels and 5 receive channels -- 1x TWAI® controller, compatible with ISO 11898-1 (CAN Specification 2.0) -- Addressable RGB LED, driven by GPIO38. - -Analog interfaces: - -- 2x 12-bit SAR ADCs, up to 20 channels -- 1x temperature sensor -- 14x touch sensing IOs - -Timers: - -- 4x 54-bit general-purpose timers -- 1x 52-bit system timer -- 3x watchdog timers - -Low Power: - -- Power Management Unit with five power modes -- Ultra-Low-Power (ULP) coprocessors: ULP-RISC-V and ULP-FSM - -Security: - -- Secure boot -- Flash encryption -- 4-Kbit OTP, up to 1792 bits for users -- Cryptographic hardware acceleration: (AES-128/256, Hash, RSA, RNG, HMAC, Digital signature) - -Asymmetric Multiprocessing (AMP) -******************************** - -ESP32S3-DevKitC allows 2 different applications to be executed in ESP32-S3 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 :zephyr:code-sample-category:`ipc` folder as code reference. - -For more information, check the datasheet at `ESP32-S3 Datasheet`_ or the technical reference -manual at `ESP32-S3 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features Supported Features ================== @@ -86,16 +21,8 @@ Supported Features System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp32s3_devkitm/doc/index.rst b/boards/espressif/esp32s3_devkitm/doc/index.rst index bb403fb5ab0c8..2d2c152776c70 100644 --- a/boards/espressif/esp32s3_devkitm/doc/index.rst +++ b/boards/espressif/esp32s3_devkitm/doc/index.rst @@ -10,92 +10,19 @@ and Bluetooth Low Energy functions. For more information, check `ESP32-S3-DevKit Hardware ******** -ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated 2.4 GHz Wi-Fi -and Bluetooth® Low Energy (Bluetooth LE). It consists of high-performance dual-core microprocessor -(Xtensa® 32-bit LX7), a low power coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband, -RF module, and numerous peripherals. - -ESP32-S3-DevKitM includes the following features: - -- Dual core 32-bit Xtensa Microprocessor (Tensilica LX7), running up to 240MHz -- Additional vector instructions support for AI acceleration -- 512KB of SRAM -- 384KB of ROM -- Wi-Fi 802.11b/g/n -- Bluetooth LE 5.0 with long-range support and up to 2Mbps data rate - -Digital interfaces: - -- 45 programmable GPIOs -- 4x SPI -- 1x LCD interface (8-bit ~16-bit parallel RGB, I8080 and MOTO6800), supporting conversion between RGB565, YUV422, YUV420 and YUV411 -- 1x DVP 8-bit ~16-bit camera interface -- 3x UART -- 2x I2C -- 2x I2S -- 1x RMT (TX/RX) -- 1x pulse counter -- LED PWM controller, up to 8 channels -- 1x full-speed USB OTG -- 1x USB Serial/JTAG controller -- 2x MCPWM -- 1x SDIO host controller with 2 slots -- General DMA controller (GDMA), with 5 transmit channels and 5 receive channels -- 1x TWAI® controller, compatible with ISO 11898-1 (CAN Specification 2.0) -- Addressable RGB LED, driven by GPIO48. - -Analog interfaces: - -- 2x 12-bit SAR ADCs, up to 20 channels -- 1x temperature sensor -- 14x touch sensing IOs - -Timers: - -- 4x 54-bit general-purpose timers -- 1x 52-bit system timer -- 3x watchdog timers - -Low Power: - -- Power Management Unit with five power modes -- Ultra-Low-Power (ULP) coprocessors: ULP-RISC-V and ULP-FSM - -Security: - -- Secure boot -- Flash encryption -- 4-Kbit OTP, up to 1792 bits for users -- Cryptographic hardware acceleration: (AES-128/256, Hash, RSA, RNG, HMAC, Digital signature) +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features Supported Features ================== .. zephyr:board-supported-hw:: -Asymmetric Multiprocessing (AMP) -******************************** - -ESP32S3-DevKitM allows 2 different applications to be executed in ESP32-S3 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 :zephyr:code-sample-category:`ipc` folder as code reference. - -For more information, check the datasheet at `ESP32-S3 Datasheet`_ or the technical reference -manual at `ESP32-S3 Technical Reference Manual`_. - System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp32s3_eye/doc/index.rst b/boards/espressif/esp32s3_eye/doc/index.rst index 7180ff7d81700..d8eaf58c27aa8 100644 --- a/boards/espressif/esp32s3_eye/doc/index.rst +++ b/boards/espressif/esp32s3_eye/doc/index.rst @@ -17,6 +17,9 @@ ESP32-S3-WROOM-1 module, camera, SD card slot, digital microphone, USB port, and and the sub board (ESP32-S3-EYE-SUB) that contains an LCD display. The main board and sub board are connected through pin headers. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + Supported Features ================== @@ -121,16 +124,8 @@ Components on the ESP32-S3-EYE-SUB Sub Board System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* @@ -152,8 +147,8 @@ Debugging References ********** -.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases +.. target-notes:: +.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases .. _`Espressif`: https://espressif.com - .. _`ESP32-S3`: https://www.espressif.com/en/products/socs/esp32-s3 diff --git a/boards/espressif/esp8684_devkitm/doc/index.rst b/boards/espressif/esp8684_devkitm/doc/index.rst index 22b0aef4f4893..77b2b0b64946a 100644 --- a/boards/espressif/esp8684_devkitm/doc/index.rst +++ b/boards/espressif/esp8684_devkitm/doc/index.rst @@ -10,38 +10,8 @@ For more information, check `ESP8684-DevKitM User Guide`_ Hardware ******** -ESP32-C2 (ESP8684 core) is a low-cost, Wi-Fi 4 & Bluetooth 5 (LE) chip. Its unique design -makes the chip smaller and yet more powerful than ESP8266. ESP32-C2 is built around a RISC-V -32-bit, single-core processor, with 272 KB of SRAM (16 KB dedicated to cache) and 576 KB of ROM. -ESP32-C2 has been designed to target simple, high-volume, and low-data-rate IoT applications, -such as smart plugs and smart light bulbs. ESP32-C2 offers easy and robust wireless connectivity, -which makes it the go-to solution for developing simple, user-friendly and reliable -smart-home devices. For more information, check `ESP8684 Datasheet`_. - -Features include the following: - -- 32-bit core RISC-V microcontroller with a maximum clock speed of 120 MHz -- 2 MB or 4 MB in chip (ESP8684) or in package (ESP32-C2) flash -- 272 KB of internal RAM -- 802.11b/g/n -- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh -- Various peripherals: - - - 14 programmable GPIOs - - 3 SPI - - 2 UART - - 1 I2C Master - - LED PWM controller, with up to 6 channels - - General DMA controller (GDMA) - - 1 12-bit SAR ADC, up to 5 channels - - 1 temperature sensor - - 1 54-bit general-purpose timer - - 2 watchdog timers - - 1 52-bit system timer - -- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) - -For detailed information check `ESP8684 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32c2-features.rst + :start-after: espressif-soc-esp32c2-features Supported Features ================== @@ -53,16 +23,8 @@ For a getting started user guide, please check `ESP8684-DevKitM User Guide`_. System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/esp_wrover_kit/doc/index.rst b/boards/espressif/esp_wrover_kit/doc/index.rst index 208550ee0ec5c..59cdcafc28222 100644 --- a/boards/espressif/esp_wrover_kit/doc/index.rst +++ b/boards/espressif/esp_wrover_kit/doc/index.rst @@ -25,12 +25,17 @@ Most of the ESP32 I/O pins are broken out to the board's pin headers for easy ac For more information, check `ESP32-WROVER-E Datasheet`_ and `ESP32 Datasheet`_. +Hardware +******** + +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features ================== .. zephyr:board-supported-hw:: - Functionality Overview ====================== @@ -160,7 +165,7 @@ The table below provides description in the following manner: .. _setup options: Setup Options -************* +============= There are three jumper blocks available to set up the board functionality. The most frequently required options are listed in the table below. @@ -190,7 +195,7 @@ required options are listed in the table below. +--------+----------------+-------------------------------------------------------+ Allocation of ESP32 Pins -************************ +======================== Some pins / terminals of ESP32 are allocated for use with the onboard or external hardware. If that hardware is not used, e.g., nothing is plugged into the Camera (JP4) header, then these @@ -211,7 +216,7 @@ For more details on which pins are shared among which peripherals, please refer the next section. Main I/O Connector / JP1 -************************ +======================== The JP1 connector consists of 14x2 male pins whose functions are shown in the middle two “I/O” columns of the table below. The two “Shared With” columns on both sides describe where else on @@ -261,7 +266,7 @@ Legend: - PSRAM - ESP32-WROVER-E's PSRAM 32.768 kHz Oscillator -********************* +===================== +---+-----------+ | . | ESP32 Pin | @@ -279,7 +284,7 @@ Legend: them to positions R12 / R24. SPI Flash / JP2 -*************** +=============== +---+--------------+ | . | ESP32 Pin | @@ -304,7 +309,7 @@ SPI Flash / JP2 module's flash bus from the pin header JP2. JTAG / JP2 -********** +========== +---+---------------+-------------+ | . | ESP32 Pin | JTAG Signal | @@ -321,7 +326,7 @@ JTAG / JP2 +---+---------------+-------------+ Camera / JP4 -************ +============ +----+-----------+-----------------------------+ | . | ESP32 Pin | Camera Signal | @@ -366,7 +371,7 @@ Camera / JP4 - Signals D0 .. D7 denote camera data bus RGB LED -******* +======= +----+-----------+---------+ | . | ESP32 Pin | RGB LED | @@ -379,7 +384,7 @@ RGB LED +----+-----------+---------+ MicroSD Card -************ +============ +---+---------------+----------------+ | . | ESP32 Pin | MicroSD Signal | @@ -400,7 +405,7 @@ MicroSD Card +---+---------------+----------------+ LCD / U5 -******** +======== +---+-----------+------------+ | . | ESP32 Pin | LCD Signal | @@ -420,14 +425,8 @@ LCD / U5 | 7 | GPIO5 | Backlight | +---+-----------+------------+ -Start Application Development -***************************** - -Before powering up your ESP-WROVER-KIT, please make sure that the board is in good -condition with no obvious signs of damage. - Initial Setup -************* +============= Please set only the following jumpers shown in the pictures below: @@ -447,16 +446,8 @@ Turn the Power Switch to ON, the 5V Power On LED should light up. System Requirements ******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* diff --git a/boards/espressif/index.rst b/boards/espressif/index.rst index b1b7dfbeede26..b9fba4b53b368 100644 --- a/boards/espressif/index.rst +++ b/boards/espressif/index.rst @@ -3,6 +3,21 @@ Espressif ######### +.. toctree:: + :hidden: + + common/board-variants.rst + common/building-flashing.rst + common/openocd-debugging.rst + common/system-requirements.rst + common/soc-esp32-features.rst + common/soc-esp32c2-features.rst + common/soc-esp32c3-features.rst + common/soc-esp32c6-features.rst + common/soc-esp32h2-features.rst + common/soc-esp32s2-features.rst + common/soc-esp32s3-features.rst + .. toctree:: :maxdepth: 1 :glob: diff --git a/boards/franzininho/esp32s2_franzininho/doc/index.rst b/boards/franzininho/esp32s2_franzininho/doc/index.rst index bdbc20574ecdb..31615fd40711c 100644 --- a/boards/franzininho/esp32s2_franzininho/doc/index.rst +++ b/boards/franzininho/esp32s2_franzininho/doc/index.rst @@ -4,172 +4,42 @@ Overview ******** Franzininho is an educational development board based on ESP32-S2 which is a highly integrated, low-power, single-core Wi-Fi Microcontroller SoC, -designed to be secure and cost-effective, with a high performance and a rich set of IO capabilities. [1]_ +designed to be secure and cost-effective, with a high performance and a rich set of IO capabilities. -The features include the following: - -- RSA-3072-based secure boot -- AES-XTS-256-based flash encryption -- Protected private key and device secrets from software access -- Cryptographic accelerators for enhanced performance -- Protection against physical fault injection attacks -- Various peripherals: - - - 43x programmable GPIOs - - 14x configurable capacitive touch GPIOs - - USB OTG - - LCD interface - - camera interface - - SPI - - I2S - - UART - - ADC - - DAC - - LED PWM with up to 8 channels - -System requirements -=================== - -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: +Hardware +******** - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/soc-esp32s2-features.rst + :start-after: espressif-soc-esp32s2-features -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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 +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -Sysbuild -======== +Programming and Debugging +************************* -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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: esp32s2_franzininho - :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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s2_franzininho - :goals: build - -The usual ``flash`` target will work with the ``esp32s2_franzininho`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s2_franzininho - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell +.. zephyr:board-supported-runners:: - west espressif monitor +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -After the board has automatically reset and booted, you should see the following -message in the monitor: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -.. code-block:: console +Debugging +========= - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! esp32s2_franzininho +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** .. target-notes:: -.. [1] https://www.espressif.com/en/products/socs/esp32-s2 +.. _`ESP32-S2 Product page`: https://www.espressif.com/en/products/socs/esp32-s2 .. _`ESP32S2 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf .. _`ESP32S2 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf diff --git a/boards/hardkernel/odroid_go/doc/index.rst b/boards/hardkernel/odroid_go/doc/index.rst index 3c14c9c23b0f8..479dcf53bae46 100644 --- a/boards/hardkernel/odroid_go/doc/index.rst +++ b/boards/hardkernel/odroid_go/doc/index.rst @@ -7,19 +7,25 @@ ODROID-GO Game Kit is a "Do it yourself" ("DIY") portable game console by HardKernel. It features a custom ESP32-WROVER with 16 MB flash and it operates from 80 MHz - 240 MHz [1]_. -The features include the following: +Hardware +******** + +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + +The board peripherals: -- Dual core Xtensa microprocessor (LX6), running at 80 - 240MHz -- 4 MB of PSRAM -- 802.11b/g/n/e/i -- Bluetooth v4.2 BR/EDR and BLE - 2.4 inch 320x240 TFT LCD - Speaker - Micro SD card slot - Micro USB port (battery charging and USB_UART data communication - Input Buttons (Menu, Volume, Select, Start, A, B, Direction Pad) - Expansion port (I2C, GPIO, SPI) -- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) + +Supported Features +================== + +.. zephyr:board-supported-hw:: External Connector ================== @@ -48,174 +54,28 @@ External Connector | 10 | VBUS | USB VBUS (5V) | +-------+------------------+-------------------------+ -Supported Features -================== - -.. zephyr:board-supported-hw:: - -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -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 +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: odroid_go - :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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: odroid_go/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``odroid_go`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: odroid_go/esp32/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! odroid_go +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: odroid_go/esp32/procpu - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: odroid_go/esp32/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/heltec/heltec_wifi_lora32_v2/doc/index.rst b/boards/heltec/heltec_wifi_lora32_v2/doc/index.rst index abe91f4ca90d2..f02eb92b4c493 100644 --- a/boards/heltec/heltec_wifi_lora32_v2/doc/index.rst +++ b/boards/heltec/heltec_wifi_lora32_v2/doc/index.rst @@ -19,169 +19,34 @@ The features include the following: - Onboard 0.96-inch 128*64 dot matrix OLED display - Integrated CP2102 USB to serial port chip -System requirements -******************* - -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: +Hardware +******** - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: heltec_wifi_lora32_v2 - :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 +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. note:: +Programming and Debugging +************************* - 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: heltec_wifi_lora32_v2/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``heltec_wifi_lora32_v2`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: heltec_wifi_lora32_v2/esp32/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset 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! heltec_wifi_lora32_v2 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. +========= -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: heltec_wifi_lora32_v2/esp32/procpu - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: heltec_wifi_lora32_v2/esp32/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging Utilizing Hardware Features *************************** diff --git a/boards/heltec/heltec_wireless_stick_lite_v3/doc/index.rst b/boards/heltec/heltec_wireless_stick_lite_v3/doc/index.rst index 431f83d41ebeb..c24e18d2166c7 100644 --- a/boards/heltec/heltec_wireless_stick_lite_v3/doc/index.rst +++ b/boards/heltec/heltec_wireless_stick_lite_v3/doc/index.rst @@ -18,6 +18,9 @@ The main hardware features are: - Integrated CP2102 USB to serial port chip, convenient for program downloading, debugging information printing. - Good RF circuit design and low-power design. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + Supported Features ================== @@ -120,178 +123,36 @@ Connections and IOs | J3.20 | TWAI_RX | CAN (optional) | +--------+---------+-----------------------------+ - -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements Programming and Debugging ************************* .. zephyr:board-supported-runners:: -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 EPS32-S3 SoC. - -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: heltec_wireless_stick_lite_v3 - :goals: build - :west-args: --sysbuild - :compact: - -By default, the ESP32S3 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: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: heltec_wireless_stick_lite_v3/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``heltec_wireless_stick_lite_v3`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: heltec_wireless_stick_lite_v3/esp32s3/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! heltec_wireless_stick_lite_v3 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ========= -As with much custom hardware, the ESP32S3 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: heltec_wireless_stick_lite_v3/esp32s3/procpu - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: heltec_wireless_stick_lite_v3/esp32s3/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** -- `Heltec Wireless Stick Lite (v3) Pinout Diagram `_ -- `Heltec Wireless Stick Lite (v3) Schematic Diagrams `_ -- `ESP-IDF Programming Guide `_ -- `esptool documentation `_ -- `OpenOCD ESP32 `_ +.. `Heltec Wireless Stick Lite (v3) Pinout Diagram `_ +.. `Heltec Wireless Stick Lite (v3) Schematic Diagrams `_ +.. `ESP-IDF Programming Guide `_ +.. `esptool documentation `_ +.. `OpenOCD ESP32 `_ .. [1] https://heltec.org/project/wireless-stick-lite-v2/ diff --git a/boards/kincony/kincony_kc868_a32/doc/index.rst b/boards/kincony/kincony_kc868_a32/doc/index.rst index 6a001bbfdd8e4..5ebeed6af4c48 100644 --- a/boards/kincony/kincony_kc868_a32/doc/index.rst +++ b/boards/kincony/kincony_kc868_a32/doc/index.rst @@ -4,9 +4,12 @@ Overview ******** Kincony KC868-A32 is a home automation relay module based on the -Espressif ESP-WROOM-32 module with all its inherent capabilities +Espressif ESP32 ESP-WROOM-32 module with all its inherent capabilities (Wi-Fi, Bluetooth, etc.) +Hardware +******** + The features include the following: - 32 digital optoisolated inputs “dry contact” @@ -20,58 +23,25 @@ The features include the following: - RESET and DOWNLOAD buttons - Powered by 12V DC -System requirements -=================== - -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features -.. code-block:: console +System Requirements +******************* - west blobs fetch hal_espressif +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -------------------- +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: kincony_kc868_a32/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``kincony_kc868_a32`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: kincony_kc868_a32/esp32/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! kincony_kc868_a32 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Enabling Ethernet ***************** diff --git a/boards/lilygo/tdongle_s3/doc/index.rst b/boards/lilygo/tdongle_s3/doc/index.rst index b90f5a214172c..82beec9651a6a 100644 --- a/boards/lilygo/tdongle_s3/doc/index.rst +++ b/boards/lilygo/tdongle_s3/doc/index.rst @@ -16,165 +16,44 @@ It features the following integrated components: - JST SH 1.0mm 4-pin UART connector - Transparent plastic case -Functional Description -********************** +Hardware +******** + This board is based on the ESP32-S3 with 16MB of flash, WiFi and BLE support. It has an USB-A port for programming and debugging, integrated battery charging and an on-board antenna. The fitted U.FL external antenna connector can be enabled by moving a 0-ohm resistor. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + Supported Features ================== .. zephyr:board-supported-hw:: -Start Application Development -***************************** - -Before powering up your Lilygo T-Dongle T8-S3, please make sure that the board is in good -condition with no obvious signs of damage. - -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Simple boot -=========== - -The board could be loaded using a 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-block:: cfg - - CONFIG_BOOTLOADER_MCUBOOT=y - -Sysbuild -======== - -The sysbuild makes it 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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: tdongle_s3/esp32s3/procpu - :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 flashed at least once. - -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: tdongle_s3/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``tdongle_s3`` board target. -Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: tdongle_s3/esp32s3/procpu - :goals: flash - -The default baud rate for the Lilygo T-Dongle S3 is set to 1500000bps. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -After the board has automatically reset and booted, you should see the following -message in the monitor: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -.. code-block:: console +Debugging +========= - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! tdongle_s3/esp32s3/procpu +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/lilygo/ttgo_lora32/doc/index.rst b/boards/lilygo/ttgo_lora32/doc/index.rst index 1b662bb030c32..cdfed61bf0715 100644 --- a/boards/lilygo/ttgo_lora32/doc/index.rst +++ b/boards/lilygo/ttgo_lora32/doc/index.rst @@ -18,161 +18,38 @@ Some of the ESP32 I/O pins are accessible on the board's pin headers. Hardware ******** +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features ================== .. zephyr:board-supported-hw:: -Start Application Development -***************************** - -Before powering up your Lilygo TTGO LoRa32, please make sure that the board is in good -condition with no obvious signs of damage. - -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order to work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Simple boot -=========== - -The board could be loaded using a 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-block:: cfg - - CONFIG_BOOTLOADER_MCUBOOT=y - -Sysbuild -======== - -The sysbuild makes it possible to build and flash all necessary images needed to -bootstrap the board with the ESP32-PICO-D4 SoC. - -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: ttgo_lora32/esp32/procpu - :goals: build - :west-args: --sysbuild - :compact: - -By default, the ESP32-PICO-D4 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: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. code-block:: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants - 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_lora32/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``ttgo_lora32`` board target. -Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_lora32/esp32/procpu - :goals: flash - -The default baud rate for the Lilygo TTGO LoRa32 is set to 1500000bps. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -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! ttgo_lora32/esp32/procpu +Lilygo TTGO LoRa32 debugging is not supported due to pinout limitations. -Code samples -============ +Sample Applications +******************* The following sample applications will work out of the box with this board: @@ -181,18 +58,16 @@ The following sample applications will work out of the box with this board: * :zephyr:code-sample:`fs` * :zephyr:code-sample:`character-frame-buffer` -Debugging -********* - -Lilygo TTGO LoRa32 debugging is not supported due to pinout limitations. - Related Documents ***************** -- `Lilygo TTGO LoRa32 schematic `_ (PDF) -- `Lilygo TTGO LoRa32 documentation `_ -- `Lilygo github repo `_ -- `ESP32-PICO-D4 Datasheet `_ (PDF) -- `ESP32 Datasheet `_ (PDF) -- `ESP32 Hardware Reference `_ -- `SX127x Datasheet `_ -- `SSD1306 Datasheet `_ (PDF) + +.. target-notes:: + +.. _`Lilygo TTGO LoRa32 schematic`: https://github.com/Xinyuan-LilyGO/LilyGo-LoRa-Series/blob/master/schematic/T3_V1.6.1.pdf +.. _`Lilygo TTGO LoRa32 documentation`: https://www.lilygo.cc/products/lora3 +.. _`Lilygo github repo`: https://github.com/Xinyuan-LilyGo +.. _`ESP32-PICO-D4 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf +.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf +.. _`ESP32 Hardware Reference`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html +.. _`SX127x Datasheet`: https://www.semtech.com/products/wireless-rf/lora-connect/sx1276#documentation +.. _`SSD1306 Datasheet`: https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf diff --git a/boards/lilygo/ttgo_t7v1_5/doc/index.rst b/boards/lilygo/ttgo_t7v1_5/doc/index.rst index 57d12645c9aed..8c4b810bb133f 100644 --- a/boards/lilygo/ttgo_t7v1_5/doc/index.rst +++ b/boards/lilygo/ttgo_t7v1_5/doc/index.rst @@ -20,155 +20,39 @@ This board is based on the ESP32-WROVER-E module with 4MB of flash (there are models 16MB as well), WiFi and BLE support. It has a Micro-USB port for programming and debugging, integrated battery charging and an on-board antenna. +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features ================== .. zephyr:board-supported-hw:: -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order to work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Simple boot -=========== - -The board could be loaded using a 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-block:: cfg - - CONFIG_BOOTLOADER_MCUBOOT=y - -Sysbuild -======== - -The sysbuild makes it 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: - -.. zephyr-app-commands:: - :tool: west - :app: samples/hello_world - :board: ttgo_t7v1_5/esp32/procpu - :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. +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -Build directory structure created by sysbuild is different from traditional -Zephyr build. Output is structured by the domain subdirectories: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -.. code-block:: +Debugging +========= - build/ - ├── hello_world - │   └── zephyr - │   ├── zephyr.elf - │   └── zephyr.bin - ├── mcuboot - │ └── zephyr - │ ├── zephyr.elf - │ └── zephyr.bin - └── domains.yaml +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging -.. 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_t7v1_5/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``ttgo_t7v1_5`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_t7v1_5/esp32/procpu - :goals: flash - -The default baud rate for the Lilygo TTGO T7 V1.5 is set to 1500000bps. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! ttgo_t7v1_5 - -Sample applications -=================== +Sample Applications +******************* The following samples will run out of the box on the TTGO T7 V1.5 board. @@ -189,8 +73,11 @@ To build the bluetooth beacon sample: :goals: build -Related Documents -***************** +References +********** + +.. target-notes:: + .. _`Lilygo TTGO T7-V1.5 schematic`: https://github.com/LilyGO/TTGO-T7-Demo/blob/master/t7_v1.5.pdf .. _`Lilygo github repo`: https://github.com/LilyGO/TTGO-T7-Demo/tree/master .. _`Espressif ESP32-WROVER-E datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf diff --git a/boards/lilygo/ttgo_t8c3/doc/index.rst b/boards/lilygo/ttgo_t8c3/doc/index.rst index 33cab6415243e..23a3b345b0239 100644 --- a/boards/lilygo/ttgo_t8c3/doc/index.rst +++ b/boards/lilygo/ttgo_t8c3/doc/index.rst @@ -22,182 +22,42 @@ has an USB-C port for programming and debugging, integrated battery charging and an on-board antenna. The fitted U.FL external antenna connector can be enabled by moving a 0-ohm resistor. +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features + Supported Features ================== .. zephyr:board-supported-hw:: -Start Application Development -***************************** - -Before powering up your Lilygo TTGO T8-C3, please make sure that the board is in good -condition with no obvious signs of damage. - -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order to work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Simple boot -=========== - -The board could be loaded using a 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 it possible to build and flash all necessary images needed to -bootstrap the board with the ESP32-C3 SoC. - -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: ttgo_t8c3 - :goals: build - :west-args: --sysbuild - :compact: - -By default, the ESP32-C3 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_t8c3 - :goals: build - -The usual ``flash`` target will work with the ``ttgo_t8c3`` board target. -Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_t8c3 - :goals: flash - -The default baud rate for the Lilygo TTGO T8-C3 is set to 1500000bps. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! ttgo_t8c3 - -Sample applications -=================== - -The following samples will run out of the box on the TTGO T8-C3 board. +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -To build the blinky sample: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/basic/blinky - :board: ttgo_t8c3 - :goals: build +Debugging +========= -To build the bluetooth beacon sample: +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/bluetooth/beacon - :board: ttgo_t8c3 - :goals: build +References +********** +.. target-notes:: -Related Documents -***************** .. _`Lilygo TTGO T8-C3 schematic`: https://github.com/Xinyuan-LilyGO/T8-C3/blob/main/Schematic/T8-C3_V1.1.pdf .. _`Lilygo github repo`: https://github.com/Xinyuan-LilyGo .. _`Espressif ESP32-C3 datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf diff --git a/boards/lilygo/ttgo_t8s3/doc/index.rst b/boards/lilygo/ttgo_t8s3/doc/index.rst index fb29b2e5f7b60..5f61d5ab1accd 100644 --- a/boards/lilygo/ttgo_t8s3/doc/index.rst +++ b/boards/lilygo/ttgo_t8s3/doc/index.rst @@ -23,168 +23,45 @@ has an USB-C port for programming and debugging, integrated battery charging and an on-board antenna. The fitted U.FL external antenna connector can be enabled by moving a 0-ohm resistor. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + Supported Features ================== .. zephyr:board-supported-hw:: -Start Application Development -***************************** - -Before powering up your Lilygo TTGO T8-S3, please make sure that the board is in good -condition with no obvious signs of damage. - System requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order to work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Simple boot -=========== - -The board could be loaded using a 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-block:: cfg - - CONFIG_BOOTLOADER_MCUBOOT=y - -Sysbuild -======== - -The sysbuild makes it 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: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: ttgo_t8s3/esp32s3/procpu - :goals: build - :west-args: --sysbuild - :compact: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -By default, the ESP32 sysbuild creates bootloader (MCUboot) and application -images. But it can be configured to create other kind of images. +Debugging +========= -Build directory structure created by sysbuild is different from traditional -Zephyr build. Output is structured by the domain subdirectories: +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging -.. 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_t8s3/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``ttgo_t8s3`` board target -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_t8s3/esp32s3/procpu - :goals: flash - -The default baud rate for the Lilygo TTGO T8-S3 is set to 1500000bps. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! ttgo_t8s3 - -Code samples -============ +Sample Applications +******************* The following code samples will run out of the box on the TTGO T8-S3 board: * :zephyr:code-sample:`wifi-shell` * :zephyr:code-sample:`fs` - References ********** diff --git a/boards/lilygo/ttgo_tbeam/doc/index.rst b/boards/lilygo/ttgo_tbeam/doc/index.rst index fa6082abaa29d..bb791dfe2a193 100644 --- a/boards/lilygo/ttgo_tbeam/doc/index.rst +++ b/boards/lilygo/ttgo_tbeam/doc/index.rst @@ -20,161 +20,38 @@ Some of the ESP32 I/O pins are accessible on the board's pin headers. Hardware ******** +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features ================== .. zephyr:board-supported-hw:: -Start Application Development -***************************** - -Before powering up your Lilygo TTGO TBeam, please make sure that the board is in good -condition with no obvious signs of damage. - -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order to work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Simple boot -=========== - -The board could be loaded using a 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-block:: cfg - - CONFIG_BOOTLOADER_MCUBOOT=y - -Sysbuild -======== - -The sysbuild makes it possible to build and flash all necessary images needed to -bootstrap the board with the ESP32-PICO-D4 SoC. - -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: ttgo_tbeam/esp32/procpu - :goals: build - :west-args: --sysbuild - :compact: - -By default, the ESP32-PICO-D4 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: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. code-block:: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants - 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_tbeam/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``ttgo_tbeam`` board target. -Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_tbeam/esp32/procpu - :goals: flash - -The default baud rate for the Lilygo TTGO TBeam is set to 1500000bps. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -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! ttgo_tbeam/esp32/procpu +Lilygo TTGO TBeam debugging is not supported due to pinout limitations. -Code samples -============ +Sample Applications +******************* The following sample applications will work out of the box with this board: @@ -185,20 +62,18 @@ The following sample applications will work out of the box with this board: * :zephyr:code-sample:`character-frame-buffer` * :zephyr:code-sample:`blinky` -Debugging -********* - -Lilygo TTGO TBeam debugging is not supported due to pinout limitations. - Related Documents ***************** -- `Lilygo TTGO TBeam schematic `_ (PDF) -- `Lilygo TTGO TBeam documentation `_ -- `Lilygo github repo `_ -- `ESP32-PICO-D4 Datasheet `_ (PDF) -- `ESP32 Datasheet `_ (PDF) -- `ESP32 Hardware Reference `_ -- `SX127x Datasheet `_ -- `SSD1306 Datasheet `_ (PDF) -- `NEO-6M Datasheet `_ (PDF) -- `NEO-N8M Datasheet `_ (PDF) + +.. target-notes:: + +.. _`Lilygo TTGO TBeam schematic`: https://github.com/Xinyuan-LilyGO/LilyGo-LoRa-Series/blob/master/schematic/LilyGo_TBeam_V1.2.pdf +.. _`Lilygo TTGO TBeam documentation`: https://www.lilygo.cc/products/t-beam-v1-1-esp32-lora-module +.. _`Lilygo github repo`: https://github.com/Xinyuan-LilyGo +.. _`ESP32-PICO-D4 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf +.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf +.. _`ESP32 Hardware Reference`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html +.. _`SX127x Datasheet`: https://www.semtech.com/products/wireless-rf/lora-connect/sx1276#documentation +.. _`SSD1306 Datasheet`: https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf +.. _`NEO-6M Datasheet`: https://content.u-blox.com/sites/default/files/products/documents/NEO-6_DataSheet_%28GPS.G6-HW-09005%29.pdf +.. _`NEO-N8M Datasheet`: https://content.u-blox.com/sites/default/files/NEO-M8-FW3_DataSheet_UBX-15031086.pdf diff --git a/boards/lilygo/ttgo_toiplus/doc/index.rst b/boards/lilygo/ttgo_toiplus/doc/index.rst index 3ea6b50446fa3..b35a1f0f1c477 100644 --- a/boards/lilygo/ttgo_toiplus/doc/index.rst +++ b/boards/lilygo/ttgo_toiplus/doc/index.rst @@ -14,12 +14,21 @@ It features the following integrated components: - optional 18340 Li-ion battery holder - LED -Functional Description -********************** +Hardware +******** + This board is based on the ESP32-C3 with 4MB of flash, WiFi and BLE support. It has an USB-C port for programming and debugging, integrated battery charging and an Grove connector. +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features + +Supported Features +================== + +.. zephyr:board-supported-hw:: + Connections and IOs =================== @@ -27,149 +36,31 @@ Connections and IOs (Note: the above UART interface also supports connecting through USB.) -Start Application Development -***************************** - -Before powering up your Lilygo TTGO T-OI-PLUS, please make sure that the board is in good -condition with no obvious signs of damage. - System requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -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-C3 SoC. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -To build the sample application using sysbuild use the command: +Programming and Debugging +************************* -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: ttgo_toiplus - :goals: build - :west-args: --sysbuild - :compact: - -By default, the ESP32-C3 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 +.. zephyr:board-supported-runners:: -.. note:: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing - With ``--sysbuild`` option the bootloader will be re-build and re-flash - every time the pristine build is used. +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -For more information about the system build please read the :ref:`sysbuild` documentation. +Debugging +========= -Manual build -============ +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging -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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_toiplus - :goals: build - -The usual ``flash`` target will work with the ``ttgo_toiplus`` board target. -Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: ttgo_toiplus - :goals: flash - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! ttgo_toiplus - -Sample applications -=================== +Sample Applications +******************* The following samples will run out of the box on the TTGO T-OI-PLUS board. @@ -190,8 +81,11 @@ To build the bluetooth beacon sample: :goals: build -Related Documents -***************** +References +********** + +.. target-notes:: + .. _`Lilygo TTGO T-OI-PLUS schematic`: https://github.com/Xinyuan-LilyGO/LilyGo-T-OI-PLUS/blob/main/schematic/T-OI_PLUS_Schematic.pdf .. _`Lilygo github repo`: https://github.com/Xinyuan-LilyGO .. _`Espressif ESP32-C3 datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf diff --git a/boards/lilygo/twatch_s3/doc/index.rst b/boards/lilygo/twatch_s3/doc/index.rst index 3dc07e37673ea..d339b55ca5c45 100644 --- a/boards/lilygo/twatch_s3/doc/index.rst +++ b/boards/lilygo/twatch_s3/doc/index.rst @@ -3,7 +3,11 @@ Overview ******** -LILYGO T-Watch S3 is an ESP32-S3 based smartwatch with the following features: +LILYGO T-Watch S3 is an ESP32-S3 based smartwatch. + + +Hardware +******** - ESP32-S3-R8 chip @@ -40,149 +44,36 @@ It does not have any GPIO that can easily be connected to something external. There is only 1 physical button which is connected to the PMU and it's used to turn on/off the device. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + Supported Features ================== .. zephyr:board-supported-hw:: -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order to work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Simple boot -=========== - -The board could be loaded using a 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-block:: cfg +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - CONFIG_BOOTLOADER_MCUBOOT=y +Programming and Debugging +************************* -Sysbuild --------- - -The sysbuild makes it 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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: twatch_s3/esp32s3/procpu - :goals: build - :west-args: --sysbuild - :compact: - -By default, the ESP32-S3 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-built and re-flashed - 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 as 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 flashed at least once. - -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: twatch_s3/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``twatch_s3`` board target -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: twatch_s3/esp32s3/procpu - :goals: flash - -The default baud rate is set to 1500000bps. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell +.. zephyr:board-supported-runners:: - west espressif monitor +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -After the board has automatically reset and booted, you should see the following -message in the monitor: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -.. code-block:: console +Debugging +========= - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! twatch_s3/esp32s3/procpu +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/luatos/esp32c3_luatos_core/doc/index.rst b/boards/luatos/esp32c3_luatos_core/doc/index.rst index 02df6687cb3c1..40342d74c9e87 100644 --- a/boards/luatos/esp32c3_luatos_core/doc/index.rst +++ b/boards/luatos/esp32c3_luatos_core/doc/index.rst @@ -1,7 +1,4 @@ -.. _esp32c3_luatos_core: - -ESP32C3_LUATOS_CORE -################### +.. zephyr:board:: esp32c3_luatos_core Overview ******** @@ -13,24 +10,11 @@ solution for connected devices. The availability of Wi-Fi and Bluetooth 5 (LE) connectivity not only makes the device configuration easy, but it also facilitates a variety of use-cases based on dual connectivity. [1]_ -The features include the following: - -- 32-bit core RISC-V microcontroller with a maximum clock speed of 160 MHz -- 400 KB of internal RAM -- 802.11b/g/n/e/i -- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh -- Various peripherals: - - - 12-bit ADC with up to 6 channels - - TWAI compatible with CAN bus 2.0 - - Temperature sensor - - 3x SPI - - 1x I2S - - 1x I2C - - 2x UART - - LED PWM with up to 6 channels +Hardware +******** -- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features There are two version hardware of this board. The difference between them is the ch343 chip. @@ -49,209 +33,37 @@ There are two version hardware of this board. The difference between them is the Supported Features ================== -Current Zephyr's ESP32C3_LUATOS_CORE board supports the following features: +.. zephyr:board-supported-hw:: -+------------+------------+-------------------------------------+ -| Interface | Controller | Driver/Component | -+============+============+=====================================+ -| UART | on-chip | serial port | -+------------+------------+-------------------------------------+ -| GPIO | on-chip | gpio | -+------------+------------+-------------------------------------+ -| PINMUX | on-chip | pinmux | -+------------+------------+-------------------------------------+ -| USB-JTAG | on-chip | hardware interface | -+------------+------------+-------------------------------------+ -| SPI Master | on-chip | spi | -+------------+------------+-------------------------------------+ -| Timers | on-chip | counter | -+------------+------------+-------------------------------------+ -| Watchdog | on-chip | watchdog | -+------------+------------+-------------------------------------+ -| TRNG | on-chip | entropy | -+------------+------------+-------------------------------------+ -| LEDC | on-chip | pwm | -+------------+------------+-------------------------------------+ -| SPI DMA | on-chip | spi | -+------------+------------+-------------------------------------+ -| TWAI | on-chip | can | -+------------+------------+-------------------------------------+ -| USB-CDC | on-chip | serial | -+------------+------------+-------------------------------------+ -| ADC | on-chip | adc | -+------------+------------+-------------------------------------+ -| Wi-Fi | on-chip | | -+------------+------------+-------------------------------------+ -| Bluetooth | on-chip | | -+------------+------------+-------------------------------------+ +Connection and IO +================= .. image:: img/esp32c3_luatos_core_pinfunc.jpg :align: center :alt: esp32c3_luatos_core_pinfunc -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -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. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -To build the sample application using sysbuild use the command: +Programming and Debugging +************************* -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: esp32c3_luatos_core - :goals: build - :west-args: --sysbuild - :compact: +.. zephyr:board-supported-runners:: -By default, the ESP32 sysbuild creates bootloader (MCUboot) and application -images. But it can be configured to create other kind of images. +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32c3_luatos_core - :goals: build - -The usual ``flash`` target will work with the ``esp32c3_luatos_core`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32c3_luatos_core - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! esp32c3_luatos_core +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -As with much custom hardware, the ESP32-C3 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32c3_luatos_core - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32c3_luatos_core - :goals: debug +========= -.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/luatos/esp32s3_luatos_core/doc/index.rst b/boards/luatos/esp32s3_luatos_core/doc/index.rst index c8e3f74375f75..aef84adb67b3f 100644 --- a/boards/luatos/esp32s3_luatos_core/doc/index.rst +++ b/boards/luatos/esp32s3_luatos_core/doc/index.rst @@ -1,7 +1,4 @@ -.. _esp32s3_luatos_core: - -ESP32S3-Luatos-Core -################### +.. zephyr:board:: esp32s3_luatos_core Overview ******** @@ -17,66 +14,8 @@ For more information, check `ESP32S3-Luatos-Core`_ (chinese) Hardware ******** -ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated 2.4 GHz Wi-Fi -and Bluetooth® Low Energy (Bluetooth LE). It consists of high-performance dual-core microprocessor -(Xtensa® 32-bit LX7), a low power coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband, -RF module, and numerous peripherals. - -ESP32S3-Luatos-Core includes the following features: - -- Dual core 32-bit Xtensa Microprocessor (Tensilica LX7), running up to 240MHz -- Additional vector instructions support for AI acceleration -- 512KB of SRAM -- 384KB of ROM -- 8MB of PSRAM -- 16MB of FLASH -- Wi-Fi 802.11b/g/n -- Bluetooth LE 5.0 with long-range support and up to 2Mbps data rate - -Digital interfaces: - -- 4x SPI -- 1x LCD interface (8-bit ~16-bit parallel RGB, I8080 and MOTO6800), supporting conversion between RGB565, YUV422, YUV420 and YUV411 -- 1x DVP 8-bit ~16-bit camera interface -- 3x UART -- 2x I2C -- 2x I2S -- 1x RMT (TX/RX) -- 1x pulse counter -- LED PWM controller, up to 8 channels -- 1x USB Port with USB switcher, supporting following modes: - - 1x full-speed USB OTG or 1x USB Serial/JTAG controller - - USB to serial chip CH343 -- 2x MCPWM -- 1x SDIO host controller with 2 slots -- General DMA controller (GDMA), with 5 transmit channels and 5 receive channels -- 1x TWAI® controller, compatible with ISO 11898-1 (CAN Specification 2.0) -- 2x Blue LED - -Analog interfaces: - -- 2x 12-bit SAR ADCs, up to 20 channels - -Timers: - -- 4x 54-bit general-purpose timers -- 1x 52-bit system timer -- 3x watchdog timers - -Low Power: - -- Power Management Unit with five power modes -- Ultra-Low-Power (ULP) coprocessors: ULP-RISC-V and ULP-FSM - -Security: - -- Secure boot -- Flash encryption -- 4-Kbit OTP, up to 1792 bits for users -- Cryptographic hardware acceleration: (AES-128/256, Hash, RSA, RNG, HMAC, Digital signature) - -For more information, check the datasheet at `ESP32-S3 Datasheet`_ or the technical reference -manual at `ESP32-S3 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features .. image:: img/esp32s3_luatos_core_pinout.jpg :align: center @@ -85,203 +24,30 @@ manual at `ESP32-S3 Technical Reference Manual`_. Supported Features ================== -Current Zephyr's ESP32S3-Luatos-Core board supports the following features: - -+------------+------------+-------------------------------------+ -| Interface | Controller | Driver/Component | -+============+============+=====================================+ -| UART | on-chip | serial port | -+------------+------------+-------------------------------------+ -| GPIO | on-chip | gpio | -+------------+------------+-------------------------------------+ -| PINMUX | on-chip | pinmux | -+------------+------------+-------------------------------------+ -| USB-JTAG | on-chip | hardware interface | -+------------+------------+-------------------------------------+ -| SPI Master | on-chip | spi | -+------------+------------+-------------------------------------+ -| TWAI/CAN | on-chip | can | -+------------+------------+-------------------------------------+ -| Timers | on-chip | counter | -+------------+------------+-------------------------------------+ -| Watchdog | on-chip | watchdog | -+------------+------------+-------------------------------------+ -| TRNG | on-chip | entropy | -+------------+------------+-------------------------------------+ -| LEDC | on-chip | pwm | -+------------+------------+-------------------------------------+ -| MCPWM | on-chip | pwm | -+------------+------------+-------------------------------------+ -| PCNT | on-chip | qdec | -+------------+------------+-------------------------------------+ -| GDMA | on-chip | dma | -+------------+------------+-------------------------------------+ -| USB-CDC | on-chip | serial | -+------------+------------+-------------------------------------+ - -Prerequisites -------------- +.. zephyr:board-supported-hw:: -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing +System Requirements ******************* -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 +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - CONFIG_BOOTLOADER_MCUBOOT=y +Programming and Debugging +************************* -Sysbuild -======== +.. zephyr:board-supported-runners:: -The sysbuild makes possible to build and flash all necessary images needed to -bootstrap the board with the ESP32 SoC. +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: esp32s3_luatos_core - :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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s3_luatos_core/esp32s3/procpu - :goals: build - -If CH343 chip is disabled, You need use the following command to build: - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s3_luatos_core/esp32s3/procpu/usb - :goals: build - -The usual ``flash`` target will work with the ``esp32s3_luatos_core`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s3_luatos_core/esp32s3/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! esp32s3_luatos_core +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_. - -ESP32-S3 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-S3`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s3_luatos_core/esp32s3/procpu - :goals: build flash - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s3_luatos_core/esp32s3/procpu - :goals: debug +========= +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/m5stack/m5stack_atom_lite/doc/index.rst b/boards/m5stack/m5stack_atom_lite/doc/index.rst index 9b84f801fd6f7..121fb55bedbac 100644 --- a/boards/m5stack/m5stack_atom_lite/doc/index.rst +++ b/boards/m5stack/m5stack_atom_lite/doc/index.rst @@ -5,6 +5,9 @@ Overview M5Stack ATOM Lite is an ESP32-based development board from M5Stack. +Hardware +******** + It features the following integrated components: - ESP32-PICO-D4 chip (240MHz dual core, Wi-Fi/BLE 5.0) @@ -13,81 +16,41 @@ It features the following integrated components: - Infrared LED - 1x Grove extension port +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + Supported Features ================== .. zephyr:board-supported-hw:: -Start Application Development -***************************** - -Before powering up your M5Stack ATOM Lite, please make sure that the board is in good -condition with no obvious signs of damage. - -System requirements -=================== - -Prerequisites -------------- +System Requirements +******************* -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. code-block:: shell - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -------------------- +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_atom_lite/esp32/procpu - :goals: build +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -The usual ``flash`` target will work with the ``m5stack_atom_lite`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_atom_lite/esp32/procpu - :goals: flash - -The baud rate of 921600bps is set by default. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! m5stack_atom_lite +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ---------- +========= M5Stack ATOM Lite debugging is not supported due to pinout limitations. Related Documents ***************** -- `M5Stack ATOM Lite docs `_ -- `M5Stack ATOM Lite schematic `_ -- `ESP32-PICO-D4 Datasheet `_ (PDF) + +.. target-notes:: + +.. _`M5Stack ATOM Lite docs`: https://docs.m5stack.com/en/core/ATOM%20Lite +.. _`M5Stack ATOM Lite schematic`: https://static-cdn.m5stack.com/resource/docs/products/core/atom_lite/atom_lite_map_01.webp +.. _`ESP32-PICO-D4 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf diff --git a/boards/m5stack/m5stack_atoms3/doc/index.rst b/boards/m5stack/m5stack_atoms3/doc/index.rst index 9cedbfb51805a..3b66b6ca3cc8f 100644 --- a/boards/m5stack/m5stack_atoms3/doc/index.rst +++ b/boards/m5stack/m5stack_atoms3/doc/index.rst @@ -5,11 +5,14 @@ Overview M5Stack AtomS3 is an ESP32-based development board from M5Stack. -It features the following integrated components: +Hardware +******** + +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + +The board peripherals: -- ESP32-S3FN8 chip (240MHz dual core, Wi-Fi/BLE 5.0) -- 512KB of SRAM -- 384KB of ROM - 8MB of Flash - LCD IPS TFT 0.85", 128x128 px screen (ST7789 compatible) - 6-axis IMU MPU6886 @@ -20,76 +23,32 @@ Supported Features .. zephyr:board-supported-hw:: -Start Application Development -***************************** - -Before powering up your M5Stack AtomS3, please make sure that the board is in good -condition with no obvious signs of damage. - -System requirements -=================== - -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: shell - - west blobs fetch hal_espressif - -.. note:: +System Requirements +******************* - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -Building & Flashing -------------------- +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_atoms3/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``m5stack_atoms3`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_atoms3/esp32s3/procpu - :goals: flash - -The baud rate of 921600bps is set by default. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! m5stack_atoms3 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ---------- +========= M5Stack AtomS3 debugging is not supported due to pinout limitations. Related Documents ***************** -- `M5Stack AtomS3 schematic `_ -- `ESP32S3 Datasheet `_ +.. target-notes:: + +.. _`M5Stack AtomS3 schematic`: https://static-cdn.m5stack.com/resource/docs/products/core/AtomS3/img-b85e925c-adff-445d-994c-45987dc97a44.jpg +.. _`ESP32S3 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf diff --git a/boards/m5stack/m5stack_atoms3_lite/doc/index.rst b/boards/m5stack/m5stack_atoms3_lite/doc/index.rst index 8403358be1e4f..b508c9fe6649d 100644 --- a/boards/m5stack/m5stack_atoms3_lite/doc/index.rst +++ b/boards/m5stack/m5stack_atoms3_lite/doc/index.rst @@ -5,8 +5,13 @@ Overview M5Stack AtomS3 Lite is an ESP32-based development board from M5Stack. -It features the following integrated components: +Hardware +******** + +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features +It features the following integrated components: - ESP32-S3FN8 chip (240MHz dual core, Wi-Fi/BLE 5.0) - 512KB of SRAM - 384KB of ROM @@ -18,76 +23,32 @@ Supported Features .. zephyr:board-supported-hw:: -Start Application Development -***************************** - -Before powering up your M5Stack AtomS3 Lite, please make sure that the board is in good -condition with no obvious signs of damage. - System requirements -=================== - -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: shell - - west blobs fetch hal_espressif - -.. note:: +******************* - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -Building & Flashing -------------------- +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_atoms3_lite/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``m5stack_atoms3_lite`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_atoms3_lite/esp32s3/procpu - :goals: flash - -The baud rate of 921600bps is set by default. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! m5stack_atoms3_lite +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ---------- +========= M5Stack AtomS3 Lite debugging is not supported due to pinout limitations. -Related Documents -***************** +References +********** + +.. target-notes:: -- `M5Stack AtomS3 Lite schematic `_ -- `ESP32S3 Datasheet `_ +.. _`M5Stack AtomS3 Lite schematic`: https://static-cdn.m5stack.com/resource/docs/products/core/AtomS3%20Lite/img-4061fdd4-6954-4709-a7e7-b0f50e5ba52e.webp +.. _`ESP32S3 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf diff --git a/boards/m5stack/m5stack_core2/doc/index.rst b/boards/m5stack/m5stack_core2/doc/index.rst index fb21227767c44..fa2f148f3ccbd 100644 --- a/boards/m5stack/m5stack_core2/doc/index.rst +++ b/boards/m5stack/m5stack_core2/doc/index.rst @@ -5,6 +5,9 @@ Overview M5Stack Core2 is an ESP32-based development board from M5Stack. It is the successor for the Core module. +Hardware +******** + M5Stack Core2 features the following integrated components: - ESP32-D0WDQ6-V3 chip (240MHz dual core, 600 DMIPS, 520KB SRAM, Wi-Fi) @@ -23,8 +26,16 @@ M5Stack Core2 features the following integrated components: - MIC SPM1423 - Battery 390mAh 3,7V +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + +Supported Features +================== + +.. zephyr:board-supported-hw:: + Functional Description -********************** +====================== The following table below describes the key components, interfaces, and controls of the M5Stack Core2 board. @@ -82,6 +93,7 @@ of the M5Stack Core2 board. Power supply ============ + M5Stack Core2 module is equipped with the feature-rich power management IC (:dtcompatible:`x-powers,axp192-regulator`). Following regulators are utilized on this module: @@ -98,87 +110,35 @@ Following regulators are utilized on this module: BUS_5V supply for Grove port. Note: This fixed regulator supply is disabled by default. - These voltages can be controlled via regulator api. -Supported Features -================== - -.. zephyr:board-supported-hw:: - -Start Application Development -***************************** - -Before powering up your M5Stack Core2, please make sure that the board is in good -condition with no obvious signs of damage. +System Requirements +******************* -System requirements -=================== +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -------------------- +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_core2/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``m5stack_core2`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_core2/esp32/procpu - :goals: flash - -The baud rate of 921600bps is set by default. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! m5stack_core2 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ---------- +========= M5Stack Core2 debugging is not supported due to pinout limitations. Related Documents ***************** -- `M5Stack-Core2 schematic `_ (PDF) -- `ESP32-PICO-D4 Datasheet `_ (PDF) -- `M5Stack-Core2 docs `_ -- `ESP32 Datasheet `_ (PDF) -- `ESP32 Hardware Reference `_ +.. _`M5Stack-Core2 schematic`: https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/schematic/Core/CORE2_V1.0_SCH.pdf +.. _`ESP32-PICO-D4 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf +.. _`M5Stack-Core2 docs`: https://docs.m5stack.com/en/core/core2 +.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf +.. _`ESP32 Hardware Reference`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html diff --git a/boards/m5stack/m5stack_cores3/doc/index.rst b/boards/m5stack/m5stack_cores3/doc/index.rst index 2fdd042c38e67..2432402da8176 100644 --- a/boards/m5stack/m5stack_cores3/doc/index.rst +++ b/boards/m5stack/m5stack_cores3/doc/index.rst @@ -7,6 +7,9 @@ M5Stack CoreS3 is an ESP32-based development board from M5Stack. It is the third M5Stack CoreS3 SE is the compact version of CoreS3. It has the same form factor as the original M5Stack, and some features were reduced from CoreS3. +Hardware +******** + M5Stack CoreS3/CoreS3 SE features consist of: - ESP32-S3 chip (dual-core Xtensa LX7 processor @240MHz, WIFI, OTG and CDC functions) @@ -26,234 +29,36 @@ M5Stack CoreS3/CoreS3 SE features consist of: - Proximity sensor LTR-553ALS-WA (Not available for CoreS3 SE) - 6-Axis IMU BMI270 (Not available for CoreS3 SE) -Start Application Development -***************************** - -Before powering up your M5Stack CoreS3, please make sure that the board is in good -condition with no obvious signs of damage. - -System requirements -=================== - -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features -Building & Flashing -******************* - -.. zephyr:board-supported-runners:: - -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 +Supported Features ================== -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: - -.. tabs:: - - .. group-tab:: M5Stack CoreS3 - - .. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu - :goals: build - :west-args: --sysbuild - :compact: - - .. group-tab:: M5Stack CoreS3 SE - - .. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu/se - :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:: +.. zephyr:board-supported-hw:: - 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. tabs:: - - .. group-tab:: M5Stack CoreS3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu - :goals: build - - .. group-tab:: M5Stack CoreS3 SE - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu/se - :goals: build - -The usual ``flash`` target will work with the ``m5stack_cores3/esp32s3/procpu`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. tabs:: - - .. group-tab:: M5Stack CoreS3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu - :goals: flash - - .. group-tab:: M5Stack CoreS3 SE - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu/se - :goals: flash - -The baud rate of 921600bps is set by default. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: +System Requirements +******************* -.. code-block:: shell +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - west espressif monitor +Programming and Debugging +************************* -After the board has automatically reset 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 build vx.x.x-xxx-gxxxxxxxxxxxx *** - Hello World! m5stack_cores3/esp32s3/procpu +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_. - -ESP32-S3 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-S3`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. tabs:: - - .. group-tab:: M5Stack CoreS3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu - :goals: debug - - .. group-tab:: M5Stack CoreS3 SE - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu/se - :goals: debug - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. tabs:: - - .. group-tab:: M5Stack CoreS3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu - :goals: debug - - .. group-tab:: M5Stack CoreS3 SE +========= - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_cores3/esp32s3/procpu/se - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/m5stack/m5stack_fire/doc/index.rst b/boards/m5stack/m5stack_fire/doc/index.rst index 0a5f940cc2fe7..afabfa2b4269d 100644 --- a/boards/m5stack/m5stack_fire/doc/index.rst +++ b/boards/m5stack/m5stack_fire/doc/index.rst @@ -5,6 +5,9 @@ Overview M5Stack Fire is an ESP32-based development board from M5Stack. +Hardware +******** + M5Stack Fire features the following integrated components: - ESP32-D0WDQ6 chip (240MHz dual core, 600 DMIPS, 520KB SRAM, Wi-Fi) @@ -22,8 +25,16 @@ M5Stack Fire features the following integrated components: - Three physical buttons - LED strips +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + +Supported Features +================== + +.. zephyr:board-supported-hw:: + Functional Description -********************** +====================== The following table below describes the key components, interfaces, and controls of the M5Stack Core2 board. @@ -69,83 +80,34 @@ of the M5Stack Core2 board. | | possibility to query current battery status. | | +------------------+------------------------------------------------------------------------+-----------+ -Supported Features -================== - -.. zephyr:board-supported-hw:: - -Start Application Development -***************************** - -Before powering up your M5Stack Fire, please make sure that the board is in good -condition with no obvious signs of damage. - -System requirements -=================== +System Requirements +******************* -Prerequisites -------------- +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -------------------- +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_fire/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``m5stack_fire`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_fire/esp32/procpu - :goals: flash +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -The baud rate of 921600bps is set by default. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! m5stack_fire +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ---------- +========= M5Stack Fire debugging is not supported due to pinout limitations. Related Documents ***************** -- `M5Stack-Fire schematic `_ (PDF) -- `M5Stack-Fire docs `_ -- `ESP32 Datasheet `_ (PDF) -- `ESP32 Hardware Reference `_ +.. target-notes:: + +.. _`M5Stack-Fire schematic`: https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/480/M5-Core-Schematic_20171206.pdf +.. _`M5Stack-Fire docs`: https://docs.m5stack.com/en/core/fire_v2.7 +.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf +.. _`ESP32 Hardware Reference`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html diff --git a/boards/m5stack/m5stack_stamps3/doc/index.rst b/boards/m5stack/m5stack_stamps3/doc/index.rst index 4e006eca8a397..53546a0e29548 100644 --- a/boards/m5stack/m5stack_stamps3/doc/index.rst +++ b/boards/m5stack/m5stack_stamps3/doc/index.rst @@ -4,6 +4,10 @@ Overview ******** M5Stack StampS3 is an ESP32-based development board from M5Stack. + +Hardware +******** + It features the following integrated components: - ESP32-S3FN8 chip (240MHz dual core) @@ -14,8 +18,16 @@ It features the following integrated components: - Bluetooth - User-Button +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + +Supported Features +================== + +.. zephyr:board-supported-hw:: + Functional Description -********************** +====================== The following table below describes the key components, interfaces, and controls of the M5Stack StampS3 module. @@ -108,71 +120,28 @@ supply. If this pin is pulled low this main 3.3V power supply for the MCU will b deactivated. It is internally equipped with a pull-up and can hence be left open if unused. -Start Application Development -***************************** - -Before powering up your M5Stack StampS3, please make sure that the board is in good -condition with no obvious signs of damage. +System Requirements +******************* -System requirements -=================== - -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - It is recommended running the command above after :file:`west update`. - -Building & Flashing -------------------- +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_stamps3/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``m5stack_stamps3`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stack_stamps3/esp32s3/procpu - :goals: flash - -The baud rate of 921600bps is set by default. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! m5stack_stamps3 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging ---------- +========= + +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging M5Stack StampS3 exports a JTAG-interface via Pins 19 (MTCK), 21 (MTDO), 23 (MTDI), 25 (MTMS). @@ -185,7 +154,9 @@ M5Stack StampS3 exports a JTAG-interface via Pins 19 (MTCK), 21 (MTDO), 23 Related Documents ***************** -- `M5Stack StampS3 schematic `_ -- `M5Stack StampS3 `_ -- `ESP32 Datasheet `_ (PDF) -- `ESP32 Hardware Reference `_ +.. target-notes:: + +.. _`M5Stack StampS3 schematic`: https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/Stamp/S007%20StampS3/Sch_M5StampS3_v0.2.pdf +.. _`M5Stack StampS3`: https://docs.m5stack.com/en/core/StampS3 +.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf +.. _`ESP32 Hardware Reference`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html diff --git a/boards/m5stack/m5stickc_plus/doc/index.rst b/boards/m5stack/m5stickc_plus/doc/index.rst index e6e65a3e1d8f1..d38c332c15704 100644 --- a/boards/m5stack/m5stickc_plus/doc/index.rst +++ b/boards/m5stack/m5stickc_plus/doc/index.rst @@ -5,6 +5,9 @@ Overview M5StickC PLUS, one of the core devices in M5Stacks product series, is an ESP32-based development board. +Hardware +******** + M5StickC PLUS features the following integrated components: - ESP32-PICO-D4 chip (240MHz dual core, 600 DMIPS, 520KB SRAM, Wi-Fi) @@ -17,8 +20,16 @@ M5StickC PLUS features the following integrated components: Some of the ESP32 I/O pins are broken out to the board's pin headers for easy access. +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + +Supported Features +================== + +.. zephyr:board-supported-hw:: + Functional Description -********************** +====================== The following table below describes the key components, interfaces, and controls of the M5StickC PLUS board. @@ -57,165 +68,35 @@ of the M5StickC PLUS board. | microphone | | +------------------+-------------------------------------------------------------------------+ - -Start Application Development -***************************** - -Before powering up your M5StickC PLUS, please make sure that the board is in good -condition with no obvious signs of damage. - -System requirements -=================== - -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - .. code:: cfg +Programming and Debugging +************************* - 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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: m5stickc_plus - :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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stickc_plus/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``m5stickc_plus`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: m5stickc_plus/esp32/procpu - :goals: flash - -The default baud rate for the M5StickC PLUS is set to 1500000bps. If experiencing issues when flashing, -try using different values by using ``--esp-baud-rate `` option during -``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). - -You can also open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset 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! m5stickc_plus +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* +========= M5StickC PLUS debugging is not supported due to pinout limitations. -Related Documents -***************** +References +********** + +.. target-notes:: -- `M5StickC PLUS schematic `_ (WEBP) -- `ESP32-PICO-D4 Datasheet `_ (PDF) -- `M5StickC PLUS docs `_ -- `ESP32 Datasheet `_ (PDF) -- `ESP32 Hardware Reference `_ +.. _`M5StickC PLUS schematic`: https://static-cdn.m5stack.com/resource/docs/products/core/m5stickc_plus/m5stickc_plus_sch_03.webp +.. _`ESP32-PICO-D4 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf +.. _`M5StickC PLUS docs`: https://docs.m5stack.com/en/core/m5stickc_plus +.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf +.. _`ESP32 Hardware Reference`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html diff --git a/boards/m5stack/stamp_c3/doc/index.rst b/boards/m5stack/stamp_c3/doc/index.rst index 704bacc6cad90..b4a33f4870630 100644 --- a/boards/m5stack/stamp_c3/doc/index.rst +++ b/boards/m5stack/stamp_c3/doc/index.rst @@ -8,171 +8,39 @@ for IoT edge devices such as home appliances and Industrial Automation. For more details see the `M5Stack STAMP-C3`_ page. +Hardware +******** + +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features + Supported Features ================== .. zephyr:board-supported-hw:: -Prerequisites -************* - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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: +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: stamp_c3 - :goals: build - :west-args: --sysbuild - :compact: +Programming and Debugging +************************* -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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: stamp_c3 - :goals: build - -The usual ``flash`` target will work with the ``stamp_c3`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: stamp_c3 - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset 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! stamp_c3 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: stamp_c3 - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: stamp_c3 - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/olimex/olimex_esp32_evb/doc/index.rst b/boards/olimex/olimex_esp32_evb/doc/index.rst index 1f5ca0033fb30..b3034b63aa496 100644 --- a/boards/olimex/olimex_esp32_evb/doc/index.rst +++ b/boards/olimex/olimex_esp32_evb/doc/index.rst @@ -38,174 +38,36 @@ these reference documents: - `ESP32-EVB GitHub Repository`_ - `ESP32-WROOM32-E/UE Datasheet`_ +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features + Supported Features -****************** +================== .. zephyr:board-supported-hw:: -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: olimex_esp32_evb - :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. +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: olimex_esp32_evb/esp32/procpu - :goals: build - -The usual ``flash`` target will work with the ``olimex_esp32_evb`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: olimex_esp32_evb/esp32/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! olimex_esp32_evb +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: olimex_esp32_evb/esp32/procpu - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: olimex_esp32_evb/esp32/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/others/esp32c3_supermini/doc/index.rst b/boards/others/esp32c3_supermini/doc/index.rst index cf7e1841e05dd..98bd1d442395b 100644 --- a/boards/others/esp32c3_supermini/doc/index.rst +++ b/boards/others/esp32c3_supermini/doc/index.rst @@ -10,201 +10,36 @@ There may be multiple variations depending on the specific vendor. For more info Hardware ******** -SoC Features: - -- IEEE 802.11 b/g/n-compliant -- Bluetooth 5, Bluetooth mesh -- 32-bit RISC-V single-core processor, up to 160MHz -- 384 KB ROM -- 400 KB SRAM (16 KB for cache) -- 8 KB SRAM in RTC -- 22 x programmable GPIOs -- 3 x SPI -- 2 x UART -- 1 x I2C -- 1 x I2S -- 2 x 54-bit general-purpose timers -- 3 x watchdog timers -- 1 x 52-bit system timer -- Remote Control Peripheral (RMT) -- LED PWM controller (LEDC) -- Full-speed USB Serial/JTAG controller -- General DMA controller (GDMA) -- 1 x TWAI® -- 2 x 12-bit SAR ADCs, up to 6 channels -- 1 x soc core temperature sensor - -For more information on the ESP32-C3 SOC, check the datasheet at `ESP32-C3 Datasheet`_ or the technical reference -manual at `ESP32-C3 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features Supported Features ================== .. zephyr:board-supported-hw:: -System requirements +System Requirements ******************* -Prerequisites -============= +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: esp32c3_supermini - :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: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. 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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32c3_supermini - :goals: build - -The usual ``flash`` target will work with the ``esp32c3_supermini`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32c3_supermini - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! esp32c3_supermini +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -As with much custom hardware, the ESP32-C3 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32c3_supermini - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32c3_supermini - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/others/icev_wireless/doc/index.rst b/boards/others/icev_wireless/doc/index.rst index f9168a1489013..f7db40d2a446a 100644 --- a/boards/others/icev_wireless/doc/index.rst +++ b/boards/others/icev_wireless/doc/index.rst @@ -3,7 +3,7 @@ Overview ******** -The ICE-V Wireless is a combined ESP32C3 and iCE40 FPGA board. +The ICE-V Wireless is a combined ESP32-C3 and iCE40 FPGA board. See the `ICE-V Wireless Github Project`_ for details. @@ -25,6 +25,9 @@ For details on iCE40 hardware please refer to the following resources: * `iCE40 UltraPlus Family Datasheet`_ +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features + Supported Features ================== @@ -55,159 +58,28 @@ below. :align: center :alt: ICE-V Wireless Pinout +System Requirements +******************* + +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements + Programming and Debugging ************************* .. zephyr:board-supported-runners:: -Programming and debugging for the ICE-V Wireless ESP32-C3 target is -incredibly easy 🎉 following the steps below. - -Building and 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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: icev_wireless - :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 +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. 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. - -For the :code:`Hello, world!` application, follow the instructions below. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: icev_wireless - :goals: build flash - -Open the serial monitor using the following command: - -.. code-block:: console - - $ west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! icev_wireless +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -As with much custom hardware, the ESP32C3 modules require patches to -OpenOCD that are not upstreamed. Espressif maintains their own fork of -the project. The custom OpenOCD can be obtained by running the following extension: - -.. code-block:: console - - west espressif install - -.. note:: - - By default, the OpenOCD will be downloaded and installed under $HOME/.espressif/tools/zephyr directory - (%USERPROFILE%/.espressif/tools/zephyr on Windows). - -The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: icev_wireless - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the -:zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: icev_wireless - :maybe-skip-config: - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/seeed/xiao_esp32c3/doc/index.rst b/boards/seeed/xiao_esp32c3/doc/index.rst index ef8bdb5a86e11..35d5d947adee8 100644 --- a/boards/seeed/xiao_esp32c3/doc/index.rst +++ b/boards/seeed/xiao_esp32c3/doc/index.rst @@ -3,7 +3,7 @@ Overview ******** -Seeed Studio XIAO ESP32C3 is an IoT mini development board based on the +Seeed Studio XIAO ESP32-C3 is an IoT mini development board based on the Espressif ESP32-C3 WiFi/Bluetooth dual-mode chip. For more details see the `Seeed Studio XIAO ESP32C3`_ wiki page. @@ -16,6 +16,9 @@ has an USB-C port for programming and debugging, integrated battery charging and an U.FL external antenna connector. It is based on a standard XIAO 14 pin pinout. +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features + Supported Features ================== @@ -32,157 +35,28 @@ The board uses a standard XIAO pinout, the default pin mapping is the following: XIAO ESP32C3 Pinout -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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: +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: xiao_esp32c3 - :goals: build - :west-args: --sysbuild - :compact: +Programming and Debugging +************************* -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. - -For the :code:`Hello, world!` application, follow the instructions below. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32c3 - :goals: build flash - -Since the Zephyr console is by default on the ``usb_serial`` device, we use -the espressif monitor to view. - -.. code-block:: console - - $ west espressif monitor - -After the board has automatically reset 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! xiao_esp32c3 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32c3 - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32c3 - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/seeed/xiao_esp32c6/doc/index.rst b/boards/seeed/xiao_esp32c6/doc/index.rst index a1b93cc9c42dc..bafed8d8cdc1e 100644 --- a/boards/seeed/xiao_esp32c6/doc/index.rst +++ b/boards/seeed/xiao_esp32c6/doc/index.rst @@ -18,11 +18,17 @@ Bluetooth 5.3 (LE) and the 802.15.4 protocol. It has an USB-C port for programmi and debugging, integrated battery charging and an U.FL external antenna connector. It is based on a standard XIAO 14 pin pinout. +.. include:: ../../../espressif/common/soc-esp32c6-features.rst + :start-after: espressif-soc-esp32c6-features + Supported Features ================== .. zephyr:board-supported-hw:: +Connections and IOs +=================== + The board uses a standard XIAO pinout, the default pin mapping is the following: .. figure:: img/xiao_esp32c6_pinout.webp @@ -31,170 +37,28 @@ The board uses a standard XIAO pinout, the default pin mapping is the following: XIAO ESP32C6 Pinout -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -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 EPS32 SoC. - -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: xiao_esp32c6/esp32c6/hpcore - :goals: build - :west-args: --sysbuild - :compact: - -By default, the ESP32-C6 sysbuild creates bootloader (MCUboot) and application -images. But it can be configured to create other kind of images. +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32c6/esp32c6/hpcore - :goals: build - -The usual ``flash`` target will work with the ``xiao_esp32c6`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32c6/esp32c6/hpcore - :goals: flash - -Since the Zephyr console is by default on the ``usb_serial`` device, we use -the espressif monitor to view. - -.. code-block:: console - - $ west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! xiao_esp32c6/esp32c6/hpcore +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -As with much custom hardware, the ESP32-C6 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32c6/esp32c6/hpcore - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32c6/esp32c6/hpcore - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/seeed/xiao_esp32s3/doc/index.rst b/boards/seeed/xiao_esp32s3/doc/index.rst index 1aacfe17bc44e..1f6fc1c58e64b 100644 --- a/boards/seeed/xiao_esp32s3/doc/index.rst +++ b/boards/seeed/xiao_esp32s3/doc/index.rst @@ -35,6 +35,9 @@ RF module, and numerous peripherals. Additionally, Sense variant integrates a OV2640 camera sensor, microphone and sdcard slot. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features + Supported Features ================== @@ -51,173 +54,31 @@ The board uses a standard XIAO pinout, the default pin mapping is the following: XIAO ESP32S3 and XIAO ESP32S3 Sense Pinout -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: xiao_esp32s3 - :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. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). +Programming and Debugging +************************* -.. tabs:: - - .. group-tab:: XIAO ESP32S3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32s3/esp32s3/procpu - :goals: build - - .. group-tab:: XIAO ESP32S3 Sense - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32s3/esp32s3/procpu/sense - :goals: build - -The usual ``flash`` target will work with the ``xiao_esp32s3`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. tabs:: - - .. group-tab:: XIAO ESP32S3 - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32s3/esp32s3/procpu - :goals: flash - - .. group-tab:: XIAO ESP32S3 Sense - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: xiao_esp32s3/esp32s3/procpu/sense - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset 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! xiao_esp32s3 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_. +========= -ESP32-S3 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. +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging -Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32-S3`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. +Sample applications +******************* .. tabs:: diff --git a/boards/vcc-gnd/yd_esp32/doc/index.rst b/boards/vcc-gnd/yd_esp32/doc/index.rst index af9e54c5a65fd..302487ffca00f 100644 --- a/boards/vcc-gnd/yd_esp32/doc/index.rst +++ b/boards/vcc-gnd/yd_esp32/doc/index.rst @@ -6,208 +6,39 @@ Overview The YD-ESP32 development board is one of VCC-GND® Studio's official boards. This board is based on the ESP32-WROOM-32E module, with the ESP32 as the core. -ESP32 -===== - -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 is created and developed by Espressif Systems, a -Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm -process. - -The features include the following: - -- Dual core Xtensa microprocessor (LX6), running at 160 or 240MHz -- 520KB of SRAM -- 802.11b/g/n/e/i -- Bluetooth v4.2 BR/EDR and BLE -- Various peripherals: - - - 12-bit ADC with up to 18 channels - - 2x 8-bit DACs - - 10x touch sensors - - Temperature sensor - - 4x SPI - - 2x I2S - - 2x I2C - - 3x UART - - SD/SDIO/MMC host - - Slave (SDIO/SPI) - - Ethernet MAC - - CAN bus 2.0 - - IR (RX/TX) - - Motor PWM - - LED PWM with up to 16 channels - - Hall effect sensor - -- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) -- 5uA deep sleep current +Hardware +******** -For more information, check the datasheet at `ESP32 Datasheet`_ or the technical reference -manual at `ESP32 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32-features.rst + :start-after: espressif-soc-esp32-features Supported Features ================== .. zephyr:board-supported-hw:: -System requirements -=================== - -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: yd_esp32 - :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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: yd_esp32/esp32/procpu - :goals: build +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -The usual ``flash`` target will work with the ``yd_esp32`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. +Programming and Debugging +************************* -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: yd_esp32/esp32/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! yd_esp32 - -RGB LED -======= - -The board contains an addressable RGB LED (`XL-5050RGBC-WS2812B`_), driven by GPIO16. -Here is an example of how to test it using the :zephyr:code-sample:`led-strip` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/drivers/led/led_strip - :board: yd_esp32/esp32/procpu - :goals: flash +.. zephyr:board-supported-runners:: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -.. _`XL-5050RGBC-WS2812B`: http://www.xinglight.cn/index.php?c=show&id=947 +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* +========= -ESP32 support on OpenOCD is available at `OpenOCD ESP32`_. +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging On the YD-ESP32 board, the JTAG pins are not run to a standard connector (e.g. ARM 20-pin) and need to be manually connected @@ -231,22 +62,6 @@ to the external programmer (e.g. a Flyswatter2): | IO15 | TDO | +------------+-----------+ -Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: yd_esp32/esp32/procpu - :goals: build flash - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: yd_esp32/esp32/procpu - :goals: debug - Note on Debugging with GDB Stub =============================== @@ -258,6 +73,23 @@ GDB stub is enabled on ESP32. This does not work as the code is on flash which cannot be randomly accessed for modification. + +Sample applications +******************* + +RGB LED +======= + +The board contains an addressable RGB LED (`XL-5050RGBC-WS2812B`_), driven by GPIO16. +Here is an example of how to test it using the :zephyr:code-sample:`led-strip` application. + +.. zephyr-app-commands:: + :zephyr-app: samples/drivers/led/led_strip + :board: yd_esp32/esp32/procpu + :goals: flash + +.. _`XL-5050RGBC-WS2812B`: http://www.xinglight.cn/index.php?c=show&id=947 + References ********** diff --git a/boards/waveshare/esp32s3_matrix/doc/index.rst b/boards/waveshare/esp32s3_matrix/doc/index.rst index 4090485a84d66..12f67aa6178f8 100644 --- a/boards/waveshare/esp32s3_matrix/doc/index.rst +++ b/boards/waveshare/esp32s3_matrix/doc/index.rst @@ -11,38 +11,13 @@ port. Hardware ******** -ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated 2.4 GHz Wi-Fi -and Bluetooth® Low Energy (Bluetooth LE). It consists of high-performance dual-core microprocessor -(Xtensa® 32-bit LX7), a low power coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband, -RF module, and numerous peripherals. - -ESP32-S3-Matrix includes the following features: - -- Dual core 32-bit Xtensa Microprocessor (Tensilica LX7), running up to 240MHz -- Additional vector instructions support for AI acceleration -- 512KB of SRAM -- 2MB of PSRAM -- 4MB of FLASH -- Wi-Fi 802.11b/g/n -- Bluetooth LE 5.0 with long-range support and up to 2Mbps data rate -- 8x8 RGB LED matrix -- Accelerometer/gyroscope - -Digital interfaces: - -- 15 programmable GPIOs +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features -Low Power: +The board included peripherals: -- Power Management Unit with five power modes -- Ultra-Low-Power (ULP) coprocessors: ULP-RISC-V and ULP-FSM - -Security: - -- Secure boot -- Flash encryption -- 4-Kbit OTP, up to 1792 bits for users -- Cryptographic hardware acceleration: (AES-128/256, Hash, RSA, RNG, HMAC, Digital signature) +- 8x8 RGB LED matrix +- Accelerometer/gyroscope Asymmetric Multiprocessing (AMP) ******************************** @@ -59,163 +34,28 @@ Supported Features .. zephyr:board-supported-hw:: -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing +System Requirements ******************* -.. zephyr:board-supported-runners:: - -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 -======== +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -The sysbuild makes possible to build and flash all necessary images needed to -bootstrap the board with the ESP32-S3 SoC. +Programming and Debugging +************************* -To build the sample application using sysbuild use the command: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: esp32s3_matrix/esp32s3/procpu - :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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s3_matrix/esp32s3/procpu - :goals: build - -The usual ``flash`` target will work with the ``esp32s3_matrix`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s3_matrix/esp32s3/procpu - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset 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! esp32s3_matrix +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_. - -ESP32-S3 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-S3`_. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s3_matrix/esp32s3/procpu - :goals: build flash - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s3_matrix/esp32s3/procpu - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/waveshare/esp32s3_touch_lcd_1_28/doc/index.rst b/boards/waveshare/esp32s3_touch_lcd_1_28/doc/index.rst index b9cab2da1d141..bdc9925c84711 100644 --- a/boards/waveshare/esp32s3_touch_lcd_1_28/doc/index.rst +++ b/boards/waveshare/esp32s3_touch_lcd_1_28/doc/index.rst @@ -10,89 +10,42 @@ Low Energy functions, an accelerometer and gyroscope, a battery charger and GPIO Hardware ******** -ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated 2.4 GHz Wi-Fi -and Bluetooth® Low Energy (Bluetooth LE). It consists of high-performance dual-core microprocessor -(Xtensa® 32-bit LX7), a low power coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband, -RF module, and numerous peripherals. - -ESP32-S3-Touch-LCD-1.28 includes the following features: - -- Dual core 32-bit Xtensa Microprocessor (Tensilica LX7), running up to 240MHz -- Additional vector instructions support for AI acceleration -- 2MB of SRAM -- 16MB of FLASH -- Wi-Fi 802.11b/g/n -- Bluetooth LE 5.0 with long-range support and up to 2Mbps data rate -- Round 1.28" LCD with touchscreen controller -- Accelerometer/gyroscope -- Battery charger - -Digital interfaces: - -- 6 programmable GPIOs -- 2 open-drain outputs - -Low Power: - -- Power Management Unit with five power modes -- Ultra-Low-Power (ULP) coprocessors: ULP-RISC-V and ULP-FSM - -Security: - -- Secure boot -- Flash encryption -- 4-Kbit OTP, up to 1792 bits for users -- Cryptographic hardware acceleration: (AES-128/256, Hash, RSA, RNG, HMAC, Digital signature) - -Asymmetric Multiprocessing (AMP) -******************************** - -ESP32-S3 allows 2 different applications to be executed in ESP32-S3 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 :zephyr:code-sample-category:`ipc` folder as code reference. - -For more information, check the datasheet at `ESP32-S3 Datasheet`_ or the technical reference -manual at `ESP32-S3 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32s3-features.rst + :start-after: espressif-soc-esp32s3-features Supported Features ================== .. zephyr:board-supported-hw:: -Prerequisites -------------- - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif - -.. note:: +System Requirements +******************* - It is recommended running the command above after :file:`west update`. +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Simple boot -=========== +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -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. +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -.. note:: +Debugging +========= - Simple boot does not provide any security features nor OTA updates. +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** .. target-notes:: -.. _ESP32-S3-Touch-LCD-1.28 Waveshare Wiki: https://www.waveshare.com/wiki/ESP32-S3-Touch-LCD-1.28 -.. _ESP32-S3 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-s3-mini-1_mini-1u_datasheet_en.pdf -.. _ESP32-S3 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf +.. _`ESP32-S3-Touch-LCD-1.28 Waveshare Wiki`: https://www.waveshare.com/wiki/ESP32-S3-Touch-LCD-1.28 +.. _`ESP32-S3 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s3-mini-1_mini-1u_datasheet_en.pdf +.. _`ESP32-S3 Technical Reference Manual`: https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf diff --git a/boards/we/orthosie1ev/doc/index.rst b/boards/we/orthosie1ev/doc/index.rst index 55f0afdb168a5..a59597daf0f84 100644 --- a/boards/we/orthosie1ev/doc/index.rst +++ b/boards/we/orthosie1ev/doc/index.rst @@ -4,209 +4,42 @@ Overview ******** Orthosie-I-EV is an entry-level development board based on Orthosie-I, -a module named for its small size. This board integrates complete Wi-Fi and Bluetooth® Low Energy functions. +a module named for its small size. This board integrates ESP32-C3 - complete Wi-Fi and Bluetooth® Low Energy functions. For more information, check `Orthosie-I Website`_. Hardware ******** -ESP32-C3 is a single-core Wi-Fi and Bluetooth 5 (LE) microcontroller SoC, -based on the open-source RISC-V architecture. It strikes the right balance of power, -I/O capabilities and security, thus offering the optimal cost-effective -solution for connected devices. -The availability of Wi-Fi and Bluetooth 5 (LE) connectivity not only makes the device configuration easy, -but it also facilitates a variety of use-cases based on dual connectivity. - -The features include the following: - -- 32-bit core RISC-V microcontroller with a maximum clock speed of 160 MHz -- 400 KB of internal RAM -- 802.11b/g/n/e/i -- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh -- Various peripherals: - - - 12-bit ADC with up to 6 channels - - TWAI compatible with CAN bus 2.0 - - Temperature sensor - - 3x SPI - - 1x I2S - - 1x I2C - - 2x UART - - LED PWM with up to 6 channels - -- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) - -For more information, check the datasheet at `ESP32-C3 Datasheet`_ or the technical reference -manual at `ESP32-C3 Technical Reference Manual`_. +.. include:: ../../../espressif/common/soc-esp32c3-features.rst + :start-after: espressif-soc-esp32c3-features Supported Features ================== .. zephyr:board-supported-hw:: -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements - west blobs fetch hal_espressif - -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -******************* +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -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: - -.. zephyr-app-commands:: - :tool: west - :zephyr-app: samples/hello_world - :board: we_orthosie1ev - :goals: build - :west-args: --sysbuild - :compact: +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -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 (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: we_orthosie1ev - :goals: build - -The usual ``flash`` target will work with the ``we_orthosie1ev`` board -configuration. Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: we_orthosie1ev - :goals: flash - -Open the serial monitor using the following command: - -.. code-block:: shell - - west espressif monitor - -After the board has automatically reset and booted, you should see the following -message in the monitor: - -.. code-block:: console - - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! we_orthosie1ev +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants Debugging -********* - -As with much custom hardware, the ESP32-C3 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 Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the -``-DOPENOCD= -DOPENOCD_DEFAULT_PATH=`` -parameter when building. - -Here is an example for building the :zephyr:code-sample:`hello_world` application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: we_orthosie1ev - :goals: build flash - :gen-args: -DOPENOCD= -DOPENOCD_DEFAULT_PATH= - -You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. +========= -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: we_orthosie1ev - :goals: debug +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** diff --git a/boards/wemos/esp32s2_lolin_mini/doc/index.rst b/boards/wemos/esp32s2_lolin_mini/doc/index.rst index 9fadc278205e2..9a8c1f3ecb169 100644 --- a/boards/wemos/esp32s2_lolin_mini/doc/index.rst +++ b/boards/wemos/esp32s2_lolin_mini/doc/index.rst @@ -3,99 +3,47 @@ Overview ******** -ESP32-S2 is a highly integrated, low-power, single-core Wi-Fi Microcontroller SoC, designed to be secure and -cost-effective, with a high performance and a rich set of IO capabilities. [1]_ - -The features include the following: - -- RSA-3072-based secure boot -- AES-XTS-256-based flash encryption -- Protected private key and device secrets from software access -- Cryptographic accelerators for enhanced performance -- Protection against physical fault injection attacks -- Various peripherals: - - - 43x programmable GPIOs - - 14x configurable capacitive touch GPIOs - - USB OTG - - LCD interface - - camera interface - - SPI - - I2S - - UART - - ADC - - DAC - - LED PWM with up to 8 channels +A mini wifi boards based ESP32-S2FN4R2. Hardware ******** +.. include:: ../../../espressif/common/soc-esp32s2-features.rst + :start-after: espressif-soc-esp32s2-features + Supported Features ================== .. zephyr:board-supported-hw:: -System requirements +System Requirements ******************* -Prerequisites -============= - -Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command -below to retrieve those files. - -.. code-block:: console - - west blobs fetch hal_espressif +.. include:: ../../../espressif/common/system-requirements.rst + :start-after: espressif-system-requirements -.. note:: - - It is recommended running the command above after :file:`west update`. - -Building & Flashing -=================== +Programming and Debugging +************************* .. zephyr:board-supported-runners:: -Build and flash applications as usual (see :ref:`build_an_application` and -:ref:`application_run` for more details). - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s2_lolin_mini - :goals: build - -The usual ``flash`` target will work with the ``esp32s2_lolin_mini`` board -configuration after putting the board into bootloader mode by holding the '0' -button then pressing 'RST' and releasing the 'RST' button. - -Here is an example for the :zephyr:code-sample:`hello_world` -application. - -.. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :board: esp32s2_lolin_mini - :goals: flash - -Open a serial port using e.g. screen - -.. code-block:: shell - - screen /dev/ttyUSB0 115200 +.. include:: ../../../espressif/common/building-flashing.rst + :start-after: espressif-building-flashing -After the board has been manually reset and booted, you should see the following -message in the monitor: +.. include:: ../../../espressif/common/board-variants.rst + :start-after: espressif-board-variants -.. code-block:: console +Debugging +========= - ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** - Hello World! esp32s2_lolin_mini +.. include:: ../../../espressif/common/openocd-debugging.rst + :start-after: espressif-openocd-debugging References ********** .. target-notes:: -.. [1] https://www.espressif.com/en/products/socs/esp32-s2 -.. _`ESP32S2 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf -.. _`ESP32S2 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf +.. _`ESP32-S2 Product pages`: https://www.espressif.com/en/products/socs/esp32-s2 +.. _`ESP32-S2 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf +.. _`ESP32-S2 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf