1.. zephyr:board:: rpi_pico 2 3Overview 4******** 5 6The Raspberry Pi Pico and Pico W are small, low-cost, versatile boards from 7Raspberry Pi. They are equipped with an RP2040 SoC, an on-board LED, 8a USB connector, and an SWD interface. The Pico W additionally contains an 9Infineon CYW43439 2.4 GHz Wi-Fi/Bluetooth module. The USB bootloader allows the 10ability to flash without any adapter, in a drag-and-drop manner. 11It is also possible to flash and debug the boards with their SWD interface, 12using an external adapter. 13 14Hardware 15******** 16- Dual core Arm Cortex-M0+ processor running up to 133MHz 17- 264KB on-chip SRAM 18- 2MB on-board QSPI flash with XIP capabilities 19- 26 GPIO pins 20- 3 Analog inputs 21- 2 UART peripherals 22- 2 SPI controllers 23- 2 I2C controllers 24- 16 PWM channels 25- USB 1.1 controller (host/device) 26- 8 Programmable I/O (PIO) for custom peripherals 27- On-board LED 28- 1 Watchdog timer peripheral 29- Infineon CYW43439 2.4 GHz Wi-Fi chip (Pico W only) 30 31 32.. figure:: img/rpi_pico.jpg 33 :align: center 34 :alt: Raspberry Pi Pico 35 36 37.. figure:: img/rpi_pico_w.jpg 38 :align: center 39 :alt: Raspberry Pi Pico W 40 41 Raspberry Pi Pico (above) and Pico W (below) 42 (Images courtesy of Raspberry Pi) 43 44Supported Features 45================== 46 47The rpi_pico board configuration supports the following 48hardware features: 49 50.. list-table:: 51 :header-rows: 1 52 53 * - Peripheral 54 - Kconfig option 55 - Devicetree compatible 56 * - NVIC 57 - N/A 58 - :dtcompatible:`arm,v6m-nvic` 59 * - UART 60 - :kconfig:option:`CONFIG_SERIAL` 61 - :dtcompatible:`raspberrypi,pico-uart` 62 * - GPIO 63 - :kconfig:option:`CONFIG_GPIO` 64 - :dtcompatible:`raspberrypi,pico-gpio` 65 * - ADC 66 - :kconfig:option:`CONFIG_ADC` 67 - :dtcompatible:`raspberrypi,pico-adc` 68 * - I2C 69 - :kconfig:option:`CONFIG_I2C` 70 - :dtcompatible:`snps,designware-i2c` 71 * - SPI 72 - :kconfig:option:`CONFIG_SPI` 73 - :dtcompatible:`raspberrypi,pico-spi` 74 * - USB Device 75 - :kconfig:option:`CONFIG_USB_DEVICE_STACK` 76 - :dtcompatible:`raspberrypi,pico-usbd` 77 * - HWINFO 78 - :kconfig:option:`CONFIG_HWINFO` 79 - N/A 80 * - Watchdog Timer (WDT) 81 - :kconfig:option:`CONFIG_WATCHDOG` 82 - :dtcompatible:`raspberrypi,pico-watchdog` 83 * - PWM 84 - :kconfig:option:`CONFIG_PWM` 85 - :dtcompatible:`raspberrypi,pico-pwm` 86 * - Flash 87 - :kconfig:option:`CONFIG_FLASH` 88 - :dtcompatible:`raspberrypi,pico-flash` 89 * - Clock controller 90 - :kconfig:option:`CONFIG_CLOCK_CONTROL` 91 - :dtcompatible:`raspberrypi,pico-clock-controller` 92 * - UART (PIO) 93 - :kconfig:option:`CONFIG_SERIAL` 94 - :dtcompatible:`raspberrypi,pico-uart-pio` 95 * - SPI (PIO) 96 - :kconfig:option:`CONFIG_SPI` 97 - :dtcompatible:`raspberrypi,pico-spi-pio` 98 99.. _rpi_pico_pin_mapping: 100 101Pin Mapping 102=========== 103 104The peripherals of the RP2040 SoC can be routed to various pins on the board. 105The configuration of these routes can be modified through DTS. Please refer to 106the datasheet to see the possible routings for each peripheral. 107 108External pin mapping on the Pico W is identical to the Pico, but note that internal 109RP2040 GPIO lines 23, 24, 25, and 29 are routed to the Infineon module on the W. 110Since GPIO 25 is routed to the on-board LED on the Pico, but to the Infineon module 111on the Pico W, the "blinky" sample program does not work on the W (use hello_world for 112a simple test program instead). 113 114Default Zephyr Peripheral Mapping: 115---------------------------------- 116 117.. rst-class:: rst-columns 118 119- UART0_TX : P0 120- UART0_RX : P1 121- I2C0_SDA : P4 122- I2C0_SCL : P5 123- I2C1_SDA : P6 124- I2C1_SCL : P7 125- SPI0_RX : P16 126- SPI0_CSN : P17 127- SPI0_SCK : P18 128- SPI0_TX : P19 129- ADC_CH0 : P26 130- ADC_CH1 : P27 131- ADC_CH2 : P28 132- ADC_CH3 : P29 133 134Programmable I/O (PIO) 135********************** 136The RP2040 SoC comes with two PIO periherals. These are two simple 137co-processors that are designed for I/O operations. The PIOs run 138a custom instruction set, generated from a custom assembly language. 139PIO programs are assembled using :command:`pioasm`, a tool provided by Raspberry Pi. 140 141Zephyr does not (currently) assemble PIO programs. Rather, they should be 142manually assembled and embedded in source code. An example of how this is done 143can be found at :zephyr_file:`drivers/serial/uart_rpi_pico_pio.c`. 144 145Sample: SPI via PIO 146==================== 147 148The :zephyr_file:`samples/sensor/bme280/README.rst` sample includes a 149demonstration of using the PIO SPI driver to communicate with an 150environmental sensor. The PIO SPI driver supports using any 151combination of GPIO pins for an SPI bus, as well as allowing up to 152four independent SPI buses on a single board (using the two SPI 153devices as well as both PIO devices). 154 155Programming and Debugging 156************************* 157 158System requirements 159=================== 160 161Prerequisites for the Pico W 162---------------------------- 163 164Building for the Raspberry Pi Pico W requires the AIROC binary blobs 165provided by Infineon. Run the command below to retrieve those files: 166 167.. code-block:: console 168 169 west blobs fetch hal_infineon 170 171.. note:: 172 173 It is recommended running the command above after :file:`west update`. 174 175Flashing 176======== 177 178Using SEGGER JLink 179------------------ 180 181You can Flash the rpi_pico with a SEGGER JLink debug probe as described in 182:ref:`Building, Flashing and Debugging <west-flashing>`. 183 184Here is an example of building and flashing the :zephyr:code-sample:`blinky` application. 185 186.. zephyr-app-commands:: 187 :zephyr-app: samples/basic/blinky 188 :board: rpi_pico 189 :goals: build 190 191.. code-block:: bash 192 193 west flash --runner jlink 194 195Using OpenOCD 196------------- 197 198To use CMSIS-DAP, You must configure **udev**. 199 200Create a file in /etc/udev.rules.d with any name, and write the line below. 201 202.. code-block:: bash 203 204 ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="000c", MODE="660", GROUP="plugdev", TAG+="uaccess" 205 206This example is valid for the case that the user joins to ``plugdev`` groups. 207 208The Raspberry Pi Pico has an SWD interface that can be used to program 209and debug the on board RP2040. This interface can be utilized by OpenOCD. 210To use it with the RP2040, OpenOCD version 0.12.0 or later is needed. 211 212If you are using a Debian based system (including RaspberryPi OS, Ubuntu. and more), 213using the `pico_setup.sh`_ script is a convenient way to set up the forked version of OpenOCD. 214 215Depending on the interface used (such as JLink), you might need to 216checkout to a branch that supports this interface, before proceeding. 217Build and install OpenOCD as described in the README. 218 219Here is an example of building and flashing the :zephyr:code-sample:`blinky` application. 220 221.. zephyr-app-commands:: 222 :zephyr-app: samples/basic/blinky 223 :board: rpi_pico 224 :goals: build flash 225 :gen-args: -DOPENOCD=/usr/local/bin/openocd -DOPENOCD_DEFAULT_PATH=/usr/local/share/openocd/scripts -DRPI_PICO_DEBUG_ADAPTER=cmsis-dap 226 227Set the environment variables **OPENOCD** to :file:`/usr/local/bin/openocd` 228and **OPENOCD_DEFAULT_PATH** to :file:`/usr/local/share/openocd/scripts`. This should work 229with the OpenOCD that was installed with the default configuration. 230This configuration also works with an environment that is set up by the `pico_setup.sh`_ script. 231 232**RPI_PICO_DEBUG_ADAPTER** specifies what debug adapter is used for debugging. 233 234If **RPI_PICO_DEBUG_ADAPTER** was not assigned, ``cmsis-dap`` is used by default. 235The other supported adapters are ``raspberrypi-swd``, ``jlink`` and ``blackmagicprobe``. 236How to connect ``cmsis-dap`` and ``raspberrypi-swd`` is described in `Getting Started with Raspberry Pi Pico`_. 237Any other SWD debug adapter maybe also work with this configuration. 238 239The value of **RPI_PICO_DEBUG_ADAPTER** is cached, so it can be omitted from 240``west flash`` and ``west debug`` if it was previously set while running 241``west build``. 242 243**RPI_PICO_DEBUG_ADAPTER** is used in an argument to OpenOCD as ``"source [find interface/${RPI_PICO_DEBUG_ADAPTER}.cfg]"``. 244Thus, **RPI_PICO_DEBUG_ADAPTER** needs to be assigned the file name of the debug adapter. 245 246You can also flash the board with the following 247command that directly calls OpenOCD (assuming a SEGGER JLink adapter is used): 248 249.. code-block:: console 250 251 $ openocd -f interface/jlink.cfg -c 'transport select swd' -f target/rp2040.cfg -c "adapter speed 2000" -c 'targets rp2040.core0' -c 'program path/to/zephyr.elf verify reset exit' 252 253Using UF2 254--------- 255 256If you don't have an SWD adapter, you can flash the Raspberry Pi Pico with 257a UF2 file. By default, building an app for this board will generate a 258:file:`build/zephyr/zephyr.uf2` file. If the Pico is powered on with the ``BOOTSEL`` 259button pressed, it will appear on the host as a mass storage device. The 260UF2 file should be drag-and-dropped to the device, which will flash the Pico. 261 262Debugging 263========= 264 265The SWD interface can also be used to debug the board. To achieve this, you can 266either use SEGGER JLink or OpenOCD. 267 268Using SEGGER JLink 269------------------ 270 271Use a SEGGER JLink debug probe and follow the instruction in 272:ref:`Building, Flashing and Debugging<west-debugging>`. 273 274 275Using OpenOCD 276------------- 277 278Install OpenOCD as described for flashing the board. 279 280Here is an example for debugging the :zephyr:code-sample:`blinky` application. 281 282.. zephyr-app-commands:: 283 :zephyr-app: samples/basic/blinky 284 :board: rpi_pico 285 :maybe-skip-config: 286 :goals: debug 287 :gen-args: -DOPENOCD=/usr/local/bin/openocd -DOPENOCD_DEFAULT_PATH=/usr/local/share/openocd/scripts -DRPI_PICO_DEBUG_ADAPTER=raspberrypi-swd 288 289As with flashing, you can specify the debug adapter by specifying **RPI_PICO_DEBUG_ADAPTER** 290at ``west build`` time. No needs to specify it at ``west debug`` time. 291 292You can also debug with OpenOCD and gdb launching from command-line. 293Run the following command: 294 295.. code-block:: console 296 297 $ openocd -f interface/jlink.cfg -c 'transport select swd' -f target/rp2040.cfg -c "adapter speed 2000" -c 'targets rp2040.core0' 298 299On another terminal, run: 300 301.. code-block:: console 302 303 $ gdb-multiarch 304 305Inside gdb, run: 306 307.. code-block:: console 308 309 (gdb) tar ext :3333 310 (gdb) file path/to/zephyr.elf 311 312You can then start debugging the board. 313 314.. target-notes:: 315 316.. _pico_setup.sh: 317 https://raw.githubusercontent.com/raspberrypi/pico-setup/master/pico_setup.sh 318 319.. _Getting Started with Raspberry Pi Pico: 320 https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf 321
