Receiver Firmware

• 224 unique prop IDs
• Per-prop hardware config (V3)
• USB mass storage upload
• 17 built-in effects
• OLED status display
• Auto-timeout (30 min)

Here's the mindset that makes the firmware click: the receiver is not "remote-controlled LEDs." It's a tiny computer that already has the whole plan, and the remote just tells it what time it is.

This is a subtle but powerful distinction. Because each prop carries its own show data, the radio link only needs to carry timing info — a few bytes every 100ms. No video stream, no effect parameters, no "do this now" commands. Just "the show clock says 12,345 milliseconds."

The practical benefit? Dozens or even hundreds of props can sync to one remote without drowning in radio traffic. And if a prop misses a packet or two, it can coast on its local clock until the next update arrives.

Boot is basically a checklist that tries to get the device into a safe, visible state quickly. OLED comes up early so you can see what’s happening even if file loading or RF setup fails.

setup():
  (1) Detect USB-mode button hold early
  (2) Init EEPROM (prop ID)
  (3) Init OLED early so failures are visible
  (4) Init NeoPixel strip with safe defaults (temporary)
  (5) If USB mode requested: runUSBMode()
  (6) Mount FatFS, load show.bin (with retry), unmount
  (7) Configure strip from PropConfig (type/order/count/brightness)
  (8) Init RF69 radio (freq/bitrate/encryption)
  (9) Show status on OLED

Here's a handy trick for checking your LED strips: a short press of the CONFIG button toggles test mode. The prop runs a rainbow chase animation so you can verify all your LEDs are wired up and responding — no remote or show file needed.

This is particularly useful when you're first building props or troubleshooting a strip that seems dead. If the test animation runs smoothly, you know the hardware is good and you can focus on software or radio issues.

Not all LED strips speak the same language. The receiver supports six common LED chipsets, each with their own timing quirks, plus all six RGB color orderings. This flexibility is configured per-prop in the show.bin file, so you can mix different LED types across props in the same show.

The receiver is intentionally strict when it reads show.bin. If the magic or version is wrong, it bails instead of trying to “make sense” of random bytes.

loadShowFromFlash():
  read header, validate magic "PICO"
  validate version == 3

  read PropConfig for THIS prop ID:
    offset = sizeof(header) + (propID - 1) * sizeof(PropConfig)
    myConfig = bytes[8]

  seek past full LUT to events:
    sizeof(header) + 224 * sizeof(PropConfig)
  read up to eventCount events into showSchedule[]

The fun part is the LUT: each receiver seeks directly to “its” 8-byte PropConfig entry based on prop ID, so one show file can support mixed LED counts/types/orders across props. Full layout details live on the show.bin page.

Timecode packets show up about every 100ms. When one arrives, the receiver treats masterTime as truth and sets currentShowTime to match. Between packets it “coasts” using local delta so animations stay smooth during brief RF hiccups.

The scheduler is where the receiver turns “time” into “behavior”. It asks: what event is active right now, and does that event actually target this prop?

bucketIndex = (propID - 1) / 32
bitMask     = 1 << ((propID - 1) % 32)

for event in showSchedule:
  if t in [start, start+duration):
    if event.targetMask[bucketIndex] & bitMask:
      choose event
      break
else:
  OFF

At this point it’s basically “paint pixels.” Each effect is a function that fills a NeoPixel buffer based on a local effect time: localTime = currentShowTime - currentEffectStart.

localTime = currentShowTime - effectStart
switch (effectType):
  SOLID   => fill(color)
  STROBE  => toggle on/off by localTime
  RAINBOW => per-pixel hue by localTime
  ...

A nice touch: most renderers use strip.numPixels(), so the same effect scales across different LED counts without special cases.

The OLED is the receiver’s “talking to you” channel. It’s a small dashboard that answers the questions you ask in the field: who am I (prop ID), did I load a show (event count), am I hearing the remote (RSSI), what mode am I in, and what time is it.

When you’re troubleshooting on a football field or backstage, this is the difference between guessing and knowing.

The receiver is built to prefer “off and predictable” over “on and confusing.” A few guardrails make it behave nicely as real hardware.

• Packet timeout: if packets stop arriving, UI reports NO SIGNAL.
• Standby: when not playing, LEDs are kept OFF for reliability.
• Show end: after the last targeted event, LEDs are forced OFF.
• Strip timeout: auto-timeout exists to prevent long-running battery drain/overheat scenarios.