Skip to content

Commit

Permalink
boards: esp32-based: update documentation
Browse files Browse the repository at this point in the history 
This PR updates all Espressif board names to meet its
original value. It also update reference links, re-organize
entries and removes unused content.

This also fixes bootloader information regarding a few boards.
IDF Bootloader was removed and these boards kept that info.
This updated it accordingly with the Simpleboot Bootloader.

Signed-off-by: Sylvio Alves <sylvio.alves@espressif.com>
  • Loading branch information
@sylvioalves @nashif
sylvioalves authored and nashif committed Sep 11, 2024
1 parent c8161dc commit 6654c2a
Show file tree
Hide file tree
Showing 25 changed files with 313 additions and 273 deletions.
38 changes: 19 additions & 19 deletions boards/espressif/esp32_devkitc_wroom/doc/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
.. _esp32_devkitc_wroom:

ESP32-DEVKITC-WROOM
ESP32-DevKitC-WROOM
###################

Overview
********

ESP32-DEVKITC-WROOM is a series of low cost, low power system on a chip microcontrollers
with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a
ESP32 is a series of low cost, low power system on a chip microcontrollers
with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a
Tensilica Xtensa LX6 microprocessor in both dual-core and single-core
variations. ESP32-WROOM is created and developed by Espressif Systems, a
variations. ESP32 is created and developed by Espressif Systems, a
Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm
process. [1]_
process. For more information, check `ESP32-DevKitC-WROOM`_.

The features include the following:

Expand Down Expand Up @@ -43,20 +43,23 @@ The features include the following:

.. figure:: img/esp32_devkitc_wroom.jpg
:align: center
:alt: ESP32-DEVKITC-WROOM
:alt: ESP32-DevKitC-WROOM

ESP32-DevKitC-WROOM-32D DK

For more information, check the datasheet at `ESP32 Datasheet`_ or the technical reference
manual at `ESP32 Technical Reference Manual`_.

Asymmetric Multiprocessing (AMP)
********************************

ESP32-DEVKITC-WROOM allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
ESP32-DevKitC-WROOM allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
and/or exchanging data over OpenAMP framework. See :ref:`ipc_samples` folder as code reference.

Supported Features
==================

Current Zephyr's ESP32-WROOM board supports the following features:
Current Zephyr's ESP32-DevKitC-WROOM board supports the following features:

+------------+------------+-------------------------------------+
| Interface | Controller | Driver/Component |
Expand Down Expand Up @@ -235,10 +238,9 @@ message in the monitor:
Debugging
*********

ESP32-DEVKITC-WROOM support on OpenOCD is available upstream as of version 0.12.0.
Download and install OpenOCD from `OpenOCD`_.
ESP32 support on OpenOCD is available at `OpenOCD ESP32`_.

On the ESP-WROOM-32 DevKitC board, the JTAG pins are not run to a
On the ESP32-DevKitC-WROOM board, the JTAG pins are not run to a
standard connector (e.g. ARM 20-pin) and need to be manually connected
to the external programmer (e.g. a Flyswatter2):

Expand All @@ -260,8 +262,7 @@ to the external programmer (e.g. a Flyswatter2):
| IO15 | TDO |
+------------+-----------+

Further documentation can be obtained from the SoC vendor in `JTAG debugging
for ESP32`_.
Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32`_.

Here is an example for building the :ref:`hello_world` application.

Expand All @@ -288,12 +289,11 @@ GDB stub is enabled on ESP32.
This does not work as the code is on flash which cannot be randomly
accessed for modification.

.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
.. _`OpenOCD`: https://github.com/openocd-org/openocd

References
**********

.. [1] https://en.wikipedia.org/wiki/ESP32
.. _ESP32 Technical Reference Manual: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _Hardware Reference: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html
.. _`ESP32-DevKitC-WROOM`: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/hw-reference/esp32/get-started-devkitc.html#
.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
.. _`ESP32 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
36 changes: 18 additions & 18 deletions boards/espressif/esp32_devkitc_wrover/doc/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
.. _esp32_devkitc_wrover:

ESP32-DEVKITC-WROVER
ESP32-DevKitC-WROVER
####################

Overview
********

ESP32 is a series of low cost, low power system on a chip microcontrollers
with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a
with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a
Tensilica Xtensa LX6 microprocessor in both dual-core and single-core
variations. ESP32 is created and developed by Espressif Systems, a
variations. ESP32 is created and developed by Espressif Systems, a
Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm
process. [1]_
process. For more information, check `ESP32-DevKitC-WROVER`_.

The features include the following:

Expand Down Expand Up @@ -43,20 +43,23 @@ The features include the following:

.. figure:: img/esp32_devkitc_wrover.jpg
:align: center
:alt: ESP32-DEVKITC-WROVER
:alt: ESP32-DevKitC-WROVER

ESP32-DevKitC-WROVER-IE

For more information, check the datasheet at `ESP32 Datasheet`_ or the technical reference
manual at `ESP32 Technical Reference Manual`_.

Asymmetric Multiprocessing (AMP)
********************************

ESP32-DEVKITC-WROVER allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
ESP32-DevKitC-WROVER allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
and/or exchanging data over OpenAMP framework. See :ref:`ipc_samples` folder as code reference.

Supported Features
==================

Current Zephyr's ESP32-devkitc board supports the following features:
Current Zephyr's ESP32-DevKitC-WROVER board supports the following features:

+------------+------------+-------------------------------------+
| Interface | Controller | Driver/Component |
Expand Down Expand Up @@ -235,10 +238,9 @@ message in the monitor:
Debugging
*********

ESP32 support on OpenOCD is available upstream as of version 0.12.0.
Download and install OpenOCD from `OpenOCD`_.
ESP32 support on OpenOCD is available at `OpenOCD ESP32`_.

On the ESP-WROOM-32 DevKitC board, the JTAG pins are not run to a
On the ESP32-DevKitC-WROVER board, the JTAG pins are not run to a
standard connector (e.g. ARM 20-pin) and need to be manually connected
to the external programmer (e.g. a Flyswatter2):

Expand All @@ -260,8 +262,7 @@ to the external programmer (e.g. a Flyswatter2):
| IO15 | TDO |
+------------+-----------+

Further documentation can be obtained from the SoC vendor in `JTAG debugging
for ESP32`_.
Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32`_.

Here is an example for building the :ref:`hello_world` application.

Expand All @@ -288,12 +289,11 @@ GDB stub is enabled on ESP32.
This does not work as the code is on flash which cannot be randomly
accessed for modification.

.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
.. _`OpenOCD`: https://github.com/openocd-org/openocd

References
**********

.. [1] https://en.wikipedia.org/wiki/ESP32
.. _ESP32 Technical Reference Manual: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _Hardware Reference: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html
.. _`ESP32-DevKitC-WROVER`: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/hw-reference/esp32/get-started-devkitc.html#
.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
.. _`ESP32 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
69 changes: 31 additions & 38 deletions boards/espressif/esp32_ethernet_kit/doc/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
.. _esp32_ethernet_kit:

ESP32-ETHERNET-KIT
ESP32-Ethernet-Kit
##################

Overview
********

The ESP32-Ethernet-Kit is an Ethernet-to-Wi-Fi development board that enables
Ethernet devices to be interconnected over Wi-Fi. At the same time, to provide
more flexible power supply options, the ESP32-Ethernet-Kit also supports power
Expand All @@ -17,16 +20,13 @@ over Ethernet (PoE).

ESP32-Ethernet-Kit V1.2 Overview

Overview
********

ESP32-Ethernet-Kit is an ESP32-based development board produced by
`Espressif <https://espressif.com>`_.
ESP32-Ethernet-Kit is an ESP32-WROVER-E based development.
For more information, check the datasheet at `ESP32-WROVER-E Datasheet`_.

It consists of two development boards, the Ethernet board A and the PoE
board B. The `Ethernet board (A)`_ contains Bluetooth/Wi-Fi dual-mode
It consists of two development boards, the Ethernet Board A and the PoE
board B. The `Ethernet Board (A)`_ contains Bluetooth/Wi-Fi dual-mode
ESP32-WROVER-E module and IP101GRI, a Single Port 10/100 Fast Ethernet
Transceiver (PHY). The `PoE board (B)`_ provides power over Ethernet
Transceiver (PHY). The `PoE Board (B)`_ provides power over Ethernet
functionality. The A board can work independently, without the board B
installed.

Expand All @@ -39,7 +39,7 @@ installed.

ESP32-Ethernet-Kit V1.2

For the application loading and monitoring, the Ethernet board (A) also
For the application loading and monitoring, the Ethernet Board (A) also
features FTDI FT2232H chip - an advanced multi-interface USB bridge.
This chip enables to use JTAG for direct debugging of ESP32 through the
USB interface without a separate JTAG debugger.
Expand Down Expand Up @@ -76,7 +76,7 @@ Ethernet Board (A)
:alt: ESP32-Ethernet-Kit V1.2
:figclass: align-center

ESP32-Ethernet-Kit - Ethernet board (A) layout
ESP32-Ethernet-Kit - Ethernet Board (A) layout

The table below provides description starting from the picture's top right
corner and going clockwise.
Expand Down Expand Up @@ -104,8 +104,7 @@ corner and going clockwise.
ESP32. FT2232H also features USB-to-JTAG interface which is available
on channel A of the chip, while USB-to-serial is on channel B.
The FT2232H chip enhances user-friendliness in terms of application
development and debugging. See
`ESP32-Ethernet-Kit V1.2 Ethernet board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_.
development and debugging. See `ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`_
* - USB Port
- USB interface. Power supply for the board as well as the communication
interface between a computer and the board.
Expand All @@ -121,7 +120,7 @@ corner and going clockwise.
* - DC/DC Converter
- Provided DC 5 V to 3.3 V conversion, output current up to 2 A.
* - Board B Connectors
- A pair male and female header pins for mounting the `PoE board (B)`_
- A pair male and female header pins for mounting the `PoE Board (B)`_
* - IP101GRI (PHY)
- The physical layer (PHY) connection to the Ethernet cable is
implemented using the
Expand Down Expand Up @@ -155,39 +154,39 @@ PoE Board (B)
^^^^^^^^^^^^^

This board coverts power delivered over the Ethernet cable (PoE) to provide a
power supply for the Ethernet board (A). The main components of the PoE board
power supply for the Ethernet Board (A). The main components of the PoE Board
(B) are shown on the block diagram under `Functionality Overview`_.

The PoE board (B) has the following features:
The PoE Board (B) has the following features:

* Support for IEEE 802.3at
* Power output: 5 V, 1.4 A

To take advantage of the PoE functionality the **RJ45 Port** of the Ethernet
board (A) should be connected with an Ethernet cable to a switch that supports
PoE. When the Ethernet board (A) detects 5 V power output from the PoE board
PoE. When the Ethernet Board (A) detects 5 V power output from the PoE Board
(B), the USB power will be automatically cut off.

.. figure:: img/esp32-ethernet-kit-b-v1.0-layout.jpg
:align: center
:alt: ESP32-Ethernet-Kit - PoE board (B)
:alt: ESP32-Ethernet-Kit - PoE Board (B)
:figclass: align-center

ESP32-Ethernet-Kit - PoE board (B) layout
ESP32-Ethernet-Kit - PoE Board (B) layout

.. list-table:: Table PoE board (B)
.. list-table:: Table PoE Board (B)
:widths: 40 150
:header-rows: 1

* - Key Component
- Description
* - Board A Connector
- Four female (left) and four male (right) header pins for connecting the
PoE board (B) to `Ethernet board (A)`_. The pins on the left accept
PoE Board (B) to `Ethernet Board (A)`_. The pins on the left accept
power coming from a PoE switch. The pins on the right deliver 5 V power
supply to the Ethernet board (A).
supply to the Ethernet Board (A).
* - External Power Terminals
- Optional power supply (26.6 ~ 54 V) to the PoE board (B).
- Optional power supply (26.6 ~ 54 V) to the PoE Board (B).

.. _get-started-esp32-ethernet-kit-v1.2-setup-options:

Expand Down Expand Up @@ -225,9 +224,7 @@ or generated from internal ESP32 APLL (not recommended).
.. note::

For additional information on the RMII clock selection, please refer to
`ESP32-Ethernet-Kit V1.2 Ethernet board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_,
sheet 2, location D2.

`ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`_, sheet 2, location D2.

RMII Clock Sourced Externally by PHY
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -267,7 +264,7 @@ for transmission line delay, and then supplied to the PHY.

To implement this option, users need to remove or add some RC components on
the board. For details please refer to
`ESP32-Ethernet-Kit V1.2 Ethernet board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_,
`ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`_,
sheet 2, location D2. Please note that if the APLL is already used for other
purposes (e.g. I2S peripheral), then you have no choice but use an external
RMII clock.
Expand Down Expand Up @@ -411,7 +408,7 @@ GPIO Allocation Summary
module that can be disabled/enabled externally. Similarly like when
using RESET_N, the oscillator module should be disabled by default and
turned on by ESP32 after power-up. For a reference design please see
`ESP32-Ethernet-Kit V1.2 Ethernet board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_.
`ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`_.

2. The ESP32 pins GPIO16 and GPIO17 are not broken out to the
ESP32-WROVER-E module and therefore not available for use. If you need
Expand Down Expand Up @@ -560,7 +557,7 @@ Debugging

As with much custom hardware, the ESP32 modules require patches to
OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_
the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_.

The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
Expand Down Expand Up @@ -615,13 +612,9 @@ Board Init
RESET_N (GPIO5) is automatically set high to enable the Ethernet PHY
during board initialization (board_init.c)

Related Documents
*****************
References
**********

* `ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_ (PDF)
* `ESP32-Ethernet-Kit PoE Board (B) Schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_B_V1.0_20190517.pdf>`_ (PDF)
* `ESP32-Ethernet-Kit V1.2 Ethernet Board (A) PCB Layout <https://dl.espressif.com/dl/schematics/PCB_ESP32-Ethernet-Kit_A_V1_2_20190829.pdf>`_ (PDF)
* `ESP32-Ethernet-Kit PoE Board (B) PCB Layout <https://dl.espressif.com/dl/schematics/PCB_ESP32-Ethernet-Kit_B_V1_0_20190306.pdf>`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROVER-E Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf>`_ (PDF)
* `OpenOCD ESP32 <https://github.com/espressif/openocd-esp32/releases>`_
.. _`ESP32-Ethernet-Kit V1.2 Ethernet Board (A) Schematic`: https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf
.. _`ESP32-WROVER-E Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf
.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
Loading

0 comments on commit 6654c2a

Please sign in to comment.