Repository files navigation

This script gives you an easy way to setup your Raspberry Pi to be able to build and run programs on your Pico-series microcontroller from the command line. Compatibility with any systems not running Raspberry Pi OS or Raspberry Pi OS Lite is not guaranteed or maintained.

To download & run this script, you can use the following commands:

wget https://raw.githubusercontent.com/raspberrypi/pico-setup/master/pico_setup.shchmod +x pico_setup.sh./pico_setup.sh

For manual command line setup instructions for other operating systems, seeBasic Setup on Other Operating Systems

If you want to use a GUI instead of the command line, then see thepico-vscode extension instead of this script - this supports 64-bit Windows, MacOS, Raspberry Pi OS, and most common Linux distros. This is documented in theGetting Started Guide.

After running the setup script, you'll want to run an example to check everything's working. First go into pico-examples:

cd pico/pico-examples

Depending on the board you're using (eg pico2), replacebuild_pico with the relevant build directory (egbuild_pico2) in the following commands.

If you're not using one of the default boards (pico, pico_w, pico2, or pico2_w), you'll need to create a new build directory for your board - you can do this with this command (replace both instances of$board with the board you are using):

cmake -S . -B build_$board -GNinja -DPICO_BOARD=$board -DCMAKE_BUILD_TYPE=Debug

To build the blink example, run the following command:

cmake --build build_pico --target blink

This builds the specified targetblink in the build folderbuild_pico - it will probably displayno work to do becauseblink was built earlier bypico_setup.sh

Then to run it, attach a Pico-series microcontroller in BOOTSEL mode, and run:

picotool load build_pico/blink/blink.uf2 -vx

This loads the file into Flash on the board, then verifies it was loaded correctly and reboots the board to execute it

You should now have a blinking LED on your board! For more info on thepicotool command which is used to load and query binaries on the device, see itsREADME

To view console output, you can either connect the UART output to aDebug Probe (or similar) and usestdio_uart (see thehello_serial example), or you can usestdio_usb (see thehello_usb example).

First, build & run the example for yourstdio choice on your Pico-series microcontroller with the same commands as before:

cmake --build build_pico --target hello_serialpicotool load build_pico/hello_world/serial/hello_serial.uf2 -vx

Then attachminicom to view the output:

minicom -b 115200 -D /dev/ttyACM0

The port number may be different, so also try/dev/ttyACM1 etc - and on other OSes may be entirely different (eg/dev/tty.usbmodem0001 on MacOS)

To exit minicom, type Ctrl+A then X

To debug programs on the Pico-series microcontroller, you first need to attach a debugger such as theDebug Probe. Once that's done, you can attach OpenOCD to your Pico-series microcontroller with this command (replacerp2040.cfg withrp2350.cfg, if using an RP2350-based board like a Pico 2):

openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c"adapter speed 5000"

In a separate window, you can run GDB and connect to that OpenOCD server:

gdb -ex"target extended-remote localhost:3333"

Then in GDB, run the following:

file build_pico/blink/blink.elfmonitor reset initloadcontinue

To exit GDB, use Ctrl+D twice. This will leave your Pico-series microcontroller in the halted state, so you will need to unplug and replug it to get it running again. To leave the device running, you can use:

monitor reset run

before exiting to leave the Pico running the code.

To configure the GDB layout, the following commands can be useful:

• layout src - displays the source code
• layout split - displays the source code and the assembly instructions
• layout regs - displays the current register contents

To step through code, you can use:

• step ors - step to the next line of code, and into any functions
• next orn - step to the next line of code, without stepping into functions
• finish orfin - step out of the current function

To step through assembly instructions, you can use:

• stepi orsi - step to the next assembly instruction, and into any functions
• nexti orni - step to the next assembly instruction, without stepping into functions

While stepping, you can just press enter again to repeat the previous command

To set breakpoints, use thebreak orb command plus the location of the breakpoint. The location can be:

• A function name -break main
• A line of code -break 12
• Either of those in a specific file -break blink.c:48,break blink.c:main
• A specific memory address -break *0x10000ff2

For more details on debugging with GDB, see theGDB docs

When debugging or viewing serial output, you might want multiple programs open in different terminals, as they all need to run at the same time.

On Raspberry Pi OS Lite, you can switch between different terminals with Alt+F1,F2,F3,F4 etc.

Alternatively you can use something likescreen ortmux to allow you to open new terminals and detach from them - for example usingscreen:

• screen -S minicom - open a new terminal calledminicom
• Ctrl+A then D - detach from the current terminal
• screen -r minicom - re-attach to an existing terminal calledminicom
• screen -ls - list existing terminals

For more details onscreen, see thescreen docs

If you're on Windows, it isstrongly recommended to useWSL2 and then follow theLinux instructions inside that. You should also installusbipd to access USB devices inside WSL2 (see the docs there for instructions).

If you're not using WSL2, then you'll need to install the following tools:

• Arm GNU Toolchain
  • Pick Windows -> AArch32 bare-metal target (arm-none-eabi) -> the .exe file
• CMake
• Microsoft Visual Studio
  • When running the installer, select Desktop Development with C++

Then follow themanual setup instructions. You will need to run all commands from the "Developer PowerShell for VS ..." terminal, not your usual terminal. For the first cmake configuration in each project (egcmake ..), you will need to replace-GNinja with-G "NMake Makefiles", and anything withsudo needs to be run as administrator. Also, you should use as short a path as possible due to path length limits on Windows.

InstallHomebrew and run these commands:

xcode-select --installbrew install cmake ninjabrew install --cask gcc-arm-embedded

Then follow themanual setup instructions.

If you haveapt, then running thepico_setup.sh script should hopefully work for you, and you won't need to do any manual setup.

If it doesn't work, or you don't haveapt, then you can manually install theGIT_DEPS (git &git-lfs) andSDK_DEPS (cmake,gcc-arm-none-eabi,gcc,g++ &ninja-build) from the script. You may also need to install a cross-compilednewlib if it isn't included ingcc-arm-none-eabi, such aslibnewlib-arm-none-eabi &libstdc++-arm-none-eabi-newlib. Once those are installed, follow themanual setup instructions.

Run this from the path you want to store the SDK:

git clone https://github.com/raspberrypi/pico-sdk.gitgit -C pico-sdk submodule update --init

Then setPICO_SDK_PATH environment variable to that path - on MacOS or Linux, just add the following to your.zshrc (MacOS) or.bashrc file:

export PICO_SDK_PATH=/path/to/pico-sdk

then reload your terminal window.

On Windows, from an administrator PowerShell run:

[System.Environment]::SetEnvironmentVariable('PICO_SDK_PATH','/path/to/pico-sdk','Machine')

Run this from the path you want to store picotool:

git clone https://github.com/raspberrypi/picotool.git

Then install libusb

• On Windows, download and extract libUSB from herehttps://libusb.info/ (hover over Downloads, and click Latest Windows Binaries), and set LIBUSB_ROOT environment variable to the extracted directory.
• On MacOSbrew install libusb
• On Linuxsudo apt install libusb-1.0-0-dev

Then build and install picotool using these commands:

cd picotoolcmake -S. -B buildcmake --build buildsudo cmake --install.

To use picotool without sudo on Linux, you'll also need to install the picotool udev rules from the picotool/udev folder.

For more details on building & installing picotool, see itsREADME

Clone pico-examples:

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

Build them all, replacing all occurences of$board with the pico board you are using:

cmake -S. -B build_$board -GNinja -DPICO_BOARD=$board -DCMAKE_BUILD_TYPE=Debugcmake --build build_$board

The cmake-S flag indicates the source directory, and the-B flag tells cmake thename of the output-directory to create, which is then supplied to the--build flag

Put your board in BOOTSEL mode and usepicotool to load the blink example:

picotool load build_$board/blink/blink.uf2 -vx

You should now have a blinking LED on your board.