1.. zephyr:board:: adafruit_qt_py_esp32s3 2 3Overview 4******** 5 6An Adafruit based Xiao compatible board based on the ESP32-S3, which is great 7for IoT projects and prototyping with new sensors. 8 9For more details see the `Adafruit QT Py ESP32S3`_ product page. 10 11Hardware 12******** 13 14This board comes in 2 variants, both based on the ESP32-S3 with WiFi and BLE 15support. The default variant supporting 8MB of flash with no PSRAM, while the 16``psram`` variant supporting 4MB of flash with 2MB of PSRAM. Both boards have a 17USB-C port for programming and debugging and is based on a standard XIAO 14 18pin pinout. 19 20In addition to the Xiao compatible pinout, it also has a RGB NeoPixel for 21status and debugging, a reset button, and a button for entering the ROM 22bootloader or user input. Like many other Adafruit boards, it has a 23`SparkFun Qwiic`_-compatible `STEMMA QT`_ connector for the I2C bus so you 24don't even need to solder. 25 26ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated 272.4 GHz Wi-Fi and Bluetooth® Low Energy (Bluetooth LE). It consists of 28high-performance dual-core microprocessor (Xtensa® 32-bit LX7), a low power 29coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband, RF module, and 30numerous peripherals. 31 32Supported Features 33================== 34 35Current Zephyr's Adafruit QT Py ESP32-S3 board supports the following features: 36 37+------------+------------+-------------------------------------+ 38| Interface | Controller | Driver/Component | 39+============+============+=====================================+ 40| UART | on-chip | serial port | 41+------------+------------+-------------------------------------+ 42| GPIO | on-chip | gpio | 43+------------+------------+-------------------------------------+ 44| PINMUX | on-chip | pinmux | 45+------------+------------+-------------------------------------+ 46| USB-JTAG | on-chip | hardware interface | 47+------------+------------+-------------------------------------+ 48| SPI Master | on-chip | spi | 49+------------+------------+-------------------------------------+ 50| I2C | on-chip | i2c | 51+------------+------------+-------------------------------------+ 52| I2S | on-chip | i2s | 53+------------+------------+-------------------------------------+ 54| TWAI/CAN | on-chip | can | 55+------------+------------+-------------------------------------+ 56| ADC | on-chip | adc | 57+------------+------------+-------------------------------------+ 58| Timers | on-chip | counter | 59+------------+------------+-------------------------------------+ 60| Watchdog | on-chip | watchdog | 61+------------+------------+-------------------------------------+ 62| TRNG | on-chip | entropy | 63+------------+------------+-------------------------------------+ 64| LEDC | on-chip | pwm | 65+------------+------------+-------------------------------------+ 66| MCPWM | on-chip | pwm | 67+------------+------------+-------------------------------------+ 68| PCNT | on-chip | qdec | 69+------------+------------+-------------------------------------+ 70| GDMA | on-chip | dma | 71+------------+------------+-------------------------------------+ 72| Wi-Fi | on-chip | | 73+------------+------------+-------------------------------------+ 74| Bluetooth | on-chip | | 75+------------+------------+-------------------------------------+ 76 77Prerequisites 78------------- 79 80Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the 81command below to retrieve those files. 82 83.. code-block:: console 84 85 west blobs fetch hal_espressif 86 87.. note:: 88 89 It is recommended running the command above after :file:`west update`. 90 91Building & Flashing 92******************* 93 94Simple boot 95=========== 96 97The board could be loaded using the single binary image, without 2nd stage 98bootloader. It is the default option when building the application without 99additional configuration. 100 101.. note:: 102 103 Simple boot does not provide any security features nor OTA updates. 104 105MCUboot bootloader 106================== 107 108User may choose to use MCUboot bootloader instead. In that case the bootloader 109must be built (and flashed) at least once. 110 111There are two options to be used when building an application: 112 1131. Sysbuild 1142. Manual build 115 116.. note:: 117 118 User can select the MCUboot bootloader by adding the following line 119 to the board default configuration file. 120 121 .. code:: cfg 122 123 CONFIG_BOOTLOADER_MCUBOOT=y 124 125Sysbuild 126======== 127 128The sysbuild makes possible to build and flash all necessary images needed to 129bootstrap the board with the ESP32 SoC. 130 131To build the sample application using sysbuild use the command: 132 133.. zephyr-app-commands:: 134 :tool: west 135 :zephyr-app: samples/hello_world 136 :board: adafruit_qt_py_esp32s3 137 :goals: build 138 :west-args: --sysbuild 139 :compact: 140 141By default, the ESP32 sysbuild creates bootloader (MCUboot) and application 142images. But it can be configured to create other kind of images. 143 144Build directory structure created by sysbuild is different from traditional 145Zephyr build. Output is structured by the domain subdirectories: 146 147.. code-block:: 148 149 build/ 150 ├── hello_world 151 │ └── zephyr 152 │ ├── zephyr.elf 153 │ └── zephyr.bin 154 ├── mcuboot 155 │ └── zephyr 156 │ ├── zephyr.elf 157 │ └── zephyr.bin 158 └── domains.yaml 159 160.. note:: 161 162 With ``--sysbuild`` option the bootloader will be re-build and re-flash 163 every time the pristine build is used. 164 165For more information about the system build please read the :ref:`sysbuild` documentation. 166 167Manual build 168============ 169 170During the development cycle, it is intended to build & flash as quickly possible. 171For that reason, images can be built one at a time using traditional build. 172 173The instructions following are relevant for both manual build and sysbuild. 174The only difference is the structure of the build directory. 175 176.. note:: 177 178 Remember that bootloader (MCUboot) needs to be flash at least once. 179 180Build and flash applications as usual (see :ref:`build_an_application` and 181:ref:`application_run` for more details). 182 183.. tabs:: 184 185 .. group-tab:: QT Py ESP32S3 186 187 .. zephyr-app-commands:: 188 :zephyr-app: samples/hello_world 189 :board: adafruit_qt_py_esp32s3/esp32s3/procpu 190 :goals: build 191 192 .. group-tab:: QT Py ESP32S3 with PSRAM 193 194 .. zephyr-app-commands:: 195 :zephyr-app: samples/hello_world 196 :board: adafruit_qt_py_esp32s3@psram/esp32s3/procpu 197 :goals: build 198 199The usual ``flash`` target will work with the ``adafruit_qt_py_esp32s3`` board 200configuration. Here is an example for the :zephyr:code-sample:`hello_world` 201application. 202 203.. tabs:: 204 205 .. group-tab:: QT Py ESP32S3 206 207 .. zephyr-app-commands:: 208 :zephyr-app: samples/hello_world 209 :board: adafruit_qt_py_esp32s3/esp32s3/procpu 210 :goals: flash 211 212 .. group-tab:: QT Py ESP32S3 with PSRAM 213 214 .. zephyr-app-commands:: 215 :zephyr-app: samples/hello_world 216 :board: adafruit_qt_py_esp32s3@psram/esp32s3/procpu 217 :goals: flash 218 219Open the serial monitor using the following command: 220 221.. code-block:: shell 222 223 west espressif monitor 224 225After the board has automatically reset and booted, you should see the following 226message in the monitor: 227 228.. code-block:: console 229 230 ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** 231 Hello World! adafruit_qt_py_esp32s3/esp32s3/procpu 232 233Debugging 234********* 235 236ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_. 237 238ESP32-S3 has a built-in JTAG circuitry and can be debugged without any 239additional chip. Only an USB cable connected to the D+/D- pins is necessary. 240 241Further documentation can be obtained from the SoC vendor 242in `JTAG debugging for ESP32-S3`_. 243 244Here is an example for building the :zephyr:code-sample:`hello_world` application. 245 246.. tabs:: 247 248 .. group-tab:: QT Py ESP32S3 249 250 .. zephyr-app-commands:: 251 :zephyr-app: samples/hello_world 252 :board: adafruit_qt_py_esp32s3/esp32s3/procpu 253 :goals: debug 254 255 .. group-tab:: QT Py ESP32S3 with PSRAM 256 257 .. zephyr-app-commands:: 258 :zephyr-app: samples/hello_world 259 :board: adafruit_qt_py_esp32s3@psram/esp32s3/procpu 260 :goals: debug 261 262You can debug an application in the usual way. Here is an example for 263the :zephyr:code-sample:`hello_world` application. 264 265.. tabs:: 266 267 .. group-tab:: QT Py ESP32S3 268 269 .. zephyr-app-commands:: 270 :zephyr-app: samples/hello_world 271 :board: adafruit_qt_py_esp32s3/esp32s3/procpu 272 :goals: debug 273 274 .. group-tab:: QT Py ESP32S3 with PSRAM 275 276 .. zephyr-app-commands:: 277 :zephyr-app: samples/hello_world 278 :board: adafruit_qt_py_esp32s3@psram/esp32s3/procpu 279 :goals: debug 280 281References 282********** 283 284.. target-notes:: 285 286.. _`Adafruit QT Py ESP32S3`: https://www.adafruit.com/product/5426 287.. _`Adafruit QT Py ESP32S3 - PSRAM`: https://www.adafruit.com/product/5700 288.. _`JTAG debugging for ESP32-S3`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/ 289.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases 290.. _`SparkFun Qwiic`: https://www.sparkfun.com/qwiic 291.. _`STEMMA QT`: https://learn.adafruit.com/introducing-adafruit-stemma-qt 292
