Microfirmware Store

What you are installing, and why

Four separate things, doing four separate jobs. Knowing which is which before you start helps, because when something breaks you need to know who to blame.

You also need the ordinary things a C project needs, git, cmake and make, plus picotool, which copies your built firmware onto the board. Install those the way you normally would on your system. Raspberry Pi's own documentation is the authority for the rest:

• The C/C++ SDK covers the ARM toolchain, OpenOCD and the CMake setup, per platform.
• raspberrypi/picotool is where picotool comes from, with build and install instructions.
• Pico-series boards documents the hardware itself. The Pico W is the one this board uses.

Where the Pico SDKs come from

There are two ways to have the SDKs on your machine. Understand which one you are doing, because it decides what your environment variables point at.

Set the environment variables

Fewer of these are mandatory than you might expect, because the template fills in most of them itself. Only one is always required:

Set whichever apply in your shell profile so they survive a new terminal. Exporting them once in a single session is the classic way to get a confusing failure two days later.

# required
export PICO_TOOLCHAIN_PATH=/path/to/arm-none-eabi/bin

# only if you are not using the template's submodules
export PICO_SDK_PATH=/path/to/pico-sdk
export PICO_EXTRAS_PATH=/path/to/pico-extras
export FATFS_SDK_PATH=/path/to/fatfs-sdk

# only for the debugger, step 9
export ARM_GDB_PATH=/path/to/arm-none-eabi/bin
export PICO_OPENOCD_PATH=/path/to/openocd/tcl

# required
$env:PICO_TOOLCHAIN_PATH="C:\Path\to\arm-none-eabi\bin"

# only for the debugger, step 9
$env:ARM_GDB_PATH="C:\Path\to\arm-none-eabi\bin"
$env:PICO_OPENOCD_PATH="C:\Path\to\openocd\tcl"

The Atari cross-compiler

The 68000 half of your microfirmware is built with vasm and vlink, wrapped in a Docker image so you do not have to build them yourself. Install Docker, then set up atarist-toolkit-docker following its README. It gives you a command called stcmd that runs the Atari tools inside the container.

THEDOCKER="logronoide/atarist-toolkit-docker-x86_64:latest"

Confirm Docker itself is running before you go further. A stopped Docker daemon produces build errors that look nothing like "Docker is not running".

docker run --rm hello-world

VS Code and its extensions

The templates include a .vscode/ directory with build and debug configuration that expects these four extensions. Install all of them:

• C/C++ Extension Pack, language support for the C half.
• CMake and CMake Tools, which drive the build.
• Cortex-Debug, to step through code on the microcontroller over the Debug Probe.

You can write a microfirmware in any editor, but the debugging setup in step 9 assumes VS Code and Cortex-Debug, and it is much less pleasant to reconstruct by hand. Raspberry Pi also publish an official Pico extension for VS Code, described in the C/C++ SDK guide .

Check it worked

Work down this list before moving on. Every item is something a later step silently depends on.

• PICO_TOOLCHAIN_PATH survives a new terminal Open a fresh terminal and run echo $PICO_TOOLCHAIN_PATH, or echo $env:PICO_TOOLCHAIN_PATH in PowerShell. An empty line means it is not set, and the build will fail looking for arm-none-eabi-gcc.
• cmake --version and make --version both answer Any recent version is fine.
• Docker is running and stcmd is on your PATH The 68000 half cannot build without it.
• picotool is installed This is how you get the built firmware onto the board in step 6.
• VS Code has all four extensions C/C++ Extension Pack, CMake, CMake Tools, Cortex-Debug.

I'm setting up a Raspberry Pi Pico W build environment on <your OS and version>.
I need PICO_TOOLCHAIN_PATH set permanently to my ARM GNU Toolchain's
arm-none-eabi/bin directory, plus cmake, make and picotool installed.
Here is what I ran and the error I got:

<paste the command and the full error>

What is missing, and what exactly should I run to fix it?