Skip to content

Getting Started with PicoFramework

Welcome to PicoFramework, 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.

1. Choose Your Starting Point

If you're already developing with the Pico SDK:

You likely already have:

  • The Arm GNU Embedded toolchain installed
  • The PICO_SDK_PATH environment variable set
  • PicoTool installed and available in your path
  • A working build setup using CMake

You can skip directly to Section 3 — Clone and Build Test App

If you're new to Pico development:

Start with the official Raspberry Pi guide:

Getting Started with Raspberry Pi Pico (PDF)

This will walk you through:

  • Installing the Arm toolchain
  • Setting up the Pico SDK
  • Building a sample app using command-line tools or VS Code

Once that is working, return here.

2. Install Dependencies

Required:

  • CMake >= 3.13
  • GNU Arm Embedded Toolchain (e.g. arm-gnu-toolchain-12.2.rel1 or newer)
  • Pico SDK
  • Picotool
  • FreeRTOS
  • Python 3 (optional, only for memory reporting tool)
  • Git

You must also set the following environment variables. You will not be able to build or use Wi-Fi without these variables set. There is an additional environment variable that is used with JWT tokens and that JWT_SECRET. But until you try out the route_aurthorization example you won't need it.

export PICO_SDK_PATH=$HOME/pico-sdk
export FREERTOS_KERNEL_PATH=$HOME/freertos-kernel
export WIFI_SSID={your ssid}
export WIFI_PASSWORD={your password}

🚨 FREERTOS_KERNEL_PATH is required but FreeRTOS-Kernel is not included in the repo. Clone it from: https://github.com/raspberrypi/FreeRTOS-Kernel

This is the Raspberry Pi version of the FreeRTOS kernel and the one I prefer to use even though the ports for both the rp2350 and rp2040 have been merged upstream to FreeRTOS.

3. Clone and Build Pico-Framework with its Test App

git clone https://github.com/pico-framework/pico-framework.git
cd pico-framework

# Pull in required submodules (pico-sdk)
git submodule update --init --recursive

This will install framework dependencies:

FreeRTOS-FAT-CLI-for-RPi-Pico littlefs nlohmann/json

Then build:

cd framework
mkdir build && cd build
cmake .. -DPICO_BOARD=pico_w -DCMAKE_BUILD_TYPE=Release
make -j

Flashing (UF2 Method):

  1. Hold BOOTSEL on your Pico and plug it into USB.
  2. Copy framework-test.uf2 to the mounted drive.

Flashing using Picotool

picotool load framework-test.uf2 -f

alternately use the flash target in the CMakeLists.txt

cmake --build . --target flash

4. VS Code Setup

You will need vscode installed as well as openocd for flashing and debugging. The easiest way to setup the toolchain is to use the Rapsberry Pi Pico extension to vscode as it will install the dependencies for you and if you make one of the examples it will create the necessary launch file in vscode to flash and run the code. You can copy that launch file into your own projects. It is also a lot easier to use a Pico Probe for flashing and debugging, I recommend it.

  1. Open the project folder in VS Code
  2. Install the CMake Tools and Cortex-Debug extensions (if not already there)
  3. Add your environment variables to your VS Code environment (or system profile)
  4. Press Ctrl+Shift+P > "CMake: Configure"
  5. Build and flash using the UI
  6. To run

Ensure your settings.json or terminal profile contains:

"terminal.integrated.env.osx": {
  "PICO_SDK_PATH": "/Users/yourname/pico-sdk",
  "FREERTOS_KERNEL_PATH": "/Users/yourname/freertos-kernel"
}

5. Run and Access the App

  • On boot, the device connects to Wi-Fi (see serial output)
  • It prints the assigned IP address
  • Open http://<ip-address> in your browser to see the dashboard

6. Explore Other Examples

After verifying test-app, try the other examples:

sprinkler-app

  • Wi-Fi sprinkler controller with authenticated API and GPIO scheduling

ping-pong-app

  • Networked HTTP client/server communication between devices

Each example has its own build/ process:

cd examples/sprinkler-app
mkdir build && cd build
cmake .. -DPICO_BOARD=pico_w
make -j

7. Documentation

8. Troubleshooting

Problem Solution
PICO_SDK_PATH not set Make sure you export it in your terminal or VS Code
FREERTOS_KERNEL_PATH missing Clone https://github.com/FreeRTOS/FreeRTOS-Kernel and export the path
Wi-Fi not connecting Check your wifi_config.h settings
Flash fails Ensure board is in BOOTSEL mode, or use picotool manually

9. Get Involved

  • Star the project on GitHub
  • Submit issues and PRs
  • Share what you build!