RP2040

Published Oct 31, 2023

Raspberry Pi Pico

Introduction

The RP2040 is the first microcontroller, or microcontroller unit (MCU), from the Raspberry Pi Foundation. As the RP2040 is not a microprocessor, it differs from the Raspberry Pi in that it cannot run a full operating system; rather, developers program the chip using compiled C/C++ or MicroPython code, similar to the Arduino development platform.

This tutorial assumes that the RP2040 development environment is being built on either macOS or a Debian-based Linux distribution, such as Ubuntu or Pop!_OS. Instructions for Windows can be found in the C/C++ SDK setup documentation.

Resources

The following web resources contain detailed information on the RP2040 and its C/C++ software development kit (pico-sdk).

Setup

This setup procedure is a consolidated version of the instructions from the C/C++ SDK setup documentation. These instructions are the same for macOS and Linux, with the exception of the build toolchain installation.

Clone the RP2040 C/C++ SDK

Clone the pico-sdk GitHub repository and update its submodules:

mkdir -p ~/Code/pico
cd ~/Code/pico
git clone -b master https://github.com/raspberrypi/pico-sdk.git
cd pico-sdk
git submodule update --init

At the time of writing, the submodule update command is needed to enable USB functionality. Failure to run this command may prevent RP2040 flashing with the UF2 bootloader!

In the future, to get the latest updates or releases for the SDK:

git pull
git submodule update

Before moving forward, we need to create an environment variable that contains the path to the pico-sdk directory, which the build tools will reference during compilation. To find the absolute path to the SDK:

pwd

Copy this path and paste it into the export command to set the PICO_SDK_PATH environment variable:

# replace the path with the output from pwd
export PICO_SDK_PATH=$HOME/Code/pico/pico-sdk

Note that this command will have to be executed each time a new terminal window is opened, or the environment reloaded. To avoid this hassle, follow the instructions below to autogenerate the environment variable.

To add PICO_SDK_PATH to the user profile:

echo 'export "PICO_SDK_PATH=$HOME/Code/pico/pico-sdk"' >> ~/.zshrc

To confirm environment variable preservation:

source ~/.zshrc
echo $PICO_SDK_PATH

Build toolchain

Pay attention to the below instructions, which differ for macOS and Linux!

Linux

To build source files, install the necessary toolchain packages:

sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential libstdc++-arm-none-eabi-newlib

macOS

brew install cmake
brew tap ArmMbed/homebrew-formulae
brew install arm-none-eabi-gcc

Configuring VS Code

VS Code is the recommended text editor for writing source code for the RP2040.

Install the extensions needed for debugging the RP2040:

code --install-extension maus25.cortex-debug
code --install-extension ms-vscode.cmake-tools
code --install-extension ms-vscode.cpptools

When first opening a project directory in VS Code, a popup will prompt user configuration. After selecting “Yes,” a dropdown menu will present a list of configuration options. Click on the option “GCC arm-non-eabi.”

Blinking an LED

Blinking an LED is the classic “Hello World” demo in the hardware space. To program the onboard LED to blink repeatedly, first create a dedicated source code directory:

mkdir ~/Code/pico/blink
cd ~/Code/pico/blink

Create a file called blink.c and paste the following source code:

/*
    Blink
    Switches LED on for one second, then off for one second, repeatedly
*/

#include "pico/stdlib.h"

int main() {
    // set led pin
    const uint LED_PIN = PICO_DEFAULT_LED_PIN;
    gpio_init(LED_PIN);
    gpio_set_dir(LED_PIN, GPIO_OUT);

    while(1) {
        // toggle led on and off
        gpio_put(LED_PIN, 1);
        sleep_ms(1000);
        gpio_put(LED_PIN, 0);
        sleep_ms(1000);
    }
}

Add another file named CMakeLists.txt and paste the following code:

# set minimum required version of CMake
cmake_minimum_required(VERSION 3.13)

# include build functions from Pico SDK
include($ENV{PICO_SDK_PATH}/external/pico_sdk_import.cmake)

# set project name and C/C++ standards
project(blink C CXX ASM)
set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)

# create a pico-sdk subdirectory in project for libraries
pico_sdk_init()

# direct CMake to executable source file
add_executable(${PROJECT_NAME}
    main.c
)

# create map/bin/hex/uf2 outputs
pico_add_extra_outputs(${PROJECT_NAME})

# link libraries
target_link_libraries(${PROJECT_NAME}
    pico_stdlib
)

# enable usb output, disable uart output
pico_enable_stdio_usb(${PROJECT_NAME} 1)
pico_enable_stdio_uart(${PROJECT_NAME} 0)

Create a build directory to store the binaries:

mkdir ~/Code/pico/blink/build
cd ~/Code/pico/blink/build

Run the build process:

cmake ..
make

When the build process completes, there should be a selection of new files added to the project directory. The file with extension .uf2 contains the program code and data in UF2 form—a file format created by Microsoft—that can be dragged onto the RP2040 board when mounted as a USB device.

To mount the RP2040 as a USB device, press and hold the BOOT button before connecting the board to the PC via USB. Depending on the board, this button may have a variation of its name.

To complete the flashing process, either drag and drop the .uf2 file onto the device or copy manually:

# confirm device mounting (replace user with home directory name)
ls /media/user # should return "RPI-RP2"
# copy compiled source code
sudo cp blink.uf2 /media/user/RPI-RP2
sudo sync
sudo unmount /media/user/RPI-RP2

lukasvasadi © 2025