From 1dd5de0cbc9080f1cfe8584ab136aedce7527cbb Mon Sep 17 00:00:00 2001 From: crasbe Date: Sat, 15 Feb 2025 01:24:30 +0100 Subject: [PATCH] boards/rpi-pico*: Update and fix documentation and images --- boards/rpi-pico-w/doc.txt | 350 +++++++++++++++++++------------------- boards/rpi-pico/doc.txt | 326 +++++++++++++++++------------------ 2 files changed, 332 insertions(+), 344 deletions(-) diff --git a/boards/rpi-pico-w/doc.txt b/boards/rpi-pico-w/doc.txt index a2383a5e22..a7283bb4d0 100644 --- a/boards/rpi-pico-w/doc.txt +++ b/boards/rpi-pico-w/doc.txt @@ -1,180 +1,174 @@ /** -@defgroup boards_rpi_pico_w Raspberry Pi Pico W -@ingroup boards -@brief Support for the RP2040 based Raspberry Pi Pico W board - -## Overview - -The Raspberry Pi Pico W and Pico WH (with headers) is a board with RP2040 MCU, -a custom dual core ARM Cortex-M0+ MCU with relatively high CPU clock, plenty of -RAM, some unique peripheral (the Programmable IO) and the Infineon CYW43439 wireless -chip. - -## Hardware - -![Raspberry Pi Pico W](https://www.raspberrypi.com/app/uploads/2022/06/Copy-of-PICO-W-HERO-800x533.jpg) - -Raspberry Pi Pico W is provided in two versions - without and with headers, -the second one is called Pico WH. Detailed photos can be found at [Raspberry Pi Pico family](https://www.raspberrypi.com/documentation/microcontrollers/images/four_picos.jpg). - -### MCU - -The Programmable IO (PIO) peripheral and the SSI/QSPI peripheral that supports execution from -flash (XIP) are the most distinguishing features of the MCU. The latter is especially important, -since the RP2040 contains no internal flash. - -| MCU | RP2040 | -|:-----------|:------------------------------------------------------------ | -| Family | (2x) ARM Cortex-M0+ | -| Vendor | Raspberry Pi | -| RAM | 264 KiB | -| Flash | 2 MiB (up to 16 MiB) | -| Frequency | up to 133 MHz | -| FPU | no | -| PIOs | 8 | -| Timers | 1 x 64-bit | -| ADCs | 1x 12-bit (4 channels + temperature sensor) | -| UARTs | 2 | -| SPIs | 2 | -| I2Cs | 2 | -| RTCs | 1 | -| USBs | 1 (USB 2.0) | -| Watchdog | 1 | -| SSI/QSPI | 1 (connected to flash, with XIP support) | -| WiFi | via wireless chip (Infineon CYW43439) (*) | -| Bluetooth | via wireless chip (Infineon CYW43439) (*) | -| Vcc | 1.62V - 3.63V | -| Datasheet | [Datasheet](https://datasheets.raspberrypi.com/picow/pico-w-datasheet.pdf) | -| Wireless chip | [Infineon CYW43439 Datasheet](https://www.infineon.com/dgdl/Infineon-CYW43439-DataSheet-v03_00-EN.pdf?fileId=8ac78c8c8386267f0183c320336c029f) | - -(*) Currently not implemented in the RIOT OS. - -### User Interface - -1 button (also used for boot selection) and 1 LED: - -| Device | PIN | -|:------ |:---------------- | -| LED0 | WL_GPIO0 (*) | -| SW0 | QSPI_SS_N (**) | - -(*) In the Pico W LED0 is directly connected to the Infineon CYW43439 module, -and cannot be directly controlled by MCU. - -(**) Since the switch is connected to the chip-select pin of the QSPI interface the flash chip RIOT -is running from via XIP, the switch is difficult to read out from software. This is currently not -supported. - -### Pinout - -![Pinout Diagram of RPi Pico W](https://www.raspberrypi.com/documentation/microcontrollers/images/picow-pinout.svg) - -## Flashing the Board - -### Flashing the Board Using the Bootloader - -Connect the device to your Micro-USB cable while the button (labeled `BOOTSEL` -on the silkscreen of the PCB) is pressed to enter the bootloader. The pico -will present itself as a storage medium to the system, to which a UF2 file -can be copied perform the flashing of the device. This can be automated by -running: - -``` -make BOARD=rpi-pico-w flash -``` - -This is default flashing option using elf2uf2 PROGRAMMER. If the storage is -not automatically mounted to `/media//RPI-RP2`, you can overwrite -the path by exporting the shell environment variable `ELF2UF2_MOUNT_PATH`. - -### Flashing the Board Using OpenOCD - -Currently (June 2021), only two methods for debugging via OpenOCD are supported: - -1. Using a bit-banging low-level adapter, e.g. via the GPIOs of a Raspberry Pi 4B -2. Using a virtual CMSIS-DAP adapter provided by the second CPU core via - https://github.com/majbthrd/pico-debug - -Option 2 requires no additional hardware however, you need to -first "flash" the gimme-cache variant of [pico-debug](https://github.com/majbthrd/pico-debug) -into RAM using the UF2 bootloader. For this, plug in the USB cable while holding down the BOOTSEL -button of the Pico and copy the `pico-debug-gimmecache.uf2` from the -[latest pico-debug release](https://github.com/majbthrd/pico-debug/releases) into the virtual FAT -formatted drive the bootloader provides. Once this drive is unmounted again, this will result in -the Raspberry Pi Pico showing up as CMSIS-DAP debugger. Afterwards run: - -``` -make BOARD=rpi-pico-w PROGRAMMER=openocd flash -``` - -@warning The `rpi-pico-w` virtual debugger is not persistent and needs to be "flashed" into RAM - again after each cold boot. - -@note As of July 2021, the latest stable release of OpenOCD does not yet support the RP2040 - MCU. Instead, compile the current `master` branch from the upstream OpenOCD source. - The OpenOCD fork of the Raspberry Pi foundation is incompatible with OpenOCD - configuration provided, so please stick with upstream OpenOCD. - -### Flashing the Board Using J-Link - -Connect the Board to an Segger J-Link debugger, e.g. the EDU mini debugger is relatively affordable, -but limited to educational purposes. Afterwards run: - -``` -make BOARD=rpi-pico-w PROGRAMMER=jlink flash -``` - -## Accessing RIOT shell - -This board's default access to RIOT shell is via UART (UART0 TX - pin 1, UART0 RX - pin 2). - -The default baud rate is 115 200. - -The simplest way to connect to the shell is the execution of the command: - -``` -make BOARD=rpi-pico-w term -``` - -@warning Raspberry Pi Pico board is not 5V tolerant. Use voltage divider or logic level shifter when connecting to 5V UART. - -## On-Chip Debugging - -There are currently (June 2021) few hardware options for debugging the Raspberry Pi Pico: - -1. Via J-Link using one of Seggers debuggers -2. Via OpenOCD using a low-level bit-banging debugger (e.g. a Raspberry Pi 4B with the GPIOs - connected to the Raspberry Pi Pico via jump wires) -3. Via a recently updated [Black Magic Probe](https://github.com/blacksphere/blackmagic) - -In addition, a software-only option is possible using -[pico-debug](https://github.com/majbthrd/pico-debug). The default linker script reserved 16 KiB of -RAM for this debugger, hence just "flash" the "gimme-cache" flavor into RAM using the UF2 -bootloader. Once this is done, debugging is as simple as running: - -``` -make BOARD=rpi-pico-w debug -``` - -***Beware:*** The `rpi-pico-w` virtual debugger is not persistent and needs to be "flashed" into RAM -again after each cold boot. The initialization code of RIOT now seems to play well with the -debugger, so it remains persistent on soft reboots. If you face issues with losing connection to -the debugger on reboot, try `monitor reset init` in GDB to soft-reboot instead. - -## Known Issues / Problems - -### Early state Implementation - -Currently no support for the following peripherals is implemented: - -- Timers -- ADC -- SPI -- I2C -- USB -- PIO -- RTC -- Watchdog -- SMP support (multi CPU support is not implemented in RIOT) -- Infineon CYW 43439 wireless chip + * @defgroup boards_rpi_pico_w Raspberry Pi Pico W + * @ingroup boards + * @brief Support for the RP2040 based Raspberry Pi Pico W board + * + * ## Overview + * + * The Raspberry Pi Pico W and Pico WH (with headers) is a board with RP2040 MCU, + * a custom dual core ARM Cortex-M0+ MCU with relatively high CPU clock, plenty of + * RAM, some unique peripheral (the Programmable IO) and the Infineon CYW43439 wireless + * chip. + * + * ## Hardware + * + * @image html https://www.raspberrypi.com/documentation/computers/images/pico-w.png "Raspberry Pi Pico W" width=50% + * + * Raspberry Pi Pico W is provided in two versions - without and with headers, + * the second one is called Pico WH. Detailed photos can be found at [Raspberry Pi Pico family](https://www.raspberrypi.com/documentation/microcontrollers/images/four_picos.jpg). + * + * ### MCU + * + * The Programmable IO (PIO) peripheral and the SSI/QSPI peripheral that supports execution from + * flash (XIP) are the most distinguishing features of the MCU. The latter is especially important, + * since the RP2040 contains no internal flash. + * + * | MCU | RP2040 | + * |:-----------|:------------------------------------------------------------ | + * | Family | (2x) ARM Cortex-M0+ | + * | Vendor | Raspberry Pi | + * | RAM | 264 KiB | + * | Flash | 2 MiB (up to 16 MiB) | + * | Frequency | up to 133 MHz | + * | FPU | no | + * | PIOs | 8 | + * | Timers | 1 x 64-bit | + * | ADCs | 1x 12-bit (4 channels + temperature sensor) | + * | UARTs | 2 | + * | SPIs | 2 | + * | I2Cs | 2 | + * | RTCs | 1 | + * | USBs | 1 (USB 2.0) | + * | Watchdog | 1 | + * | SSI/QSPI | 1 (connected to flash, with XIP support) | + * | WiFi | via wireless chip (Infineon CYW43439) (*) | + * | Bluetooth | via wireless chip (Infineon CYW43439) (*) | + * | Vcc | 1.62V - 3.63V | + * | Datasheet | [Datasheet](https://datasheets.raspberrypi.com/picow/pico-w-datasheet.pdf) | + * | Wireless chip | [Infineon CYW43439 Datasheet](https://www.infineon.com/dgdl/Infineon-CYW43439-DataSheet-v03_00-EN.pdf?fileId=8ac78c8c8386267f0183c320336c029f) | + * + * (*) Currently not implemented in the RIOT OS. + * + * ### User Interface + * + * 1 button (also used for boot selection) and 1 LED: + * + * | Device | PIN | + * |:------ |:---------------- | + * | LED0 | WL_GPIO0 (*) | + * | SW0 | QSPI_SS_N (**) | + * + * (*) In the Pico W LED0 is directly connected to the Infineon CYW43439 module, + * and cannot be directly controlled by MCU. + * + * (**) Since the switch is connected to the chip-select pin of the QSPI interface the flash chip RIOT + * is running from via XIP, the switch is difficult to read out from software. This is currently not + * supported. + * + * ### Pinout + * + * ![Pinout Diagram of the RPi Pico W](https://www.raspberrypi.com/documentation/microcontrollers/images/picow-pinout.svg) + * + * ## Flashing the Board + * + * ### Flashing the Board Using the Bootloader + * + * Connect the device to your Micro-USB cable while the button (labeled `BOOTSEL` + * on the silkscreen of the PCB) is pressed to enter the bootloader. The pico + * will present itself as a storage medium to the system, to which a UF2 file + * can be copied perform the flashing of the device. This can be automated by + * running: + * + * ``` + * make BOARD=rpi-pico-w flash + * ``` + * + * This is default flashing option using elf2uf2 PROGRAMMER. If the storage is + * not automatically mounted to `/media//RPI-RP2`, you can overwrite + * the path by exporting the shell environment variable `ELF2UF2_MOUNT_PATH`. + * + * ### Flashing the Board Using OpenOCD + * + * Currently (June 2021), only two methods for debugging via OpenOCD are supported: + * + * 1. Using a bit-banging low-level adapter, e.g. via the GPIOs of a Raspberry Pi 4B + * 2. Using a virtual CMSIS-DAP adapter provided by the second CPU core via + * https://github.com/majbthrd/pico-debug + * + * Option 2 requires no additional hardware however, you need to + * first "flash" the gimme-cache variant of [pico-debug](https://github.com/majbthrd/pico-debug) + * into RAM using the UF2 bootloader. For this, plug in the USB cable while holding down the BOOTSEL + * button of the Pico and copy the `pico-debug-gimmecache.uf2` from the + * [latest pico-debug release](https://github.com/majbthrd/pico-debug/releases) into the virtual FAT + * formatted drive the bootloader provides. Once this drive is unmounted again, this will result in + * the Raspberry Pi Pico showing up as CMSIS-DAP debugger. Afterwards run: + * + * ``` + * make BOARD=rpi-pico-w PROGRAMMER=openocd flash + * ``` + * + * @warning The `rpi-pico-w` virtual debugger is not persistent and needs to be "flashed" into RAM + * again after each cold boot. + * + * @note The RP2040 MCU is supported from OpenOCD version 0.12.0 onwards. + * + * ### Flashing the Board Using J-Link + * + * Connect the Board to an Segger J-Link debugger, e.g. the EDU mini debugger is relatively affordable, + * but limited to educational purposes. Afterwards run: + * + * ``` + * make BOARD=rpi-pico-w PROGRAMMER=jlink flash + * ``` + * + * ## Accessing RIOT shell + * + * This board's default access to RIOT shell is via UART (UART0 TX - pin 1, UART0 RX - pin 2). + * + * The default baud rate is 115 200. + * + * The simplest way to connect to the shell is the execution of the command: + * + * ``` + * make BOARD=rpi-pico-w term + * ``` + * + * @warning Raspberry Pi Pico board is not 5V tolerant. Use voltage divider or logic level shifter when connecting to 5V UART. + * + * ## On-Chip Debugging + * + * There are currently (June 2021) few hardware options for debugging the Raspberry Pi Pico: + * + * 1. Via J-Link using one of Seggers debuggers + * 2. Via OpenOCD using a low-level bit-banging debugger (e.g. a Raspberry Pi 4B with the GPIOs + * connected to the Raspberry Pi Pico via jump wires) + * 3. Via a recently updated [Black Magic Probe](https://github.com/blacksphere/blackmagic) + * + * In addition, a software-only option is possible using + * [pico-debug](https://github.com/majbthrd/pico-debug). The default linker script reserved 16 KiB of + * RAM for this debugger, hence just "flash" the "gimme-cache" flavor into RAM using the UF2 + * bootloader. Once this is done, debugging is as simple as running: + * + * ``` + * make BOARD=rpi-pico-w debug + * ``` + * + * ***Beware:*** The `rpi-pico-w` virtual debugger is not persistent and needs to be "flashed" + * into RAM again after each cold boot. The initialization code of RIOT now seems to play well with the + * debugger, so it remains persistent on soft reboots. If you face issues with losing connection to + * the debugger on reboot, try `monitor reset init` in GDB to soft-reboot instead. + * + * ## Known Issues / Problems + * + * ### Early State Implementation + * + * Currently no support for the following peripherals is implemented: + * + * - USB + * - RTC + * - Watchdog + * - SMP support (multi CPU support is not implemented in RIOT) + * - Infineon CYW 43439 wireless chip + * + * The I2C peripheral is implemented through the PIO. */ diff --git a/boards/rpi-pico/doc.txt b/boards/rpi-pico/doc.txt index 8bb64fc314..c185eaf989 100644 --- a/boards/rpi-pico/doc.txt +++ b/boards/rpi-pico/doc.txt @@ -1,168 +1,162 @@ /** -@defgroup boards_rpi_pico Raspberry Pi Pico -@ingroup boards -@brief Support for the RP2040 based Raspberry Pi Pico board - -## Overview - -The Raspberry Pi Pico is sold by the Raspberry Pi foundation for about 4 USD. It features the -RP2040 MCU, a custom dual core ARM Cortex-M0+ MCU with relatively high CPU clock, plenty of RAM and -some unique peripheral (the Programmable IO). - -## Hardware - -![Raspberry Pi Pico](https://www.raspberrypi.org/homepage-9df4b/static/rp2040@2x-d1b9dae9345ad2bd15a23c6a567edb5c.jpg) - -### MCU - -The Programmable IO (PIO) peripheral and the SSI/QSPI peripheral that supports execution from -flash (XIP) are the most distinguishing features of the MCU. The latter is especially important, -since the RP2040 contains no internal flash. - -| MCU | RP2040 | -|:-----------|:------------------------------------------------------------ | -| Family | (2x) ARM Cortex-M0+ | -| Vendor | Raspberry Pi | -| RAM | 264 KiB | -| Flash | 2 MiB (up to 16 MiB) | -| Frequency | up to 133 MHz | -| FPU | no | -| PIOs | 8 | -| Timers | 1 x 64-bit | -| ADCs | 1x 12-bit (4 channels + temperature sensor) | -| UARTs | 2 | -| SPIs | 2 | -| I2Cs | 2 | -| RTCs | 1 | -| USBs | 1 (USB 2.0) | -| Watchdog | 1 | -| SSI/QSPI | 1 (connected to flash, with XIP support) | -| Vcc | 1.62V - 3.63V | -| Datasheet | [Datasheet](https://datasheets.raspberrypi.com/pico/pico-datasheet.pdf) | - -### User Interface - -1 button (also used for boot selection) and 1 LED: - -| Device | PIN | -|:------ |:---------------- | -| LED0 | 25 | -| SW0 | QSPI_SS_N (*) | - -(*) Since the switch is connected to the chip-select pin of the QSPI interface the flash chip RIOT -is running from via XIP, the switch is difficult to read out from software. This is currently not -supported. - -### Pinout - -![Pinout Diagram of RPi Pico](https://projects-static.raspberrypi.org/projects/getting-started-with-the-pico/f009ad94826c2f0cd7573a295897e76955301096/en/images/Pico-R3-Pinout.png) - -## Flashing the Board - -### Flashing the Board Using the Bootloader - -Connect the device to your Micro-USB cable while the button (labeled `BOOTSEL` -on the silkscreen of the PCB) is pressed to enter the bootloader. The pico -will present itself as a storage medium to the system, to which a UF2 file -can be copied perform the flashing of the device. This can be automated by -running: - -``` -make BOARD=rpi-pico flash -``` - -This is default flashing option using elf2uf2 PROGRAMMER. If the storage is -not automatically mounted to `/media//RPI-RP2`, you can overwrite -the path by exporting the shell environment variable `ELF2UF2_MOUNT_PATH`. - -### Flashing the Board Using OpenOCD - -Currently (June 2021), only two methods for debugging via OpenOCD are supported: - -1. Using a bit-banging low-level adapter, e.g. via the GPIOs of a Raspberry Pi 4B -2. Using a virtual CMSIS-DAP adapter provided by the second CPU core via - https://github.com/majbthrd/pico-debug - -Option 2 requires no additional hardware however, you need to -first "flash" the gimme-cache variant of [pico-debug](https://github.com/majbthrd/pico-debug) -into RAM using the UF2 bootloader. For this, plug in the USB cable while holding down the BOOTSEL -button of the Pico and copy the `pico-debug-gimmecache.uf2` from the -[latest pico-debug release](https://github.com/majbthrd/pico-debug/releases) into the virtual FAT -formatted drive the bootloader provides. Once this drive is unmounted again, this will result in -the Raspberry Pi Pico showing up as CMSIS-DAP debugger. Afterwards run: - -``` -make BOARD=rpi-pico PROGRAMMER=openocd flash -``` - -@warning The `rpi-pico` virtual debugger is not persistent and needs to be "flashed" into RAM - again after each cold boot. - -@note As of July 2021, the latest stable release of OpenOCD does not yet support the RP2040 - MCU. Instead, compile the current `master` branch from the upstream OpenOCD source. - The OpenOCD fork of the Raspberry Pi foundation is incompatible with OpenOCD - configuration provided, so please stick with upstream OpenOCD. - -### Flashing the Board Using J-Link - -Connect the Board to an Segger J-Link debugger, e.g. the EDU mini debugger is relatively affordable, -but limited to educational purposes. Afterwards run: - -``` -make BOARD=rpi-pico PROGRAMMER=jlink flash -``` - -## Accessing RIOT shell - -This board's default access to RIOT shell is via UART (UART0 TX - pin 1, UART0 RX - pin 2). - -The default baud rate is 115 200. - -The simplest way to connect to the shell is the execution of the command: - -``` -make BOARD=rpi-pico term -``` - -@warning Raspberry Pi Pico board is not 5V tolerant. Use voltage divider or logic level shifter when connecting to 5V UART. - -## On-Chip Debugging - -There are currently (June 2021) few hardware options for debugging the Raspberry Pi Pico: - -1. Via J-Link using one of Seggers debuggers -2. Via OpenOCD using a low-level bit-banging debugger (e.g. a Raspberry Pi 4B with the GPIOs - connected to the Raspberry Pi Pico via jump wires) -3. Via a recently updated [Black Magic Probe](https://github.com/blacksphere/blackmagic) - -In addition, a software-only option is possible using -[pico-debug](https://github.com/majbthrd/pico-debug). The default linker script reserved 16 KiB of -RAM for this debugger, hence just "flash" the "gimme-cache" flavor into RAM using the UF2 -bootloader. Once this is done, debugging is as simple as running: - -``` -make BOARD=rpi-pico debug -``` - -***Beware:*** The `rpi-pico` virtual debugger is not persistent and needs to be "flashed" into RAM -again after each cold boot. The initialization code of RIOT now seems to play well with the -debugger, so it remains persistent on soft reboots. If you face issues with losing connection to -the debugger on reboot, try `monitor reset init` in GDB to soft-reboot instead. - -## Known Issues / Problems - -### Early state Implementation - -Currently no support for the following peripherals is implemented: - -- Timers -- ADC -- SPI -- I2C -- USB -- PIO -- RTC -- Watchdog -- SMP support (multi CPU support is not implemented in RIOT) - + * @defgroup boards_rpi_pico Raspberry Pi Pico + * @ingroup boards + * @brief Support for the RP2040 based Raspberry Pi Pico board + * + * ## Overview + * + * The Raspberry Pi Pico is sold by the Raspberry Pi foundation for about 4 USD. It features the + * RP2040 MCU, a custom dual core ARM Cortex-M0+ MCU with relatively high CPU clock, plenty of RAM and + * some unique peripheral (the Programmable IO). + * + * ## Hardware + * + * @image html https://www.raspberrypi.com/documentation/computers/images/pico.png "Raspberry Pi Pico" width=50% + * + * ### MCU + * + * The Programmable IO (PIO) peripheral and the SSI/QSPI peripheral that supports execution from + * flash (XIP) are the most distinguishing features of the MCU. The latter is especially important, + * since the RP2040 contains no internal flash. + * + * | MCU | RP2040 | + * |:-----------|:------------------------------------------------------------ | + * | Family | (2x) ARM Cortex-M0+ | + * | Vendor | Raspberry Pi | + * | RAM | 264 KiB | + * | Flash | 2 MiB (up to 16 MiB) | + * | Frequency | up to 133 MHz | + * | FPU | no | + * | PIOs | 8 | + * | Timers | 1 x 64-bit | + * | ADCs | 1x 12-bit (4 channels + temperature sensor) | + * | UARTs | 2 | + * | SPIs | 2 | + * | I2Cs | 2 | + * | RTCs | 1 | + * | USBs | 1 (USB 2.0) | + * | Watchdog | 1 | + * | SSI/QSPI | 1 (connected to flash, with XIP support) | + * | Vcc | 1.62V - 3.63V | + * | Datasheet | [Datasheet](https://datasheets.raspberrypi.com/pico/pico-datasheet.pdf) | + * + * ### User Interface + * + * 1 button (also used for boot selection) and 1 LED: + * + * | Device | PIN | + * |:------ |:---------------- | + * | LED0 | 25 | + * | SW0 | QSPI_SS_N (*) | + * + * (*) Since the switch is connected to the chip-select pin of the QSPI interface the flash chip RIOT + * is running from via XIP, the switch is difficult to read out from software. This is currently not + * supported. + * + * ### Pinout + * + * ![Pinout Diagram of RPi Pico](https://www.raspberrypi.com/documentation/microcontrollers/images/pico-pinout.svg) + * + * ## Flashing the Board + * + * ### Flashing the Board Using the Bootloader + * + * Connect the device to your Micro-USB cable while the button (labeled `BOOTSEL` + * on the silkscreen of the PCB) is pressed to enter the bootloader. The pico + * will present itself as a storage medium to the system, to which a UF2 file + * can be copied perform the flashing of the device. This can be automated by + * running: + * + * ``` + * make BOARD=rpi-pico flash + * ``` + * + * This is default flashing option using elf2uf2 PROGRAMMER. If the storage is + * not automatically mounted to `/media//RPI-RP2`, you can overwrite + * the path by exporting the shell environment variable `ELF2UF2_MOUNT_PATH`. + * + * ### Flashing the Board Using OpenOCD + * + * Currently (June 2021), only two methods for debugging via OpenOCD are supported: + * + * 1. Using a bit-banging low-level adapter, e.g. via the GPIOs of a Raspberry Pi 4B + * 2. Using a virtual CMSIS-DAP adapter provided by the second CPU core via + * https://github.com/majbthrd/pico-debug + * + * Option 2 requires no additional hardware however, you need to + * first "flash" the gimme-cache variant of [pico-debug](https://github.com/majbthrd/pico-debug) + * into RAM using the UF2 bootloader. For this, plug in the USB cable while holding down the BOOTSEL + * button of the Pico and copy the `pico-debug-gimmecache.uf2` from the + * [latest pico-debug release](https://github.com/majbthrd/pico-debug/releases) into the virtual FAT + * formatted drive the bootloader provides. Once this drive is unmounted again, this will result in + * the Raspberry Pi Pico showing up as CMSIS-DAP debugger. Afterwards run: + * + * ``` + * make BOARD=rpi-pico PROGRAMMER=openocd flash + * ``` + * + * @warning The `rpi-pico` virtual debugger is not persistent and needs to be "flashed" into RAM + * again after each cold boot. + * + * @note The RP2040 MCU is supported from OpenOCD version 0.12.0 onwards. + * + * ### Flashing the Board Using J-Link + * + * Connect the Board to an Segger J-Link debugger, e.g. the EDU mini debugger is relatively affordable, + * but limited to educational purposes. Afterwards run: + * + * ``` + * make BOARD=rpi-pico PROGRAMMER=jlink flash + * ``` + * + * ## Accessing RIOT shell + * + * This board's default access to RIOT shell is via UART (UART0 TX - pin 1, UART0 RX - pin 2). + * + * The default baud rate is 115 200. + * + * The simplest way to connect to the shell is the execution of the command: + * + * ``` + * make BOARD=rpi-pico term + * ``` + * + * @warning Raspberry Pi Pico board is not 5V tolerant. Use voltage divider or logic level shifter when connecting to 5V UART. + * + * ## On-Chip Debugging + * + * There are currently (June 2021) few hardware options for debugging the Raspberry Pi Pico: + * + * 1. Via J-Link using one of Seggers debuggers + * 2. Via OpenOCD using a low-level bit-banging debugger (e.g. a Raspberry Pi 4B with the GPIOs + * connected to the Raspberry Pi Pico via jump wires) + * 3. Via a recently updated [Black Magic Probe](https://github.com/blacksphere/blackmagic) + * + * In addition, a software-only option is possible using + * [pico-debug](https://github.com/majbthrd/pico-debug). The default linker script reserved 16 KiB of + * RAM for this debugger, hence just "flash" the "gimme-cache" flavor into RAM using the UF2 + * bootloader. Once this is done, debugging is as simple as running: + * + * ``` + * make BOARD=rpi-pico debug + * ``` + * + * ***Beware:*** The `rpi-pico` virtual debugger is not persistent and needs to be "flashed" + * into RAM again after each cold boot. The initialization code of RIOT now seems to play well with the + * debugger, so it remains persistent on soft reboots. If you face issues with losing connection to + * the debugger on reboot, try `monitor reset init` in GDB to soft-reboot instead. + * + * ## Known Issues / Problems + * + * ### Early State Implementation + * + * Currently no support for the following peripherals is implemented: + * + * - USB + * - RTC + * - Watchdog + * - SMP support (multi CPU support is not implemented in RIOT) + * + * The I2C peripheral is implemented through the PIO. + * */