Parrot Cart developersGet a Parrot Cart

Features you can turn on

You turn on the features your plugin uses with one line of CMake. Each feature adds its code, sets up the USB port with only what that feature needs, and adds its flag to the .CVP’s USES. Features you don’t turn on add no code to your plugin.

cvcart_features(myplugin PADS KEYBOARD MOUSE MIDI_IN MIDI_OUT PSRAM CARD)

Put it before cvcart_plugin(). tools/new-plugin.py writes this line for you, and puts working code for each feature in src/main.c so you can see it on the TV:

tools/new-plugin.py                         # asks, a question at a time
tools/new-plugin.py --name "Star Sweeper" --by "Ann" \
    --features pads,keyboard,midi-in --screen text

The new plugin leaves out the kit’s examples/, unless you add --examples. The examples named below are in the kit.

FeatureWhat plugs inThe USB portUSES
PADSup to two game padshostusb-host
KEYBOARDa USB keyboardhostusb-host
MOUSEa USB mousehostusb-host
MIDI_INa USB MIDI keyboard, or any class-compliant MIDI devicehostusb-host
MIDI_OUTa computer, with the cart as a MIDI device on itdeviceusb-device
PSRAMnothing (it’s the cart’s 8 MB PSRAM)psram
CARDnothing (it’s the SD card, for files and saves)

tools/new-plugin.py --name "Feature Test" --by You --features all makes a plugin with every feature turned on and every input shown on the TV. It’s a quick way to try a pad, a hub or a keyboard on the console.

The USB port: host or device

The cart’s USB port works as either a host or a device.

  • As a host, it’s for PADS, KEYBOARD, MOUSE and MIDI_IN. The cart can’t power what’s plugged in, so put a powered USB hub between the devices and the cart. A hub can take several devices at once, such as two pads, a keyboard, a mouse and a MIDI keyboard together. The SDK finds what’s already on the hub when the plugin starts, and what’s plugged in or pulled out while it runs, so a plugin only reads its devices. Some hubs never report a change, so it reads every hub’s ports every 100 ms.
  • As a device, it’s for MIDI_OUT. The cart shows up as a MIDI port on a computer, named after the plugin.

If you turn on host features and MIDI_OUT together, the port starts as a device. If a computer connects to the cart within 1.5 seconds, the port stays a device. Otherwise (with a hub, or with nothing at all), it becomes a host. A Mac asks its user before it accepts a new MIDI device (“Allow accessory to connect?”). While the Mac is asking, the port waits for up to a minute, and cvusb_mode() returns CVUSB_ASKING. Show that on the screen, and let a button call cvusb_host_now() to stop waiting. The port picks host or device once, at the start.

MIDI works in both directions on whichever MIDI connection there is. As a device, cvusb_midi_read() gets what the computer sends, and cvusb_midi_send() sends to the computer. As a host with MIDI_IN, both talk to the MIDI keyboard.

The calls

They’re all in sdk/firmware/revc/sdk/cvusb.h:

#include "cvusb.h"

cvusb_start();                  // once, after cvk_start() or cvf_start()
for (;;) {
    cvusb_task();               // every pass of the loop: it never waits
    ...
}

If you call a function for a feature that’s turned off, the build fails with an error that names the feature, such as turn on KEYBOARD in cvcart_features().

Game pads: PADS

gamepad_t p;
if (cvusb_pad(0, &p)) {         // pad 0 or 1: false if it isn't there (yet)
    p.buttons                   // GP_SOUTH, GP_EAST, GP_UP, GP_L, GP_ZR ... held (gamepad.h)
    p.lx, p.ly, p.rx, p.ry      // the sticks, -2048..2047, y up
}
cvusb_pad_kind(0)               // "SWITCH PRO" or "HID PAD": what it is
cvusb_pad_dirs(&p)              // GP_UP GP_DOWN GP_LEFT GP_RIGHT: the d-pad, or the left stick past about 40%

Buttons are named by where they are, so GP_SOUTH is the bottom face button (B on a Nintendo pad, A on an Xbox one). The Switch Pro Controller, pads in Switch mode and plain HID pads are supported. A Switch pad takes a moment to start after it’s plugged in, so cvusb_pad_kind() can name it before cvusb_pad() returns it. The triggers are buttons (GP_ZL, GP_ZR). On a PS4 pad, Share is GP_MINUS and Options GP_PLUS.

On a console, the cart has been tried with the Switch Pro Controller, a PS4 controller, 8BitDo pads in their Switch mode, and an Anker hub with a Genesys GL3523 chip. That hub never reports a change, which is why the SDK reads the ports. With it, a pad was found when plugged in, when pulled out, and when it was already on the hub at RESET.

cvinput.h puts USB pad 1 together with the console’s controller, for plugins that want one set of controls. The arcade plugins’ keys are in the Claude skill’s porting notes, .claude/skills/parrot-cart-plugin/references/porting.md (“Arcade games”).

The keyboard: KEYBOARD

cvkey_t k;
while (cvusb_key(&k)) {         // each key as it goes down and as it comes up
    k.usage                     // the key's USB code: 0x04 is A, 0x28 Enter (HID's usage table)
    k.ascii                     // its character on a US keyboard, 0 for none (the arrows, F1)
    k.mods                      // CVKEY_SHIFT, CVKEY_CTRL, CVKEY_ALT, CVKEY_GUI: held with it
    k.down                      // true: it went down
}

The modifier keys come in as keys too (usage 0xE0-0xE7). Up to 32 keys can be waiting to be read.

The mouse: MOUSE

cvmouse_t m;
if (cvusb_mouse(&m)) {          // false: no mouse
    m.dx, m.dy                  // how far it moved since the last call, y down
    m.wheel                     // the same, for the wheel
    m.buttons                   // 1 left, 2 right, 4 middle
}

MIDI: MIDI_IN, MIDI_OUT

uint8_t m[3];
int n;
while ((n = cvusb_midi_read(m)) > 0) {      // n bytes: m[0] the status (0x90 note on ... | channel)
    ...
}
const uint8_t note_on[3] = {0x90, 60, 100};
cvusb_midi_send(note_on, 3);    // whole messages (a SysEx too); false: nowhere to send it, or no room now

Incoming MIDI includes note, controller, program and pitch messages, the clock, and the other one-byte messages, but not SysEx. Up to 64 messages can be waiting, and cvusb_midi_dropped() counts any that didn’t fit.

The port

cvusb_mode()                    // CVUSB_HOST, CVUSB_DEVICE, CVUSB_WAITING, CVUSB_ASKING
cvusb_mode_name(cvusb_mode())   // "HOST", "ON A COMPUTER" ...: for the screen
cvusb_status_t s;
cvusb_status(&s);               // s.pads, s.keyboards, s.mice: how many; s.midi: a MIDI connection

As a host, the USB work runs every millisecond from a timer interrupt, so the pads are still read while your plugin is busy. If your plugin uses these calls, please don’t also call TinyUSB’s functions (tuh_*, tud_*) directly, since cvusb is already running TinyUSB for you.

Player 1: cvinput.h

cvinput.h combines the console’s controller and USB pad 1 into one player, for either kernel. With PADS on, a USB pad works like the console’s controller, the same way it does in the cart’s menu. The d-pad or left stick is the stick, B and A are the fire buttons, and X and Y are the keypad’s * and #. Without PADS, it reads only the console’s controller.

cvin_t in;
cvin_init(&in);
cvin_report(&in, kind, bits);   // the screen kernel: each cvk_report()
cvin_frame(&in, joy, fire, key);    // the frame kernel: each frame's cvf_input()
cvin_update(&in);               // once a step
in.held                         // CVIN_UP, CVIN_FIRE_L ...: down now
in.key                          // 0-9, CVIN_STAR, CVIN_HASH, or -1
cvin_pressed(&in), cvin_key(&in)    // what went down since you last asked

The PSRAM: PSRAM

if (cvpsram_init()) {           // once, at the start
    CVPSRAM_CACHED[i]           // a uint8_t pointer to all 8 MB
}

examples/psram has more.

The card: CARD

cvsd.h covers the card and its FAT or exFAT file system, reading files, and writing a file in place. examples/sd-card lists a folder and keeps a save file, and examples/open-file reads the file the menu started the plugin with. A plugin made by tools/new-plugin.py keeps its save in its home folder (HOME), or in /PLUGINS next to the plugin if it has no home folder. With --opens .ext, tools/new-plugin.py turns CARD on even without saves, and its src/main.c opens the file the menu started it with and shows the file’s name and size. That plugin doesn’t make its home folder, so the user needs to make it, or your plugin can make it with fs_mkdir() (fsro.h).

What it costs

A plugin runs from the cart’s RAM, which is about 500 KB, so its code uses RAM too. Here’s what each feature adds to a plugin with no features (GCC 9.2.1):

FeaturesCodeData
PADS41.7K4.8K
KEYBOARD32.5K3.8K
MOUSE30.2K3.7K
MIDI_IN28.9K3.4K
MIDI_OUT14.1K7.1K
PADS MIDI_OUT53.8K12.0K
all five USB features60.8K13.2K

Most of that is the USB host code, which the host features share, so each one after the first adds only a few KB. PSRAM and CARD only cost what your plugin calls.

Trying it on a Mac

test/run.sh builds your plugin’s code for the Mac and runs it against a model of the console and the USB port. It reads cvcart_features() from CMakeLists.txt, and its script can plug in devices (docs/testing.md):

ScriptWhat happens
pad=south+left, lstick=1500,-900, rstick=0,2047, pad=offa game pad
pad2=east, lstick2=..., rstick2=...a second game pad
padkind=hid, pad2kind=hida pad that isn’t a Switch Pro Controller (switch is one)
keydown=04, keyup=04, mods=02a keyboard, by USB code (E0 to E7 are the modifiers)
mouse=40,20,1,1a mouse, with dx, dy, buttons and wheel
midiin=90,3C,64MIDI coming in
computer=0, computer=askno computer on the port, or one that asks its user first

The simulator (docs/simulator.md) reads cvcart_features() too, and gives the plugin your computer’s game pads, keyboard, mouse and MIDI ports.

The model can’t check real devices, a real hub or a real computer, so try those on a console.

Not here yet

  • Keyboards and mice in report protocol. They’re read in the simpler boot protocol, so a keyboard’s media keys and a mouse’s extra buttons don’t come through.
  • Keyboard layouts other than US. usage is right, but ascii is the character of the US key.
  • MIDI on more than one cable (port) of a device, or from more than one MIDI device at a time.
  • Switching the port between host and device after the start, for example when a computer is plugged in later.
  • A DualShock 4’s right stick. A pad’s right stick is read from its Rx and Ry when it has them, and from Z and Rz otherwise. A DualShock 4 has both, with its triggers on Rx and Ry, so its right stick reads as its triggers.

This page is docs/features.md in the starter kit.