Parrot Cart developersGet a Parrot Cart

Examples

Each example is a small plugin that shows one thing. Start from the one closest to what you want to make.

  • Hello

    src

    Hello is the smallest plugin for Parrot Cart, the ColecoVision SD cartridge. It puts text on the TV and shows what you’re doing with the console’s controller.

    Code on GitHub

  • Screen Example

    examples/screen

    Shows text and tile graphics on the TV, with the font at two sizes, the console’s 15 colors, a map made of 8x8 tiles, and a moving ball.

    Code on GitHub

  • Sound Example

    examples/sound

    Plays notes on one voice of the ColecoVision’s sound chip, and a drum on its noise voice.

    Code on GitHub

  • Game Pad Example

    examples/usb-gamepad

    Shows what a USB game pad is doing, with its buttons, both sticks, and the four directions a game would read.

    Code on GitHub

  • Keyboard Example

    examples/usb-keyboard-mouse

    Shows what you type on a USB keyboard, and moves a pointer on the TV with a USB mouse.

    Code on GitHub

  • MIDI Out Example

    examples/usb-midi-out

    Turns the cart into a USB MIDI device. Plug the cart’s USB-C port into a computer, and it shows up as a MIDI input called Parrot Cart MIDI Example. The keypad then plays notes on any music app that’s listening.

    Code on GitHub

  • SD Card Example

    examples/sd-card

    Lists the card’s top folder and shows the start of the first file. It also counts how many times it has run in a 512-byte save file, /SDCARD.SAV, which it makes the first time. You can delete that file whenever you like.

    Code on GitHub

  • Text Viewer

    examples/open-file

    Opens .txt files. Pick one in the menu and press the fire button to see its first 8 KB, 30 columns wide.

    Code on GitHub

  • Frames Example

    examples/frames

    Color bars and a bouncing ball, drawn on the cart 60 times a second. Each TV frame, it sends the console one command list, the same way the emulator plugins do.

    Code on GitHub

  • PSRAM Example

    examples/psram

    Tests the cart’s 8 MB of PSRAM. It fills the PSRAM with a pattern, reads it back, and shows how long each step took.

    Code on GitHub

Building the examples

cmake -S examples -B build-examples -G Ninja -DPICO_SDK_PATH=$HOME/pico-sdk
ninja -C build-examples            # build-examples/<folder>/EX....CVP
test/run.sh                        # all of them on the Mac (docs/testing.md)

The SDK’s cvusb does what the three USB examples do, and MIDI in as well. You turn each feature on with one word in CMake (docs/features.md), and tools/new-plugin.py can write a plugin with any of them working. The keyboard and MIDI examples call TinyUSB directly, for a plugin that needs that. The game pad example uses only cvpad, the SDK’s game pad library.

To start your plugin from an example, copy its files over src/, and copy its CMakeLists.txt lines into the top CMakeLists.txt in place of the ones there (main.c becomes src/main.c, and so on). Then change the ID.

Two kinds of plugin

Plugins on the screen kernel (parrotcart_screen(), used by every example except frames) draw into a canvas whenever they like, and the SDK sends the console what changed, one list at a time. Sound is the chip’s 10 bytes, sent when they change, and the console’s controller comes in as reports. The screen kernel is a good fit for tools, menus, viewers, players, and turn-based or slow-moving games.

Plugins on the frame kernel (parrotcart_frames(), used by frames) give the console one command list every TV frame, and choose exactly which bytes of video memory and which sound-chip bytes go out in it. The frame kernel is a good fit for emulators, video and fast games. It has no canvas or font, so you encode the picture yourself (our NES plugin has a full encoder).

Each plugin uses one kernel or the other, never both.

What isn’t in the SDK

  • A way for a plugin to go back to the menu by itself. To go back, press RESET on the console or switch it off. The frame kernel has cvf_menu_now() for a plugin that can’t continue, but it isn’t a clean exit, because the console is left running the plugin’s kernel.
  • Sprites, scrolling or a text console. The screen kernel shows a bitmap, and the frame kernel shows whatever you send it.
  • A way to ask the menu for a second file. A plugin gets one file when it starts, but it can list folders and open other files itself (sd-card).

This page is examples/README.md in the starter kit.