QLAB Buddy

QLAB Buddy

Current firmware: v… · built checking… · Release History

A wireless touchscreen that shows your show live — cue name, timer, and connection status on a bright 3.5″ display. Put it anywhere: the tech table, the wings, your hand. Works with QLab 5 on a Mac, or Go Button on an iPhone with no Mac at all. Pair wireless RF and WiFi props — motor controllers, sub-GHz relays, and more — and fire them straight from your cues.

Hardware

The three buttons

Everything the buddy does day-to-day is on the touchscreen, but the board has three physical buttons and each one is worth knowing before a show.

BOOT doubles as the flashing button — see Flash Firmware. Try all three in the Simulator.

RF Relay

Current firmware: v… · built checking… · board: LilyGo T-Embed CC1101

A networked sub-GHz capture and replay node. Point a 315, 390, 418, 433.92, 868.35, or 915 MHz fixed-code remote at it, learn the code via OSC or the onboard encoder, then replay it directly from QLab on every subsequent show. Once provisioned the RF Relay fires independently — the buddy is only needed for initial WiFi SYNC and monitoring. There’s no Go Button device tag for it yet (see OSC reference); trigger it from QLab directly.

Designed for battery-powered remotes that control props or practical effects that can’t be wired: wireless LED controllers, RF dimmers, ceiling fans, and any fixed-code PT2262/EV1527 remote.

Pairing with the buddy

The RF Relay pairs exactly like every other prop — hotspot, boot, one tap on SYNC. The full walkthrough lives in Pairing Props with the Buddy.

On this board: there is no BOOT button — factory re-pair holds the encoder knob pressed straight in. A successful pair shows a green PAIRED screen; a wipe shows a red DELETED one.

Cabled to a Mac (LAN)

Over USB-C the relay appears as a USB Ethernet device at 192.168.9.1, port 8000 — the address in its status bar. Patch a Network cue straight at it: no WiFi, no router, no buddy. Sub-millisecond and RF-immune, so it’s the best showtime path. The .9 subnet is deliberate (the buddy uses .7), so both can be cabled to one Mac.

A bare cable carries no internet — only Mac-to-relay traffic. Two things need it: the status-bar clock and OTA updates. A relay that’s also paired to WiFi (the normal setup) has both regardless of the cable. Only a cable-only relay goes without: the clock stays --:-- -- and OTA is unavailable until it’s paired. Cue firing, QLab detection and the screensaver timer all work over the bare cable either way.

Hardware

Two hardware options — both run the same firmware. The Plus adds an external SMA antenna for better range and a built-in microphone (unused by current firmware). All pins and features are otherwise identical.

Display UI

Rotate to scroll · short press to confirm/fire · long press to open setup or go back.

OSC reference

Port 8000 (UDP; firmware 0.12.0+ also accepts TCP on the same port — use TCP if the cue must be guaranteed). Send Network cues (e.g. a QLab Custom Message cue) directly to the board’s static IP — the relay subscribes these addresses itself. Every address below is QLab/direct-OSC only — there’s no Go Button device tag for the RF Relay yet (see Device Triggering from Go Button).

One slot fires at a time. There’s a single sub-GHz radio on board, so firing a new slot while an earlier hold is still running doesn’t queue or run alongside it — it immediately takes over the radio and replaces the transmission in progress. If two cues might land close together, give the first a hold time short enough to finish before the second one fires.

Workflow: before the show, fire /rf/learn/N/MHZ (or use the onboard LEARN option), hold the remote button until captured. During the show, fire /rf/N or /rf/N/TIME from your cue stack exactly like any other prop trigger.

Reading the Status Dot

Bottom-left of every view. The bar tints dark blue whenever a show is actually open, the label names the path the buddy is using, and the dot tells you how ready that path is. Grouped by path below, so you can see what each one looks like before and after the internet check confirms.

The dot answers one question — is a show open? Blue means yes, and nothing else is blue. Whether the internet check has confirmed is a separate fact, and it rides the ring and label colour on every path.

Status bar	Path	What it means
	Show open, internet confirmed	Blue dot + gold ring — the healthy showtime state. Blue only ever means a show is open, readable from across a tech table without parsing the label.
	Show open, internet not confirmed	Blue dot + white ring. Cues still work fine — the buddy reaches QLab over the local network regardless; the internet check only affects the clock and OTA.
	On WiFi, no show found yet	Always gold on this path, confirmed internet or not — gold here means “network is fine, still looking”, not “ready to run”.
	Cabled to a Mac	Always white on this path, confirmed internet or not. Internet still works behind the scenes for the clock and OTA; it just isn’t surfaced here.
	Hotspot / Pairing, nothing joined	White — the buddy’s own hotspot is up and nothing has joined it yet.
	Hotspot / Pairing, device joined	Gold — a device has joined. During Pair Devices this is your cue that the prop has arrived and SYNC is ready to tap.
	No network, never set up	Grey — no network has ever been saved. What a freshly flashed buddy shows until you enter WiFi credentials on the device (Devices tab → SETTINGS → WiFi).
	No network, connection lost	Red — a network was configured and has been lost. Plug in USB-C or re-enter WiFi credentials. The difference from grey is the point: grey is “never set up”, red is “something broke”.

Every dot above is a real screenshot from the firmware simulator, not a mockup — see it live in the Simulator.

Pairing Props with the Buddy

Every prop pairs the same way — RF Relay, Universal Controller, and both Card Fountains. The buddy raises a temporary hotspot, the prop joins it on boot, and one tap hands over your real WiFi credentials plus a permanent address. You only do this once per prop.

1. Start pairing mode. On the buddy, tap Devices → Pair Devices. This turns on the hotspot and begins scanning.
2. Power on the prop. It scans for the “QLAB Buddy” hotspot on every boot and joins automatically. The hotspot just needs to be active when the prop boots — there is no countdown to beat.
3. Tap SYNC on the buddy when the prop appears in the list. This pushes your main WiFi credentials, assigns a static IP, and completes the pairing. The prop reboots onto your network.

The static IP it receives is reboot-survivable, so the OSC addresses you write into cues never need updating afterwards. Find it any time under Devices on the buddy, listed beneath the prop’s name.

Factory re-pair

To move a prop to a different buddy or a different network, wipe its stored credentials: hold the board’s button while powering on, and keep holding for 3 seconds after power-up. That clears NVS and reboots the prop into SYNC mode, ready to pair again. The button is sampled during boot, so holding it after the boot sequence finishes does nothing.

Which button depends on the board:

OSC passcode

There is nothing to set on the prop — the buddy syncs the Go Button passcode to every paired prop by itself, and re-syncs whenever you change it. See Passcode auto-sync to props.

Firmware Updates (OTA)

Every board on the rig — the buddy and every paired prop — updates itself wirelessly. There are two separate update paths, and the one thing worth knowing up front is that the buddy never actually relays firmware to a prop; it only points the prop at where to get its own.

Updating the buddy itself

Settings → Software shows the buddy’s own version, with Check Again and Install buttons. It checks for its own updates automatically in the background (roughly every 15 minutes) but nothing installs until you tap Install — there is no silent auto-update.

Updating a paired prop

Open Devices on the buddy. Any prop with a newer version available shows an UPDATE chip next to it — the buddy checks each paired prop’s version roughly every 10 minutes. Tap it once; there is no confirmation step. The chip goes outlined while the update is in flight, then flashes DONE or ERR.

Blocked while the buddy’s own hotspot is on — the tap flashes a HOTSPOT hint instead, since a prop reached only through the hotspot has no route to the internet to pull its binary from. Turn the hotspot off first.

Verification and rollback

Every OTA binary is SHA-256 verified as it downloads, on both the buddy and every prop — a mismatch aborts before anything is written, so a corrupted or interrupted download can’t half-install. Once flashed, the new firmware has to run cleanly for 60 seconds before it’s marked good; if it crashes or hangs before then, the bootloader itself reboots back into the previous version automatically. None of this needs anything from you — a bad update reverts on its own.

OTA needs real internet, not just a local link: a prop reachable only over a bare USB cable or the buddy’s hotspot can’t update until it also has a working WiFi connection with an actual route out.

Workspace Lock

The buddy auto-selects the first workspace it finds on the network — whether that’s a QLab workspace or a Go Button show. In a more complex rig you can lock it to exactly the right one.

Workspace picker

Go to Settings → Workspace to open the picker. Every workspace the buddy has discovered on the current network appears as a row. Short-tap a workspace to select it as the active workspace — the buddy stays on that selection through WiFi drops, reboots, and restarts.

To hard-lock onto a specific host device, hold a workspace row for 2.5 seconds. The row fills as you hold. When it completes, the buddy locks to that workspace and that device IP — it won’t wander to another host on the network even if something else responds first. The locked row turns blue and pins to the top of the list with a LOCKED badge. Hold the same row again to unlock.

If the locked host goes offline, its row stays pinned at the top with the LOCKED badge — Offline shows in place of the address, so you can always see it is still locked and unlock it on purpose. The buddy waits quietly for that host to come back, ignoring everything else on the network.

The picker stays open after a tap or lock so you can review the state. Tap the ‹ Back pill (top-right) to return to Settings.

No workspaces showing? Tap Enter IP Manually at the bottom of the picker to type the host’s IP directly (e.g. 192.168.1.42). Useful when mDNS is blocked or the device hasn’t announced yet.

OSC Access

Tap Settings → OSC Access to open the OSC Access page. This is where all OSC permission and passcode settings live.

• Mode (VIEW / CTRL) — CTRL (default) lets the buddy send GO, PANIC, STOP, and cue-navigation commands. Switch to VIEW to make the buddy read-only: it monitors the show live but all control buttons and chevron navigation are silenced. Useful at the tech table or for a second monitor display you don’t want to accidentally trigger.
• QLab passcode — if your QLab workspace has an OSC passcode set under Workspace Settings → Network → OSC Access, enter the same numeric code here. The buddy sends it automatically on every connect. Leave blank if no passcode is set.
• Go Button passcode — if your Go Button show has an OSC passcode set, enter the matching numeric code here. This is the only place you enter it: the buddy shares it with every paired prop automatically (see Passcode auto-sync to props below). Leave blank if no passcode is set.

Tap a passcode row to open the numeric pad. Tap x to the right of a set passcode to clear it.

Passcode auto-sync to props

When OSC is passcode-locked, a prop only fires for a matching passcode, so it won’t fire for an unauthorized sender on a shared network. You never type that passcode into the prop itself. Enter it once on the buddy — Settings → OSC Access → Go Button passcode — and the buddy pushes it to every paired prop: Card Fountain, De Kolta, RF Relay, and Universal Controller alike.

• Set once, shared everywhere — the buddy sends the stored Go Button passcode to each paired prop in the background. Newly discovered props, props that reconnect, and props pairing via SYNC all receive it — no per-prop entry and no re-pairing.
• Changes re-push automatically. Change the passcode on the buddy, from the numeric pad or by tapping x to clear it, and the new value reaches every paired prop right away. Clearing it propagates too, so props stop expecting a passcode and keep firing.
• Self-healing on reconnect — if a prop was offline when you changed the passcode, or a push was missed, it re-syncs silently the next time it reports in. Each prop advertises a fingerprint of its stored passcode; when the buddy sees a mismatch it re-pushes the current code on its own. Cue triggering just keeps working — no manual action needed.

Show Timers

The buddy can put a clock on screen next to the cue name — a countdown to a curtain, a stopwatch across an act, or the show-elapsed time. How you drive it depends on which app is running the show, so both are here together.

From QLab — cue-note directives

Drop directives into a cue’s Notes field — the buddy reads them and strips them from the visible text, so the operator never sees them on the QLab screen. Both : and . work as separators.

From Go Button — show timer

Go Button handles timing differently from QLab — there are no cue notes, so there are no #timer/ directives. What the buddy shows depends on whether that show file has a duration set:

• No duration set — Go Button counts up. The buddy shows elapsed time in green, from 00:00.00.
• Duration set — Go Button counts down. The buddy shows time remaining in amber. Once the show runs over, it flips to red and shows how far over.

It resets to 00:00.00 when the show resets in Go Button. The buddy detects motion from Go Button’s own elapsed time, so firing the first cue is what starts the clock.

For per-cue countdowns, count-up stopwatches, pause, and resume — use QLab with #timer/ directives. See timer directives from QLab.

On the RF Relay

The RF Relay mirrors the same timer on its own screen once it has been idle for 30 seconds, so a relay sitting in the wings doubles as a second clock. Nothing to configure — see RF Relay.

Simulator

Run a show in your browser, with no hardware at all. A virtual QLab drives a QLAB Buddy and an RF Relay — and neither device is a mockup: each runs its actual firmware, compiled to WebAssembly, on one shared clock, so what you see on both is genuinely the same moment.

Teach the relay a remote, then hit GO. The cue tagged for RF fires the relay while the buddy advances, because QLab reaches both devices independently — which is exactly how a real rig behaves. The director panel underneath goes deeper: the buddy’s three physical buttons, VIEW-only OSC access, #timer/ directives, battery and radio states, and the relay’s full setup menu — every control drives the real firmware, never a re-enactment.

In this demo, the buddy does not fire the relay. QLab addresses it directly, and the buddy’s role here is monitoring: its Devices row flashes when the relay reports back that it fired. That matches real hardware — there’s no Go Button device tag for the RF Relay yet, so QLab is currently the only way to trigger it. See RF Relay OSC reference.

The simulator rebuilds automatically from firmware source on every commit that touches it, so it can’t drift from the boards on your bench.

Flash Firmware

Buy the board in QLAB Buddy above, plug it in over USB-C, and install it right here: the page identifies which board it is and arms the matching installer itself, so you never pick a firmware. After flashing, give the buddy WiFi on the device (Devices tab → SETTINGS → WiFi), then jump to Using with QLab 5 or Using with Go Button for your show setup.

Auto-install: plug in and flash

Plug the board in over USB-C and leave it. The page watches for it, reads what it is, and arms the matching installer by itself — then one click flashes it. Two boards share each chip (Buddy/RF Relay are both ESP32-S3; three props are ESP32-C3), so esptool can’t refuse a mismatched flash on chip grounds alone; asking the board is what makes picking the right firmware automatic. That answer is remembered by every other Install button on the page too, so clicking one for a different device gets stopped before it overwrites anything.

Using with QLab 5

OSC setup in QLab

Two settings in every workspace. Do this once per show file and it sticks in the .qlab5 file.

1. Enable OSC input on port 53000 Workspace Settings → Network → OSC Controls (or OSC Receiver).
   Tick Enable Network OSC. Set the listen / input port to 53000.
2. Allow control Workspace Settings → Network → OSC Access.
   Check Allow OSC connections. In the No Passcode row, tick Control. Save.

   To run in view-only mode (buddy shows cues but GO/PANIC/STOP do nothing), tick View only and leave Control unchecked. You can flip back any time.

Three ways to connect

• USB-C — sub-millisecond latency, completely RF-immune. Best choice for showtime. The buddy presents as a USB-NCM Ethernet device at 192.168.7.1 — your Mac’s WiFi stays the default route, so QLab and internet work normally alongside it.
• WiFi — join the same network as your QLab Mac. Discovery is automatic, typically connects within 2–3 seconds.
• Hotspot — the buddy hosts its own AP if you have no router. Used for prop pairing too. Credentials below.

USB-C and WiFi are both live all the time. The hotspot joins them once you turn it on (off by default — Settings → Hotspot). A silent host is dropped automatically after 5 s so another path can take over — unless you’ve manually locked to one via the workspace picker, which stays locked through silence. See Workspace Lock.

Cabled with no WiFi at all

USB-C to the QLab Mac works with WiFi off entirely — no router, no venue network. QLab reaches the buddy over the cable at 192.168.7.1 the same way it would over WiFi.

The one thing that needs real internet, not just the cable, is the status-bar clock — it syncs from an internet time server, and with WiFi off there’s no route to one, so it shows --:-- -- until the buddy also has WiFi or a hotspot-fed connection. Cue firing, QLab detection, and everything else run fine over the bare cable regardless.

Using with Go Button

Go Button is an iPhone and iPad app by Figure 53, the makers of QLab. It’s a standalone cue-advance controller — load a show file, press GO. The buddy connects to Go Button over WiFi and mirrors the show in real time. No Mac needed at all. You can also trigger paired Card Fountain props from a Go Button show — see Device Triggering from Go Button.

Setup

1. Put both on the same network The buddy and the iPhone / iPad running Go Button must share one network — the buddy uses UDP broadcast for discovery, so it won’t cross subnets or VLANs. Two ways to do that:

   • Shared WiFi — join both to the same router (same SSID). Best when you have a venue or house network.
   • Buddy hotspot — no router? Turn the buddy’s hotspot on at Settings → Hotspot (press and hold the row to enable), then join the iPhone to it. Great for a self-contained rig. The iPhone won’t have internet on the hotspot — that’s fine, Go Button and the buddy only need to reach each other. Same fixed credentials as always — see Three ways to connect.
2. Set UDP Reply Port to 53001 Open Go Button on your device. Tap Settings → Connections. Set UDP Reply Port to 53001. Do this once — it persists across sessions.
3. Match the OSC passcode If OSC Access in Go Button has a passcode set, open the buddy’s Settings → OSC Access → Go Button passcode and enter the same numeric code. If no passcode is set in Go Button, leave the buddy’s field blank.
4. Passcode auto-shares with paired props Set the Go Button passcode once on the buddy and every paired prop receives it in the background — no per-prop setup, no re-pairing. Cue triggering keeps working while OSC is passcode-locked, and a prop that was offline re-syncs itself on reconnect.
5. Open a show in Go Button Load your show file and start the session. The buddy will detect the broadcast within a few seconds.
6. Pick the show on the buddy Tap the workspace name in the buddy’s status bar (or go to Settings → Workspace) to open the picker. Go Button shows appear alongside any QLab workspaces. Tap yours. The status dot turns solid blue labeled Go Button.

What you see in Go Button mode

• Top-bar timer — show elapsed time in HH:MM.SS format, counting up from 00:00 when the show is running. Resets to 00:00 when the show resets. The timer detects motion — it pauses automatically when Go Button stops advancing cues.
• Stage view — current cue name and cue number, updated each time Go Button advances.
• Chevron nav — left and right screen-edge arrows appear when a show is live. Hold either edge to step one cue back or forward in Go Button. Chevrons are hidden and navigation is disabled when the buddy is in VIEW mode (Settings → OSC Access → VIEW / CTRL).
• Status bar — the Go Button show name appears in the center. Status dot is solid blue, labeled Go Button.

Tips

• If the timer shows 00:00.00 and doesn’t move, fire a cue in Go Button first — it takes one poll cycle (~0.2 s) to detect motion.
• If your show appears in the picker but the timer is always blank: double-check the UDP Reply Port setting (53001) — that’s almost always the cause.
• Workspace picker flickering during search is normal — the buddy broadcasts every 400 ms while scanning. It settles within 1–2 s once Go Button replies.

Universal Controller BETA

Current firmware: v… · built checking… · boards: NULLLAB Maker-ESP32  ·  DFRobot Romeo Mini ESP32-C3

A wireless OSC prop controller for live shows. Pair it with the buddy, give it a static IP, and drive motors and servos directly from QLab cues or Go Button. Two board options: the NULLLAB Maker-ESP32 gives you four DC motor channels and four servo channels; the Romeo Mini ESP32-C3 is a smaller form factor with two motor channels and four servo channels.

Build anything that moves: turntables, lifts, reveals, automated set pieces, puppet rigs. If it takes a motor or a servo, the Universal Controller drives it from your cue stack.

Pairing with the buddy

The Universal Controller pairs exactly like every other prop — hotspot, boot, one tap on SYNC. The full walkthrough lives in Pairing Props with the Buddy.

On this board: factory re-pair holds BOOT — GPIO 0 on NULLLAB, GPIO 9 on Romeo Mini.

Hardware

LED status

Romeo Mini has no onboard LED — everything below is NULLLAB only.

Blue / green updates instantly when the buddy broadcasts a QLab open / close event.

OSC reference

Same transport as every other prop — port 8000, UDP or TCP. See the RF Relay’s OSC reference for the transport details and when to prefer TCP.

Swap the channel number for another: m1–m4 for motors, s1–s4 for servos. M3 and M4 are NULLLAB Maker-ESP32 only — the Romeo Mini has two motor channels. Both boards have all four servo channels. Servo angles are 0–180° and every servo boots centred at 90°. Durations accept 00:00:03, 3s, 500ms, or a bare number (3, 1.5) read as seconds.

Aliases: /start, /reverse, and /test (without a channel prefix) target M1 — so any existing QLab patch that already uses those commands works without changes.

OSC passcode: nothing to set here — the buddy syncs it automatically. See Passcode auto-sync to props.

Card Fountain — Handheld ALPHA

Current firmware: v… · built checking…

Pocket-sized Card Fountain. Fires on the same OSC interface as the De Kolta. Pairs over the buddy’s hotspot, gets a static IP, and takes /start from QLab Network Cues or Go Button cue tags.

Pairing with the buddy

The Handheld pairs exactly like every other prop — hotspot, boot, one tap on SYNC. The full walkthrough lives in Pairing Props with the Buddy.

On this board: factory re-pair holds BOOT. There is no status LED, so there is nothing to watch for — just hold through the power-up.

Hardware

Card Fountain — De Kolta ALPHA

Current firmware: v… · built checking…

Stage Card Fountain. Pairs over the buddy’s hotspot; QLab drives it over OSC. Cosine ramp for smooth motor acceleration. Static IP survives reboots and router restarts.

Pairing with the buddy

The De Kolta pairs exactly like every other prop — hotspot, boot, one tap on SYNC. The full walkthrough lives in Pairing Props with the Buddy.

On this board: factory re-pair holds BOOT. There is no status LED, so there is nothing to watch for — just hold through the power-up.

Hardware