Blackbird basics

Blackbird speaks the same language as monome crow: it runs crow's Lua scripts, and anything that talks to crow over USB (druid, web-druid, norns, Max for Live) talks to blackbird the same way, without knowing the difference. Crow's documentation and script reference apply as they are, with the jacks mapped as shown here.

Getting started

1. Connect the Computer's USB to a computer and open web-druid (or druid). Wait until blackbird has started: its welcome message appears and the bottom-left LED flashes.
2. Type Lua at the prompt, for example output[1].volts = 3.
3. Upload a script with druid's u (saved to the program card and run at power-up) or r (run without saving). It starts straight away. Make the first line start with --- to name it: the name is printed at startup.

With no script uploaded, blackbird runs First.lua, crow's "unique melody box".

Jacks

The knobs and switch do nothing until a script uses them. The LEDs always show the outputs: the four CV and audio outputs light with their positive voltage, and the pulse output LEDs while the pulse is high.

Blackbird extras

• bb.noise(level): an ASL action that generates noise in the audio loop, for example output[4](bb.noise(0.5)).
• bb.asap: a function run as often as possible on the control thread, for following knobs smoothly. Keep it light. bb.asap = nil stops it.
• bb.connected: whether a cable is plugged into each input (cv1, cv2, pulse1, pulse2, audio1, audio2), from the Computer's normalisation probe.
• MIDI over USB, as a device or a host: see the MIDI tab.
• ii (I2C) on the Computer's UART pads: see the ii tab.

More

• Crow scripts to try: bowery, and bbbowery, versions adapted to use the Computer's knobs, switch and pulse jacks.
• Sharing scripts as a single UF2.
• Integer-only Lua, for heavy DSP-style scripts.

First.lua: unique melody box

First.lua is crow's default script, and blackbird runs it whenever no script has been uploaded (or after ^^c clears the saved one). It's a two-voice melody generator, and each card plays its own: the patterns are generated from the RP2040's unique ID, so no two Computers play the same tune.

Patching

• CV In 1: clock. Each rising edge (crossing about 1V) moves both voices on a step. Any clock or gate works: a pulse output, an LFO, another sequencer.
• CV In 2: range. The further from 0V (in either direction), the wider the melodies range and the more varied they get. 0V and above picks a major pentatonic scale, below 0V the major scale. Leave it empty for simple, narrow tunes.
• CV Out 1 and CV Out 2: pitch (1V/octave) for voice 1 and voice 2. Voice 2 has a short slew.
• Audio Out 1 and Audio Out 2: envelopes for voice 1 and voice 2, attack-decay shapes. Patch them to a VCA or filter for each voice.

A typical patch: CV Out 1 to an oscillator's pitch, Audio Out 1 opening its VCA, and the same for voice 2 with CV Out 2 and Audio Out 2.

How it plays

Each voice runs two step sequences, each of its own length (6 to 24 steps): one decides on which clocks the voice's envelope fires, the other on which clocks its pitch changes. With four sequences of different lengths, the voices drift against each other and the whole pattern takes a long time to repeat.

• Not every clock fires an envelope or changes a pitch, so the rhythms have rests, and a pitch can change under a sustaining envelope.
• The envelopes respond to the rhythm: the longer voice 1 has rested, the longer its next decay, and the longer voice 2 has rested, the longer its next attack.

The knobs, switch, audio inputs and pulse jacks aren't used: First.lua is crow's script, and crow has none of them. Upload your own script to use them (see the Basics tab).

MIDI Support

Blackbird can receive and send USB MIDI. The API follows monome iii's MIDI functions, with the same names, arguments and message tables, placed in the bb table:

MIDI channels are always 1–16 (not 0–15).

USB device mode vs USB host mode

Blackbird supports USB-MIDI in both directions, depending on the USB role it boots into:

• Device mode: Blackbird enumerates as a USB device (CDC serial + USB-MIDI). This is the mode you use with a computer + web-druid/druid for live coding and seeing print() output.
• Host mode: Blackbird acts as a USB host and talks MIDI with a class-compliant USB-MIDI device plugged into it (controller, keyboard, etc.).

Role selection is automatic at boot, based on the Workshop Computer’s USB power orientation (whether it believes it is downstream-facing power / DFP). In host mode, Blackbird waits briefly at startup for a USB-MIDI device to mount. Note you always need to power the Workshop System completely off and back on to switch between device and host mode- resetting computer alone is not enough.

Tip: during the startup “waiting” period, the LEDs animate differently:

• Device mode: “around-the-world” loop
• Host mode: top-to-bottom sweep

Recommended workflow: develop in device mode, then switch to host mode

This lets you iterate quickly with web-druid while keeping the exact same bb.event_midi handler for your final host-mode setup.

1. Develop + debug in device mode

• Connect Blackbird to your computer and open web-druid.
• Load a script that defines bb.event_midi and uses print() so you can see events arriving.
• Send MIDI to Blackbird from the computer (DAW, MIDI monitor, virtual keyboard). Your handler should fire and you should see prints in web-druid.

1. Move to host mode (same script, same handler)

• Disconnect from the computer.
• Connect a class-compliant USB-MIDI device to Blackbird (so Blackbird can be the USB host).
• Reset/reboot Blackbird with the MIDI device already connected so it mounts during the startup window.
• Your existing bb.event_midi will still be called on incoming MIDI, and bb.midi_out & co. send to the connected device.

Note: in host mode, you generally won’t have the web-druid serial console available, so prefer debugging by driving outputs/LEDs instead of relying on print().

Receive

bb.event_midi(byte1, byte2, byte3)

Define this function to receive MIDI. It is called with the raw bytes of each incoming message; unused bytes are 0. Decode the bytes with bb.midi_to_msg:

bb.event_midi = function(b1, b2, b3)
  local m = bb.midi_to_msg({b1, b2, b3})
  if m.type == 'note_on' then
    output[1].volts = (m.note - 60) / 12   -- middle C = 0V, 1V/oct
  elseif m.type == 'cc' and m.cc == 1 then
    output[2].volts = m.val / 127 * 5      -- mod wheel -> 0..5V
  end
end

Notes:

• Every message type is delivered, including program change, clock/start/stop/continue, song position and sysex. Active sensing (0xFE) is ignored.
• MIDI clock messages also drive Blackbird's clock when the clock source is MIDI (see below).
• To keep up with fast controllers, Blackbird passes at most one CC / pitch bend / pressure message per millisecond to Lua and drops the rest. Notes and all other messages always get through.
• If bb.event_midi is not defined, notes, CC, pitch bend and aftertouch are forwarded to the host as crow-style messages (e.g. ^^midi('on',60,100,1), ^^midi('cc',1,64,1), ^^midi('bend',0.5,1), ^^midi('aftertouch',64,1)). These go out at most one every 4ms, so a burst (an all-notes-off is ~128 messages) can't overrun the host: norns' crow reader loses data if lines arrive faster than its Lua handles them. Up to 128 can wait their turn; beyond that, the extras are dropped.

bb.midi_to_msg(data)

Decodes data, an array of MIDI bytes, into a table. type is one of:

Active sensing decodes to an empty table.

Transmit

Messages go to the computer in device mode, or to the connected MIDI device in host mode.

bb.midi_note_on(note, vel, ch) / bb.midi_note_off(note, vel, ch) / bb.midi_cc(cc, val, ch)

Shortcuts for the most common messages. All arguments are optional: note defaults to 66, cc to 1, vel / val to 100 and ch to 1.

-- play a short note every beat
clock.run(function()
  while true do
    clock.sync(1)
    bb.midi_note_on(60, 100, 1)
    clock.sleep(0.1)
    bb.midi_note_off(60, 0, 1)
  end
end)

bb.midi_out(msg)

Sends a message table in the format produced by bb.midi_to_msg (so incoming messages can be passed straight through), or an array of raw bytes.

bb.midi_out({type = 'pitchbend', val = 8192 + 4096, ch = 1})
bb.midi_out({type = 'program_change', val = 5, ch = 10})
bb.midi_out({type = 'clock'})
bb.midi_out({0xF0, 0x7E, 0x7F, 0x06, 0x01, 0xF7})  -- raw bytes, e.g. sysex

-- MIDI thru, transposed up an octave
bb.event_midi = function(b1, b2, b3)
  local m = bb.midi_to_msg({b1, b2, b3})
  if m.note then m.note = math.min(m.note + 12, 127) end
  bb.midi_out(m)
end

When fields are missing, ch defaults to 1, note vel to 100 and pitch bend val to 8192 (centre). Everything else defaults to 0. An unknown type raises an error.

bb.midi_tx(byte1, byte2, byte3)

Sends one raw MIDI message. If byte1 is a status byte, exactly that message's length is sent (so bb.midi_tx(0xC0, 5) sends a 2-byte program change), with missing bytes sent as 0. Data and sysex bytes are sent as given.

Values and ranges

• Data values (note, vel, cc, val) are 7-bit and are masked to 0–127; channels outside 1–16 are clamped.
• Unlike iii, CC88 high-resolution velocity is not combined into vel: the CC88 arrives in bb.event_midi as a normal cc message just before the Note On. (bb.event_mpe_note does combine it, see below.)

Optional: MPE routing

Blackbird can route the per-note expression of an MPE controller into dedicated callbacks. This is a Blackbird extension with no iii equivalent.

bb.mpe_mode(enable)

• bb.mpe_mode(true) turns MPE routing on, bb.mpe_mode(false) turns it off. Each new script starts with it off.
• bb.mpe_mode() returns the current state (true / false).

When MPE mode is on, these messages go to the callbacks below instead of bb.event_midi. All other messages (other CCs, program change, clock, etc.) still go to bb.event_midi.

function init()
  bb.mpe_mode(true)
end

local voice_ch = nil
bb.event_mpe_note = function(type, note, vel, ch)
  if type == 'note_on' then
    voice_ch = ch
    output[1].volts = (note - 60) / 12
  elseif ch == voice_ch then
    voice_ch = nil
  end
end

bb.event_mpe_pressure = function(val, ch)
  if ch == voice_ch then output[2].volts = val / 127 * 5 end
end

Notes:

• Each MPE note plays on its own channel, so use ch to tell which note an expression message belongs to. In a standard MPE setup, channel 1 is the zone's master channel: bend/pressure there apply to all notes, and notes arrive on channels 2–16.
• Expression (bend, pressure, slide) is coalesced, not dropped: if a controller sends faster than Lua can keep up, intermediate values are skipped but the latest value per channel is always delivered, so a release back to 0 is never lost. A channel's pending expression is delivered before its next Note On/Off, preserving the order MPE controllers rely on.
• Callbacks you don't define are forwarded to the host as crow-style messages via ^^mpe(...) (e.g. ^^mpe('on',note,vel,ch), ^^mpe('pressure',val,ch)), paced the same way as ^^midi.

High-resolution velocity (CC88) in MPE mode

If a controller sends CC88 (High Resolution Velocity Prefix) immediately before a Note On on the same channel, bb.event_mpe_note receives vel as a fractional number:

vel = vel7 + (fine7 / 128), so vel14 = math.floor(vel * 128 + 0.5) recovers the 14-bit velocity (0..16383).

CC88 applies to the next Note On on that channel and expires if no Note On follows soon.

MIDI Clock integration (optional)

Blackbird also listens for MIDI realtime messages:

• Clock tick (0xF8)
• Start (0xFA)
• Continue (0xFB)
• Stop (0xFC)

When the system clock source is set to MIDI, these messages drive Blackbird’s internal clock engine (tempo and transport). They are also passed to bb.event_midi. In Lua, the clock-source helpers are exposed as global functions:

• clock_get_source() returns 1-based: 1=internal, 2=MIDI, 3=LINK, 4=CROW
• clock_set_source(source) sets the source (pass 0 for “auto”)

Example: force MIDI clock

clock_set_source(2)

Coming from iii

• The functions are the same, but live in bb: event_midi → bb.event_midi, midi_out → bb.midi_out, and so on.
• Message tables, type names, field names, defaults and channel numbering are the same.
• Blackbird adds USB host mode, MPE routing and MIDI clock sync, and limits how fast CC / pitch bend / pressure messages reach Lua.

ii (I2C)

WARNING: If you are not confident with I2C or don't know what pullup resistors are, it is not recommended to connect your Computer module to anything via wiring on the back.

Computer module must be in the same case, on the same power supply to safely and successfully connect i2c devices since the ground is shared via the case PSU

Blackbird speaks ii, the I2C protocol that crow, Teletype and Whimsical Raps / monome / Mannequins modules use to talk to each other. It works as crow's does: a script can lead (send commands and queries to other modules) and blackbird always follows (answers commands and queries from a leader such as Teletype or another crow).

Wiring

The Computer has no ii jack. It uses the two UART pads on its circuit board, which are usually unpopulated, so you'll need to (carefully) solder a header to them.

Pull-ups

An I2C bus needs pull-up resistors, and the Computer has none strong enough on its own. crow and Teletype provide them (crow by default), so with either on the bus you need nothing else. Never pull up to 5V: the RP2040 isn't 5V tolerant.

ii.pullup(true) only switches on the RP2040's weak internal pull-ups, which are far too weak to run a bus by themselves.

Running other cards while wired up

The UART pads belong to the Computer, not the card, so the wiring stays connected whatever card is running, and other cards don't know an ii bus is there:

It is therefore recommended to disconnect the i2c/ii wires when you run other cards.

Wire the pads to an i2c bus or to a serial (UART) partner, never both at once.

Leading

The syntax is crow's: see crow's ii reference. For example:

ii.jf.mode(1)
ii.jf.play_note(0, 5)          -- Just Friends: a note at 0V, velocity 5

ii.crow.volts(1, 2.5)          -- another crow's output 1 to 2.5V

ii.crow.event = function(e, value)
  print(e.name, e.device, value)
end
ii.crow.get('input', 1)        -- ask that crow for its input 1: the answer arrives in .event

Supported devices: Ansible (and Kria, Meadowphysics, Levels), crow, disting EX, ER-301, 16n Faderbank, Just Friends, TELEXi, TELEXo, W/Delay, W/Syn and W/Tape. ii.help() lists them, and ii.<device>.help() lists a device's commands.

• ii.raw(address, bytes, [read_length]) sends raw bytes; a reply arrives in ii.event_raw(address, command, data, arg).
• ii.fastmode(true) runs the bus at 400kHz (100kHz by default, as crow).
• Messages to an address nothing answers are dropped quickly and don't hold up the bus.

Following

Blackbird answers at crow address 4: to a Teletype it's crow 4 (select it with CROW.SEL 4, or prefix a crow op with CROW4:), and to another crow it's ii.crow[4]. A script can move it to crow 1-3 with ii.set_address(n) (ii.get_address() reads it back).

With no script, blackbird already answers crow's built-in commands: volts, slew, reset, pulse, ar and lfo act on outputs 1-4, and the input and output queries report its inputs and outputs. A script handles the rest:

ii.self.call = function(args)         -- call1 .. call4 from the leader
  print('called with', #args, 'arguments')
end

ii.self.query = function(args)        -- query0 .. query3: answer with a whole number
  return math.floor(bb.knob.main * 100)
end

Query answers are 16-bit whole numbers, as on crow. ^^k (and loading a new script) puts the handlers back to these defaults.