Skip to content

Commit 922ae85

Browse files
sylvioalvescarlescufi
sylvioalves
authored and
carlescufi
committed
boards: esp32: update Espressif boards documentation
Zephyr SDK toolchain integration requires all ESP32 family board's documentation updates. Signed-off-by: Sylvio Alves <[email protected]>
1 parent 20fbaac commit 922ae85

File tree

7 files changed

+387
-486
lines changed

7 files changed

+387
-486
lines changed

‎boards/riscv/esp32c3_devkitm/doc/index.rst

Lines changed: 55 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -35,104 +35,88 @@ The features include the following:
3535
System requirements
3636
*******************
3737

38-
Build Environment Setup
39-
=======================
38+
Prerequisites
39+
-------------
4040

41-
Some variables must be exported into the environment prior to building this port.
42-
Find more information at :ref:`env_vars` on how to keep this settings saved in you environment.
41+
Espressif HAL requires binary blobs in order work. The west extension below performs the required
42+
syncronization to clone, checkout and pull the submodules:
43+
44+
.. code-block:: console
45+
46+
west espressif update
4347
4448
.. note::
4549

46-
In case of manual toolchain installation, set :file:`ESPRESSIF_TOOLCHAIN_PATH` accordingly.
47-
Otherwise, set toolchain path as below. If necessary.
50+
It is recommended running the command above after :file:`west update`.
4851

49-
On Linux and macOS:
52+
Building & Flashing
53+
-------------------
5054

51-
.. code-block:: console
55+
Build and flash applications as usual (see :ref:`build_an_application` and
56+
:ref:`application_run` for more details).
57+
58+
.. zephyr-app-commands::
59+
:zephyr-app: samples/hello_world
60+
:board: esp32c3_devkitm
61+
:goals: build
62+
63+
The usual ``flash`` target will work with the ``esp32c3_devkitm`` board
64+
configuration. Here is an example for the :ref:`hello_world`
65+
application.
66+
67+
.. zephyr-app-commands::
68+
:zephyr-app: samples/hello_world
69+
:board: esp32c3_devkitm
70+
:goals: flash
71+
72+
Open the serial monitor using the following command:
73+
74+
.. code-block:: shell
5275
53-
export ZEPHYR_TOOLCHAIN_VARIANT="espressif"
54-
export ESPRESSIF_TOOLCHAIN_PATH="${HOME}/.espressif/tools/zephyr"
76+
west espressif monitor
5577
56-
On Windows:
78+
After the board has automatically reset and booted, you should see the following
79+
message in the monitor:
5780

5881
.. code-block:: console
5982
60-
# on CMD:
61-
set ESPRESSIF_TOOLCHAIN_PATH=%USERPROFILE%\.espressif\tools\zephyr
62-
set ZEPHYR_TOOLCHAIN_VARIANT=espressif
83+
***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
84+
Hello World! esp32c3_devkitm
6385
64-
# on PowerShell
65-
$env:ESPRESSIF_TOOLCHAIN_PATH="$env:USERPROFILE\.espressif\tools\zephyr"
66-
$env:ZEPHYR_TOOLCHAIN_VARIANT="espressif"
86+
Debugging
87+
---------
6788

68-
Finally, retrieve required submodules to build this port. This might take a while for the first time:
89+
As with much custom hardware, the ESP32C3 modules require patches to
90+
OpenOCD that are not upstreamed. Espressif maintains their own fork of
91+
the project. The custom OpenOCD can be obtained by running the following extension:
6992

7093
.. code-block:: console
7194
72-
west espressif update
95+
west espressif install
7396
7497
.. note::
7598

76-
It is recommended running the command above after :file:`west update` so that submodules also get updated.
99+
By default, the OpenOCD will be downloaded and installed under $HOME/.espressif/tools/zephyr directory
100+
(%USERPROFILE%/.espressif/tools/zephyr on Windows).
77101

78-
Flashing
79-
========
102+
The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
103+
``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
104+
parameter when building.
80105

81-
The usual ``flash`` target will work with the ``esp32c3_devkitm`` board
82-
configuration. Here is an example for the :ref:`hello_world`
83-
application.
106+
Here is an example for building the :ref:`hello_world` application.
84107

85108
.. zephyr-app-commands::
86109
:zephyr-app: samples/hello_world
87110
:board: esp32c3_devkitm
88-
:goals: flash
89-
90-
Refer to :ref:`build_an_application` and :ref:`application_run` for
91-
more details.
92-
93-
It's impossible to determine which serial port the ESP32 board is
94-
connected to, as it uses a generic RS232-USB converter. The default of
95-
``/dev/ttyUSB0`` is provided as that's often the assigned name on a Linux
96-
machine without any other such converters.
97-
98-
The baud rate of 921600bps is recommended. If experiencing issues when
99-
flashing, try halving the value a few times (460800, 230400, 115200,
100-
etc).
101-
102-
All flashing options are now handled by the :ref:`west` tool, including flashing
103-
with custom options such as a different serial port. The ``west`` tool supports
104-
specific options for the ESP32C3 board, as listed here:
105-
106-
--esp-idf-path ESP_IDF_PATH
107-
path to ESP-IDF
108-
--esp-device ESP_DEVICE
109-
serial port to flash, default $ESPTOOL_PORT if defined.
110-
If not, esptool will loop over available serial ports until
111-
it finds ESP32 device to flash.
112-
--esp-baud-rate ESP_BAUD_RATE
113-
serial baud rate, default 921600
114-
--esp-flash-size ESP_FLASH_SIZE
115-
flash size, default "detect"
116-
--esp-flash-freq ESP_FLASH_FREQ
117-
flash frequency, default "40m"
118-
--esp-flash-mode ESP_FLASH_MODE
119-
flash mode, default "dio"
120-
--esp-tool ESP_TOOL if given, complete path to espidf. default is to
121-
search for it in [ESP_IDF_PATH]/components/esptool_py/
122-
esptool/esptool.py
123-
--esp-flash-bootloader ESP_FLASH_BOOTLOADER
124-
Bootloader image to flash
125-
--esp-flash-partition_table ESP_FLASH_PARTITION_TABLE
126-
Partition table to flash
127-
128-
For example, to flash to ``/dev/ttyUSB2``, use the following command after
129-
having build the application in the ``build`` directory:
130-
131-
132-
.. code-block:: console
111+
:goals: build flash
112+
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
133113

134-
west flash -d build/ --skip-rebuild --esp-device /dev/ttyUSB2
114+
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
135115

116+
.. zephyr-app-commands::
117+
:zephyr-app: samples/hello_world
118+
:board: esp32c3_devkitm
119+
:goals: debug
136120

137121
References
138122
**********

‎boards/xtensa/esp32/doc/index.rst

Lines changed: 49 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -45,145 +45,90 @@ System requirements
4545
*******************
4646

4747
Prerequisites
48-
=============
48+
-------------
4949

50-
The ESP32 toolchain :file:`xtensa-esp32-elf` is required to build this port.
51-
The toolchain installation can be performed in two ways:
50+
Espressif HAL requires binary blobs in order work. The west extension below performs the required
51+
syncronization to clone, checkout and pull the submodules:
5252

53-
#. Automatic installation
54-
55-
.. code-block:: console
56-
57-
west espressif install
53+
.. code-block:: console
5854
59-
.. note::
55+
west espressif update
6056
61-
By default, the toolchain will be downloaded and installed under $HOME/.espressif directory
62-
(%USERPROFILE%/.espressif on Windows).
57+
.. note::
6358

64-
#. Manual installation
59+
It is recommended running the command above after :file:`west update`.
6560

66-
Follow the `ESP32 Toolchain`_ link to download proper OS package version.
67-
Unpack the toolchain file to a known location as it will be required for environment path configuration.
61+
Building & Flashing
62+
-------------------
6863

69-
Build Environment Setup
70-
=======================
64+
Build and flash applications as usual (see :ref:`build_an_application` and
65+
:ref:`application_run` for more details).
7166

72-
Some variables must be exported into the environment prior to building this port.
73-
Find more information at :ref:`env_vars` on how to keep this settings saved in you environment.
67+
.. zephyr-app-commands::
68+
:zephyr-app: samples/hello_world
69+
:board: esp32
70+
:goals: build
7471

75-
.. note::
72+
The usual ``flash`` target will work with the ``esp32`` board
73+
configuration. Here is an example for the :ref:`hello_world`
74+
application.
7675

77-
In case of manual toolchain installation, set :file:`ESPRESSIF_TOOLCHAIN_PATH` accordingly.
78-
Otherwise, set toolchain path as below. If necessary, update the version folder path as in :file:`esp-2020r3-8.4.0`.
76+
.. zephyr-app-commands::
77+
:zephyr-app: samples/hello_world
78+
:board: esp32
79+
:goals: flash
7980

80-
On Linux and macOS:
81+
Open the serial monitor using the following command:
8182

82-
.. code-block:: console
83+
.. code-block:: shell
8384
84-
export ZEPHYR_TOOLCHAIN_VARIANT="espressif"
85-
export ESPRESSIF_TOOLCHAIN_PATH="${HOME}/.espressif/tools/zephyr"
85+
west espressif monitor
8686
87-
On Windows:
87+
After the board has automatically reset and booted, you should see the following
88+
message in the monitor:
8889

8990
.. code-block:: console
9091
91-
# on CMD:
92-
set ESPRESSIF_TOOLCHAIN_PATH=%USERPROFILE%\.espressif\tools\zephyr
93-
set ZEPHYR_TOOLCHAIN_VARIANT=espressif
92+
***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
93+
Hello World! esp32
9494
95-
# on PowerShell
96-
$env:ESPRESSIF_TOOLCHAIN_PATH="$env:USERPROFILE\.espressif\tools\zephyr"
97-
$env:ZEPHYR_TOOLCHAIN_VARIANT="espressif"
95+
Debugging
96+
---------
9897

99-
Finally, retrieve required submodules to build this port. This might take a while for the first time:
98+
As with much custom hardware, the ESP32 modules require patches to
99+
OpenOCD that are not upstreamed. Espressif maintains their own fork of
100+
the project. The custom OpenOCD can be obtained by running the following extension:
100101

101102
.. code-block:: console
102103
103-
west espressif update
104+
west espressif install
104105
105106
.. note::
106107

107-
It is recommended running the command above after :file:`west update` so that submodules also get updated.
108+
By default, the OpenOCD will be downloaded and installed under $HOME/.espressif/tools/zephyr directory
109+
(%USERPROFILE%/.espressif/tools/zephyr on Windows).
108110

109-
Flashing
110-
========
111+
The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
112+
``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
113+
parameter when building.
111114

112-
The usual ``flash`` target will work with the ``esp32`` board
113-
configuration. Here is an example for the :ref:`hello_world`
114-
application.
115+
Here is an example for building the :ref:`hello_world` application.
115116

116117
.. zephyr-app-commands::
117118
:zephyr-app: samples/hello_world
118119
:board: esp32
119-
:goals: flash
120+
:goals: build flash
121+
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
120122

121-
Refer to :ref:`build_an_application` and :ref:`application_run` for
122-
more details.
123-
124-
It's impossible to determine which serial port the ESP32 board is
125-
connected to, as it uses a generic RS232-USB converter. The default of
126-
``/dev/ttyUSB0`` is provided as that's often the assigned name on a Linux
127-
machine without any other such converters.
128-
129-
The baud rate of 921600bps is recommended. If experiencing issues when
130-
flashing, try halving the value a few times (460800, 230400, 115200,
131-
etc). It might be necessary to change the flash frequency or the flash
132-
mode; please refer to the `esptool documentation`_ for guidance on these
133-
settings.
134-
135-
All flashing options are now handled by the :ref:`west` tool, including flashing
136-
with custom options such as a different serial port. The ``west`` tool supports
137-
specific options for the ESP32 board, as listed here:
138-
139-
--esp-idf-path ESP_IDF_PATH
140-
path to ESP-IDF
141-
--esp-device ESP_DEVICE
142-
serial port to flash, default $ESPTOOL_PORT if defined.
143-
If not, esptool will loop over available serial ports until
144-
it finds ESP32 device to flash.
145-
--esp-baud-rate ESP_BAUD_RATE
146-
serial baud rate, default 921600
147-
--esp-flash-size ESP_FLASH_SIZE
148-
flash size, default "detect"
149-
--esp-flash-freq ESP_FLASH_FREQ
150-
flash frequency, default "40m"
151-
--esp-flash-mode ESP_FLASH_MODE
152-
flash mode, default "dio"
153-
--esp-tool ESP_TOOL if given, complete path to espidf. default is to
154-
search for it in [ESP_IDF_PATH]/components/esptool_py/
155-
esptool/esptool.py
156-
--esp-flash-bootloader ESP_FLASH_BOOTLOADER
157-
Bootloader image to flash
158-
--esp-flash-partition_table ESP_FLASH_PARTITION_TABLE
159-
Partition table to flash
160-
161-
For example, to flash to ``/dev/ttyUSB2``, use the following command after
162-
having build the application in the ``build`` directory:
123+
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
163124

164-
165-
.. code-block:: console
166-
167-
west flash -d build/ --skip-rebuild --esp-device /dev/ttyUSB2
125+
.. zephyr-app-commands::
126+
:zephyr-app: samples/hello_world
127+
:board: esp32
128+
:goals: debug
168129

169130
Using JTAG
170-
==========
171-
172-
As with much custom hardware, the ESP-32 modules require patches to
173-
OpenOCD that are not upstream. Espressif maintains their own fork of
174-
the project here. By convention they put it in ``~/esp`` next to the
175-
installations of their toolchain and SDK:
176-
177-
.. code-block:: console
178-
179-
cd ~/esp
180-
181-
git clone https://github.com/espressif/openocd-esp32
182-
183-
cd openocd-esp32
184-
./bootstrap
185-
./configure
186-
make
131+
======================
187132

188133
On the ESP-WROVER-KIT board, the JTAG pins are connected internally to
189134
a USB serial port on the same device as the console. These boards

0 commit comments

Comments
 (0)