Initial commit with basic project structure and Firebeetle 2 board definition
This commit is contained in:
256
boards/espressif/esp32_devkitc/doc/index.rst
Normal file
256
boards/espressif/esp32_devkitc/doc/index.rst
Normal file
@@ -0,0 +1,256 @@
|
||||
.. zephyr:board:: esp32_devkitc
|
||||
|
||||
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
|
||||
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. 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.
|
||||
|
||||
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
|
||||
*******************
|
||||
|
||||
.. 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: esp32_devkitc
|
||||
: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: esp32_devkitc/esp32/procpu
|
||||
:goals: build
|
||||
|
||||
The usual ``flash`` target will work with the ``esp32_devkitc`` board
|
||||
configuration. Here is an example for the :zephyr:code-sample:`hello_world`
|
||||
application.
|
||||
|
||||
.. zephyr-app-commands::
|
||||
:zephyr-app: samples/hello_world
|
||||
:board: esp32_devkitc/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! esp32_devkitc
|
||||
|
||||
Debugging
|
||||
*********
|
||||
|
||||
ESP32 support on OpenOCD is available at `OpenOCD ESP32`_.
|
||||
|
||||
On the ESP32-DevKitC 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):
|
||||
|
||||
+------------+-----------+
|
||||
| ESP32 pin | JTAG pin |
|
||||
+============+===========+
|
||||
| 3V3 | VTRef |
|
||||
+------------+-----------+
|
||||
| EN | nTRST |
|
||||
+------------+-----------+
|
||||
| IO14 | TMS |
|
||||
+------------+-----------+
|
||||
| IO12 | TDI |
|
||||
+------------+-----------+
|
||||
| GND | GND |
|
||||
+------------+-----------+
|
||||
| IO13 | TCK |
|
||||
+------------+-----------+
|
||||
| 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: esp32_devkitc/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: esp32_devkitc/esp32/procpu
|
||||
:goals: debug
|
||||
|
||||
Note on Debugging with GDB Stub
|
||||
===============================
|
||||
|
||||
GDB stub is enabled on ESP32.
|
||||
|
||||
* When adding breakpoints, please use hardware breakpoints with command
|
||||
``hbreak``. Command ``break`` uses software breakpoints which requires
|
||||
modifying memory content to insert break/trap instructions.
|
||||
This does not work as the code is on flash which cannot be randomly
|
||||
accessed for modification.
|
||||
|
||||
References
|
||||
**********
|
||||
|
||||
.. target-notes::
|
||||
|
||||
.. _`ESP32-DevKitC`: https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-devkitc/index.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
|
||||
Reference in New Issue
Block a user