Skip to content

Getting Started with Pico-Framework

Welcome to Pico-Framework, a lightweight but powerful application framework for Raspberry Pi Pico microcontrollers, in partciluar the Pico W and the Pico 2 W. This guide will help you set up your development environment and build your first application using the framework.

Before we get started, please recogzine that this platform is intended for professional developers, experienced embedded developers whether professional or enthusiast. It will also be of interest to embedded develpers that want to take advantage of FreeRTOS capabilities for the first time. It is not necessary to have FreeRTOS experience before using the framework, althought it will help. If you are an absolute beginner, this platform is probably not the right starting point as Arduino offers a much easier learning curve for beginners.

Having said all that. Try building the framework with the test app and try out some of the examples. You'll see how easy it is to build micro-applications with an MVC or MVP architecture witha few lines of code.

Introduction

This guide to getting started covers the tools, software, environment and building Pico_Framework applications. You will end up with a working build environment, flashing tools and a running demo. We’ll be building the test-app provided with the framework. You will also get advice on building the examples.

Of course, you’ll need a Pico W or Pico 2 W and it’s helpful but not necessary to have a Picoprobe for debugging and flashing.

Common Setup (All Platforms)

There is a set of software and tools that are required on all platforms (Linux, MacOS, Windows). In addition the environment setup is common. What tools are installed by default on your platform and how you install the tools are the variables between the platforms.

Tools

You will need the following tools for building applications. How you get these varies by platform, see Tool Installation below.

  • CMake – build configuration system
  • Ninja – fast build tool used by many Pico projects (alternative to make)
  • Git – source code management
  • Python 3 – required by SDK build scripts
  • Tar – used to unpack toolchain and SDK archives
  • GCC, G++ – native compilers (used to build host tools like pioasm and picotool)
  • gcc-arm-none-eabi – the compiler toolchain targeting bare-metal ARM devices

In addition, for flashing, you will need picotool or openocd with gdb (for debugging).

Visual Studio Code

If you plan to use an IDE, Visual Studio Code is the way to go as the Raspberry Pi Pico extension makes it easy to get going.

You’ll want to install the following extensions: - C/C++ - CMake Tools - Cortex-Debug (if debugging - you’ll need a Picoprobe or other programmer for this) - Python (optional)

Using the CMake extension means that Code will use the CMakelists.txt file (CMake build control) as its build input. When you hit build in the bottom panel, CMake is invoked using CMakeLists.txt as its input.

Tip: You can still use the integrated terminal to run cmake or ninja manually inside VS Code.

Tools for Flashing

Up to now, we have been concerned with how to get C/C++ source code built into an executable, the output from the build is a .elf or .uf2 executable file.

The simplest way to get an executable onto the Pico is to simply hold down the Bootsel button and plug it into a USB port. It will appear as a removable drive. Simply drop the .uf2 file on the drive and it will be flashed.

However, this is not the optimal way of flashing and there are two tools that can be used to flash the Pico without having to resort to unplugging the device etc.

The first is Picotool, this has many capabilities and one of them is being able to flash the Pico. This can be performed without putting the Pico into boot mode.

The second is openocd, this is the same tool that is used for debugging and prior to a debugging session or even without a debugging session, it can be used to flash the device.

Both of these tools can be obtained from https://github.com/raspberrypi/pico-sdk-tools. Select releases and get the latest stable versions as binaries to save building them.

Note: The system-installed version of openocd (e.g., via apt or brew) may work fine, but it may not include the required interface/ and target/ config scripts for the Raspberry Pi Pico. These can be found with the openocd binary in the github repo above.

While you are in that repo, get the pioasm binary, which is required to use PIO capabilities used by the SDIO drivers.

If you are planning to use littlefs and to flash a littlefs partition as part of your application you will need mklittlefs. You can get a binary for your platform from https://github.com/earlephilhower/mklittlefs in Releases.

Summary of Additional Tools

In summary, here are the additional tools:

  • Picotool – flashing using USB – https://github.com/raspberrypi/pico-sdk-tools
  • Openocd – flashing using picoprobe – https://github.com/raspberrypi/pico-sdk-tools
  • Pioasm – compiling PIO programs – https://github.com/raspberrypi/pico-sdk-tools
  • Mklittlefs – flashing littlefs partitions – https://github.com/earlephilhower/mklittlefs

Software

There are three repos required to build Pico-Framework applications: - pico-sdk – https://github.com/raspberrypi/pico-sdk - FreeRTOS-Kernel – https://github.com/FreeRTOS/FreeRTOS-Kernel - pico-framework – https://github.com/Pico-Framework/pico-framework

In each case, you must update each of the submodules:

git clone {repo url}
git submodule update –init –recursive

In the case of pico-sdk, if you do not update the submodules you will not bring in the third-party support for lwip (networking stack) or mbedtls (encryption/TLS).

In the case of the FreeRTOS kernel, there will be no raspberry pi pico ports if you don’t update the submodules because they are part of a submodule.

Pico-Framework is dependent on nlohmann json, littlefs and FreeRTOS-FAT-CLI-for-RPi-Pico and these are installed as submodules. You can find these repos on Github here:

  • FreeRTOS-FAT-CLI-for-RPi-Pico – https://github.com/carlk3/FreeRTOS-FAT-CLI-for-RPi-Pico
  • nlohmann/json – https://github.com/nlohmann/json
  • littlefs – https://github.com/littlefs-project/littlefs

There’s no special location required for the software, you’ll use environment variables so that they can be located at build time.

Environment

There are some environment variables that need to be set to enable tools and software to be located during a build. These are:

Software

  • PICO_SDK_PATH – location of the Pico SDK
  • FREERTOS_KERNEL_PATH – location of the FreeRTOS-Kernel
  • PICO_FRAMEWORK_PATH – location of the Pico-Framework

Tools

Note that apart from pioasm all these tools are used for flashing. You don’t need both picotool and openocd but I am often switching between testing and debug environments and like the flexibility of using either.

Setting picotool_DIR and pioasm_DIR is not essential but will avoid fetching sources and rebuilding these tools in every build. It also removes a compilation of building host tools and target software in the same build (requiring different compilers).

  • picotool_DIR – path to picotool binary
  • pioasm_DIR – path to pioasm binary
  • OPENOCD_EXECUTABLE – path to the OpenOCD binary
  • PICO_OPENOCD_SCRIPTS – path to the OpenOCD scripts/ directory
  • MKLITTLEFS_EXECUTABLE – path to the mklittlefs binary

Board

  • PICO_BOARD – set to pico_w or pico2_w

Wi-Fi

  • WIFI_SSID – name of the Wi-Fi network your application will connect to
  • WIFI_PASSWORD – password for the Wi-Fi network

JWT Encryption

  • JWT_SECRET – token used for signing JWTs (optional, but recommended if using JWT authentication)

Platform-Specific Setup

Linux

The following tools are often already present on a fresh Debian 12 install:

  • CMake – build configuration system
  • Ninja – fast build tool used by many Pico projects (alternative to make)
  • Git – source code management
  • Python 3 – required by SDK build scripts
  • Tar – used to unpack toolchain and SDK archives
  • Gcc, g++ – native compilers (used to build host tools like pioasm and picotool)

If not installed on your distro, you can install them with:

sudo apt update
sudo apt install build-essential cmake ninja-build git
sudo apt install python3 tar

build-essential includes gcc, g++, make, and other required toolchain components.

The ARM cross-compiler is not installed by default and is required to build firmware that runs on the Pico:

  • Gcc-arm-none-eabi – the compiler toolchain targeting bare-metal ARM devices

You will need to install it:

sudo apt install gcc-arm-none-eabi

For newer versions, you can download the latest toolchain directly from Arm Developer.

To install Microsoft Visual Studio Code:

sudo apt install code

Or use the .deb package from https://code.visualstudio.com.

macOS

The following tools are typically installed using Homebrew. If you don’t already have it installed, follow the instructions at https://brew.sh.

You’ll need the following tools:

  • CMake – build configuration system
  • Ninja – fast build tool used by many Pico projects (alternative to make)
  • Git – source code management
  • Python 3 – required by SDK build scripts
  • Tar – used to unpack toolchain and SDK archives
  • Gcc-arm-none-eabi – the compiler toolchain targeting bare-metal ARM devices

Install them using Homebrew:

brew install cmake ninja git python
brew install --cask gcc-arm-embedded

Note: tar is included by default on macOS and does not need to be installed.

To install Microsoft Visual Studio Code:

brew install --cask visual-studio-code

Or download it from https://code.visualstudio.com.

After installation, launch VS Code and install the following extensions:

  • C/C++
  • CMake Tools
  • Cortex-Debug (if debugging – you’ll need a Picoprobe or other programmer for this)
  • Python (optional)

Tip: You can still use the integrated terminal to run cmake or ninja manually inside VS Code.

Note on OpenOCD

If you install OpenOCD using Homebrew:

brew install openocd

It may work fine with the Pico but typically does not include the necessary interface/ and target/ scripts. You should manually download them from the Raspberry Pi OpenOCD GitHub repo:
https://github.com/raspberrypi/openocd

Then set the PICO_OPENOCD_SCRIPTS environment variable to point to the scripts/ directory.

Download mklittlefs from: https://github.com/earlephilhower/mklittlefs

Place it in your PATH or set MKLITTLEFS_EXECUTABLE.

Windows

On Windows, you will need to manually install some tools or use a package manager like Chocolatey.

The following tools are required:

  • CMake – build configuration system
  • Ninja – fast build tool used by many Pico projects (alternative to make)
  • Git – source code management
  • Python 3 – required by SDK build scripts
  • Gcc-arm-none-eabi – the compiler toolchain targeting bare-metal ARM devices

Option 1: Install via Chocolatey

If you have Chocolatey installed, open an Administrator Command Prompt or PowerShell and run:

choco install cmake ninja git python vscode
choco install gcc-arm-embedded

Option 2: Manual Installation

Download and install:

Extract/install and add the bin/ directory to your system PATH.

Download mklittlefs from: https://github.com/earlephilhower/mklittlefs

Environment Variables

Linux/macOS

Set via .bashrc, .zshrc, or equivalent:

  • PICO_SDK_PATH
  • FREERTOS_KERNEL_PATH
  • PICO_FRAMEWORK_PATH
  • PICO_BOARD, WIFI_SSID, WIFI_PASSWORD, JWT_SECRET
  • OPENOCD_EXECUTABLE, PICO_OPENOCD_SCRIPTS, MKLITTLEFS_EXECUTABLE
  • picotool_DIR, pioasm_DIR

Windows

Control Panel → System → Advanced → Environment Variables → User/System variables:

  • Same keys as listed above.

You may need to restart VS Code or your terminal.

Building and Running the Pico-Framework Examples

There are a set of examples provided as part of the Pico-Framework. We’ll walk through the minimum example.

Step 1: Choose an Example

Navigate to the example you want to build. For this guide, we’ll use minimum:

cd pico-framework/examples/minimum

Step 2: Configure the Build

Use CMake to configure the project:

cmake -B build -G Ninja [-DFLASH_METHOD=usb|openocd] [-DCMAKE_BUILD_TYPE=Release|Debug]

This tells CMake to generate build files into the build/ directory using the Ninja build system in Release or Debug mode and flash using either the default usb or openocd.

Step 3: Build the Application and Flash the Firmware

From the same directory:

cmake --build build --target flash_all

This builds the firmware and flashes the target.

Notes on Flashing Requirements

If using picotool:

  • Connect via USB
  • No need to hold BOOTSEL (framework reboots via -f)
  • Ensure picotool is in your system PATH

If using openocd:

  • Connect via SWD (Picoprobe/CMSIS-DAP)
  • Set OPENOCD_EXECUTABLE and PICO_OPENOCD_SCRIPTS
  • scripts/ must contain:
  • interface/cmsis-dap.cfg
  • target/rp2040.cfg or target/rp2350.cfg

Documentation