Raspberry Pi Pico User

Guide

A Newbie to Expert Guide to Master and

Use the New Raspberry Pi Pico to the Max!

Ola Wealth
 Copyright 2021 © Ola Wealth

All rights reserved. This book is copyright and no

part of it may be reproduced, distributed, or
transmitted in any form or by any means, including
photocopying, recording, or other electronic or
mechanical methods, without the prior written
permission of the publisher, except in the case of
brief quotations embodied in critical reviews and
certain other noncommercial uses permitted by
copyright law.

Printed in the United States of America Copyright

2021 © Ola Wealth
Contents
Introduction ......................................................................................................1
CHAPTER ONE: QUICK PICO SETUP ...................................................................2
Chapter 2: The Pico SDK ....................................................................................5
Chapter 3: Blinking a LED in C ...........................................................................8
Chapter 4: Saying “Hello World” in C ..............................................................15
Chapter 5: Debugging with SWD.....................................................................26
Chapter 6: Using Visual Studio Code ...............................................................33
Chapter 7: Creating your own Project ............................................................42
Chapter 8: Building on other platforms ..........................................................56
Chapter 9: Using other Integrated Development Environments ....................76
Appendix A: Using Picoprobe ..........................................................................98
Appendix B: Using Picotool ...........................................................................112
 Introduction

The Raspberry pico is a new microcontroller board that is

powered by new rp2040. The best thing about this processor is the
insanely detailed data sheet.

The raspberry pi pico is very useful for makers, hobbyist and

beginners, who want to use hardware and software, python or C++
to control things like stepper motors, temperature sensors, etc.

Another nice thing about the pico is that it has more speed, more
memory and it is a dual core micro controller and best of all, it is a
32 bit arm controller compared to the 8 bit of the arduino nano.

In this guide, you're going to learn jow to use the raspberry pi pico
microcontroller like a Pro, even if you are a total beginner.

With that said, let's dive right in.

1
 CHAPTER ONE: QUICK PICO SETUP

The installation steps in this Getting Started guide

can be skipped if you are only developing for
Raspberry Pi Pico on the Raspberry Pi 4B and the
Raspberry Pi 400. Just run the setup script and you
will be fine. Get the script by running the following
code:

$ git clone https://github.com/raspberrypi/pico-setup.git①

First run this code sudo apt install git if you don’t
have Git installed.

Thereafter, run

$ pico-setup/pico_setup.sh

Running this script does the following:

● Creates a directory pico
● Install the necessary dependencies required.

2
 ● Download the pico-sdk, pico-examples, pico-
extras, and pico-playground repositories
● Creates the paths for the following;
Pico_SDk_path, Pico_Examples_Path, and
Pico_Playground_Path inside your `/. Bashrc.
● Prototype the blink and hello_world examples
in Pico_examples/build/blink and pico-
examples/build/hello-world.
● Download the build protocol. Once you are
done, copy it to /usr/local/bin.
● Download and build picoprobe
● Download and compile OpenOCD – this is to
create support for debugging.
● Download and install Visual Studio Code.
● Install the necessary Visual Studio Code
extensions.

Configure your Raspberry Pi UART to use with the

Raspberry Pi Pico. When everything is setup, reboot
your Raspberry Pi to have it all together. After
rebooting the system, the UART changes and
reconfigurations take effect.

$ sudo reboot
3
Open the Visual Studio Code in the “Programming”
menu using the instructions from Section 6.2

4
 Chapter 2: The Pico SDK

Important

The followinging struction sassume that you are using a Raspberry Pi

Pico and some details may differ if you are using a different RP2040-
basedboard.They also assume you are using Raspberry Pi OS running
on a Raspberry Pi4, or an equivalent Debian-based Linux distribution
running on another platform. Alternative instructions for those using
MicrosoftWindows(seeSection8.2)orApplemacOS(seeSection8.1)area ls
provided.

The RP2040 microcontroller on the Raspberry Pi was

designed to be compatible with the Raspberry Pi
Pico. The components on the board supports C/C
++ SDK, including an official MicroPython port. This
book takes you by the hand to build, install and use
the SDK toolchain, and generally starting out with
the SDK.

For more information on the official MicroPython port see thePico Python SDKbook which
documents the port, and "Get started with MicroPython on Raspberry Pi Pico" by
Gareth Halfacree published by Raspberry Pi Press.

5
 2.1. Get the Pico SDK and examples

Check the Pico-examples repository

(https://github.com/raspberrypi/pico-examples) for
examples on applications written with the pico-sdk
(https://github.com/raspberrypi/pico-sdk). Create a
pico directory to store your pico related checkouts
as you clone the repositories. Check /home/pi/pico
for instructions to create a pico directory.

$ cd ~/

$ mkdir pico

$ cd pico

Thereafter, clone the pico-sdk and pico-examples git

repositories

$ git clone -b master https://github.com/raspberrypi/pico-sdk.git

$ cd pico-sdk

$ git submodule update --init

$ cd ..

$ git clone -b master https://github.com/raspberrypi/pico-examples.git

6
2.2. Install the Toolchain

You may have to install extra tools to build the

applications shown in pico-examples. One of them is
CMake, a project-building and a cross-platform tool
to build software, including the GNU Embedded
Toolchain for Arm. Find and install these tools
through apt directly from the command line. If you
had installed an earlier tool, it is ignored by apt.

$ sudo apt update

$ sudo apt install cmake gcc-arm-none-eabi build-essential①

1. To compile pioasm, elf2uf2, you need native gcc

and g++.

7
 Chapter 3: Blinking a LED in C

Switching on a LED and turning it off is a typical

software program for hardware. This program is one
that is initiated in a new programming environment.
Learning to flash the LED is the first step of the
journey. In this chapter, you will learn to blink the
LED on-board the Raspberry Pi Pico attached to pin
25 of the RP2040.

3.1. Building “Blink”

Use the command directory to access pico-examples

from the earlier pico directory created to create a
build directory.

8
$ cd pico-examples

$ mkdir build

$ cd build

Let us assume that you cloned pico-sdk and pico-

examples repositories and position them beside
each other, create the PICO_SDK_PATH:

$ export PICO_SDK_PATH=../../pico-sdk

Also, prepare your cmake build directory with the

cmake .

$ cmake ..

Using PICO_SDK_PATH from

environment ('../../pico-sdk') PICO
SDK is located at
/home/i/pico/pico-sdk

Note

cmakewill default to aReleasebuild with compiler optimisations enabled and debugging

information removed. To build a debug version, runcmake -DCMAKE_BUILD_TYPE=Debug
...

There is an area prepared by CMake for the pico-

examples tree. It is this place that you will build its
9
 example applications by typing make. Although we
are only changing directory into the blink directory
as we are only building blink before going ahead
with typing make

Tip

Invokingmakewith-j4will run four make jobs in parallel to speed it up. A Raspberry Pi 4 has 4
cores so-j4is a reasonable number.

$ cdblink

$ make-j4

Scanning dependencies of target

ELF2UF2Build Scanning dependencies of
target boot_stage2_original [ 0%] Creating
directories for'ELF2UF2Build'

[100%] Linking CXX executable

blink.elf [100%] Built target
blink

Now we have built the following:

● Blink. Elf, that the debugger will use.

● Blink uf2 that can be superimposed into the
RP2040 USB Mass Storage Device.

10
The binary prompts the microprocessor to blink the
on-board LED of the Raspberry Pi Pico connected to
GPIO25 of RP2040.

3.2. Load and run “Blink”

Mount software to load it on your RP2040 board,

which is the simplest method to load software as a
Mass Storage Device. With this simple action, you
can drag a file on the board to make the flash
happen. Connect your Raspberry Pi Pico to your
Raspberry Pi with a micro-USB cable. First hold
down the BOOTSEL button to change it into the USB
Mass Storage Mode.

Note

Loading code via the USB Mass Storage method is great if you know
your program is going to work first time, but if you are developing
anything new it is likely you will want to debug it.

So you can also load your software on to RP2040 using the Serial Wire
Debug interface, seeChapter 5. As well as loading software this allows
you to; set breakpoints, inspect variables, and inspect memory contents.

11
Note

3.2.1. From the Desktop

The Raspberry Pi Pico will mount by itself on the

Raspberry Pi Desktop as a USB Mass Storage
Device. Once it has mounted, Drag-and-drop blink
uf2 on the Mass Storage Device. RP2040 rboots,

If you are not following these instructions on a Raspberry Pi Pico, you

may not have aBOOTSELbutton, seeFigure 1. If this is the case, you should
check if there is some other way grounding the flashCSpin, such as a
jumper, to tell RP2040 to enter the BOOTSEL mode on boot. If there is no
such method, you can load code using the Serial Wire Debug interface.

and unmounts as a Mass Storage Device.

Immediately the flash code begins to run.

12
3.2.2. Using the command line

The only way to manually mount the mass storage

device is when you are logged in via ssh:

$ dmesg | tail

[ 371.973555] sd 0:0:0:0: [sda] Attached SCSI removable disk

$ sudo mkdir -p /mnt/pico

$ sudo mount /dev/sda1 /mnt/pico

If you checked the /mnt/pico directory and see

some files in there, it means one thing, that your
USB Mass Storage Device has been mounted
successfully.

Copy the blink. Uf2 on your RP2040:

$ ls /mnt/pico/

INDEX.HTM INFO_UF2.TXT

13
Since your code is still running, although RP2040 is
no longer a USB Mass Storage Device, and to keep
your programming environment decluttered, go
ahead to unmount.

Note

More information

Removing power from the board does not remove the code. When the board
is reattached to power the code you have just loaded will begin running
again. If you want to remove the code from the board, and upload new code,
press and hold the BOOT SEL switch when applying power to put the board
into Mass Storage mode.

If you are looking at building software and load it on

your Raspberry Pi Pico, you will find the information
in this document. The Pico C/C++ SDK book pulls
the lid allowing you to see what goes on behind the
screen as your blink application is transformed into
a binary program. It goes in-depth into the
processes involved.

14
 Chapter 4: Saying “Hello World” in C

Developers and eager programmers like to create

and use a serial port once they learn to toggle the
LED on and off, eventually learning to be interactive
with the “Hello World” feedback.

4.1. Serial input and output on Raspberry Pi

Pico

15
The default Raspberry Pi Pico UART TX pin (out from Raspberry Pi Pico) is pin
GP0, and the UART RX pin (in to Raspberry Pi Pico) is pin GP1. The default UART
pins are configured on a per-board basis using board configuration files. The
Raspberry Pi Pico configuration can be found
inhttps://github.com/raspberrypi/pico-
sdk/tree/master/src/boards/include/boards/pico.h. The Pico SDK defaults to a
board name of Raspberry Pi Pico if no other board is specified.

Although stdio and printf will run the default

Raspberry Pi Pico UART0, you can direct your stdin
(serial input) and stdout (serial output) to a serial
UART or USB CDC (USB serial) Important

The Pico SDK controls its own build system with

CMake from the pico_stdlib interface library to sum
up pertinent source files for particular actions.

16
Use the CMAke directory to change the path of
stdout, with output channeled to UART or USB CDC

1. Allow printf output through USB CDC (USB

serial).
2. Disallow printf output through UART.

The destination for stdio from UART to USB can be

changed without altering the C source code.

17
4.2. Create “Hello World”

Change hello_world directory and place it within the

pico-example tree, hust like the “Blink” example.
Run make

These lines of codes will create two separate

examples of programs in the hello_world/serial/ and
hello_world/usb/ directories.

Apart from other targets that we have, we have

created this path;

● Serial/hello_serial.elf, that the debugger uses.

● Serial/hello_serial.uf2 that can be dragged on
RP2040 USB Mass Storage Device (UART serial
binary).
18
 ● Usb/hello_usb.elf, that is used by the
debugger.
● Usb/hello_usb.uf2, that can be dragged on the
RP2040 USB Mass Storage Device (USB serial
Binary). Hello_serial channels stdio to UART0
on GP0 and GP1 pins; hello_usb channels stdio
to USB CDC serial.

4.3. Flash and Run “Hello World”

With a micro USB cable, connect your Raspberry Pi

Pico to your Raspberry Pi. Long-press the BOOTSEL
button to change it into the USB Mass Storage
Mode. Release the BOOTSEL button after it is
connected, although connection should be automatic
on the Raspberry Pi Desktop. You can drag-and-
drop the hello_serial.uf2 or hello_usb.uf2 on the
Mass Storage Device.

Immediately RP2040 reboots and unmounts as a

Mass Storage Device, and the flash code begins to
run. The text is invisible at the moment although
the “Hello World” line of code is running. Connect
your host computer to the standard UART on the
Raspberry Pi Pico to see what comes out.
19
4.4. see “Hello World” USB output

With the hello_usb.uf2 binary dropped where it is

supposed to be, the “Hello World” text goes to the
USB serial.

The text installs minicom once your Raspberry Pi

Pico is connected to your Raspberry Pi through the
USB.

$ sudo apt install minicom

Select and open the serial port:

20
There you go! Hello, world! Is printed boldly on the
console.

Tip

4.5. See “Hello World” UART output

If you dragged and dropped the hello_usb.uf2

binary, the “Hello World” text is channeled to UART0
on GP0 and GP1 pins. First, before you can see any
text displayed, enable UART serial communications
on the Raspberry Pi host. Run the raspi-config.

Select Interfacing Options > Serial and click “No”

when you are prompted; “Would you like a login
shell to be accessible over serial?” select “Yes” once
this prompt; “Would you like the serial port

21
hardware to be enabled?” check out the picture
below to see what happens.

Tap “Yes” with the raspi-config. Reboot your

Raspberry Pi to allow the serial port functionality.
Wire the Raspberry Pi and the Raspberry Pi Pico
together with the following mapping:

Raspberry Pi Raspberry Pi Pico

GND (Pin 14) GND (Pin 3)

GPIO15 (UART_RX0, Pin GP0 (UART0_TX, Pin 1)

10)

GPIO14 (UART_TX0, Pin GP1 (UART0_RX, Pin 2)

22
 8)

With the boards joined together, now it is time to

install minicom,

That is if you have not done so already:

Open the serial port:

23
Once you toggle the power to Raspberry Pi Pico,
Hello world stares at you from the console’s screen.

To exit minicom, useCTRL-Afollowed byX.

Tip

4.6. Powering the board

If you don’t want to power the board through the

USB, you can connect the Raspberry Pi’s pin to the
Raspberry Pi Pico VSYS pin through a diode. Under
normal conditions, the diode is a Schottky diode.

24
Connecting the 5V pin on Raspberry Pi to the
Raspberry Pi Pico VBUS pin is practical but not
recommended.

If you go ahead with it, the Micro USB becomes

useless. Although, there is an exception using the
Raspberry Pi Pico in USB host mode where the 5V is
connected to the VBUS pin.

The 3.3V pin is an OUTPUT pin that cannot be

converted to a power source for your Raspberry Pi
Pico. Note that it should NEVER be connected to a
power source.

25
 Chapter 5: Debugging with SWD

Important

These instructions assume that you are using a Raspberry Pi Pico,

details may differ if you are using an alternative RP2040-based board.

There is a SWD (Single Wire Debug) port which

interacts with binary programs on the RP2040. If
you want to use this special feature, it requires a
special debug version of your binary program and
the installation of extra tools.

5.1. Create “Hello World” debug version

Create “Hello World” debug version using the

CMAKE_BUILD_TYPE=Debug like the one shown
below,

26
5.2. Installing OpenOCD

OpenOCD is a debug translator that let a host

system load, run, and debug software on RP2040,
including greater interaction with hardware
registers. Using several hardware interfaces on the
RP2040 SWD port, direct bitbanging on Raspberry Pi
GPIOs is one of the hardware features of OpenOCD,
among others.

But there is a basic configuration to the hardware

connection, and that is having SWDIO on Pi GPIO
24, and SWCLK on GPIO 25. The good thing is that
the configuration can be wired to a Raspberry Pi
Pico following the Mapping below.

Alternatively, to get the signal integrity that you

want, wiring the SWD port through a breadboard or
indirect methods only reduce the signal integrity.
Wiring the SWD port directly to the Raspberry Pi
ensures that your codes are loaded on the
connection smoothly.
27
Another important wiring is the ground wire (0v),
especially a direct connection between the two, and
not relying or going with another ground route.

Note: To debug, Raspberry Pi Pico is powered,

among other means by USB. The OpenOCD branch
is created to work closely with the SWD support.

These instructions assume you want to build openocd in/home/pi/pico/openocd

Note

$ cd ~/pico

$ sudo apt install automake autoconf build-essential texinfo libtool

libftdi-dev libusb-1.0-0- dev

$ git clone https://github.com/raspberrypi/openocd.git --recursive --branch

rp2040 --depth=1

$ cd openocd

$ ./bootstrap

$ ./configure --enable-ftdi --enable-sysfsgpio --enable-bcm2835gpio

$ make -j4

$ sudo make install

5.3. Installing GDB

Install gdb-multiarch

28
$ sudo apt install gdb-multiarch

5.4. Use GDB and OpenOCD to debug Hello

World

The chip can be attached to OpenOCD to make sure

$ openocd -f interface/raspberrypi-swd.cfg -f target/rp2040.cfg

your Raspberry Pi 4 and Raspberry Pi Pico are wired

together perfectly. This is done through the
raspberrypi-swd interface.

Below is what your output looks like

...

Info : rp2040.core0: hardware has 4 breakpoints,

2watchpoints Info : rp2040.core1: hardware has 4
breakpoints, 2watchpoints Info : starting gdb
server for rp2040.core0 on 3333

Info : Listening on port 3333 for gdb connections

29
 Warning

If you see an error likeInfo : DAP init failedthen your Raspberry Pi Pico is either
powered off, wired incorrectly, or has signal integrity issues. Try different
GPIO jumper cables.

Leave this OpenOCD terminal open. First, open

another terminal where you attach a gdb extension
to OpenOCD. Go to the “Hello World” example
earlier and introduce gdb into the command line.

$ cd ~/pico/pico-examples/build/hello_world

$ gdb-multiarch hello_world.elf

Use the line of code below to connect GDB to Open

OCD

(gdb) target remote localhost:3333

Tip

You can create a.gdbinitfile so you don’t have to typetarget remote

localhost:3333every time. Do this withecho "target remote localhost:3333" >
~/.gdbinit. However, this interferes with debugging in VSCode (Chapter 6).

30
 Load hello_world.elf into flash

(gdb) load

Loading section .boot2, size 0x100

lma 0x10000000 Loading section
.text, size 0x22d0 lma 0x10000100
Loading section .rodata, size 0x4a0
lma 0x100023d0 Loading section
.ARM.exidx, size 0x8 lma 0x10002870
Loading section .data, size 0xb94
lma 0x10002878 Start address
0x10000104, load size 13324

Transfer rate: 31 KB/sec, 2664 bytes/write.

And get the code running.

Before running the executable, you may set a

breakpoint at main() with the line of code below:

31
Once you hit the breakpoint and before you
proceed, run the continue line of code:

To leave the gdb mode, run the line of code below:

32
 Chapter 6: Using Visual Studio Code

The popular open-source editor developed by

Microsoft is the best Integrated Development
Environment (IDE) to get a graphical feedback as
you edit and debug your lines of code on the
Raspberry Pi 4.

6.1. Installing Visual Studio Code

Important

These installation instructions rely on you already having downloaded and

installed the command line toolchain, seeChapter 3, as well as
downloading and building both OpenOCD and GDB and configuring them
for command line debugging, seeChapter 5.

Get the ARM versions of Visual Studio Code from

https://code.visualstudio.com/ Download for your
Raspberry Pi. Download the ARM.deb file for a 32-
bit operating system like the basic Raspberry Pi Os.
For a 64-bit operating system, download the ARM
64 .deb file. When the download is completed, click
on the .deb package twice using the instructions to
complete installation.
33
 Use the .deb package on the command line .cd to a
folder path the file was downloaded, install with
dpkg -i<downloaded file name. deb>

After installation has been completed, install

necessary extensions to debug Raspberry Pi Pico:

code --install-extension marus25.cortex-debug

code --install-extension ms-vscode.cmake-tools
code --install-extension ms-vscode.cpptools

Launch Visual Studio Code from a terminal window:

$ export PICO_SDK_PATH=/home/pi/pico/pico-sdk

$ code

Set the PICO_SDK_PATH to allow Visual Studio

Code discover the Pico SDk

Note

IfPICO_SDK_PATHis not set by default in your shell’s environment you will have to set it
each time you open a new Terminal window before starting vscode, or start vscode
from the menus. You may therefore want to add it to your

.profileor.bashrcfile.
34
6.2. Loading a Project

Go to the Explorer toolbar ( Ctrl + Shift + E), click

Open Folder and go to /home/pi/pico-examples in
the file popup. These are the steps to optn the pico-
examples folder. Click “OK” to load the Folder into
VSCode.

There is a popup close to the base of the vscode

window. If you do not see it, that means CMake

Tools extension is not installed on your computer. If

everything looks good, hit “Yes” to configure the
project. You will be requested to use a compiler
from a prompt.

35
 Choose GCC for arm-none-eabi on the drop-down
menu.

Tip

If you miss the popups that close after a few seconds, configure the
compiler through the “No Kit Selected” in the blue bottom of the VScode.

Do one of these things; click on the “Build” button

to build the examples in the pico-examples folder
just below the blue bottom bar, or tap where you
see “[all]” in the blue bottom bar.

The second alternative gives you a drop down to

select a project. At the moment, type in
“hello_world” and choose the “Hello World”
executable. By choosing this option, VScode runs
the “Hello World” example saving you and the
compiler time.

Tip

You can toggle between building "Debug" and "Release" executables by clicking on where
it says "CMake: [Debug]: Ready" in the blue bottom bar. The default is to build a "Debug"
enabled executable ready for SWD debugging.

36
Tap on the “Build” button, the one with the cog
wheel symbol at the base of the blue bar on the
window. The build directory is created where you
can run CMake like we did earlier in Section 3.1,
before going to the build itself.

The projects below have been created just like what

we did from the command line the other time
among other things

37
 ● Hello_world.elf that is used by the debugger
● Hello_world.uf2 that can be dragged on the
RP2040 USB Mass Storage Device.

6.3. Debugging a Project

OpenOCD will launch by itself because the Pico-

examples has a debug configuration that also
attaches GDB and the application that CMake has
been configured to create. Copy this file (launch-
raspberrypi-swd.json) directly into the pico-
examples/.vscode directory as launch.json. there is
another file of importance, which is the settings.json
file that you should copy. Settings.json gets rid of
options that may increase your confusion from the
CMake plugin (which includes a broken Debug and
Run buttons that superimpose the Pico binary on a
host).

$ cd ~/pico/pico-examples

$ mkdir .vscode

$ cp ide/vscode/launch-raspberrypi-swd.json .vscode/launch.json

$ cp ide/vscode/launch-raspberrypi-swd.json .vscode/settings.json

38
 1 {

2 "version":"0.2.0",

3 "configurations": [
4 {

● "name":"PicoDebug",
● "cwd":"${workspaceRoot}",
● "executable":"${command:cmake.launchTargetPath}",
● "request":"launch",
● "type":"cortex-debug",
● "servertype":"openocd",

You may have to amend thegdbpathin launch.json if your gdb is calledarm-none-eabi-gdbinstead ofgdb-multiarch

Note

6.3.1. Running “Hello World” on the Raspberry

Pi Pico

Ensure that the example "Hello World" code has been as a Debug binary (CMAKE_BUILD_TYPE=Debug).

Important

Press Ctrl + Shift + D to go to the Debug toolbar

where you click the small green arrow which is the
play button at the top of the window pane to load
your code on the Raspberry Pi Pico and debug.
39
Now that the code is loaded and displayed on your
Raspberry Pi Pico, the source code for “Hello World”
should also be displayed on the upper pane of the
window. The code runs and go to the first
breakpoint which is enabled by the runToMain
directive found int the Launch.json file. Tap the
small blue arrow or the play button above the
source code window to Continue (F5) and get the
code working.

40
 Tip

If you switch to the "Terminal" tab in the bottom right-hand pane, below
thehello_world.ccode, you can use this to openminicominside VSCode to see the UART
output from the "Hello World" example by typing,

41
Chapter 7: Creating your own Project

First create a directory to save your experimental

project somewhere beside the pico-sdk directory.

Create a test.c file in the directory

42
 1. The line of code above enables serial output via
the USB.
2. The second one allows serial output via the
UART.

Once you are done, copy the

pico_sdk_import.cmake file from the external folder
in pico-sdk installation directory to the project’s
folder.

$ cp ../pico-sdk/external/pico_sdk_import.cmake .

43
 Here is what everything looks like

$ ls -la
total 24

drwxr-xr-x 5aastaff 160 6 Apr 10:46./

drwxr-xr-x 7aastaff 224 6 Apr 10:41../

-rw-r--r--@ 1aastaff 394 6 Apr 10:37CMakeLists.txt

-rw-r--r-- 1 aa staff 2744 6 Apr 10:40 pico_sdk_import.cmake

-rw-r--r-- 1aastaff 383 6 Apr 10:37test.c

Using the earlier “Hello World” example, we can

now build it as a prototype.

$ mkdir build
$ cd build

$ export PICO_SDK_PATH=../../pico-sdk

$ cmake ..

$ make

The new project will create different files. The

important files are displayed in the table below.

File extension Description

.bin Raw binary dump of the

44
 program code and data

.elf The full program output,

possibly including debug
information

.uf2 The program code and

data in a UF2 form that
you can drag-and-drop on
to the RP2040 board
when it is mounted as a
USB drive

.dis A disassembly of the

compiled binary

.hex Hexdump of the compiled

binary

.map A map file to accompany

the .elf file describing
where the linker has
arranged segments in
memory

45
 Note

UF2 (USB Flashing Format) is a file format, developed by Microsoft, that is used for
flashing the RP2040 board over USB. More details can be found on theMicrosoft UF2
Specification Repo

To build a binary to run in SRAM, rather than Flash memory you can either setup
your cmake build with-DPICO_NO_FLASH=1or you can add pico_set_binary_type(TARGET_NAMEno_flash)to

control it on a per binary basis in your CMakeLists.txt file. You can download the RAM
binary to RP2040 via UF2. For example, if there is no flash chip on your board, you
can download a binary that runs on the on-chip RAM using UF2 as it simply specifies
the addresses of where data goes. Note you can only download into RAM or
FLASH,notboth.
Note

7.1. debugging your project

Using the same “Hello World” example, use a similar

approach to debug your project from the command
line. First, connect your Raspberry Pi Pico and the
Raspberry Pi Pico.

46
 Use the CMAKE_BUILD_TYPE=Debug to create a
debug version of your project.

$ cd ~/pico/test

$ rmdirbuild

$ mkdirbuild

$ cd build

$ export PICO_SDK_PATH=../../pico-sdk

$ cmake -DCMAKE_BUILD_TYPE=Debug ..

$ make

Open a terminal window to attach the OpenOCD

with the raspberrypi-swd interface.

47
$ openocd -f interface/raspberrypi-swd.cfg -f target/rp2040.cfg
 Leave the OpenOCD terminal open. Open another
terminal window to implement the gdb-multiarch
function with the command line below:

$ cd ~/pico/test/build

$ gdb-multiarch test.elf

Connect GDB to OpenOCD and tap the test.elf

binary extension to load into flash.

(gdb) target remote localhost:3333

(gdb) load

Allow it run.

(gdb) monitor reset init

(gdb) continue

7.2. Working in Visual Code

You may have to check Chapter 6 for instructions

about configuring the Visual Studio Code
environment to load a new project as opposed to
loading directly from the command line. This one is

48
 a great option for those that like to write and build
code in a development environment.

If you are interested in debugging and loading your

code onto the Raspberry Pi Pico from the Visual
Studio Code, you must create a launch.json file for
your project. Use the launch-raspberrypi-swd.json
example in Chapter 6 for this one. First, copy it into
your project directory as .vcode/launch.json.

7.3. Automating project creation

To automate your project to create a “clone” project

which is side-by-side with your creative efforts, just
use the automation feature which requires cloning
the project script directly from its Git repository

$ git clone https://github.com/raspberrypi/pico-project-generator.git

The clone is then presented in a graphical mode:

$ cd pico-project-generator

$ ./pico_project.py --gui

49
This script displays a GUI interface that provides a
visual feedback as you configure your project.

From here, include specific features to your project

by identifying them from the check boxes on the
GUI. The build system automatically includes the
right code to the project you are creating, including
a basic example of the code describing how the
feature can be used. There are several options
available that also describes functionality such as
the one below:

50
Console Options Description

Console over UART Enable a0serial console

over the0UART. This is
the default.

Console over USB Enable a0console over

the USB. 0Thedevice will
act as a0USB serial port.
This0can be used in
addition to or instead0of
the UART0option, but
note that0when enabled
other0USB functionality
is not0possible.

Code Options Description

Add examples for Pico Example0code will be

library generated for some of
the0standard library
features that0by default
are in the0build, for
example, 0UART

51
 support and HW
dividers.

Run from RAM Usually, the0build

creates a0binary that
will be0installed to the
flash0memory. This
forces the binary0to
work directly0from RAM

Advanced Brings up0a table

allowing0selection of
specific0board build
options. These
options0alter the way
the0features work,
and should be0used
with caution.

Build Options Description

Run Build Once the project has

been created, build it.

52
 This will0produce files
ready0for download to
the Raspberry Pi Pico.

Overwrite Project If a project0already

exists in the specified
folder, 0overwrite it
with the0new
project. This will
overwrite any
changes you0may
have made.

Create VSCode Project As well as0the CMake

files, also0create the
appropriate Visual
Studio0Code project
files.

7.3.1. Project generation from the command

line

The script below allows you to create your project

straight from the command line

53
$ export PICO_SDK_PATH="/home/pi/pico/pico-sdk"

$ ./pico_project.py --feature spi --feature i2c --project vscode test

To add specific library code to the build, use the -

feature options. There is an example code that
demonstrates the use of the feature options. From
here, you may include several features stretching
the limit of RP2040 storage capacity.

Also, have a list of all available features using the -

list option of the script. The command line example
shown above includes a support for the I2C and SPI
interfaces.

One feature that let you know that your -project

option feature is successful is the creation of
.vscode/launch.json, .vscode/c_cpp_properties.json,
and .vscode/settings.json files apart from the
normal CMake project files.

Once the feature files and other necessary files have

been created, you can start building your project
from the command line

$ cd test/build

$ cmake ..
54
Or from the Visual Studio Code directly. Use the -
help option to see a list of command line
permutations that become useful using the
graphical mode.

55
 Chapter 8: Building on other

platforms

Apart from the major platform, which is the

Raspberry Pi on the RP2040, there are other
platforms such as Apple macOS and Microsoft
Windows, that are open to developers to create and
build projects.

8.1. Building on Apple macOS

Building projects using codes on macOS for RP2040

is an experience akin to that on Linux.

8.1.1. Installing the Toolchain

To install, you have to download and install

Homebrew. If you already have it, you can skip this
stage.

$ /bin/bash -c "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/mas
ter/install.sh)"

56
 Install the toolchain

$ brew install cmake

$ brew tap ArmMbed/homebrew-formulae

$ brew install arm-none-eabi-gcc

Raspberry Pi has made every other thing simple as

long as you can use its instructions to build code for
the RP2040. With the toolchain now installed, you
will discover that there are not dissimilarities
between macOS and Linux. Check Section 2.1 and
use the instructions there to get the Pico SDK and
create the “Blink” example.

8.1.2. Using Visual Studio Code

You will find Visual Studio Code for macOS, Linux,

and Microsoft Windows as it is largely a cross
platform environment. Check and download the
macOS version that is available, unzip and drag it to
your Applications Folder. Go to Applications and tap
the icon to launch the Visual Studio Code.

57
8.1.3. Building with CMake Tools

Launch the Visual Studio Code environment and

install the CMake Tools extension. Tap the Extension
icon placed in the toolbar on the left, or use CMD +
SHIFT + X. search for “CMake Tools” and tap on the
list to install your preference.

After installing the extension, now it is time to

create the PICO_SDK_PATH variable. Go to the
pico-examples directory to create a. vscode
directory and add a file settings.json which instructs
CMake Tools the location of the Pico SDK.

{ "cmake.environment": {

"PICO_SDK_PATH":"../../pico-sdk" }, }

The next thing you want to do is to click on the Cog

Wheel located at the very bottom of the navigation
bar on the left-hand side of the interface. Then
choose "Settings".

When you’re in the settings pane, ensure you click

on click on "Extensions" as well as the "CMake
Tools configuration". After that, scroll down to

58
"Cmake: Generator" and then enter "Unix
Makefiles" into the box

Based on your local setup, you are not actually

required to manually set the CMake generator to
"Unix Makefiles".

But, if you fail to do so, in few cases, Visual Studio

will default to ninja instead to make and this may
cause the build to fail.

If you’re in a situation where you need to manually

configure this variable, then you have to try taking
a possible step to point Visual Studio at the CMake
Tools extension plainly. You can do this if you add
the an additional line to your settings.json file,

{ "cmake.environment": {

"PICO_SDK_PATH": "../../pico-sdk" },

"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" }

Return to the File menu and select “Add Folder to

Workspace…” go to the Pico-examples repo and tap
“Okay.”

59
Soon you will receive a prompt as the project loads
requesting to select a compiler. Tap “GCC for arm-
none-eabi” for your compiler.

Select the “Build” button, with the cog wheel symbol

in the blue bar of the window. Clicking this feature
creates the build directory allowing CMake to launch
like we did earlier before the build itself
commenced, see Figure 8.

This action produces ELF, bin, and Uf2 targets.

These targets are found in the hello_world directory
in the new build directory. Drag-and-drop the uf2

60
binary on the RP2040 board directly once your
computer is linked to it with a USB.

8.1.4. Saying “Hello World”

As long as you have stdio channeled to a USB CDC

(SERial) or UART0 on GP0 and GP1 pins, you can
build the Hello World example all the time. You
don’t even need a driver installation when building
with USB CDC as the target output because it is a
class compliant device. Run with a terminal
program, the likes of Serial or something similar to
connect to the USB serial port.

8.1.4.1. UART output

If you are connecting to the Raspberry Pi Pico UART

to check the output, although it is not necessary,
you may have to connect your Raspberry Pi Pico to
your Mac with a serial converter (USB to UART) an
example is the SparkFUn FTDI Basic board.

61
You may have to check the manufacturer’s website
for FTDI Chip Drivers if you are not using a recent
version of macOS such as Catalina, where the
drivers load up by itself automatically. To connect
the serial port once you are not running the
platform on the latest software, use a Terminal
program such as Serial or something similar. Don’t
forget that Serial includes driver support.

8.2. Building on MS Windows

Installing the toolchain is very unique on Microsoft

Windows; the installation is different to other
platforms. Once you install the building code for
RP2040, you realize that it is similar to other
platforms.

8.2.1. installing the Toolchain

The extra tools that you need to start building are;

● ARM GCC compiler

● CMake
● Build Tools for Visual Studio 2019
● Python 3
● Git

62
All you need is to download the executable installer
for these tools, and install the five packages on your
Windows machine.

8.2.1.1. Installing ARM GCC Compiler

Figure 14. ensure that you register the path to the

compiler when installing the required tools to your
Windows machine as an environment variable to be
accessed directly from the command line.

63
Tick the box to register the path to the ARM
compiler during installation to identify it as an
environment variable inside the Windows with the
prompt displayed.

8.2.1.2. Installing CMake

Add CMake to the system PATH during installation

for all users once the installer requests you to do
so.

8.2.1.3. Installing Visual Studio Code

64
Wait for the prompt to install the C++ build tools
during the Build Tools for Visual Studio installation.

8.2.1.4. Installing Python 3

You will also need to add Python 3.7 to the system

PATH for all users once you receive the prompt from
their installers. Also, disable the MAX_PATH length
from the prompt displayed at the end of the Python
installation.

65
Select “Customize installation” when installing
Python and go through the “Optional Features” and
select “Install for all users” from “Advanced
Features.”

Note

You may have to make a symbolic link so that the Makefile can find Python
3. To do so typecmdin the Run Window next to the Windows Menu to open a
Developer Command Prompt Window but select "Run as administrator" in
the right hand pane to open the window with administrative privileges.
Then navigate toC:\Program Files\Python37and make a symlink.

8.2.1.5. Installing Git

Change the default editor from vim when you are

installing Git.

66
It is very important to tick the checkbox to allow Git
to be used from third-party tools, although you can
disallow this feature when you are not comfortable
with it. During Git installation, check the “Checkout
as is, commit as-is”, click the “Use Windows’ default
console window.” Also check the “Enable
experimental support for pseudo consoles” during
installation.

8.2.2. Getting the Pico SDK and examples

C:\Users\pico\Downloads> git clone -b master

https://github.com/raspberrypi/pico-sdk.git

C:\Users\pico\Downloads> cd pico-sdk

C:\Users\pico\Downloads\pico-sdk> git submodule update --init

C:\Users\pico\Downloads\pico-sdk> cd ..

C:\Users\pico\Downloads> git clone -b master

https://github.com/raspberrypi/pico-examples.git

8.2.3. Building “Hello World” from the

Command line

Launch a Developer Command Prompt Window on

the Windows Menu. First select Windows > Visual
Studio 2019 > Developer Command Prompt on the
menu.
67
 Create the path to the Pico SDK with this line of
code:

C:\Users\pico\Downloads> setx PICO_SDK_PATH "..\..\pico-sdk"

Close your active Command Prompt Window. Open

another one where the environment variable is now
available in the right order. Go to the pico-examples
folder, and use the “Hello World” example to build.

C:\Users\pico\Downloads> cd pico-examples
C:\Users\pico\Downloads\pico-examples>
mkdir build

C:\Users\pico\Downloads\pico-examples> cd
build

C:\Users\pico\Downloads\pico-examples\build> cmake -G "NMake Makefiles" ..

C:\Users\pico\Downloads\pico-examples\build> nmake

The line of command above will build the target and

produce the ELF, bin, and uf2 targets. These targets
are located in the hello_world directory in your build
directory. If your computer and RP2040 board are
68
connected via a USB, simply drag-and-drop the Uf2
binary on the RP2040 board.s

8.2.4. Building “Hello World” from Visual

Studio Code

After installing the toolchain, install Visual Studio

Code and build your awesome projects with the
coding environment rather than the command line.
Download and install Visual Studio Code for
Windows. Launch a Developer Command Prompt
Window from the Windows Menu once

Installation is completed. Select Windows > Visual

Studio 2019 > Developer Command Prompt on the
menu. And input this line:

C:> code

This line is entered once a prompt requesting it is

displayed. The environment variables in the right
order are opened in the Visual Studio Code allowing
the toolchain to be configured well.

69
 If you start Visual Studio code by clicking on its desktop icon, or directly
from the Start Menu then the build environment will not be correctly
configured. Although this can be done manually later in the CMake
Tools Settings, the easiest way to configure the VisualStudio Code
environment is just to open it from a Developer CommandPrompt
Window where these environmental variables are already set.

Warning

First the CMake Tools extension will be installed.

Select the Extension icon in the left-hand toolbar
using the CTRL + SHIFT + X to search for “CMake
Tools”. Choose from an entry in the list and tap the
install button.

Go over to the Cog wheel at the base of the

navigation bar on the left-side of the interface and
click “Settings”. Tap “Extensions” and the “CMake
Tools configuration”. Just below, you will find
Cmake: Configure Environment”.

70
Return to the File menu and select the “Open
Folder” towards pico-examples repo. Tap “Okay”
and wait for a prompt requesting the configuration
of your project. Once it appears, click “GCC for arm-
none-eabi” as the compiler.

71
Tap the “Build” button, the one with the cog wheel
in the blue bar. It creates a directory for your
projects, runs CMake and clones the project
examples, including “Hello World”.

The new directories contain ELF, bin, and uf2

targets that are available inside the hello_world
directly inside the fresh build directory. Drag-and-
drop the Uf2 binary on the RP2040 board that is
connected to your computer with the USB.

72
8.2.5. Flashing and Running “Hello World”

Use a micro-USB cable to connect the Raspberry Pi

Pico to your Raspberry Pi.

When doing this, hold down the BOOTSEL button to

mount it literally and change it into USB Mass
STORage Mode. The board now appears as an
external drive where you can now drag-and-drop
the uf2 binary on the external drive.

Soon the Raspberry Pi Pico reboots and unmount as

an external drive, and immediately runs the flash
code.

Just like what happened in Chapter 4, the Hello

world example can be built once you route the stdio
to USB CDC (Serial) or to UART0 on GP0 and GP1
pins. You do not require any driver installation
especially with USB CDC as the target output
because it is a class compliant device.

8.2.5.1. UART output

If you want to connect to the Raspberry Pi Pico

standard UART to check out its output, you must
connect your Raspberry Pi Pico to your Mac with a
73
USB to UART Serial converter, an example is the
SparkFun FTDI Basic board described in Figure 13.

There is no need or requesting to install drivers on a

recent Windows OS like Windows 10 because the
important drivers are already loaded. If not check
the website of the manufacturer for FTDI Chip
Drivers.

C:> chgport

COM4 = \Device\ProlificSerial10

COM5 = \Device\VCP0

74
 If the drivers are not available, download and install
PuTTY. Run and choose “Serial”, enter 115,200 as
the baud rate when you tap the “Speed” box. Also
tick the serial port for your UART converter.

Use the hgport command to discover the UART

converter of your board.

You will get a list of active serial ports. Check COM5

for the USB to UART Serial converter.

If you have multiple serial devices and can’t figure out which one is your UART to USB
serial converter, try unplugging your cable, and runningchgportagain to see which COM
port disappears.

Note

Input the speed and port data, click the “Open”

button and there you will see the UART output that
leads from your Raspberry Pi Pico to your Terminal
window.

75
 Chapter 9: Using other Integrated

Development Environments

The recommended IDE is Visual Studio Code,

although you can use other environments with the
RP2040 and the Raspberry Pi Pico

9.1. Using Eclipse

Eclipse is a great IDE that is available on x86 Linux,

Mac and Windows. As a multiplatform IDE, you will
find its 64-bit ARM systems, which is the latest
version online or in stores.

They really work with the Raspberry Pi 4/400 range,

particularly 4 GB and recent versions with the 64-bit
OS. The instructions here describe the technicalities
to set up Eclipse on a linux device to run with the
Raspberry Pi Pico. The instructions to set up the
Raspberry Pi Pico on another software platform are
generic, although similar with connection methods
to Raspberry Pi Pico varying a little bit.

Check Section 8.2 and Section 8.1 for more

information for connecting non-Linux platforms.

76
 9.1.1. Setting up Eclipse for Pico on a Linux
machine

Requirements

Device must have a recent version of Linux

including a RAM capacity of 4 GB,

64-bit operating system

CMake 3.11 or recent

At present the 64-bit Raspberry Pi OS is0still in beta test. The latest beta0version
can be found herehttp://downloads.raspberrypi.org/raspios_arm64/images/. Other
64-bit Linux distributions can also be used but are untested by us, for example,
Ubuntu for Raspberry Pi. 0Please follow the usual procedure for installing an
operating system image0on to your SD card.

Note

Allow the standard UART using the config.txt syntax

particularly for Raspberry Pi

Enable_uart=1

Also install OpenOCD and the SWD debug system.

Check chapter 5 for more instructions about this

77
9.1.1.1. Installing Eclipse and Eclipse plugins

With the instructions provided, install the recent

version of Eclipse with Embedded CDT. Although
running on an ARM platform requires installing an
AArch64, which is the 64-bit ARM version of Eclipse.
Go to the website
https://projects.eclipse.org/projects/iot.embed-
cdt/downloads to get and download your own
version.

Download and extract the right file compatible with

your system. Pick and return to the extraction
location where you run the “eclipse” executable.

./eclipse

The C/C++ development kit and the Embedded

development kit are both the Embedded CDT
version of Eclipse that are available with the
complete tools and environment to develop and
build projects on Raspberry Pi Pico.

78
9.1.1.2. Using Pico-examples

CMake is the standard build system for the Pico

environment. Although Eclipse does not use CMake
by default since it uses its own build system.

First, the pico-examples for CMake projects to an

Eclipse project.

● Create a new folder just like the pico-examples

folder; an example is pico-examples-eclipse.
● Change the directory to that folder.
● Create a path of the directory to the
PICO_SDK_PATH

Export PICO_SDK_PATH=< wherever>

Enter the syntax below in the command line:

cmake -G"Eclipse CDT4 - Unix Makefiles" -D

CMAKE_BUILD_TYPE=Debug ../pico-examples

the Eclipse project files in out Pico-examples-eclipse

folder are created having a source from the CMake
tree. Open project From File System option inside
the menu on the file can now be used to load your
new project files into Eclipse.

79
9.1.1.3. Building

Right click on the project directly from project

explorer and choose Build. The examples are now
generated.

9.1.1.4. OpenOCD

the example here uses the OpenOCD system to

communicate with the Raspberry Pi Pico. As part of
the pre-requisite, attach the 2-wire debug
connections from the host device to the Raspberry
Pi Pico. Use GPIo connections on your Raspberry Pi,
although you will require more hardware to create
this connection with a laptop or desktop device. An
alternative is using a second Raspberry Pi Pico, this
time running the Picoprobe software described in
Appendix A. find more information on the debug
connections in Chapter 5.

With OpenOCD installed and the right connection

successfully done, Eclipse then should be set up to
talk to OpenOCD once programs begin to run. There
is a GDB interface to Eclipse on OpenOCD, and it is
there that the debugging is done.

80
To create the OPenOCD system, choose Preferences
inside the Window menu. Tap on MCU arrow to see
more options and select Global OpenOCD path.

Type “openocd” to execute the program. Choose the

location or path of the system that you cloned the
Pico OpenOcD fork from Github to retrieve the
folder.

9.1.1.5. Creating a Run configuration

First set up a Run configuration to run or debug

code in Eclipse. The configuration put in place the
information that you need to identify the code that
you will run, parameters, the debugger, source
paths and SVD information.
81
Tap Run configurations from the Eclipse Run menu.
Choose GDB OpenOCD Debugging to create a
debugger configuration. Choose the New
Configuration button.

9.1.1.5.1. Setting up the application to run

The pico-examples directory and building projects

create several executable programs, you must
select the one to run or debug all by yourself. Click
the Browse on the Main tab of the Run

configuration page to choose the C/C ++

applications that you want to run. You will find the
executables created by Eclipse in the sub folders of
the Eclipse project folder, like this example;
82
…/pico-examples-eclipse/<name of example
folder>/<optional name of example
subfolder>/executable.elf

The LED blink example will be found at;

…/pico-examples-eclipse/blink/blink.elf

9.1.1.5.2. Setting up the debugger

Because the OpenOCD is used to interact with the

Raspberry Pi Pico, it must be set up for the task

Click openocd in the Executable box and Actual

Executable box. The OpenOCD also needs to be set
up to use the Pico specific configuration, make the

83
changes to the Config options. It is also important
to change the path to another location where the
Pico version of OpenOCD is installed.

-f interface/raspberrypi-swd.cfg -f target/rp2040.cfg

The other options and settings on OpenOCD should

be left at default values. GDB remains the major
debugger. The GDB communicates with the
Raspberry Pi Pico directly from the OpenOCD
debugger. And the good thing is that, there is a
standard interface directly on the IDE.

The version of GDB is gdb-multiarch which should

be entered into the Executable name and the Actual
Executable fields.

84
9.1.1.5.3. setting the SVD plugin up

SVD views and creates peripheral registers on the

Pico board. You will find locations, descriptions, and
the SVD plugin for Eclipse to further integrate its
features and functionality inside the Eclipse IDE.
The SVD plugin is a default tool that comes with the
Embedded development plugins. Click the SVD path
tab on the Launch configuration, inputting the
location on the file system the location of the SVD
file itself. Check out the pico-sdk source tree for the
path.

85
···/pico-sdk/src/rp2040/hardware_regs/rp2040.svd

9.1.1.5.4. Running the debugger

Launch the program once the Run configuration has

been completed and saved. The Run button is at the
base of the dialog. Click Apply to make changes and
Close the dialog. Use the Run Menu and the Debug
option to run the application.

Eclipse goes into debug showing several debug and

source code windows, including Peripherals that
uses the SVD data to give access to peripheral
registers. What you see is the standard Eclipse
debugging session.

86
9.2. Using CLion

JetBrains created the multiplatform IDE called

CLion, which is available on Linux, Mac and
Windows. Because it is a commercial IDE, you will
find it being used by professional developers, or
folks that love the JetBrains IDEs. You can get free
versions as well as licensed versions.

The IDE runs on any Raspberry Pi, which means

that you will run CLion on your laptop or desktop. It
is very easy to set up projects with the intuitive
IDE, although setting up debug with the platform
has a low engagement as it is still new.

87
9.2.1. Setting up CLion

Get CLion from https://www.jetbrains.com/ clion/

and install it.

9.2.1.1. Setting up a project

Pico-example project is the one that we will use as

our example. Click Open*** to access the pico-
examples project from the File menu, scroll through
and pick the pico-examples project from the
directory.

Pay attention to the bottom of this picture as CLion

wanted to load the CMake project, which led to an
error of path specification PICO_SDK_PATH.

88
9.2.1.1.1. Configuring CMake Profiles

Tap the Settings*** from the File menu, scroll down

and choose “CMake below Build, Execution,
Deployment.

Put the environment variable PICO_SDK_PATH

below Environment as described above in the
picture or create the environment syntax as -
DPICO_SDK_PATH=xxx below CMake options:. Both
syntaxes are basic command line arguments and
environment variables to call CMake directly from
the command line. It is also the place to specify
CMake settings such as PICO_BOARD,
PICO_TOOLCHAIN_PATH etc.

89
Create several CMake profiles with their unique
settings, and perhaps include Release build by
pressing the + button, and input the
PICO_SDK_PATH once more. Press the copy button
two towards the right to fix the name and settings
of the build profile.

Once you click OK, the feedback that you get is

similar to the one in the image below. Pay attention
to the two tabs on both profiles (Debug and
Release) at the base of the window. Here, Release is
enabled. The CMake setup was also successful.

90
9.2.1.1.2. Running a build.

Experiment with one or more targets. First, go to

the drop-down selector within the toolbar and type
hello_usb; tap the tool icon on the left to build a
project like the one in the figure below. Similarly, go
ahead with a full build of all targets that you have in
mind using the Build menu.

91
Use the drop-down selector to choose the target
you wish to build and a CMake profile to use which
is Debug or Release.

In the figure above, you will notice hello_usb and

Debug in the status bar. They are the target and
CMake profile used to manage syntax highlighting in
the editor. It selected itself automatically because
you had earlier selected hello_usb. In the stdio.c
file, you can see the activity of an earlier user,
especially with setting PICO_STDIO_USB or
PICO_STDIO_UART that are not included in the
hello_usb settings.

92
Which is interesting, because build time per binary
configuration of libraries is one ubiquitous feature of
the Pico SDK.

9.2.1.1.3. Build Artifacts

You will find the build artifacts under cmake-build-

<profile> just below the project root in the figure
below. It is also the cmake-build-debug directory.

The uf2 file can be moved into any RP2040 device in

BOOTSEL mode, and the ELF is used for debugging.

9.3. other environments

Building environments for Pico are inexhaustible

that cannot be fully described here, although most

93
of them are compatible with the Pico SDK. You will
need a few things to ensure that your IDE and
Raspberry Pi Pico go together:

● CMake integration
● Allowing GDB support with other remote
settings.
● SVD is not necessary, although with it, reading
peripheral status becomes easier.
● Extra ARM embedded development plugin –
with these plugins available, support becomes
easier.

9.3.1. Using openocd-svd

This tool is a python GUI utility that let you access

peripheral registers of ARM MCUs through a
combination of OpenOCD and CMSIS-SVD.

Install its dependencies before installing the

openocd-svd program.

$ sudo apt install python3-pyqt5

$ pip3 install -U cmsus-svd

94
 After installation, clone the openocd-svd git
repository.

$ cd ~/pico

$ git clone https://github.com/esynr3z/openocd-svd.git

Once your Raspberry Pi 4 and Raspberry Pi Pico are

wired together, fix the OpenOCD through the swd

and rp2040 configuration channels.

$ openocd -f interface/raspberrypi-swd.cfg -f target/rp2040.cfg

Leave the OpenOCD terminal open. Launch a new

terminal and attach a gdb instance to OpenOCD.

Go to your project and begin gdb

$ cd ~/pico/test

$ gdb-multiarch test.elf

95
 Connect GDB to OPenOCD,

(gdb) target remote localhost:3333

Load it into flash and get it running.

(gdb)0 load

(gdb) 0monitor reset init

(gdb) 0continue

Once openocd and gdb are running, open a third

terminal window where you launch the openocd-svd
directing it to the SVD file in the Pico SDK.

$ python3 openocd_svd.py /home/pi/pico/pico-

sdk/src/rp2040/hardware_regs/rp2040.svd

Another openocd-svd window opens. Go to the File

menu and select the “Connect OpenOCD” to connect
through telnet to one of the running openocd target.

The telnet connection inspects the registers of the

running codes on your Raspberry Pi Pico, as shown
in the figure below.

96
97
 Appendix A: Using Picoprobe

Debugging another Pi Pico with a Raspberry Pi Pico

sounds impractical, but it is very possible. Get an
application called picoprobe that simulates a
Raspberry Pi Pico as a USB > SWD and UART
converter. With this emulator program, Raspberry Pi
Pico can be used on other unsupported platforms
such as Windows, Mac, and Linux computers
without the GPIos pins.

98
 A.1. Build OpenOCD

Create openocd terminals and enable the picoprobe

driver for picoprobe to work.

$ cd ~/pico

$ sudo apt install automake autoconf build-essential texinfo libtool

libftdi-dev libusb-1.0-0- dev

$ git clone https://github.com/raspberrypi/openocd.git --branch picoprobe --depth=1

$ cd openocd

$ ./bootstrap

$ ./configure --enable-picoprobe①

$ make -j4

$ sudo make install

A.1.1. Linux

1. Use this syntax –enable-sysfsgpio -enable-

bcm2835gpio to enable btbanging SWD through
the GPIO pins, it is an extra option when you are
building on a Raspberry Pi.

A.1.2. Windows

We are going to use MSYS2 to make building

OpenOCD very convenient. MSYS2 is a huge
collection of tools and libraries that creates a
99
 convenient building environment to install and run
native Windows software.

Check https://www.msys2.org/ to download and

run the installer.

First, update the package database and core system

packages using this script:

pacman -Syu

Your MYSYS2 may force-close, there is no need to

panic. Restart it and ensure that you picked the 64-
bit version before running:
100
pacman -Su

Install the necessary dependencies to complete the

update

pacman -S mingw-w64-x86_64-toolchain git make libtool

pkg-config autoconf automake texinfo mingw-w64-x86_64-libusb

Select all programs, especially the mingw-w64-

x86_64 toolchain during installation. Press enter
when you are done.

101
Close MSYS2 and launch its 64-bit version ensuring
that the environment notices the GCC.

$ git clone https://github.com/raspberrypi/openocd.git --branch picoprobe

--depth=1

$ cd openocd

$ ./bootstrap $ ./configure --enable-picoprobe --disable-werror ①

$ make -j4

Look out for disable-werror, since not every

program runs or compiles on Windows. Run
OpenOCD to see that it was built the right way.

It will produce error results a few times which is

fine. One reason is that there are no configuration
options in place.

102
 A.1.3. Mac

Install brew if it is required

/bin/bash -c "$(curl -fsSL

https://raw.githubusercontent.com/Homebrew/install/mas
ter/install.sh)"

Install dependencies

brew install libtool automake libusb wget pkg-config gcc texinfo①

1. There is one example of texinfo used with OSX in

the version below is required to create OpenOCD
documents.

$ cd ~/pico

$ git clone https://github.com/raspberrypi/openocd.git --branch picoprobe --depth=1

$ cd openocd

$ export PATH="/usr/local/opt/texinfo/bin:$PATH"①

$ ./bootstrap

$ ./configure --enable-picoprobe --disable-werror②

$ make -j4

103
● Place a recent version of texinfo inside the
path.
● Expect to see disable-werror as the
configuration is not completely compiled on
OSX.
● Look for OpenOCD runs and expect some error
feedback since there are no configuration
feedbacks.

● A.2. Build and flash picoprobe

The build instructions assume that Linux is your
default OS. Similarly, you can get a UF2
picoprobe from rptl.io/pico-picoprobe.

104
$ cd ~/pico

$ git clone https://github.com/raspberrypi/openocd.git --branch picoprobe --depth=1

$ cd openocd

$ export PATH="/usr/local/opt/texinfo/bin:$PATH"①

$ ./bootstrap

$ ./configure --enable-picoprobe --disable-werror②

$ make -j4

Select and Boot the Raspberry Pi Pico that you want

as a debugger pressing the BOOTSEL button and
picoprobe.uf2 dragged on the device.

Picoprobe Wiring

105
 The wiring loom between both Pico boards is
described in this illustration above.

To alternate between powering Pico A and Pico B,

do this wiring;

Pico A GND -> Pico B GND

Pico A GP2 -> Pico B SWCLK
Pico A GP3 -> Pico B SWDIO

Pico A GP4/UART1 TX -> Pico B GP1/UART0 RX

Pico A GP5/UART1 RX -> Pico B GP0/UART0 TX

The least amount of connections to load and

run code through OpenOCD is GND, SWDIO, and
SWCLK.

If you want to connect UART wires, then you will likely

communicate with the right-hand Pico’s UART serial port
via the USB connection of the Pico’s left-hand.

Also, if you make use of the UART wires, you will be able
to communicate to any other UART serial device, like the
boot console on a Raspberry Pi.

Also, if you’d like to power Pico A from Pico B you can

choose to wire,

Pico A VSYS -> Pico B VSYS

106
 Important

One slight caveat on Figure 34is that if Pico B is a0USB Host then you’d0want to hook VBUS
up to VBUS so it can0provide 5V instead of VSYS to VSYS.

A.4. Install Picoprobe driver (only needed on

Windows)

There are two USB interfaces on the picoprobe:

1. A CDC UART serial port that works on

Windows without extra installation of drivers.
2. A vendor interface for SWD probe data that is
personalized to individuals and requires a
driver to work.

First, download and install http://zadig.akeo.ie.

Run Zadig and choose a Picoprobe, the second

interface from the dropdown box. Choose lilbusb-
win32 as the driver.

107
 Click install driver

A.5. Using Picoprobe’s UART

A.5.1. Linux

sudo minicom -D /dev/ttyACM0 -b 115200

A.5.2. Windows

First, download and install PuTTY

https://www.chiark.greenend.org.uk/~sgtatham/pu
tty/latest.html
108
Select Device Manager and search Picoprobe’s COM
port number. For this example, the port number is
COM7.

Click PuTTTY. Choose Serial below connection type.

Type the name of your COM port and change its
speed’s number to 115200.

109
Click Open to begin the serial console as you are
getting ready to run your very first application.

110
brew install minicom

minicom -D /dev/tty.usbmodem1234561 -b 115200

A.5.3. Mac

A.6. Using Picoprobe with OpenOCD

src/openocd -f interface/picobrobe.cfg -f target/rp2040.cfg -s tcl

This syntax is the same on all platforms

Connect GDB like you normally would.

target remote localhost:3333

111
 Appendix B: Using Picotool

You can embed information into Raspberry Pi Pico

binary and retrieve it later with a command line
utility known as picotool.

B.1. Getting picotool

You will find the picotool utility in another repository

$ git clone -b master https://github.com/raspberrypi/picotool.git

$ cd picotool

apart from the usual Pico SDK. If you are running it

the first time, clone and build it with this pico-setup
script.

$ sudo apt-get install libusb-1.0-0-dev

Install libusb if you don’t have it

112
Note

B.2. Building Picotool

Use these methods to build picotool

this syntax creates a picotool command-line binary

just inside the build/picotool directory.

Note

B.3. Using Picotool

There are several command-line help features on

the picotool binary.

113
 Note

The majority of commands require an RP2040 device in BOOTSEL mode to be connected.

Important

The information is accessible on devices connected

to the RP2040 in BOOTSEL mode, or from any point
such as a file. The file is either an ELF, a Uf2, or a
BIN document.

114
B.3.1. Display information

You don’t have to struggle with storing compact

information again with the Binary information
support on picotool. Tap the info command to read
this information.

115
For instance, connect your Raspberry Pi Pico to your
computer using the Mass Storage Mode – one way
to do this is to long-press the BOOTSEL button
before plugging the USB. After that, open a
Terminal window to type

$ sudo picotool info

Program Information

name: hello_world

features: stdout to UART

Alternatively,

Although you can get information on the pins with

the following syntax;
116
Use the tools on the binaries inside your local file
system like this;

B.3.2. Save the program

Directly save your program, a section of it, or the

whole flash from the device in a BIN file or a Uf2
file.

117
For example

118
B.4. Binary Information

Every binary information has a location that can be

tracked and data that can be used by the machine.
This is because, its broad application means that
anyone can embed any information, that is different
to ours, and it is the choice of the individual to add
descriptive tags to the data created.

B.4.1. Basic Information

This one is the go-to to use find your way on Pico.

Basic information are not limited to the following.

● Program name
● Program description
● Program version string
● Program build date
● Program URL
● Program end address.
● Program features – this is a list created from
individual strings in the binary. It is displayed
according to its channel or connectivity in the
SDK.

119
 ● Build attributes are concerned with similar
data in the strings that are pertinent to the
binary like the Debug Build.

B.4.2. Pins

If you cannot recall the RP2040 based board a

project or an executable is built, especially when it
is built on several boards with several pins either
broken or missing, use the pins to resolve and
launch any executable program.

You will find static or fixed pin assignments in

binary in very compact form:

$ picotool info --pins sprite_demo.elf

File sprite_demo.elf:

Fixed Pin Information

0-4: Red 0-4

6-10: Green 0-4

11-15: Blue 0-4

16: HSync

17: VSync

18: Display Enable

120
 19: Pixel Clock

20: UART1 TX 21: UART1 RX

B.4.3. Adding Binary Information

You will see binary information declared as macros

in the program.

$ picotool info --pins

sprite_demo.elf File
sprite_demo.elf:

Fixed Pin
Information 0-4:
Red0-4

6-10: Green0-4

11-15: Blue 0-4

16: HSync

17: VSync

18: DisplayEnable

19: PixelClock

20: UART1TX

21: UART1RX

121
Add one line in the setup_default_uart function:

bi_decl_if_func_used(bi_2pins_with_func(PICO_DEFAULT_UART_RX_PIN,
PICO_DEFAULT_UART_TX_PIN, GPIO_FUNC_UART));

Both pin numbers and the UART function are stored

and later parsed as their real names on picotool.
Use the bi_decl_if_func_used to include the binary
information that contains the function called.

Similarly, you will find a video code with the

following lines:

bi_decl_if_func_used(bi_pin_mask_with_name(0x1f<<
(PICO_SCANVIDEO_COLOR_PIN_BASE+
PICO_SCANVIDEO_DPI_PIXEL_RSHIFT),"Red 0-4"));

B.4.4. Details

Programs and functions have been developed to

judiciously use space, although you can disable the
space management feature with preprocessor
through PICO_NO_BINARY_INFO=1.

122
Also, exclude any SDK code using its preprocessor
variable when it inserts a binary information.

You will need,

#include "pico/binary_info.h"

You will find several bi___ macros in the headers

like these:

There are also the ones that use underlying macros,

e.g.

123
Use either bi_dec1 (bi_blah(***)) for regular
inclusion of the binary info, if that is what you want,
or bi_decl_if_func_used(bi_blah(***)) to remove
binary information when the enclosing function is
not part of the binary via the linker (think –gc-
sections).

An example is below,

124
 B.4.5. Setting common fields from CMake

Set fields from CMake directory of your current

project, for example,

Now, “foo” becomes the default.

Note

All of these are passed as command line0arguments to the compilation, so if you plan to use
quotes, newlines etc you may0have better luck defining it usingbi_declin the code.

125
126