Home

Backyard Hero Documentation

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).
2. Plug a dongle in, flash a receiver, run start_prod.sh (or start_prod.bat).
3. Open http://localhost:1776 and walk through the End-to-End Show Example.

---

Table of contents

Getting started

• Getting Started — overview
• 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

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

• 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
• Firmware downloads

---

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 (runs outside Docker so the daemon container can reach the dongle).
host/config/	systemcfg.json and example configs.
host/data/	Runtime data (SQLite DB, state files, catalog cache).
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).
devices/os4_cuemodule/	8-cue module hardware design.
devices/utils/	build_receiver.sh, flash_receiver.py, set_node_id.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.