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 <RP2040_Datasheet>`_ SoC, an on-board LED,
8a USB connector, and an SWD interface.
9
10The Pico W additionally contains an `Infineon CYW43439`_ 2.4 GHz Wi-Fi/Bluetooth module.
11
12The USB bootloader allows the ability to flash without any adapter,
13in a drag-and-drop manner.
14It is also possible to flash and debug the boards with their SWD interface,
15using an external adapter.
16
17Hardware
18********
19
20- Dual core Arm Cortex-M0+ processor running up to 133MHz
21- 264KB on-chip SRAM
22- 2MB on-board QSPI flash with XIP capabilities
23- 26 GPIO pins
24- 3 Analog inputs
25- 2 UART peripherals
26- 2 SPI controllers
27- 2 I2C controllers
28- 16 PWM channels
29- USB 1.1 controller (host/device)
30- 8 Programmable I/O (PIO) for custom peripherals
31- On-board LED
32- 1 Watchdog timer peripheral
33- Infineon CYW43439 2.4 GHz Wi-Fi chip (Pico W only)
34
35
36.. figure:: img/rpi_pico.jpg
37     :align: center
38     :alt: Raspberry Pi Pico
39
40
41.. figure:: img/rpi_pico_w.jpg
42     :align: center
43     :alt: Raspberry Pi Pico W
44
45     Raspberry Pi Pico (above) and Pico W (below)
46     (Images courtesy of Raspberry Pi)
47
48Supported Features
49==================
50
51.. zephyr:board-supported-hw::
52
53.. _rpi_pico_pin_mapping:
54
55Pin Mapping
56===========
57
58The peripherals of the RP2040 SoC can be routed to various pins on the board.
59The configuration of these routes can be modified through DTS. Please refer to
60the datasheet to see the possible routings for each peripheral.
61
62External pin mapping on the Pico W is identical to the Pico, but note that internal
63RP2040 GPIO lines 23, 24, 25, and 29 are routed to the Infineon module on the W.
64Since GPIO 25 is routed to the on-board LED on the Pico, but to the Infineon module
65on the Pico W, the "blinky" sample program does not work on the W (use hello_world for
66a simple test program instead).
67
68Default Zephyr Peripheral Mapping:
69----------------------------------
70
71.. rst-class:: rst-columns
72
73- UART0_TX : P0
74- UART0_RX : P1
75- I2C0_SDA : P4
76- I2C0_SCL : P5
77- I2C1_SDA : P6
78- I2C1_SCL : P7
79- SPI0_RX : P16
80- SPI0_CSN : P17
81- SPI0_SCK : P18
82- SPI0_TX : P19
83- ADC_CH0 : P26
84- ADC_CH1 : P27
85- ADC_CH2 : P28
86- ADC_CH3 : P29
87
88Programmable I/O (PIO)
89**********************
90
91The RP2040 SoC comes with two PIO peripherals. These are two simple
92co-processors that are designed for I/O operations. The PIOs run
93a custom instruction set, generated from a custom assembly language.
94PIO programs are assembled using :command:`pioasm`, a tool provided by Raspberry Pi.
95
96Zephyr does not (currently) assemble PIO programs. Rather, they should be
97manually assembled and embedded in source code. An example of how this is done
98can be found at :zephyr_file:`drivers/serial/uart_rpi_pico_pio.c`.
99
100Sample:  SPI via PIO
101====================
102
103The :zephyr_file:`samples/sensor/bme280/README.rst` sample includes a
104demonstration of using the PIO SPI driver to communicate with an
105environmental sensor.  The PIO SPI driver supports using any
106combination of GPIO pins for an SPI bus, as well as allowing up to
107four independent SPI buses on a single board (using the two SPI
108devices as well as both PIO devices).
109
110.. _rpi_pico_pio_based_features:
111
112PIO Based Features
113==================
114
115Raspberry Pi Pico's PIO is a programmable chip that can implement a variety of peripherals.
116
117.. list-table::
118   :header-rows: 1
119
120   * - Peripheral
121     - Kconfig option
122     - Devicetree compatible
123   * - UART (PIO)
124     - :kconfig:option:`CONFIG_SERIAL`
125     - :dtcompatible:`raspberrypi,pico-uart-pio`
126   * - SPI (PIO)
127     - :kconfig:option:`CONFIG_SPI`
128     - :dtcompatible:`raspberrypi,pico-spi-pio`
129   * - WS2812 (PIO)
130     - :kconfig:option:`CONFIG_LED_STRIP`
131     - :dtcompatible:`worldsemi,ws2812-rpi_pico-pio`
132
133Programming and Debugging
134*************************
135
136Applications for the ``rpi_pico`` board configuration can be built and
137flashed in the usual way (see :ref:`build_an_application` and
138:ref:`application_run` for more details).
139
140System requirements
141===================
142
143Prerequisites for the Pico W
144----------------------------
145
146Building for the Raspberry Pi Pico W requires the AIROC binary blobs
147provided by Infineon. Run the command below to retrieve those files:
148
149.. code-block:: console
150
151   west blobs fetch hal_infineon
152
153.. note::
154
155   It is recommended running the command above after :file:`west update`.
156
157Debug Probe and Host Tools
158--------------------------
159
160Several debugging tools support the Raspberry Pi Pico.
161The `Raspberry Pi Debug Probe`_ is an easy-to-obtain CMSIS-DAP adapter
162officially provided by the Raspberry Pi Foundation,
163making it a convenient choice for debugging ``rpi_pico``.
164
165It can be used with
166
167- :ref:`openocd-debug-host-tools`
168- :ref:`pyocd-debug-host-tools`
169
170OpenOCD is the default for ``rpi_pico``.
171
172- `SEGGER J-Link`_
173- `Black Magic Debug Probe <Black Magic Debug>`_
174
175can also be used.
176These are used with dedicated probes.
177
178Flashing
179========
180
181The ``rpi_pico`` can flash with Zephyr's standard method.
182See also :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:: console
192
193  west flash --runner jlink
194
195
196.. _rpi_pico_flashing_using_openocd:
197
198Using OpenOCD
199-------------
200
201To use a debugging adapter such as the Raspberry Pi Debug Probe,
202You must configure **udev**. Refer to :ref:`setting-udev-rules` for details.
203
204The Raspberry Pi Pico has an SWD interface that can be used to program
205and debug the onboard SoC. This interface can be used with OpenOCD.
206To use it, OpenOCD version 0.12.0 or later is needed.
207
208If you are using a Debian based system (including RaspberryPi OS, Ubuntu. and more),
209using the `pico_setup.sh`_ script is a convenient way to set up the forked version of OpenOCD.
210
211Here is an example of building and flashing the :zephyr:code-sample:`blinky` application.
212
213.. zephyr-app-commands::
214   :zephyr-app: samples/basic/blinky
215   :board: rpi_pico
216   :goals: build flash
217   :gen-args: -DOPENOCD=/usr/local/bin/openocd -DRPI_PICO_DEBUG_ADAPTER=cmsis-dap
218
219Set the CMake option **OPENOCD** to :file:`/usr/local/bin/openocd`. This should work
220with the OpenOCD that was installed with the default configuration.
221This configuration also works with an environment that is set up by the `pico_setup.sh`_ script.
222
223**RPI_PICO_DEBUG_ADAPTER** specifies what debug adapter is used for debugging.
224
225If **RPI_PICO_DEBUG_ADAPTER** was not set, ``cmsis-dap`` is used by default.
226The ``raspberrypi-swd`` and ``jlink`` are verified to work.
227How to connect ``cmsis-dap`` and ``raspberrypi-swd`` is described in `Getting Started with Raspberry Pi Pico`_.
228Any other SWD debug adapter maybe also work with this configuration.
229
230The value of **RPI_PICO_DEBUG_ADAPTER** is cached, so it can be omitted from
231``west flash`` and ``west debug`` if it was previously set while running
232``west build``.
233
234**RPI_PICO_DEBUG_ADAPTER** is used in an argument to OpenOCD as ``"source [find interface/${RPI_PICO_DEBUG_ADAPTER}.cfg]"``.
235Thus, **RPI_PICO_DEBUG_ADAPTER** needs to be assigned the file name of the debug adapter.
236
237.. _rpi_pico_flashing_using_uf2:
238
239Using UF2
240---------
241
242If you don't have an SWD adapter, you can flash the Raspberry Pi Pico with
243a UF2 file. By default, building an app for this board will generate a
244:file:`build/zephyr/zephyr.uf2` file. If the Pico is powered on with the ``BOOTSEL``
245button pressed, it will appear on the host as a mass storage device. The
246UF2 file should be drag-and-dropped to the device, which will flash the Pico.
247
248Debugging
249=========
250
251Like flashing, debugging can also be performed using Zephyr's standard method
252(see :ref:`application_run`).
253The following sample demonstrates how to debug using OpenOCD and
254the `Raspberry Pi Debug Probe`_.
255
256.. zephyr-app-commands::
257   :zephyr-app: samples/basic/blinky
258   :board: rpi_pico
259   :maybe-skip-config:
260   :goals: debug
261   :gen-args: -DOPENOCD=/usr/local/bin/openocd -DRPI_PICO_DEBUG_ADAPTER=cmsis-dap
262
263The default debugging tool is ``openocd``.
264If you use a different tool, specify it with the ``--runner``,
265such as ``jlink``.
266
267If you use OpenOCD, see also the description about flashing :ref:`rpi_pico_flashing_using_uf2`
268for more information.
269
270
271.. target-notes::
272
273.. _Raspberry Pi Pico:
274   https://www.raspberrypi.com/products/raspberry-pi-pico/
275
276.. _RP2040 Datasheet:
277   https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf
278
279.. _Infineon CYW43439:
280   https://www.infineon.com/cms/en/product/wireless-connectivity/airoc-wi-fi-plus-bluetooth-combos/wi-fi-4-802.11n/cyw43439/
281
282.. _pico_setup.sh:
283   https://raw.githubusercontent.com/raspberrypi/pico-setup/master/pico_setup.sh
284
285.. _Getting Started with Raspberry Pi Pico:
286   https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf
287
288.. _Raspberry Pi Debug Probe:
289   https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html
290
291.. _SEGGER J-Link:
292   https://www.segger.com/products/debug-probes/j-link/
293
294.. _Black Magic Debug:
295   https://black-magic.org/
296