V1 2 Clip On Dongle Hardware Guide
This guide covers the external, operator‑facing parts of the assembled V1.2 Clip‑On Dongle: the status lights on the face, the three control switches, the two antenna connectors, and the USB connection. It is written for operators running a show, not for firmware developers.
The dongle is the USB‑connected "base station" of the Backyard Hero system. It plugs into the host computer (Windows / macOS / Raspberry Pi), talks to the field OS4 receivers over 2.4 GHz, and can also trigger legacy 433 MHz firing boxes. The host app (
http://localhost:1776) drives it.
The face carries a row of 7 RGB status lights (NeoPixels) plus the three control switches (see Section 2).
When the dongle is first powered/plugged in, all 7 lights run a quick green chase across the row and then settle. This confirms every light works. After the chase, light 1 (System) stays green and the rest go dark until the host app connects.
The lights are numbered 1–7 from bottom to top. Each light is tied to one part of the system. Colors and effects share a common code across all lights:
| Effect | Meaning |
|---|---|
| Solid | steady state |
| Blinking | on/off about twice per second — attention / in‑progress |
| Pulsing | smooth fade up/down — active / live |
Note: light positions below follow the firmware order. Confirm the physical left‑to‑right order against the face photo once it's added, and renumber if needed.
| State | Meaning |
|---|---|
| Green | Host service is running and talking to the dongle |
| Off | No host service (app not started, or USB/serial down) |
| State | Meaning |
|---|---|
| Off | Web app layer not active |
| Green | Web app connected and running |
| Yellow | Web app disconnected |
| Red | Web app crashed |
| State | Meaning |
|---|---|
| Off | Idle / no link state reported |
| Green | Actively transmitting to receivers |
| Yellow | Connected to the serial bridge, ready |
| Red | Device / bridge error (dongle not reachable) |
| State | Meaning |
|---|---|
| Off | No show loaded |
| Green | Show loaded and ready |
| Yellow | Show is loading |
| Red | Load error (see the app for details) |
| State | Meaning |
|---|---|
| Off | Not running |
| Pulsing green | Show is running |
| Blinking yellow | Manual‑fire mode engaged |
| Solid red | Stopped |
| Solid blue | Paused |
| Solid purple | Armed / ready to start |
| Solid white | Waiting for a delegated (client) start |
| Blinking cyan | Pre‑flight check (battery / continuity) in progress |
Countdown is handled internally but is not shown as a distinct color on this light in current firmware.
Any color here means a fault is present; off means no fault. The color hints at the source:
| State | Meaning |
|---|---|
| Off | No error |
| Green | Daemon‑level error |
| Yellow | RF front‑end error |
| Red | Socket / connection error |
| Blue | Unclassified error |
At boot, if the 2.4 GHz radio hardware does not respond, this light goes solid red while the dongle retries every few seconds. If it stays red, see Troubleshooting.
| State | Meaning |
|---|---|
| Pulsing red | System is ARMED (live) |
| Solid blue | System is DISARMED (safe) |
Overall light brightness is set in the app settings (1–100%). It does not change the meanings above.
The dongle has three toggle switches. They are the physical, hardware‑level controls for arming and running a show and are read directly by the dongle.
The master safety control.
- Armed: the system is live. A loaded show can be started, and manual fire is permitted. Light 7 pulses red.
- Disarmed: the system is safe. Disarming immediately stops any running show. Light 7 is solid blue.
Always keep the system disarmed until you are ready and the field is clear.
Runs and halts the loaded show. Only effective while the system is armed.
- Start: begins the loaded show sequence (runs the pre‑flight check, then the countdown and firing).
- Stop: halts the running show and returns to a stopped/ready state.
Engages live manual‑firing mode.
- Engaging manual fire stops any running scheduled show first.
- While manual fire is engaged you cannot start a scheduled show — disengage manual fire, hit Stop, then start the show.
- Light 5 blinks yellow while manual fire is engaged.
The dongle has two separate radios, each with its own antenna connector. They are not interchangeable — each antenna serves a different radio and frequency band.
- Radio: nRF24L01(+PA+LNA), 2.4 GHz, ~250 kbps.
- Purpose: the primary two‑way control link between the dongle and the Backyard Hero OS4 field receivers. Carries cue commands, clock sync, arming/start, and receives live receiver status (battery, continuity, ready state) back in the acknowledgement.
- This is the antenna that matters for firing your OS4 receivers. Keep it installed, undamaged, and with line‑of‑sight to the field for best range.
- Radio: 433 MHz on/off‑keyed (OOK) transmitter.
-
Purpose: one‑way triggering of legacy 433 MHz firing boxes
(Bilusocn‑style remotes) via the app's
433firecommand. There is no return status on this band — it transmits only. - Used only if you are firing third‑party 433 MHz boxes alongside or instead of OS4 receivers. If you don't use 433 MHz boxes, this radio is simply idle.
Don't swap the antennas. A 2.4 GHz antenna on the 433 MHz port (or vice versa) will badly reduce range and reliability. Match the antenna to the labeled port.
The dongle connects to the host computer over USB and appears as a serial device. The host app and the on‑host bridge talk to the dongle through it.
- Plug the dongle into the host before launching the app.
- On Windows, the device shows up as a
COMport (e.g.COM3/COM4). - On macOS it appears as
/dev/tty.usbmodem*; on the Pi as/dev/ttyACM0. - If Light 1 (System) or Light 3 (TX link) won't come up, re‑seat the USB cable and confirm the app is pointed at the right serial port.
- Install both antennas. Plug the dongle into the host via USB.
- Launch the app and open
http://localhost:1776.- Light 1 turns green (service up); Light 3 turns yellow/green (link up).
- Load your show in the app. Light 4 turns green when loaded.
- When the field is clear and you're ready, set ARM. Light 7 pulses red, Light 5 turns purple (armed/ready).
- Hit START. Light 5 blinks cyan (pre‑flight check), then runs and pulses green while the show fires.
- To stop early, hit STOP or DISARM. Disarming always safes the system immediately.
| Symptom | Likely cause | What to do |
|---|---|---|
| Light 6 solid red at boot | 2.4 GHz radio not detected | Power‑cycle; check the radio module / Antenna 1 seating |
| Light 1 off | Host service not running / USB down | Start the app; re‑seat USB; check the serial port |
| Light 3 red | Dongle/bridge unreachable | Check USB and that the bridge process is running |
| Light 2 yellow/red | App link dropped/crashed | Reload the app page; restart the app |
| Light 4 red | Show failed to load | Open the app for the load error detail |
| Light 5 won't leave purple after START | Pre‑flight/arming issue | Confirm ARM is set and the field receivers report ready |
| No firing on a 433 MHz box | Wrong/idle 433 MHz path | Confirm Antenna 2 installed and the box is on the 433 MHz remote protocol |
- Treat ARM as a live switch. Keep the system disarmed until the field is clear and you are ready to fire.
- Disarming (or unplugging USB / cutting power) is the fastest way to safe the system.
- Manual fire is live the moment it is engaged while armed — know your cues before engaging it.
- Keep both antennas attached during operation; transmitting without an antenna can damage the radio over time.