patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 8 Packages Projects Releases Wiki Activity

boards: esp32: update Espressif boards documentation

Browse source 
Zephyr SDK toolchain integration requires all ESP32 family
board's documentation updates.

Signed-off-by: Sylvio Alves <sylvio.alves@espressif.com>
This commit is contained in:
Sylvio Alves 2022-05-04 12:31:18 -03:00 committed by Carles Cufí
parent 20fbaaccc4
commit 922ae85767
7 changed files with 408 additions and 507 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

128
boards/riscv/esp32c3_devkitm/doc/index.rst
View file

@ -35,37 +35,11 @@ The features include the following:
System requirements
*******************
Build Environment Setup
=======================
Prerequisites
-------------
Some variables must be exported into the environment prior to building this port.
Find more information at :ref:`env_vars` on how to keep this settings saved in you environment.
.. note::
In case of manual toolchain installation, set :file:`ESPRESSIF_TOOLCHAIN_PATH` accordingly.
Otherwise, set toolchain path as below. If necessary.
On Linux and macOS:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT="espressif"
export ESPRESSIF_TOOLCHAIN_PATH="${HOME}/.espressif/tools/zephyr"
On Windows:
.. code-block:: console
# on CMD:
set ESPRESSIF_TOOLCHAIN_PATH=%USERPROFILE%\.espressif\tools\zephyr
set ZEPHYR_TOOLCHAIN_VARIANT=espressif
# on PowerShell
$env:ESPRESSIF_TOOLCHAIN_PATH="$env:USERPROFILE\.espressif\tools\zephyr"
$env:ZEPHYR_TOOLCHAIN_VARIANT="espressif"
Finally, retrieve required submodules to build this port. This might take a while for the first time:
Espressif HAL requires binary blobs in order work. The west extension below performs the required
syncronization to clone, checkout and pull the submodules:
.. code-block:: console
@ -73,10 +47,18 @@ Finally, retrieve required submodules to build this port. This might take a whil
.. note::
It is recommended running the command above after :file:`west update` so that submodules also get updated.
It is recommended running the command above after :file:`west update`.
Flashing
========
Building & Flashing
-------------------
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_devkitm
:goals: build
The usual ``flash`` target will work with the ``esp32c3_devkitm`` board
configuration. Here is an example for the :ref:`hello_world`
@ -87,52 +69,54 @@ application.
:board: esp32c3_devkitm
:goals: flash
Refer to :ref:`build_an_application` and :ref:`application_run` for
more details.
Open the serial monitor using the following command:
It's impossible to determine which serial port the ESP32 board is
connected to, as it uses a generic RS232-USB converter. The default of
``/dev/ttyUSB0`` is provided as that's often the assigned name on a Linux
machine without any other such converters.
.. code-block:: shell
The baud rate of 921600bps is recommended. If experiencing issues when
flashing, try halving the value a few times (460800, 230400, 115200,
etc).
All flashing options are now handled by the :ref:`west` tool, including flashing
with custom options such as a different serial port. The ``west`` tool supports
specific options for the ESP32C3 board, as listed here:
--esp-idf-path ESP_IDF_PATH
path to ESP-IDF
--esp-device ESP_DEVICE
serial port to flash, default $ESPTOOL_PORT if defined.
If not, esptool will loop over available serial ports until
it finds ESP32 device to flash.
--esp-baud-rate ESP_BAUD_RATE
serial baud rate, default 921600
--esp-flash-size ESP_FLASH_SIZE
flash size, default "detect"
--esp-flash-freq ESP_FLASH_FREQ
flash frequency, default "40m"
--esp-flash-mode ESP_FLASH_MODE
flash mode, default "dio"
--esp-tool ESP_TOOL if given, complete path to espidf. default is to
search for it in [ESP_IDF_PATH]/components/esptool_py/
esptool/esptool.py
--esp-flash-bootloader ESP_FLASH_BOOTLOADER
Bootloader image to flash
--esp-flash-partition_table ESP_FLASH_PARTITION_TABLE
Partition table to flash
For example, to flash to ``/dev/ttyUSB2``, use the following command after
having build the application in the ``build`` directory:
west espressif monitor
After the board has automatically reset and booted, you should see the following
message in the monitor:
.. code-block:: console
west flash -d build/ --skip-rebuild --esp-device /dev/ttyUSB2
***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
Hello World! esp32c3_devkitm
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=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
Here is an example for building the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32c3_devkitm
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32c3_devkitm
:goals: debug
References
**********

169
boards/xtensa/esp32/doc/index.rst
View file

@ -45,58 +45,10 @@ System requirements
*******************
Prerequisites
=============
-------------
The ESP32 toolchain :file:`xtensa-esp32-elf` is required to build this port.
The toolchain installation can be performed in two ways:
#. Automatic installation
.. code-block:: console
west espressif install
.. note::
By default, the toolchain will be downloaded and installed under $HOME/.espressif directory
(%USERPROFILE%/.espressif on Windows).
#. Manual installation
Follow the `ESP32 Toolchain`_ link to download proper OS package version.
Unpack the toolchain file to a known location as it will be required for environment path configuration.
Build Environment Setup
=======================
Some variables must be exported into the environment prior to building this port.
Find more information at :ref:`env_vars` on how to keep this settings saved in you environment.
.. note::
In case of manual toolchain installation, set :file:`ESPRESSIF_TOOLCHAIN_PATH` accordingly.
Otherwise, set toolchain path as below. If necessary, update the version folder path as in :file:`esp-2020r3-8.4.0`.
On Linux and macOS:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT="espressif"
export ESPRESSIF_TOOLCHAIN_PATH="${HOME}/.espressif/tools/zephyr"
On Windows:
.. code-block:: console
# on CMD:
set ESPRESSIF_TOOLCHAIN_PATH=%USERPROFILE%\.espressif\tools\zephyr
set ZEPHYR_TOOLCHAIN_VARIANT=espressif
# on PowerShell
$env:ESPRESSIF_TOOLCHAIN_PATH="$env:USERPROFILE\.espressif\tools\zephyr"
$env:ZEPHYR_TOOLCHAIN_VARIANT="espressif"
Finally, retrieve required submodules to build this port. This might take a while for the first time:
Espressif HAL requires binary blobs in order work. The west extension below performs the required
syncronization to clone, checkout and pull the submodules:
.. code-block:: console
@ -104,10 +56,18 @@ Finally, retrieve required submodules to build this port. This might take a whil
.. note::
It is recommended running the command above after :file:`west update` so that submodules also get updated.
It is recommended running the command above after :file:`west update`.
Flashing
========
Building & Flashing
-------------------
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: esp32
:goals: build
The usual ``flash`` target will work with the ``esp32`` board
configuration. Here is an example for the :ref:`hello_world`
@ -118,72 +78,57 @@ application.
:board: esp32
:goals: flash
Refer to :ref:`build_an_application` and :ref:`application_run` for
more details.
Open the serial monitor using the following command:
It's impossible to determine which serial port the ESP32 board is
connected to, as it uses a generic RS232-USB converter. The default of
``/dev/ttyUSB0`` is provided as that's often the assigned name on a Linux
machine without any other such converters.
.. code-block:: shell
The baud rate of 921600bps is recommended. If experiencing issues when
flashing, try halving the value a few times (460800, 230400, 115200,
etc). It might be necessary to change the flash frequency or the flash
mode; please refer to the `esptool documentation`_ for guidance on these
settings.
All flashing options are now handled by the :ref:`west` tool, including flashing
with custom options such as a different serial port. The ``west`` tool supports
specific options for the ESP32 board, as listed here:
--esp-idf-path ESP_IDF_PATH
path to ESP-IDF
--esp-device ESP_DEVICE
serial port to flash, default $ESPTOOL_PORT if defined.
If not, esptool will loop over available serial ports until
it finds ESP32 device to flash.
--esp-baud-rate ESP_BAUD_RATE
serial baud rate, default 921600
--esp-flash-size ESP_FLASH_SIZE
flash size, default "detect"
--esp-flash-freq ESP_FLASH_FREQ
flash frequency, default "40m"
--esp-flash-mode ESP_FLASH_MODE
flash mode, default "dio"
--esp-tool ESP_TOOL if given, complete path to espidf. default is to
search for it in [ESP_IDF_PATH]/components/esptool_py/
esptool/esptool.py
--esp-flash-bootloader ESP_FLASH_BOOTLOADER
Bootloader image to flash
--esp-flash-partition_table ESP_FLASH_PARTITION_TABLE
Partition table to flash
For example, to flash to ``/dev/ttyUSB2``, use the following command after
having build the application in the ``build`` directory:
west espressif monitor
After the board has automatically reset and booted, you should see the following
message in the monitor:
.. code-block:: console
west flash -d build/ --skip-rebuild --esp-device /dev/ttyUSB2
***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
Hello World! esp32
Debugging
---------
As with much custom hardware, the ESP32 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=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
Here is an example for building the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32
:goals: debug
Using JTAG
==========
As with much custom hardware, the ESP-32 modules require patches to
OpenOCD that are not upstream. Espressif maintains their own fork of
the project here. By convention they put it in ``~/esp`` next to the
installations of their toolchain and SDK:
.. code-block:: console
cd ~/esp
git clone https://github.com/espressif/openocd-esp32
cd openocd-esp32
./bootstrap
./configure
make
======================
On the ESP-WROVER-KIT board, the JTAG pins are connected internally to
a USB serial port on the same device as the console. These boards

128
boards/xtensa/esp32s2_saola/doc/index.rst
View file

@ -32,37 +32,11 @@ The features include the following:
System requirements
*******************
Build Environment Setup
=======================
Prerequisites
-------------
Some variables must be exported into the environment prior to building this port.
Find more information at :ref:`env_vars` on how to keep this settings saved in you environment.
.. note::
In case of manual toolchain installation, set :file:`ESPRESSIF_TOOLCHAIN_PATH` accordingly.
Otherwise, set toolchain path as below. If necessary.
On Linux and macOS:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT="espressif"
export ESPRESSIF_TOOLCHAIN_PATH="${HOME}/.espressif/tools/zephyr"
On Windows:
.. code-block:: console
# on CMD:
set ESPRESSIF_TOOLCHAIN_PATH=%USERPROFILE%\.espressif\tools\zephyr
set ZEPHYR_TOOLCHAIN_VARIANT=espressif
# on PowerShell
$env:ESPRESSIF_TOOLCHAIN_PATH="$env:USERPROFILE\.espressif\tools\zephyr"
$env:ZEPHYR_TOOLCHAIN_VARIANT="espressif"
Finally, retrieve required submodules to build this port. This might take a while for the first time:
Espressif HAL requires binary blobs in order work. The west extension below performs the required
syncronization to clone, checkout and pull the submodules:
.. code-block:: console
@ -70,10 +44,18 @@ Finally, retrieve required submodules to build this port. This might take a whil
.. note::
It is recommended running the command above after :file:`west update` so that submodules also get updated.
It is recommended running the command above after :file:`west update`.
Flashing
========
Building & Flashing
-------------------
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_saola
:goals: build
The usual ``flash`` target will work with the ``esp32s2_saola`` board
configuration. Here is an example for the :ref:`hello_world`
@ -84,52 +66,54 @@ application.
:board: esp32s2_saola
:goals: flash
Refer to :ref:`build_an_application` and :ref:`application_run` for
more details.
Open the serial monitor using the following command:
It's impossible to determine which serial port the ESP32-S2 board is
connected to, as it uses a generic RS232-USB converter. The default of
``/dev/ttyUSB0`` is provided as that's often the assigned name on a Linux
machine without any other such converters.
.. code-block:: shell
The baud rate of 921600bps is recommended. If experiencing issues when
flashing, try halving the value a few times (460800, 230400, 115200,
etc).
All flashing options are now handled by the :ref:`west` tool, including flashing
with custom options such as a different serial port. The ``west`` tool supports
specific options for the ESP32-S2 board, as listed here:
--esp-idf-path ESP_IDF_PATH
path to ESP-IDF
--esp-device ESP_DEVICE
serial port to flash, default $ESPTOOL_PORT if defined.
If not, esptool will loop over available serial ports until
it finds ESP32 device to flash.
--esp-baud-rate ESP_BAUD_RATE
serial baud rate, default 921600
--esp-flash-size ESP_FLASH_SIZE
flash size, default "detect"
--esp-flash-freq ESP_FLASH_FREQ
flash frequency, default "40m"
--esp-flash-mode ESP_FLASH_MODE
flash mode, default "dio"
--esp-tool ESP_TOOL if given, complete path to espidf. default is to
search for it in [ESP_IDF_PATH]/components/esptool_py/
esptool/esptool.py
--esp-flash-bootloader ESP_FLASH_BOOTLOADER
Bootloader image to flash
--esp-flash-partition_table ESP_FLASH_PARTITION_TABLE
Partition table to flash
For example, to flash to ``/dev/ttyUSB2``, use the following command after
having build the application in the ``build`` directory:
west espressif monitor
After the board has automatically reset and booted, you should see the following
message in the monitor:
.. code-block:: console
west flash -d build/ --skip-rebuild --esp-device /dev/ttyUSB2
***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
Hello World! esp32s2_saola
Debugging
---------
As with much custom hardware, the ESP32S2 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=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
Here is an example for building the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32s2_saola
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32s2_saola
:goals: debug
References
**********

136
boards/xtensa/esp_wrover_kit/doc/index.rst
View file

@ -19,11 +19,12 @@ USB bridge. This chip enables to use JTAG for direct debugging of ESP32 through
without a separate JTAG debugger. ESP-WROVER-KIT makes development convenient, easy, and
cost-effective.
Most of the ESP32 I/O pins are broken out to the board’s pin headers for easy access.
Most of the ESP32 I/O pins are broken out to the board's pin headers for easy access.
.. note::
ESP32’s GPIO16 and GPIO17 are used as chip select and clock signals for PSRAM. By default, the two
GPIOs are not broken out to the board’s pin headers in order to ensure reliable performance.
ESP32's GPIO16 and GPIO17 are used as chip select and clock signals for PSRAM. By default, the two
GPIOs are not broken out to the board's pin headers in order to ensure reliable performance.
Functionality Overview
**********************
@ -268,6 +269,7 @@ Legend:
+---+-----------+
.. note::
Since GPIO32 and GPIO33 are connected to the oscillator by default, they are not connected to
the JP1 I/O connector to maintain signal integrity. This allocation may be changed from the
oscillator to JP1 by desoldering the zero-ohm resistors from positions R11 / R23 and re-
@ -442,37 +444,11 @@ Turn the Power Switch to ON, the 5V Power On LED should light up.
System requirements
*******************
Build Environment Setup
=======================
Prerequisites
-------------
Some variables must be exported into the environment prior to building this port.
Find more information at :ref:`env_vars` on how to keep this settings saved in you environment.
.. note::
In case of manual toolchain installation, set :file:`ESPRESSIF_TOOLCHAIN_PATH` accordingly.
Otherwise, set toolchain path as below. If necessary.
On Linux and macOS:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT="espressif"
export ESPRESSIF_TOOLCHAIN_PATH="${HOME}/.espressif/tools/zephyr"
On Windows:
.. code-block:: console
# on CMD:
set ESPRESSIF_TOOLCHAIN_PATH=%USERPROFILE%\.espressif\tools\zephyr
set ZEPHYR_TOOLCHAIN_VARIANT=espressif
# on PowerShell
$env:ESPRESSIF_TOOLCHAIN_PATH="$env:USERPROFILE\.espressif\tools\zephyr"
$env:ZEPHYR_TOOLCHAIN_VARIANT="espressif"
Finally, retrieve required submodules to build this port. This might take a while for the first time:
Espressif HAL requires binary blobs in order work. The west extension below performs the required
syncronization to clone, checkout and pull the submodules:
.. code-block:: console
@ -480,10 +456,18 @@ Finally, retrieve required submodules to build this port. This might take a whil
.. note::
It is recommended running the command above after :file:`west update` so that submodules also get updated.
It is recommended running the command above after :file:`west update`.
Flashing
========
Building & Flashing
-------------------
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: esp_wrover_kit
:goals: build
The usual ``flash`` target will work with the ``esp_wrover_kit`` board
configuration. Here is an example for the :ref:`hello_world`
@ -494,52 +478,54 @@ application.
:board: esp_wrover_kit
:goals: flash
Refer to :ref:`build_an_application` and :ref:`application_run` for
more details.
Open the serial monitor using the following command:
It's impossible to determine which serial port the ESP-WROVER-KIT board is
connected to, as it uses a generic RS232-USB converter. The default of
``/dev/ttyUSB1`` is provided as that's often the assigned name on a Linux
machine without any other such converters.
.. code-block:: shell
The baud rate of 921600bps is recommended. If experiencing issues when
flashing, try halving the value a few times (460800, 230400, 115200,
etc).
All flashing options are now handled by the :ref:`west` tool, including flashing
with custom options such as a different serial port. The ``west`` tool supports
specific options for the ESP32-S2 board, as listed here:
--esp-idf-path ESP_IDF_PATH
path to ESP-IDF
--esp-device ESP_DEVICE
serial port to flash, default $ESPTOOL_PORT if defined.
If not, esptool will loop over available serial ports until
it finds ESP32 device to flash.
--esp-baud-rate ESP_BAUD_RATE
serial baud rate, default 921600
--esp-flash-size ESP_FLASH_SIZE
flash size, default "detect"
--esp-flash-freq ESP_FLASH_FREQ
flash frequency, default "40m"
--esp-flash-mode ESP_FLASH_MODE
flash mode, default "dio"
--esp-tool ESP_TOOL if given, complete path to espidf. default is to
search for it in ``[ESP_IDF_PATH]/components/esptool_py/
esptool/esptool.py``
--esp-flash-bootloader ESP_FLASH_BOOTLOADER
Bootloader image to flash
--esp-flash-partition_table ESP_FLASH_PARTITION_TABLE
Partition table to flash
For example, to flash to ``/dev/ttyUSB2``, use the following command after
having build the application in the ``build`` directory:
west espressif monitor
After the board has automatically reset and booted, you should see the following
message in the monitor:
.. code-block:: console
west flash -d build/ --skip-rebuild --esp-device /dev/ttyUSB2
***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
Hello World! esp_wrover_kit
Debugging
---------
As with much custom hardware, the ESP32 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=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
Here is an example for building the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp_wrover_kit
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp_wrover_kit
:goals: debug
Related Documents
*****************

152
boards/xtensa/heltec_wifi_lora32_v2/doc/index.rst
View file

@ -6,7 +6,7 @@ Heltec WiFi LoRa 32 (V2)
Overview
********
Heltec WiFi LoRa 32 is a classic IoT dev-board designed & produced by Heltec Automation(TM), it’s a highly
Heltec WiFi LoRa 32 is a classic IoT dev-board designed & produced by Heltec Automation(TM), it's a highly
integrated product based on ESP32 + SX127x, it has Wi-Fi, BLE, LoRa functions, also Li-Po battery management
system, 0.96" OLED are also included. [1]_
@ -26,58 +26,10 @@ System requirements
*******************
Prerequisites
=============
-------------
The ESP32 toolchain :file:`xtensa-esp32-elf` is required to build this port.
The toolchain installation can be performed in two ways:
#. Automatic installation
.. code-block:: console
west espressif install
.. note::
By default, the toolchain will be downloaded and installed under $HOME/.espressif directory
(%USERPROFILE%/.espressif on Windows).
#. Manual installation
Follow the `ESP32 Toolchain`_ link to download proper OS package version.
Unpack the toolchain file to a known location as it will be required for environment path configuration.
Build Environment Setup
=======================
Some variables must be exported into the environment prior to building this port.
Find more information at :ref:`env_vars` on how to keep this settings saved in you environment.
.. note::
In case of manual toolchain installation, set :file:`ESPRESSIF_TOOLCHAIN_PATH` accordingly.
Otherwise, set toolchain path as below. If necessary, update the version folder path as in :file:`esp-2020r3-8.4.0`.
On Linux and macOS:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT="espressif"
export ESPRESSIF_TOOLCHAIN_PATH="${HOME}/.espressif/tools/zephyr"
On Windows:
.. code-block:: console
# on CMD:
set ESPRESSIF_TOOLCHAIN_PATH=%USERPROFILE%\.espressif\tools\zephyr
set ZEPHYR_TOOLCHAIN_VARIANT=espressif
# on PowerShell
$env:ESPRESSIF_TOOLCHAIN_PATH="$env:USERPROFILE\.espressif\tools\zephyr"
$env:ZEPHYR_TOOLCHAIN_VARIANT="espressif"
Finally, retrieve required submodules to build this port. This might take a while for the first time:
Espressif HAL requires binary blobs in order work. The west extension below performs the required
syncronization to clone, checkout and pull the submodules:
.. code-block:: console
@ -85,10 +37,18 @@ Finally, retrieve required submodules to build this port. This might take a whil
.. note::
It is recommended running the command above after :file:`west update` so that submodules also get updated.
It is recommended running the command above after :file:`west update`.
Flashing
========
Building & Flashing
-------------------
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
:goals: build
The usual ``flash`` target will work with the ``heltec_wifi_lora32_v2`` board
configuration. Here is an example for the :ref:`hello_world`
@ -99,54 +59,54 @@ application.
:board: heltec_wifi_lora32_v2
:goals: flash
Refer to :ref:`build_an_application` and :ref:`application_run` for
more details.
Open the serial monitor using the following command:
It's impossible to determine which serial port the ESP32 board is
connected to, as it uses a generic RS232-USB converter. The default of
``/dev/ttyUSB0`` is provided as that's often the assigned name on a Linux
machine without any other such converters.
.. code-block:: shell
The baud rate of 921600bps is recommended. If experiencing issues when
flashing, try halving the value a few times (460800, 230400, 115200,
etc). It might be necessary to change the flash frequency or the flash
mode; please refer to the `esptool documentation`_ for guidance on these
settings.
All flashing options are now handled by the :ref:`west` tool, including flashing
with custom options such as a different serial port. The ``west`` tool supports
specific options for the ESP32 board, as listed here:
--esp-idf-path ESP_IDF_PATH
path to ESP-IDF
--esp-device ESP_DEVICE
serial port to flash, default $ESPTOOL_PORT if defined.
If not, esptool will loop over available serial ports until
it finds ESP32 device to flash.
--esp-baud-rate ESP_BAUD_RATE
serial baud rate, default 921600
--esp-flash-size ESP_FLASH_SIZE
flash size, default "detect"
--esp-flash-freq ESP_FLASH_FREQ
flash frequency, default "40m"
--esp-flash-mode ESP_FLASH_MODE
flash mode, default "dio"
--esp-tool ESP_TOOL if given, complete path to espidf. default is to
search for it in [ESP_IDF_PATH]/components/esptool_py/
esptool/esptool.py
--esp-flash-bootloader ESP_FLASH_BOOTLOADER
Bootloader image to flash
--esp-flash-partition_table ESP_FLASH_PARTITION_TABLE
Partition table to flash
For example, to flash to ``/dev/ttyUSB2``, use the following command after
having build the application in the ``build`` directory:
west espressif monitor
After the board has automatically reset and booted, you should see the following
message in the monitor:
.. code-block:: console
west flash -d build/ --skip-rebuild --esp-device /dev/ttyUSB2
***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
Hello World! heltec_wifi_lora32_v2
Debugging
---------
As with much custom hardware, the ESP32 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=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
Here is an example for building the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: heltec_wifi_lora32_v2
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: heltec_wifi_lora32_v2
:goals: debug
References
**********

133
boards/xtensa/odroid_go/doc/index.rst
View file

@ -75,34 +75,14 @@ features:
| I2C | on-chip | i2c |
+------------+------------+-------------------------------------+
Programming
***********
System requirements
*******************
The ESP32 toolchain :file:`xtensa-esp32-elf` is required to build this port.
Install the toolchain:
Prerequisites
-------------
.. code-block:: console
west espressif install
.. note::
By default, the toolchain will be downloaded and installed under $HOME/.espressif directory
(%USERPROFILE%/.espressif on Windows).
Set up build environment
------------------------
With the toolchain installed, the Zephyr build system must be instructed to
use this particular variant by setting the following shell variables:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT="espressif"
export ESPRESSIF_TOOLCHAIN_PATH="/path/to/xtensa-esp32-elf/"
Finally, retrieve required submodules to build this port. This might take
a while for the first time:
Espressif HAL requires binary blobs in order work. The west extension below performs the required
syncronization to clone, checkout and pull the submodules:
.. code-block:: console
@ -110,68 +90,77 @@ a while for the first time:
.. note::
It is recommended running the command above after :file:`west update` so
that submodules also get updated.
It is recommended running the command above after :file:`west update`.
Flashing
--------
Building & Flashing
-------------------
The usual ``flash`` target will work with the ``odroid_go`` board configuration.
Here is an example for the :ref:`hello_world` application.
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
:host-os: unix
:board: odroid_go
:goals: build
Refer to :ref:`build_an_application` and :ref:`application_run` for more
details.
The usual ``flash`` target will work with the ``odroid_go`` board
configuration. Here is an example for the :ref:`hello_world`
application.
All flashing options are handled by the :ref:`west` tool, including flashing
with custom options such as a different serial port. The ``west`` tool supports
specific options for the ESP32 board, as listed here:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: odroid_go
:goals: flash
--esp-idf-path ESP_IDF_PATH
path to ESP-IDF
--esp-device ESP_DEVICE
serial port to flash, default /dev/ttyUSB0
--esp-baud-rate ESP_BAUD_RATE
serial baud rate, default 921600
--esp-flash-size ESP_FLASH_SIZE
flash size, default "detect"
--esp-flash-freq ESP_FLASH_FREQ
flash frequency, default "40m"
--esp-flash-mode ESP_FLASH_MODE
flash mode, default "dio"
--esp-tool ESP_TOOL complete path to espidf, default is to search for it in
[ESP_IDF_PATH]/components/esptool_py/esptool/esptool.py
--esp-flash-bootloader ESP_FLASH_BOOTLOADER
Bootloader image to flash
--esp-flash-partition_table ESP_FLASH_PARTITION_TABLE
Partition table to flash
Open the serial monitor using the following command:
For example, to flash to ``/dev/ttyUSB0``, use the following command after
having build the application in the ``build`` directory:
.. code-block:: console
west flash -d build/ --skip-rebuild --esp-device /dev/ttyUSB0
Connect ODROID-GO to your PC via the mini USB port and run your favorite
terminal program to listen for output.
.. code-block:: console
minicom -D /dev/ttyUSB0 -b 115200
Power off and then power on ODROID-GO. You should see the following message in
your terminal:
.. 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
Debugging
---------
As with much custom hardware, the ESP32 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=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
Here is an example for building the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: odroid_go
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: odroid_go
:goals: debug
References
**********

69
boards/xtensa/olimex_esp32_evb/doc/index.rst
View file

@ -49,7 +49,7 @@ these reference documents:
- `ESP32-WROOM32-E/UE Datasheet`_
Supported Features
==================
******************
The olimex_esp32_evb board configuration supports the following hardware
features:
@ -87,16 +87,37 @@ The default configuration can be found in the defconfig file:
Other hardware features are not currently supported by the port.
Programming and Debugging
*************************
System requirements
*******************
Prerequisites
-------------
Espressif HAL requires binary blobs in order work. The west extension below performs the required
syncronization to clone, checkout and pull the submodules:
.. code-block:: console
west espressif update
.. note::
It is recommended running the command above after :file:`west update`.
Building & Flashing
-------------------
Build and flash applications as usual (see :ref:`build_an_application` and
:ref:`application_run` for more details).
Flashing
========
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: olimex_esp32_evb
:goals: build
Here is an example for the :ref:`hello_world` application.
The usual ``flash`` target will work with the ``olimex_esp32_evb`` board
configuration. Here is an example for the :ref:`hello_world`
application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
@ -117,8 +138,40 @@ message in the monitor:
***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
Hello World! olimex_esp32_evb
Please see the generic :ref:`esp32` instructions for further tips on programming
and debugging.
Debugging
---------
As with much custom hardware, the ESP32 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=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
Here is an example for building the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: olimex_esp32_evb
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: olimex_esp32_evb
:goals: debug
.. _ESP32-EVB Website:
https://www.olimex.com/Products/IoT/ESP32/ESP32-EVB/open-source-hardware