From 9af6f8cbd1e97b2aa95ce882e560963a16200a9c Mon Sep 17 00:00:00 2001 From: krzysztof-cabaj Date: Sat, 17 Dec 2022 09:39:32 -0500 Subject: [PATCH] boards/rpi-picow: add board documentation --- boards/rpi-picow/doc.txt | 179 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 boards/rpi-picow/doc.txt diff --git a/boards/rpi-picow/doc.txt b/boards/rpi-picow/doc.txt new file mode 100644 index 000000000000..19cc73e06600 --- /dev/null +++ b/boards/rpi-picow/doc.txt @@ -0,0 +1,179 @@ +/** +@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 (third from left) and Pico WH (forth from right). + +![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-picow 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-picow 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) +- Infineon CYW 43439 wireless chip + */