🎚️ Desk controller

What it does

The props only ever hear remote-button codes over radio. The controller sends those same codes, so to a lantern it is indistinguishable from the hobby remote — nothing on the props changes, show-mode WiFi-off still applies, and the hand remote keeps working alongside. Three things can make it transmit:

Hardware and cabling

Three parts stack together: the M5Stack CoreS3 (the screen), the M5Stack DMX Base underneath it (RS-485 with XLR adapters), and the RF433T transmitter on a Grove lead from Port A with its little antenna.

1. DMX Base DIP switches. Switch 3 = input termination — ON if the controller is the last device on the line. Switch 1 = bias, per your line position. Switch 2 selects whether the Base feeds the host (normal) or bypasses it.
2. DMX in. Desk (or Art-Net / sACN node) → XLR → the Base's IN. The controller listens to the whole universe; which channel matters is set in the map, not by an address switch.
3. DMX through. The Base's OUT is a hard-wired pass-through of IN (it parallels the pair, the controller keeps listening either way), so the controller can sit mid-line in front of other fixtures.
4. Antenna placement. Keep the RF433T and its antenna clear of the DMX Base — stacking them detunes the link, and the lanterns stop hearing it reliably. Sitting it a hand's width away on its Grove lead is enough.
5. Power. USB-C. The unit has a small internal battery for carrying between positions, but run it from mains at the desk.

The Art-Net variant (CoreS3 Lite + node)

Where the desk speaks Art-Net rather than XLR, a second build of the same firmware (controller-artnet.bin) runs on a CoreS3 Lite with three Grove units instead of the DMX Base: the RF433T on Port A as before, an M5Stack Unit PoESP32 on Port C (the Ethernet node, running its own small firmware) and an M5Stack Unit DMX on Port B giving an XLR OUT. The Lite itself only has Port A, so it sits on a Base DIN or a Bus Module to get Ports B and C. Two Art-Net universes are subscribed: the prop universe feeds the same DMX map and fires cues exactly as XLR does, and the out universe is retransmitted as plain DMX512 on the Unit DMX — so the controller doubles as a one-universe Art-Net node for anything else at the desk.

1. Settings → Art-Net sets both universes (net / subnet / universe) and the node's name; the node shows up in the desk's node list under that name with two output ports.
2. The status strip reads NO NODE (nothing on the Grove link), NO NET (node up, no Ethernet link), NO IP (waiting for DHCP; after 10 s the node falls back to a 2.x.y.z address), then the usual dmx:live / dmx:idle.
3. On the MON screen, tap anywhere except the X to flip the grid between the prop and out universes.
4. The node is updated from Settings → Node firmware over the same Grove link; only its very first flash needs a USB serial adapter on the unit's internal header.
5. Power: the node runs on PoE if the switch provides it, otherwise from the Lite's Grove 5 V; with both present a small diode mod inside the node keeps the two supplies apart (bench notes in the repo).

First boot and WiFi

1. A controller with no configuration boots into its own hotspot, vivo-ctrl-xxxxxx (ask your production tech for the password — it's the same one the props use). Join it from a phone or laptop; the setup page opens by itself.
2. Under Settings, give it a name and add your venue WiFi (up to five networks, tried in order — Scan networks fills the fields). Press Save; the page asks Join & save and the controller leaves the hotspot and joins the venue network straight away.
3. From then on it boots WiFi-on and reachable at http://vivo-ctrl-xxxxxx.local (or the IP in the screen's header). Untick Bring WiFi up on boot if you'd rather it started dark.

Whatever the boot setting, the left segment of the on-screen header is a WiFi toggle: tap it to bring WiFi up or take it down without touching a browser. The header shows the IP once it has one.

The screen

The touchscreen is the controller's show-time face and works with no network at all.

• Sends are sequential, one in the queue. Each send takes about half a second (eight repeats, so the props can't miss it). A tap during a send is held and goes as soon as the current one finishes; a third tap inside that window replaces the held one, so only the first and the last of a flurry get out. Space deliberate taps a second apart.
• Same code, all props. Because RF is broadcast, tapping lantern / Candle lights every lantern that has that button captured — same as pressing the remote.

The book: where the codes come from

The controller never invents codes. It keeps a book of sources, each one a prop's exported configuration; every scene (slot) in that file becomes a cue with that scene's captured codes. Set the props up first — names, buttons, looks — then fill the book. Three ways, all on the web UI:

One fleet, one source

Twenty identical lanterns would make twenty identical sources, so imports are de-duplicated by content: a config whose scenes and codes match an existing source is reported as identical to "lantern" — skipped, and a config that differs only in name replaces the matching source rather than sitting beside it. A synced fleet therefore converges on one source, which is what you want — one heading of tiles on the screen and one fixture on the desk.

Each source card also offers Download (the stored file, byte-identical) and Delete.

The DMX map

The map is the bridge from desk to book: this channel, in this value band, fires this cue. The natural shape is one DMX channel per source, with the source's cues sharing the channel as even value bands. That gives the desk one fixture per prop type with a single "scene" parameter — the Desk setup page covers the desk side of that.

1. Open DMX Map, pick a source in the drop-down and press Add source to map. The controller auto-maps it: next free channel, bands evenly spread over 0–255, any cue whose name contains "off" placed first (lowest band) so a fader at zero means dark.
2. Adjust if you like: type a different channel, or edit any band's lo/hi. Rows on one channel must not overlap — the page flags an overlap and won't save it. Re-band evenly resets the bands.
3. Save. The change is live immediately.
4. Download GDTF exports the mapped source as a fixture file for the desk (see Desk setup). Remove takes the source off the map.

The map holds up to 64 rows in total. A card marked entries span more than one channel was hand-edited or imported that way — Re-band it onto one channel before exporting a fixture for it.

The on-screen stepper (MAP)

For quick fixes at the desk without a browser, MAP in the header opens a stepper over the same map. Up/Down move a cursor over the rows (source headings and cues); tap a row to jump the cursor there. The bottom row of buttons depends on what's selected:

Save writes it; Cancel discards. Cue assignment (which cue a row points at) stays web-only. A source showing MIXED spans channels and can't be stepped on screen — re-band it from the web page.

The DMX monitor (MON)

MON shows all 512 incoming channels as a 32×16 grid of bars coloured by level — the fastest way to confirm the desk is actually sending on the channel you think. Cue firing carries on underneath it; the monitor yields to RF, so a burst is never delayed by the display. The bottom line reads RF n/n · def · Hz · loop ms (sends attempted/completed, paints deferred for RF, repaint rate, worst loop time) and is prefixed NO SIGNAL when no DMX is arriving. Gridlines and their accent spacing are a Settings option. Tap X to leave.

Settings and updates

• Device — name (also the hostname), the WiFi-on-boot tickbox, monitor gridlines.
• WiFi networks — up to five, tried in order; Scan networks to pick from the air.
• Firmware update — Choose firmware… and pick a controller.bin (CoreS3 SE with the DMX Base) or controller-artnet.bin (CoreS3 Lite with the node) from the Firmware page's controller section — flashing the other variant costs you DMX until you flash back. The controller verifies the image before switching to it, then reboots; the book, map and settings all survive. An interrupted upload is abandoned cleanly — just try again. If a bad flash ever leaves it unbootable, USB is the recovery path (bench job).
• Node firmware (Art-Net variant only) — Choose node firmware… with a node.bin from the Firmware page's node section; the controller stages it, streams it to the node over the Grove link and reports progress, and the node verifies and reboots. Cue firing keeps running meanwhile.
• Advanced: device state — the raw status the controller reports, for diagnosis. map.unresolved greater than zero is the tell for the source-name problem above.
• Log — the panel at the foot of the page; it fills from the controller as things happen while the page is connected.

Troubleshooting