1.. zephyr:board:: icev_wireless 2 3Overview 4******** 5 6The ICE-V Wireless is a combined ESP32C3 and iCE40 FPGA board. 7 8See the `ICE-V Wireless Github Project`_ for details. 9 10Hardware 11******** 12 13This board combines an Espressif ESP32-C3-MINI-1 (which includes 4MB of flash in the module) with a 14Lattice iCE40UP5k-SG48 FPGA to allow WiFi and Bluetooth control of the FPGA. ESP32 and FPGA I/O is 15mostly uncommitted except for the pins used for SPI communication between ESP32 and FPGA. Several 16of the ESP32C3 GPIO pins are available for additonal interfaces such as serial, ADC, I2C, etc. 17 18For details on ESP32-C3 hardware please refer to the following resources: 19 20* `ESP32-C3-MINI-1 Datasheet`_ 21* `ESP32-C3 Datasheet`_ 22* `ESP32-C3 Technical Reference Manual`_ 23 24For details on iCE40 hardware please refer to the following resources: 25 26* `iCE40 UltraPlus Family Datasheet`_ 27 28Supported Features 29================== 30 31The ICE-V Wireless board configuration supports the following hardware 32features: 33 34+-----------+------------+------------------+ 35| Interface | Controller | Driver/Component | 36+===========+============+==================+ 37| PMP | on-chip | arch/riscv | 38+-----------+------------+------------------+ 39| INTMTRX | on-chip | intc_esp32c3 | 40+-----------+------------+------------------+ 41| PINMUX | on-chip | pinctrl_esp32 | 42+-----------+------------+------------------+ 43| USB UART | on-chip | serial_esp32_usb | 44+-----------+------------+------------------+ 45| GPIO | on-chip | gpio_esp32 | 46+-----------+------------+------------------+ 47| UART | on-chip | uart_esp32 | 48+-----------+------------+------------------+ 49| I2C | on-chip | i2c_esp32 | 50+-----------+------------+------------------+ 51| SPI | on-chip | spi_esp32_spim | 52+-----------+------------+------------------+ 53| ADC | on-chip | | 54+-----------+------------+------------------+ 55 56Other hardware features have not been enabled yet for this board. 57 58Connections and IOs 59=================== 60 61The ICE-V Wireless provides 1 row of reference, ESP32-C3, and iCE40 signals 62brought out to J3, as well as 3 PMOD connectors for interfacing directly to 63the iCE40 FPGA. Note that several of the iCE40 pins brought out to the PMOD 64connectors are capable of operating as differential pairs. 65 66.. figure:: img/icev_wireless_back.jpg 67 :align: center 68 :alt: ICE-V Wireless (Back) 69 70 ICE-V Wireless (Back) 71 72The J3 pins are 4V, 3.3V, NRST, GPIO2, GPIO3, GPIO8, GPIO9, GPIO10, GPIO20, 73GPIO21, FPGA_P34, and GND. Note that GPIO2 and GPIO3 may be configured for 74ADC operation. 75 76For PMOD details, please refer to the `PMOD Specification`_ and the image 77below. 78 79.. figure:: img/icev_wireless_pinout.jpg 80 :align: center 81 :alt: ICE-V Wireless Pinout 82 83Programming and Debugging 84************************* 85 86Programming and debugging for the ICE-V Wireless ESP32-C3 target is 87incredibly easy �� following the steps below. 88 89Building and Flashing 90********************* 91 92Simple boot 93=========== 94 95The board could be loaded using the single binary image, without 2nd stage bootloader. 96It is the default option when building the application without additional configuration. 97 98.. note:: 99 100 Simple boot does not provide any security features nor OTA updates. 101 102MCUboot bootloader 103================== 104 105User may choose to use MCUboot bootloader instead. In that case the bootloader 106must be built (and flashed) at least once. 107 108There are two options to be used when building an application: 109 1101. Sysbuild 1112. Manual build 112 113.. note:: 114 115 User can select the MCUboot bootloader by adding the following line 116 to the board default configuration file. 117 118 .. code:: cfg 119 120 CONFIG_BOOTLOADER_MCUBOOT=y 121 122Sysbuild 123======== 124 125The sysbuild makes possible to build and flash all necessary images needed to 126bootstrap the board with the ESP32 SoC. 127 128To build the sample application using sysbuild use the command: 129 130.. zephyr-app-commands:: 131 :tool: west 132 :zephyr-app: samples/hello_world 133 :board: icev_wireless 134 :goals: build 135 :west-args: --sysbuild 136 :compact: 137 138By default, the ESP32 sysbuild creates bootloader (MCUboot) and application 139images. But it can be configured to create other kind of images. 140 141Build directory structure created by sysbuild is different from traditional 142Zephyr build. Output is structured by the domain subdirectories: 143 144.. code-block:: 145 146 build/ 147 ├── hello_world 148 │ └── zephyr 149 │ ├── zephyr.elf 150 │ └── zephyr.bin 151 ├── mcuboot 152 │ └── zephyr 153 │ ├── zephyr.elf 154 │ └── zephyr.bin 155 └── domains.yaml 156 157.. note:: 158 159 With ``--sysbuild`` option the bootloader will be re-build and re-flash 160 every time the pristine build is used. 161 162For more information about the system build please read the :ref:`sysbuild` documentation. 163 164Manual build 165============ 166 167During the development cycle, it is intended to build & flash as quickly possible. 168For that reason, images can be built one at a time using traditional build. 169 170The instructions following are relevant for both manual build and sysbuild. 171The only difference is the structure of the build directory. 172 173.. note:: 174 175 Remember that bootloader (MCUboot) needs to be flash at least once. 176 177For the :code:`Hello, world!` application, follow the instructions below. 178 179.. zephyr-app-commands:: 180 :zephyr-app: samples/hello_world 181 :board: icev_wireless 182 :goals: build flash 183 184Open the serial monitor using the following command: 185 186.. code-block:: console 187 188 $ west espressif monitor 189 190After the board has automatically reset and booted, you should see the following 191message in the monitor: 192 193.. code-block:: console 194 195 ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** 196 Hello World! icev_wireless 197 198Debugging 199********* 200 201As with much custom hardware, the ESP32C3 modules require patches to 202OpenOCD that are not upstreamed. Espressif maintains their own fork of 203the project. The custom OpenOCD can be obtained by running the following extension: 204 205.. code-block:: console 206 207 west espressif install 208 209.. note:: 210 211 By default, the OpenOCD will be downloaded and installed under $HOME/.espressif/tools/zephyr directory 212 (%USERPROFILE%/.espressif/tools/zephyr on Windows). 213 214The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the 215``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>`` 216parameter when building. 217 218Here is an example for building the :zephyr:code-sample:`hello_world` application. 219 220.. zephyr-app-commands:: 221 :zephyr-app: samples/hello_world 222 :board: icev_wireless 223 :goals: build flash 224 :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts> 225 226You can debug an application in the usual way. Here is an example for the 227:zephyr:code-sample:`hello_world` application. 228 229.. zephyr-app-commands:: 230 :zephyr-app: samples/hello_world 231 :board: icev_wireless 232 :maybe-skip-config: 233 :goals: debug 234 235References 236********** 237 238.. target-notes:: 239 240.. _ICE-V Wireless Github Project: 241 https://github.com/ICE-V-Wireless/ICE-V-Wireless 242 243.. _ESP32-C3-MINI-1 Datasheet: 244 https://www.espressif.com/sites/default/files/documentation/esp32-c3-mini-1_datasheet_en.pdf 245 246.. _ESP32-C3 Datasheet: 247 https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf 248 249.. _ESP32-C3 Technical Reference Manual: 250 https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf 251 252.. _iCE40 UltraPlus Family Datasheet: 253 https://www.latticesemi.com/-/media/LatticeSemi/Documents/DataSheets/iCE/iCE40-UltraPlus-Family-Data-Sheet.ashx 254 255.. _PMOD Specification: 256 https://digilent.com/reference/_media/reference/pmod/pmod-interface-specification-1_2_0.pdf 257
