Getting Started

Getting Started

First, pick your path

Before anything else, decide why you're here. There are two routes, and they barely overlap:

Your goal	Route	What you do
I just want to use it — run shows and fire cues, and I won't be touching the code.	Installer	Download the one-click desktop installer. No Docker, no Python, no WSL, no repo clone. See Host installer downloads.
I want to get into the code — modify the UI, daemon, or firmware (or I'm on an unsupported setup like an Intel Mac).	Build from source	Follow the from-source OS guide below: install Docker + Python, clone the repo, and run the launchers.

Just using it? Stop here and go to Host installer downloads (macOS Apple Silicon + Windows). Everything below this point is the from-source/developer route — you don't need it.

Getting into the code? Keep reading. The rest of this page picks the right from-source guide for your OS and install mode.

Going Pi? A Raspberry Pi is its own thing — 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.