1.. zephyr:board:: yd_esp32 2 3Overview 4******** 5 6The YD-ESP32 development board is one of VCC-GND® Studio's official boards. 7This board is based on the ESP32-WROOM-32E module, with the ESP32 as the core. 8 9ESP32 10===== 11 12ESP32 is a series of low cost, low power system on a chip microcontrollers 13with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a 14Tensilica Xtensa LX6 microprocessor in both dual-core and single-core 15variations. ESP32 is created and developed by Espressif Systems, a 16Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm 17process. 18 19The features include the following: 20 21- Dual core Xtensa microprocessor (LX6), running at 160 or 240MHz 22- 520KB of SRAM 23- 802.11b/g/n/e/i 24- Bluetooth v4.2 BR/EDR and BLE 25- Various peripherals: 26 27 - 12-bit ADC with up to 18 channels 28 - 2x 8-bit DACs 29 - 10x touch sensors 30 - Temperature sensor 31 - 4x SPI 32 - 2x I2S 33 - 2x I2C 34 - 3x UART 35 - SD/SDIO/MMC host 36 - Slave (SDIO/SPI) 37 - Ethernet MAC 38 - CAN bus 2.0 39 - IR (RX/TX) 40 - Motor PWM 41 - LED PWM with up to 16 channels 42 - Hall effect sensor 43 44- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) 45- 5uA deep sleep current 46 47For more information, check the datasheet at `ESP32 Datasheet`_ or the technical reference 48manual at `ESP32 Technical Reference Manual`_. 49 50Supported Features 51================== 52 53Current Zephyr's YD-ESP32 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: yd_esp32 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: yd_esp32/esp32/procpu 204 :goals: build 205 206The usual ``flash`` target will work with the ``yd_esp32`` 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: yd_esp32/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! yd_esp32 228 229RGB LED 230======= 231 232The board contains an addressable RGB LED (`XL-5050RGBC-WS2812B`_), driven by GPIO16. 233Here is an example of how to test it using the :zephyr:code-sample:`led-strip` application. 234 235.. zephyr-app-commands:: 236 :zephyr-app: samples/drivers/led/led_strip 237 :board: yd_esp32/esp32/procpu 238 :goals: flash 239 240 241.. _`XL-5050RGBC-WS2812B`: http://www.xinglight.cn/index.php?c=show&id=947 242 243Debugging 244********* 245 246ESP32 support on OpenOCD is available at `OpenOCD ESP32`_. 247 248On the YD-ESP32 board, the JTAG pins are not run to a 249standard connector (e.g. ARM 20-pin) and need to be manually connected 250to the external programmer (e.g. a Flyswatter2): 251 252+------------+-----------+ 253| ESP32 pin | JTAG pin | 254+============+===========+ 255| 3V3 | VTRef | 256+------------+-----------+ 257| EN | nTRST | 258+------------+-----------+ 259| IO14 | TMS | 260+------------+-----------+ 261| IO12 | TDI | 262+------------+-----------+ 263| GND | GND | 264+------------+-----------+ 265| IO13 | TCK | 266+------------+-----------+ 267| IO15 | TDO | 268+------------+-----------+ 269 270Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32`_. 271 272Here is an example for building the :zephyr:code-sample:`hello_world` application. 273 274.. zephyr-app-commands:: 275 :zephyr-app: samples/hello_world 276 :board: yd_esp32/esp32/procpu 277 :goals: build flash 278 279You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. 280 281.. zephyr-app-commands:: 282 :zephyr-app: samples/hello_world 283 :board: yd_esp32/esp32/procpu 284 :goals: debug 285 286Note on Debugging with GDB Stub 287=============================== 288 289GDB stub is enabled on ESP32. 290 291* When adding breakpoints, please use hardware breakpoints with command 292 ``hbreak``. Command ``break`` uses software breakpoints which requires 293 modifying memory content to insert break/trap instructions. 294 This does not work as the code is on flash which cannot be randomly 295 accessed for modification. 296 297References 298********** 299 300.. target-notes:: 301 302.. _`ESP32-DevKitC-WROVER`: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/hw-reference/esp32/get-started-devkitc.html# 303.. _`ESP32 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf 304.. _`ESP32 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf 305.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html 306.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases 307
