1.. zephyr:board:: esp8684_devkitm 2 3Overview 4******** 5 6The ESP8684-DevKitM is an entry-level development board based on ESP8684-MINI-1, a general-purpose 7module with 1 MB/2 MB/4 MB SPI flash. This board integrates complete Wi-Fi and Bluetooth LE functions. 8For more information, check `ESP8684-DevKitM User Guide`_ 9 10Hardware 11******** 12 13ESP32-C2 (ESP8684 core) is a low-cost, Wi-Fi 4 & Bluetooth 5 (LE) chip. Its unique design 14makes the chip smaller and yet more powerful than ESP8266. ESP32-C2 is built around a RISC-V 1532-bit, single-core processor, with 272 KB of SRAM (16 KB dedicated to cache) and 576 KB of ROM. 16ESP32-C2 has been designed to target simple, high-volume, and low-data-rate IoT applications, 17such as smart plugs and smart light bulbs. ESP32-C2 offers easy and robust wireless connectivity, 18which makes it the go-to solution for developing simple, user-friendly and reliable 19smart-home devices. For more information, check `ESP8684 Datasheet`_. 20 21Features include the following: 22 23- 32-bit core RISC-V microcontroller with a maximum clock speed of 120 MHz 24- 2 MB or 4 MB in chip (ESP8684) or in package (ESP32-C2) flash 25- 272 KB of internal RAM 26- 802.11b/g/n 27- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh 28- Various peripherals: 29 30 - 14 programmable GPIOs 31 - 3 SPI 32 - 2 UART 33 - 1 I2C Master 34 - LED PWM controller, with up to 6 channels 35 - General DMA controller (GDMA) 36 - 1 12-bit SAR ADC, up to 5 channels 37 - 1 temperature sensor 38 - 1 54-bit general-purpose timer 39 - 2 watchdog timers 40 - 1 52-bit system timer 41 42- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES) 43 44For detailed information check `ESP8684 Technical Reference Manual`_. 45 46Supported Features 47================== 48 49Current Zephyr's ESP8684-DevKitM board supports the following features: 50 51+------------+------------+-------------------------------------+ 52| Interface | Controller | Driver/Component | 53+============+============+=====================================+ 54| UART | on-chip | serial port | 55+------------+------------+-------------------------------------+ 56| GPIO | on-chip | gpio | 57+------------+------------+-------------------------------------+ 58| PINMUX | on-chip | pinmux | 59+------------+------------+-------------------------------------+ 60| Watchdog | on-chip | watchdog | 61+------------+------------+-------------------------------------+ 62| TRNG | on-chip | entropy | 63+------------+------------+-------------------------------------+ 64| Timers | on-chip | counter | 65+------------+------------+-------------------------------------+ 66| Wi-Fi | on-chip | | 67+------------+------------+-------------------------------------+ 68| LEDC | on-chip | pwm | 69+------------+------------+-------------------------------------+ 70| SPI Master | on-chip | spi | 71+------------+------------+-------------------------------------+ 72| SPI DMA | on-chip | spi | 73+------------+------------+-------------------------------------+ 74 75For a getting started user guide, please check `ESP8684-DevKitM User Guide`_. 76 77System requirements 78******************* 79 80Prerequisites 81============= 82 83Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command 84below to retrieve those files. 85 86.. code-block:: console 87 88 west blobs fetch hal_espressif 89 90.. note:: 91 92 It is recommended running the command above after :file:`west update`. 93 94Building & Flashing 95******************* 96 97Simple boot 98=========== 99 100The board could be loaded using the single binary image, without 2nd stage bootloader. 101It is the default option when building the application without additional configuration. 102 103.. note:: 104 105 Simple boot does not provide any security features nor OTA updates. 106 107MCUboot bootloader 108================== 109 110User may choose to use MCUboot bootloader instead. In that case the bootloader 111must be built (and flashed) at least once. 112 113There are two options to be used when building an application: 114 1151. Sysbuild 1162. Manual build 117 118.. note:: 119 120 User can select the MCUboot bootloader by adding the following line 121 to the board default configuration file. 122 123 .. code:: cfg 124 125 CONFIG_BOOTLOADER_MCUBOOT=y 126 127Sysbuild 128======== 129 130The sysbuild makes possible to build and flash all necessary images needed to 131bootstrap the board with the ESP32 SoC. 132 133To build the sample application using sysbuild use the command: 134 135.. zephyr-app-commands:: 136 :tool: west 137 :zephyr-app: samples/hello_world 138 :board: esp8684_devkitm 139 :goals: build 140 :west-args: --sysbuild 141 :compact: 142 143By default, the ESP32 sysbuild creates bootloader (MCUboot) and application 144images. But it can be configured to create other kind of images. 145 146Build directory structure created by sysbuild is different from traditional 147Zephyr build. Output is structured by the domain subdirectories: 148 149.. code-block:: 150 151 build/ 152 ├── hello_world 153 │ └── zephyr 154 │ ├── zephyr.elf 155 │ └── zephyr.bin 156 ├── mcuboot 157 │ └── zephyr 158 │ ├── zephyr.elf 159 │ └── zephyr.bin 160 └── domains.yaml 161 162.. note:: 163 164 With ``--sysbuild`` option the bootloader will be re-build and re-flash 165 every time the pristine build is used. 166 167For more information about the system build please read the :ref:`sysbuild` documentation. 168 169Manual build 170============ 171 172During the development cycle, it is intended to build & flash as quickly possible. 173For that reason, images can be built one at a time using traditional build. 174 175The instructions following are relevant for both manual build and sysbuild. 176The only difference is the structure of the build directory. 177 178.. note:: 179 180 Remember that bootloader (MCUboot) needs to be flash at least once. 181 182Build and flash applications as usual (see :ref:`build_an_application` and 183:ref:`application_run` for more details). 184 185.. zephyr-app-commands:: 186 :zephyr-app: samples/hello_world 187 :board: esp8684_devkitm 188 :goals: build 189 190The usual ``flash`` target will work with the ``esp8684_devkitm`` board 191configuration. Here is an example for the :zephyr:code-sample:`hello_world` 192application. 193 194.. zephyr-app-commands:: 195 :zephyr-app: samples/hello_world 196 :board: esp8684_devkitm 197 :goals: flash 198 199Open the serial monitor using the following command: 200 201.. code-block:: shell 202 203 west espressif monitor 204 205After the board has automatically reset and booted, you should see the following 206message in the monitor: 207 208.. code-block:: console 209 210 ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** 211 Hello World! esp8684_devkitm 212 213Debugging 214********* 215 216As with much custom hardware, the ESP8684 modules require patches to 217OpenOCD that are not upstreamed yet. Espressif maintains their own fork of 218the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_. 219 220The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the 221``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>`` 222parameter when building. 223 224Here is an example for building the :zephyr:code-sample:`hello_world` application. 225 226.. zephyr-app-commands:: 227 :zephyr-app: samples/hello_world 228 :board: esp8684_devkitm 229 :goals: build flash 230 :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts> 231 232You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. 233 234.. zephyr-app-commands:: 235 :zephyr-app: samples/hello_world 236 :board: esp8684_devkitm 237 :goals: debug 238 239References 240********** 241 242.. target-notes:: 243 244.. _`ESP8684-DevKitM User Guide`: https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp8684/esp8684-devkitm-1/user_guide.html 245.. _`ESP8684 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp8684_datasheet_en.pdf 246.. _`ESP8684 Technical Reference Manual`: https://www.espressif.com/sites/default/files/documentation/esp8684_technical_reference_manual_en.pdf 247.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases 248
