Parrot Cart developersGet a Parrot Cart

Getting started

If you use Claude Code, the starter kit comes with a skill that helps Claude write, test and release your plugin.

A Parrot Cart plugin is a program that runs on the cart. The cart uses the RP2350, the same chip as the Raspberry Pi Pico 2. You build a plugin into a single .CVP file and copy it to the /PLUGINS folder on the SD card, and the cart’s menu lists it there for you to start. You can build plugins on a Mac or a Linux computer with the same free tools a Pico project uses.

1. Tools

ToolVersionFor
Arm GNU toolchain (arm-none-eabi-gcc)9 or later (developed with 9.2.1)compiling for the cart
CMake, NinjaCMake 3.13 or laterthe build
Python 33.8 or later, no packagespacking the .CVP, the README, the tools
sjasmplus1.20 or later (developed with 1.23.1)assembling the SDK’s Z80 kernels
pico-sdk2.1.1the chip’s SDK
picotool2.3.1 (2.1.1 makes a different, 512 KB image)packaging. Install it, because without it pico-sdk 2.1.1 downloads and builds picotool’s development branch instead

macOS, with Homebrew:

brew install cmake ninja sjasmplus picotool
brew install --cask gcc-arm-embedded

Debian or Ubuntu:

sudo apt install cmake ninja-build python3 build-essential \
    gcc-arm-none-eabi libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib
# sjasmplus isn't packaged: build it
git clone --depth 1 -b v1.23.1.1 --recurse-submodules https://github.com/z00m128/sjasmplus
make -C sjasmplus && sudo make -C sjasmplus install
# and picotool, from https://github.com/raspberrypi/picotool (tag 2.3.1),
# built against pico-sdk 2.3.1 with its mbedtls, as tools/ci/setup.sh does

tools/ci/setup.sh runs exactly these steps. The GitHub workflows use it on Ubuntu 24.04.

Clone the pico-sdk wherever you like. You don’t need its submodules, because the cart’s SDK comes with TinyUSB:

git clone --depth 1 -b 2.1.1 https://github.com/raspberrypi/pico-sdk ~/pico-sdk

2. Build

cmake -B build -G Ninja -DPICO_SDK_PATH=$HOME/pico-sdk
ninja -C build

The last line it prints is the plugin file:

build/HELLO.CVP: Hello 0.1.0 (yourname.hello), image 55552 bytes from 0x10e00000

If you add export PICO_SDK_PATH=$HOME/pico-sdk to your shell’s profile, you won’t need to type it each time. You can also use -DPICO_SDK_FETCH_FROM_GIT=ON instead, and the build downloads pico-sdk 2.1.1 into the build folder.

You build all the examples at once the same way:

cmake -S examples -B build-examples -G Ninja -DPICO_SDK_PATH=$HOME/pico-sdk
ninja -C build-examples

3. On the cart

  1. Put the SD card in your computer and copy the .CVP into its /PLUGINS folder. If the card doesn’t have that folder yet, make it.
  2. Put the card back in the cart and turn the console on. In the menu, press B in the card’s top folder to go to Home, then open Apps. Pick your plugin and press A to start it. The first time, the cart copies the plugin into its flash and shows how far it has got, in percent, on the bottom line. After that, it starts right away.
  3. Press RESET on the console to go back to the menu.

The Plugin Manager on Home lists everything in /PLUGINS with its icon, name and version. Press A on a plugin there to see its details: the version, developer, ID and the files it opens. * shows its README. A folder in /PLUGINS, such as /PLUGINS/GAMES, gets a row on Home with the apps in it.

If your plugin opens files (OPENS .txt), it starts when you pick one of those files in the card’s folders and press A. It’s listed in Apps only if it can also start without a file (USES standalone, docs/plugin-rules.md).

To put a new build on the card, copy the new file over the old one. The cart copies a changed plugin into flash again. To remove a plugin, delete its file, or press # on its details page.

You don’t need to flash the cart from a computer to run a plugin, and a plugin that crashes can’t harm the cart. Press RESET, or turn the console off and on, to get back to the menu.

4. Make it yours

The quickest way is tools/new-plugin.py. It asks for the plugin’s name, your name, the screen and the features you want (game pads, a keyboard, a mouse, MIDI in and out, the PSRAM, saves). Then it writes a plugin that builds, with each feature working on the TV and YOUR CODE marking where your code goes:

tools/new-plugin.py                   # a new folder beside this one
tools/new-plugin.py --here            # this copy, in place of Hello

The new plugin leaves out examples/, unless you add --examples. Its license is MIT unless you pick another one. tools/new-plugin.py includes the full license text for MIT, BSD-2-Clause, BSD-3-Clause, ISC, Apache-2.0, GPL-2.0 and GPL-3.0 (each -only or -or-later) and LGPL-2.1-or-later. docs/features.md describes the features.

To do it by hand instead, edit this line in CMakeLists.txt:

cvcart_plugin(hello ID yourname.hello NAME "Hello" VERSION 0.1.0 BY "Your Name"
              ICON src/icon.txt README README.md)
  • ID stays the same for the life of your plugin, so pick it carefully (docs/plugin-rules.md).
  • ICON is the plugin’s icon (docs/icons.md).
  • README is the file the cart shows on the plugin’s details page (docs/readme-spec.md).
  • The target’s name (hello, which appears three times in the file) sets the output’s name, HELLO.CVP. To use a different file name, add FILE MYPLUGIN.CVP.

Then open src/main.c and read it from the top. Every plugin has the same basic shape. examples/README.md lists what each example shows, and sdk/firmware/revc/sdk/README.md is the SDK reference.

5. Try it without the console

sim/run.sh src             # your plugin in a window, with sound and controls
test/run.sh hello          # your plugin, on a model of the console
tools/screenshot.sh shot.png src 3000 "500:joy=up 1000:key=5"

The simulator needs SDL3. docs/simulator.md explains how to install it and which keys act as the controller. docs/testing.md covers the rest, including what you can only test on a real console.

Things that go wrong

What you seeWhy
sjasmplus: command not found during the buildsjasmplus isn’t installed. See section 1.
the plugin's .bss reaches the switch's reserved RAMThe plugin’s data is too big for the chip’s RAM. Move big buffers to the PSRAM (examples/psram).
links malloc: its heap would grow into the launch blockSomething calls malloc, new, or printf with a float. Remove that call, or add HEAP to cvcart_plugin() (sdk/.../cvheap.h).
a warning that the pico-sdk isn’t 2.1.1It will probably still work. We build and test the cart with 2.1.1.
on the TV: It needs newer cart firmwareThe plugin was built with a newer SDK than the cart’s menu supports. Update the cart’s firmware.
the plugin isn’t in AppsIt opens files and doesn’t have USES standalone, so it starts from its files and is listed only in the Plugin Manager. Or it’s two folders down in /PLUGINS (/PLUGINS/GAMES/OLD), where Home doesn’t look.
the plugin isn’t in the Plugin ManagerThe file isn’t in /PLUGINS, or its name doesn’t end in .CVP. If the menu can’t read it as a plugin, it’s listed under its file name instead.

This page is docs/getting-started.md in the starter kit.