tartelette / documentation demossource ↗

USB

The RP2040's USB controller is emulated in device mode, and tartelette plugs a small USB host into the other end of the cable. The host enumerates the device the way a PC does and then talks to the functions it recognises:

  • CDC-ACM serial ports;
  • HID interfaces (keyboards, mice, anything with a report descriptor);
  • USB-MIDI.

Unmodified TinyUSB (pico-sdk, MicroPython), embassy-usb and usb-device (rp2040-hal) firmware works.

How it's modelled

The controller (rp2040-core/src/periph/usb.rs) follows section 4.1 of the datasheet: the registers, the 4 KiB dual-port RAM, the buffer control words (AVAILABLE, FULL, PID, LENGTH, STALL, double buffering and its buffer selector), BUFF_STATUS and the SIE_STATUS interrupts.

The host (crates/core/usbhost) speaks to it one transaction at a time: SETUP, IN and OUT tokens, answered with data, ACK, NAK or STALL from the endpoint's buffer control word. Each transaction takes as long as it would on a full-speed bus. Like everything else, it runs on emulated time and is deterministic.

Electrical detail (line states, the PHY, suspend and resume) and host mode are not modelled.

Without a bridge

With nothing else set, the serial port shows up in the USB serial tab, and the USB tab logs the traffic: enumeration, every control transfer decoded, every packet on the other endpoints. Both work in the browser too.

Headless, the serial port is on stdin and stdout, and --usb-log prints the traffic log to stderr.

tartelette micropython.uf2 --headless     # MicroPython's REPL in the terminal

Bridges

--usb-bridge hands the device's functions to the computer tartelette runs on. It takes a comma-separated list:

BridgeThe function becomesPlatforms
seriala pseudo-terminal, like /dev/ttyACM0. DTR follows whether a program has it open. --usb-tty-link PATH adds a symlink with a stable nameLinux
hida kernel input device through /dev/uhid: an emulated keyboard types into your desktopLinux, needs access to /dev/uhid (root or a udev rule)
midivirtual MIDI ports, tartelette: USB MIDI out and tartelette: USB MIDI inLinux (ALSA), macOS (CoreMIDI)

On Windows and in the browser (WebMIDI), the USB tab can connect the MIDI interface to existing MIDI ports instead.

# MicroPython over a real serial port
tartelette micropython.uf2 --usb-bridge serial --usb-tty-link /tmp/ttyACM
mpremote connect /tmp/ttyACM

# A MIDI device, in real time, with its traffic logged
tartelette synth.elf --usb-bridge midi --usb-log --headless --speed 1

When bridging to programs that expect a real device's timing, run with --speed 1 so the firmware doesn't run ahead of the wall clock.

Example firmware

firmware/examples/pico-usb (embassy-usb) and firmware/examples/pico-usb-hal (rp2040-hal with usb-device) are the same composite device: a serial port that echoes in upper case, a boot keyboard, and a MIDI interface that echoes notes an octave up. The end-to-end tests use both.

scripts/micropython-tests.sh runs MicroPython's own test suite over the emulated USB serial port; see development.md.