Home

Backyard Hero Documentation

PEOPLE WITH HARDWARE SHIPPED MAY/JUNE 2026 - if having issues with dongle not connecting to receivers, see this troubleshooting guide

Welcome to the Backyard Hero wiki — comprehensive documentation for the open-source DIY firework control system.

Backyard Hero is a complete, ground-up firework firing platform: a local web app, a Python firing daemon, custom 2.4 GHz receiver/dongle hardware, and an optional 433 MHz bridge for legacy Bilusocn one-way receivers. The whole system is designed to run on a laptop, a Raspberry Pi, or any small box that can host Docker.

TL;DR for new operators

1. Read Getting Started (pick the page for your OS). On macOS/Windows the fastest path is a one-click desktop installer; on a Pi, use the install script.
2. Plug a dongle in, flash a receiver, run host/run/<platform>/start.sh (or start.bat).
3. Open http://localhost:1776 (or http://backyardhero/ on a Pi) and walk through the End-to-End Show Example.

---

Table of contents

Getting started

• Getting Started — overview
• Desktop installers (macOS / Windows) — one-click, no Docker/Python
• Getting Started — macOS
• Getting Started — Linux
• Getting Started — Windows
• Production vs. Development mode
• Connecting the dongle
• Flashing a receiver
• Flashing a dongle
• OTA flashing receivers in the field

Raspberry Pi

• Pi install script — bare-OS-to-appliance one-shot installer
• WiFi access point — how the AP, NAT, and friendly URLs work
• Updating the Pi — update.sh walkthrough

System overview

• System architecture
• Glossary and terms
• Show lifecycle
• End-to-end show example

Subsystems

• Web application (Next.js)
• PC daemon (Python)
• WebSocket server
• TCP-to-serial bridge
• Database (SQLite)
• Configuration files

Hardware deep-dives

Hardware BOMs, schematics, fabrication files, and related board resources are available in the Contributor Portal.

• Receiver firmware
• Dongle firmware
• RF protocol details

UI walkthrough

• Status bar and modes
• Console page
• Editor page (Show Builder)
• Receivers page
• Loadout page
• Inventory page
• Manual fire page
• Settings page

Reference

• Daemon command reference
• Wire protocol reference
• REST API reference

Downloads

Installers

• Host installer downloads — one-click macOS/Windows desktop installers

Firmware

• Latest releases — top-level page with the current receiver and dongle binaries
• Receiver firmware releases — index of every receiver FW with release notes
• Dongle firmware releases — index of every dongle FW with release notes

---

Repository layout

Path	Purpose
host/	Everything that runs on the host computer: web app, Python services, Docker config, helper scripts.
host/byh_app/backyardhero/	The Next.js web application (byh-app, port 1776).
host/pythings/pc_daemon/	The Python firing daemon (firework-daemon).
host/pythings/websock_server/	The WebSocket server (websock, port 8090) that pushes daemon state to browsers.
host/pythings/inv_crawl/	Catalog crawler for the inventory library.
host/pythings/fp_gen/	YouTube audio analyzer that generates firing profiles.
host/tcp_serial_bridge/	Native Python TCP↔serial bridge plus the host-side flash server for UI-driven dongle updates (runs outside Docker so it can hold the USB serial port).
host/config/	systemcfg.json and example configs.
host/data/	Runtime data (SQLite DB, state files, catalog cache, AP request/status files).
host/run/pi/	Raspberry Pi launchers + install.sh + update.sh + update_dongle.sh + AP / NAT systemd integration.
host/run/osx/	macOS launchers + compose files + Docker Hub push script.
host/run/windows/	Windows launchers (start.bat) + compose files.
devices/	Firmware sources, CAD enclosures, helper flashing scripts.
devices/os4_receiver/	Receiver firmware (os4_receiver.ino) and bin/ artifacts.
devices/os4_dongle/	Dongle firmware (os4_dongle.ino) and bin/ artifacts.
devices/os4_cuemodule/	8-cue module hardware design.
devices/utils/	build_receiver.sh, flash_receiver.py, set_node_id.py, build_dongle.sh, flash_dongle.py.

What this system does, in 60 seconds

1. You design a firework show in the web UI — drag inventory items onto a timeline, optionally synced to an audio track, and assign each cue to a zone:target (a receiver and a cue number on it).
2. You stage the show, load it onto the system, and arm the box (physical switch on the dongle).
3. The daemon preloads the entire show schedule onto every nRF24 receiver over the air. Each receiver stores its own copy of "what to fire when".
4. You hit Launch. The daemon picks a synchronized start time about 25 seconds in the future, broadcasts it to every receiver, and at T-0 the receivers run the show autonomously — even if the host loses RF for a few seconds, every cue still fires on time. (Legacy 433 MHz Bilusocn cues are timed by the host and bit-banged on the dongle's 433 MHz frontend.)
5. Throughout the show, telemetry — battery, continuity, latency, success percentage — streams back from each receiver via ACK payloads. Flipping the dongle's start/stop switch (or the abort button in the UI) immediately broadcasts a stop.

If that sounds interesting, start with Getting Started.