1.. zephyr:board:: esp32_devkitc_wrover 2 3Overview 4******** 5 6ESP32 is a series of low cost, low power system on a chip microcontrollers 7with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a 8Tensilica Xtensa LX6 microprocessor in both dual-core and single-core 9variations. ESP32 is created and developed by Espressif Systems, a 10Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm 11process. For more information, check `ESP32-DevKitC-WROVER`_. 12 13The features include the following: 14 15- Dual core Xtensa microprocessor (LX6), running at 160 or 240MHz 16- 520KB of SRAM 17- 802.11b/g/n/e/i 18- Bluetooth v4.2 BR/EDR and BLE 19- Various peripherals: 20 21 - 12-bit ADC with up to 18 channels 22 - 2x 8-bit DACs 23 - 10x touch sensors 24 - Temperature sensor 25 - 4x SPI 26 - 2x I2S 27 - 2x I2C 28 - 3x UART 29 - SD/SDIO/MMC host 30 - Slave (SDIO/SPI) 31 - Ethernet MAC 32 - CAN bus 2.0 33 - IR (RX/TX) 34 - Motor PWM 35 - LED PWM with up to 16 channels 36 - Hall effect sensor 37 38- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) 39- 5uA deep sleep current 40 41For more information, check the datasheet at `ESP32 Datasheet`_ or the technical reference 42manual at `ESP32 Technical Reference Manual`_. 43 44Asymmetric Multiprocessing (AMP) 45******************************** 46 47ESP32-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 48and/or exchanging data over OpenAMP framework. See :zephyr:code-sample-category:`ipc` folder as code reference. 49 50Supported Features 51================== 52 53Current Zephyr's ESP32-DevKitC-WROVER board supports the following features: 54 55+------------+------------+-------------------------------------+ 56| Interface | Controller | Driver/Component | 57+============+============+=====================================+ 58| UART | on-chip | serial port | 59+------------+------------+-------------------------------------+ 60| GPIO | on-chip | gpio | 61+------------+------------+-------------------------------------+ 62| PINMUX | on-chip | pinmux | 63+------------+------------+-------------------------------------+ 64| USB-JTAG | on-chip | hardware interface | 65+------------+------------+-------------------------------------+ 66| SPI Master | on-chip | spi | 67+------------+------------+-------------------------------------+ 68| Timers | on-chip | counter | 69+------------+------------+-------------------------------------+ 70| Watchdog | on-chip | watchdog | 71+------------+------------+-------------------------------------+ 72| TRNG | on-chip | entropy | 73+------------+------------+-------------------------------------+ 74| LEDC | on-chip | pwm | 75+------------+------------+-------------------------------------+ 76| MCPWM | on-chip | pwm | 77+------------+------------+-------------------------------------+ 78| PCNT | on-chip | qdec | 79+------------+------------+-------------------------------------+ 80| SPI DMA | on-chip | spi | 81+------------+------------+-------------------------------------+ 82| TWAI | on-chip | can | 83+------------+------------+-------------------------------------+ 84| ADC | on-chip | adc | 85+------------+------------+-------------------------------------+ 86| DAC | on-chip | dac | 87+------------+------------+-------------------------------------+ 88| Wi-Fi | on-chip | | 89+------------+------------+-------------------------------------+ 90| Bluetooth | on-chip | | 91+------------+------------+-------------------------------------+ 92 93System requirements 94=================== 95 96Prerequisites 97------------- 98 99Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command 100below to retrieve those files. 101 102.. code-block:: console 103 104 west blobs fetch hal_espressif 105 106.. note:: 107 108 It is recommended running the command above after :file:`west update`. 109 110Building & Flashing 111******************* 112 113Simple boot 114=========== 115 116The board could be loaded using the single binary image, without 2nd stage bootloader. 117It is the default option when building the application without additional configuration. 118 119.. note:: 120 121 Simple boot does not provide any security features nor OTA updates. 122 123MCUboot bootloader 124================== 125 126User may choose to use MCUboot bootloader instead. In that case the bootloader 127must be built (and flashed) at least once. 128 129There are two options to be used when building an application: 130 1311. Sysbuild 1322. Manual build 133 134.. note:: 135 136 User can select the MCUboot bootloader by adding the following line 137 to the board default configuration file. 138 139 .. code:: cfg 140 141 CONFIG_BOOTLOADER_MCUBOOT=y 142 143Sysbuild 144======== 145 146The sysbuild makes possible to build and flash all necessary images needed to 147bootstrap the board with the ESP32 SoC. 148 149To build the sample application using sysbuild use the command: 150 151.. zephyr-app-commands:: 152 :tool: west 153 :zephyr-app: samples/hello_world 154 :board: esp32_devkitc_wrover 155 :goals: build 156 :west-args: --sysbuild 157 :compact: 158 159By default, the ESP32 sysbuild creates bootloader (MCUboot) and application 160images. But it can be configured to create other kind of images. 161 162Build directory structure created by sysbuild is different from traditional 163Zephyr build. Output is structured by the domain subdirectories: 164 165.. code-block:: 166 167 build/ 168 ├── hello_world 169 │ └── zephyr 170 │ ├── zephyr.elf 171 │ └── zephyr.bin 172 ├── mcuboot 173 │ └── zephyr 174 │ ├── zephyr.elf 175 │ └── zephyr.bin 176 └── domains.yaml 177 178.. note:: 179 180 With ``--sysbuild`` option the bootloader will be re-build and re-flash 181 every time the pristine build is used. 182 183For more information about the system build please read the :ref:`sysbuild` documentation. 184 185Manual build 186============ 187 188During the development cycle, it is intended to build & flash as quickly possible. 189For that reason, images can be built one at a time using traditional build. 190 191The instructions following are relevant for both manual build and sysbuild. 192The only difference is the structure of the build directory. 193 194.. note:: 195 196 Remember that bootloader (MCUboot) needs to be flash at least once. 197 198Build and flash applications as usual (see :ref:`build_an_application` and 199:ref:`application_run` for more details). 200 201.. zephyr-app-commands:: 202 :zephyr-app: samples/hello_world 203 :board: esp32_devkitc_wrover/esp32/procpu 204 :goals: build 205 206The usual ``flash`` target will work with the ``esp32_devkitc_wrover`` board 207configuration. Here is an example for the :zephyr:code-sample:`hello_world` 208application. 209 210.. zephyr-app-commands:: 211 :zephyr-app: samples/hello_world 212 :board: esp32_devkitc_wrover/esp32/procpu 213 :goals: flash 214 215Open the serial monitor using the following command: 216 217.. code-block:: shell 218 219 west espressif monitor 220 221After the board has automatically reset and booted, you should see the following 222message in the monitor: 223 224.. code-block:: console 225 226 ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** 227 Hello World! esp32_devkitc_wrover 228 229Debugging 230********* 231 232ESP32 support on OpenOCD is available at `OpenOCD ESP32`_. 233 234On the ESP32-DevKitC-WROVER board, the JTAG pins are not run to a 235standard connector (e.g. ARM 20-pin) and need to be manually connected 236to the external programmer (e.g. a Flyswatter2): 237 238+------------+-----------+ 239| ESP32 pin | JTAG pin | 240+============+===========+ 241| 3V3 | VTRef | 242+------------+-----------+ 243| EN | nTRST | 244+------------+-----------+ 245| IO14 | TMS | 246+------------+-----------+ 247| IO12 | TDI | 248+------------+-----------+ 249| GND | GND | 250+------------+-----------+ 251| IO13 | TCK | 252+------------+-----------+ 253| IO15 | TDO | 254+------------+-----------+ 255 256Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32`_. 257 258Here is an example for building the :zephyr:code-sample:`hello_world` application. 259 260.. zephyr-app-commands:: 261 :zephyr-app: samples/hello_world 262 :board: esp32_devkitc_wrover/esp32/procpu 263 :goals: build flash 264 265You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. 266 267.. zephyr-app-commands:: 268 :zephyr-app: samples/hello_world 269 :board: esp32_devkitc_wrover/esp32/procpu 270 :goals: debug 271 272Note on Debugging with GDB Stub 273=============================== 274 275GDB stub is enabled on ESP32. 276 277* When adding breakpoints, please use hardware breakpoints with command 278 ``hbreak``. Command ``break`` uses software breakpoints which requires 279 modifying memory content to insert break/trap instructions. 280 This does not work as the code is on flash which cannot be randomly 281 accessed for modification. 282 283References 284********** 285 286.. target-notes:: 287 288.. _`ESP32-DevKitC-WROVER`: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/hw-reference/esp32/get-started-devkitc.html# 289.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf 290.. _`ESP32 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf 291.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html 292.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases 293
