Getting Started

Getting Started

This is the meta page that picks the right install path for you. Pick your operating system and your install mode, then jump to the matching page.

1. Pick your operating system

If you're on…	Go here
macOS (Intel or Apple Silicon)	Getting Started — macOS
Linux (Ubuntu, Debian, Raspberry Pi OS, …)	Getting Started — Linux
Windows 10/11	Getting Started — Windows

2. Pick your install mode

Backyard Hero supports two ways to run the host stack:

Mode	What you get	When to use it
Production (recommended for first-time users)	Pulls the prebuilt Docker image os4ivmb/backyardhero from Docker Hub. No need to clone the full repo or install Node.js / Python build deps. Fastest path to "I can fire a cue".	You just want to run shows.
Development	Builds the Docker image from the local source tree, mounts source directories so changes hot-reload.	You're modifying the UI, daemon, or firmware.

See Production vs Development mode for the full breakdown.

3. The big picture (so you know what's happening)

Each OS guide walks through the same five things:

1. Install prerequisites — Docker, Python 3 for the serial bridge, plus arduino-cli + esptool if you'll be flashing firmware yourself.
2. Get the launcher files — clone the repo (dev mode) or download a slim release tarball with just the launcher scripts and host/config/ (production mode).
3. Flash one or more receivers — see Flashing a Receiver. Each receiver gets a NODE_ID like RX146 written to its NVS once.
4. Flash a dongle (only if you don't already have one) — see Flashing a Dongle.
5. Plug the dongle in and start the system — start_prod.sh (or .bat). Open http://localhost:1776, add the receivers in the UI, and you're live.

There is no cloud account, license server, or external service. Everything runs on your laptop.

4. Hardware checklist

Before you can fire a cue, you'll need:

• One dongle (custom 2.4 GHz + optional 433 MHz, USB-C to host).
• One or more receivers (custom 2.4 GHz, USB-C charged, with one or more 8-cue modules attached).
• A host computer with at least one free USB port. A laptop, a Mac mini, or a Raspberry Pi 4/5 all work.
• Docker Desktop (macOS / Windows) or Docker Engine (Linux).
• Python 3.9+ for the host-native serial bridge.

You do not need an internet connection at show time. You do need one the first time you run the system, to pull the Docker image and the firmware bin files.

5. After you're up

Once the UI loads, head to:

• Connecting the dongle to confirm your serial port is set correctly.
• Show lifecycle for a conceptual overview of what happens when you load and fire a show.
• End-to-end show example for a concrete two-receiver, four-cue walkthrough.
• UI walkthrough for a tour of every page.