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.

On macOS or Windows? If you just want to run and use the system, skip the manual setup — grab a one-click desktop installer. No Docker, no Python, no WSL. See Host installer downloads. If you intend to develop Backyard Hero (or are on an unsupported setup like an Intel Mac), use the from-source build instructions in the OS guides below.

Going Pi? Start from a fresh Raspberry Pi OS (64-bit) install and run the Pi install script. One command sets up the WiFi AP, NAT, mDNS, dongle udev rule, systemd auto-start, and pre-pulls the Docker image. After it finishes, plug in the dongle and open http://backyardhero/.

1. Pick your operating system

If you're on…	Go here
macOS (Apple Silicon) — easiest	Host installer downloads (one-click .dmg), or Getting Started — macOS from source.
Windows 10/11 — easiest	Host installer downloads (one-click .exe), or Getting Started — Windows from source.
Raspberry Pi (any 64-bit Pi)	Pi install script.
Intel Mac	Getting Started — macOS (no desktop installer for Intel — use Docker).
Linux (Ubuntu, Debian, …)	Getting Started — Linux

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. (On a Pi, the install script does all of this for you.)
2. Get the launcher files — clone the repo. Production-only users could in principle skip byh_app/, pythings/, and devices/ (the container brings its own copy), but on most installs you want the whole tree.
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 — host/run/<platform>/start.sh (or .bat). Open http://localhost:1776 (or http://backyardhero/ on a Pi), 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.