Remote Firmware

The clean mental model is: the remote is a metronome with buttons. It doesn’t try to “drive LEDs” directly. It just runs a clock and tells everyone what that clock says.

In code that clock is masterTime (milliseconds). When you press play, it advances. When you stop, it freezes. When you reset, it goes back to 0.

• Time unit: milliseconds.
• Authority: receivers treat the remote's time as the show clock.
• Control plane: play/pause toggles time; reset stops and returns time to 0.

The remote has 6 buttons: one for config/stop, one for play/pause, and four dedicated cue buttons (A-D). This allows quick jumps to preset cue points loaded from show.bin.

Hold the Config/Stop button on boot to enter USB mode for uploading new show files. During playback, it stops and resets to time 0.

The LCD shows the current state (CUE X PLAY, PLAYING, PAUSED, or STOPPED) and elapsed time. On boot, it displays how many cues are configured (e.g., "Cues: 2/4").

Cue points let you jump to specific times in your show. They're configured in PicoLume Studio and stored in the show.bin file as a trailing CUE1 block.

The firmware is small enough that you can hold the whole flow in your head: initialize hardware, then run an event loop that increments time and broadcasts packets. The interesting parts are mostly about making that loop stable and predictable.

now = millis()
delta = now - lastLoopTime

if playing:
  masterTime += delta

handle buttons (debounced)

every ~100ms:
  send RadioPacket(masterTime, state, counter)

update LCD periodically

This is the #1 "it's not working" culprit: RF settings must match between the remote and every receiver. If they don't match, receivers will act like the remote doesn't exist — you'll see "NO SIGNAL" on their OLEDs even if the radios are wired perfectly.

The good news: once you get it right, you typically set it and forget it. The default 19.2 kbps bitrate is a nice sweet spot that balances range and reliability. Only change it if you have a specific reason.

The radio packet is intentionally tiny — just 11 bytes. It's not "instructions"; it's just a clock update plus play/stop state. The receiver uses this to keep its local show timeline aligned.

The hopCount and sourceID fields are there for future mesh networking — receivers could eventually relay packets to extend range. For now they're just set to 0.

Packet (11 bytes)

struct RadioPacket {
  uint32_t packetCounter;
  uint32_t masterTime;
  uint8_t  state;     // 0=STOPPED, 1=PLAYING
  uint8_t  hopCount;
  uint8_t  sourceID;  // 0=remote
}

When debugging, start with the "boring" checks. If the clock isn't being broadcast correctly, nothing downstream can look right.

• LCD shows time increasing when playing.
• RF69_FREQ matches receivers.
• RF_BITRATE matches receivers.
• ENCRYPT_KEY is exactly 16 chars and matches receivers.
• On receivers, RSSI changes when the remote is nearby (sanity check for RF link).