1.. _icev_wireless: 2 3ICE-V Wireless 4############## 5 6Overview 7******** 8 9The ICE-V Wireless is a combined ESP32C3 and iCE40 FPGA board. 10 11See the `ICE-V Wireless Github Project`_ for details. 12 13.. figure:: img/icev_wireless.jpg 14 :align: center 15 :alt: ICE-V Wireless 16 17 ICE-V Wireless 18 19Hardware 20******** 21 22This board combines an Espressif ESP32-C3-MINI-1 (which includes 4MB of flash in the module) with a 23Lattice iCE40UP5k-SG48 FPGA to allow WiFi and Bluetooth control of the FPGA. ESP32 and FPGA I/O is 24mostly uncommitted except for the pins used for SPI communication between ESP32 and FPGA. Several 25of the ESP32C3 GPIO pins are available for additonal interfaces such as serial, ADC, I2C, etc. 26 27For details on ESP32-C3 hardware please refer to the following resources: 28 29* `ESP32-C3-MINI-1 Datasheet`_ 30* `ESP32-C3 Datasheet`_ 31* `ESP32-C3 Technical Reference Manual`_ 32 33For details on iCE40 hardware please refer to the following resources: 34 35* `iCE40 UltraPlus Family Datasheet`_ 36 37Supported Features 38================== 39 40The ICE-V Wireless board configuration supports the following hardware 41features: 42 43+-----------+------------+------------------+ 44| Interface | Controller | Driver/Component | 45+===========+============+==================+ 46| PMP | on-chip | arch/riscv | 47+-----------+------------+------------------+ 48| INTMTRX | on-chip | intc_esp32c3 | 49+-----------+------------+------------------+ 50| PINMUX | on-chip | pinctrl_esp32 | 51+-----------+------------+------------------+ 52| USB UART | on-chip | serial_esp32_usb | 53+-----------+------------+------------------+ 54| GPIO | on-chip | gpio_esp32 | 55+-----------+------------+------------------+ 56| UART | on-chip | uart_esp32 | 57+-----------+------------+------------------+ 58| I2C | on-chip | i2c_esp32 | 59+-----------+------------+------------------+ 60| SPI | on-chip | spi_esp32_spim | 61+-----------+------------+------------------+ 62| ADC | on-chip | | 63+-----------+------------+------------------+ 64 65Other hardware features have not been enabled yet for this board. 66 67Connections and IOs 68=================== 69 70The ICE-V Wireless provides 1 row of reference, ESP32-C3, and iCE40 signals 71brought out to J3, as well as 3 PMOD connectors for interfacing directly to 72the iCE40 FPGA. Note that several of the iCE40 pins brought out to the PMOD 73connectors are capable of operating as differential pairs. 74 75.. figure:: img/icev_wireless_back.jpg 76 :align: center 77 :alt: ICE-V Wireless (Back) 78 79 ICE-V Wireless (Back) 80 81The J3 pins are 4V, 3.3V, NRST, GPIO2, GPIO3, GPIO8, GPIO9, GPIO10, GPIO20, 82GPIO21, FPGA_P34, and GND. Note that GPIO2 and GPIO3 may be configured for 83ADC operation. 84 85For PMOD details, please refer to the `PMOD Specification`_ and the image 86below. 87 88.. figure:: img/icev_wireless_pinout.jpg 89 :align: center 90 :alt: ICE-V Wireless Pinout 91 92Programming and Debugging 93************************* 94 95Programming and debugging for the ICE-V Wireless ESP32-C3 target is 96incredibly easy �� following the steps below. 97 98Building and Flashing 99********************* 100 101ESP-IDF bootloader 102================== 103 104The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. 105It is build as a subproject at each application build. No further attention 106is expected from the user. 107 108MCUboot bootloader 109================== 110 111User may choose to use MCUboot bootloader instead. In that case the bootloader 112must be build (and flash) at least once. 113 114There are two options to be used when building an application: 115 1161. Sysbuild 1172. Manual build 118 119.. note:: 120 121 User can select the MCUboot bootloader by adding the following line 122 to the board default configuration file. 123 ``` 124 CONFIG_BOOTLOADER_MCUBOOT=y 125 ``` 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 :app: samples/hello_world 138 :board: icev_wireless 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 build 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 182For the :code:`Hello, world!` application, follow the instructions below. 183 184.. zephyr-app-commands:: 185 :zephyr-app: samples/hello_world 186 :board: icev_wireless 187 :goals: build flash 188 189Open the serial monitor using the following command: 190 191.. code-block:: console 192 193 $ west espressif monitor 194 195After the board has automatically reset and booted, you should see the following 196message in the monitor: 197 198.. code-block:: console 199 200 ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** 201 Hello World! icev_wireless 202 203Debugging 204********* 205 206As with much custom hardware, the ESP32C3 modules require patches to 207OpenOCD that are not upstreamed. Espressif maintains their own fork of 208the project. The custom OpenOCD can be obtained by running the following extension: 209 210.. code-block:: console 211 212 west espressif install 213 214.. note:: 215 216 By default, the OpenOCD will be downloaded and installed under $HOME/.espressif/tools/zephyr directory 217 (%USERPROFILE%/.espressif/tools/zephyr on Windows). 218 219The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the 220``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>`` 221parameter when building. 222 223Here is an example for building the :ref:`hello_world` application. 224 225.. zephyr-app-commands:: 226 :zephyr-app: samples/hello_world 227 :board: icev_wireless 228 :goals: build flash 229 :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts> 230 231You can debug an application in the usual way. Here is an example for the 232:ref:`hello_world` application. 233 234.. zephyr-app-commands:: 235 :zephyr-app: samples/hello_world 236 :board: icev_wireless 237 :maybe-skip-config: 238 :goals: debug 239 240References 241********** 242 243.. _ICE-V Wireless Github Project: 244 https://github.com/ICE-V-Wireless/ICE-V-Wireless 245 246.. _ESP32-C3-MINI-1 Datasheet: 247 https://www.espressif.com/sites/default/files/documentation/esp32-c3-mini-1_datasheet_en.pdf 248 249.. _ESP32-C3 Datasheet: 250 https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf 251 252.. _ESP32-C3 Technical Reference Manual: 253 https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf 254 255.. _iCE40 UltraPlus Family Datasheet: 256 https://www.latticesemi.com/-/media/LatticeSemi/Documents/DataSheets/iCE/iCE40-UltraPlus-Family-Data-Sheet.ashx 257 258.. _PMOD Specification: 259 https://digilent.com/reference/_media/reference/pmod/pmod-interface-specification-1_2_0.pdf 260
