Getting Started macOS

Getting Started — macOS

This page walks you from "freshly-imaged Mac" to "Backyard Hero web UI open at http://localhost:1776". Tested on macOS 13 Ventura and newer, on both Intel and Apple Silicon Macs.

On an Apple Silicon Mac and just want to run and use the system? You probably don't need this page. Grab the one-click installer instead — no Docker, no Python, no Homebrew. See Host installer downloads. This from-source build guide is for when you intend to develop Backyard Hero, or for Intel Macs (which have no desktop installer build).

If you already have Docker Desktop and Python 3 installed, jump to Step 3.

---

Step 1 — Install prerequisites

Open Terminal and run the following one-liners. None of them require admin (sudo) password if you already have Homebrew set up.

Homebrew (skip if you already have it)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Docker Desktop

The easiest way is the GUI installer at https://www.docker.com/products/docker-desktop. Or via Homebrew:

brew install --cask docker
open -a Docker          # launch Docker Desktop and let it finish starting

Wait for the Docker whale icon in the menu bar to stop animating. Test:

docker run --rm hello-world

Python 3 + git

Both ship with macOS' Command Line Tools. Force the install if you've never compiled anything before:

xcode-select --install

(Only if you'll flash your own firmware) arduino-cli

brew install arduino-cli

You don't need this if you already received pre-flashed hardware or only ever plan to flash receivers over-the-air with the OTA flasher.

---

Step 2 — Decide between production and development

Read Production vs Development mode if you haven't yet.

You want to…	Use this mode
Just run shows. Don't care about modifying the codebase.	Production — pulls os4ivmb/backyardhero from Docker Hub.
Hack on the UI / daemon / firmware.	Development — clones the full repo, builds locally, hot-reloads.

The rest of this page covers both. Skip the steps marked (dev only) if you're going production.

---

Step 3 — Get the source

The launchers and compose files live under host/run/osx/. There's no slim "production-only" download — just clone the whole repo:

git clone https://github.com/os4-ivmb/backyardhero_pyro ~/byh
cd ~/byh

You can in principle delete byh_app/, pythings/, and devices/ after first run if you only ever plan to run prod (the container ships its own copy), but they're useful to keep around for firmware flashing.

---

Step 4 — Plug in the dongle and find its serial port

Plug the dongle into a USB-C port. macOS will enumerate it as a USB-CDC serial device. List ports:

ls /dev/tty.usbmodem*
# Typical output: /dev/tty.usbmodem01

If you see nothing, the dongle's firmware might be missing — flash it (see Flashing a Dongle).

Edit host/config/systemcfg.json and set the dongle_port to the value you saw:

{
  "host_version": 0.08,
  "system": {
    "dongle_port": "/dev/tty.usbmodem01",
    "dongle_baud": 115200,
    "dongle_protocol": "BKYD_TS_HYBRID"
  }
}

If your port is different (e.g. /dev/tty.usbmodem1101), use that string verbatim. See Connecting the dongle if the port number changes between unplug/replug.

---

Step 5 — Flash and provision your receivers

Skip this step if your receivers were pre-flashed for you.

# From the repo root:
devices/utils/build_receiver.sh                       # one-time, requires arduino-cli
devices/utils/flash_receiver.py --full --node 146     # provision a brand-new receiver as RX146

Repeat for each receiver, picking a unique NODE_ID (1–254) for each one. The full reference is on Flashing a Receiver. You'll add each receiver to the web UI in Step 7.

---

Step 6 — Start everything

Production

cd ~/byh
./host/run/osx/start.sh

You'll see:

• The script create a Python venv on first run and install pyserial.
• The TCP-to-serial bridge start (logs to the terminal).
• Docker pull os4ivmb/backyardhero:latest (a few hundred MB on first run).
• The container start, the daemon connect, and the web app come up.

Development

cd ~/byh
./host/run/osx/start-dev.sh    # uses docker-compose-dev.yml; mounts ./byh_app and ./pythings

To stop everything cleanly: Ctrl-C in the terminal — the script will tear down both the bridge and the docker stack.

---

Step 7 — Open the UI and add your receivers

Open http://localhost:1776 in your browser. You'll see the dark Backyard Hero shell with the Console tab selected.

1. Click Receivers in the top nav. You'll see an empty fleet.
2. Click Add receiver and fill in:
   • Identifier: the same string you flashed (e.g. RX146).
   • Type: BKYD_TS_24_1.
   • Cues: click the cue grid to mark which cues this receiver controls (typically 1..8 for one cue module, 1..16 for two, …).
3. Save. Within a few seconds the receiver should turn green ("Online") in the list. Telemetry — battery, signal, success percentage — will start populating.
4. If it never goes online, see the troubleshooting section in Flashing a Receiver.

---

Step 8 — Run a test fire

Now hop to End-to-end show example for a complete walkthrough. The short version:

1. Inventory tab → add at least one shell.
2. Editor tab → create a show, drop the shell on the timeline, point it at a real cue.
3. Console tab → stage the show, click Load show, type the auth code from the editor, then physically arm the dongle (start switch to STOP, arming switch to ARMED). When the receivers report loadComplete, click Launch, then flip the dongle's start switch to START. The countdown begins; the receiver fires.

Don't actually wire up real pyro until you've done a blind dry-run with no e-matches connected.

---

Common problems on macOS

• "docker compose: command not found" — the modern Docker Desktop uses docker compose (a plugin) instead of the standalone docker-compose binary. The launcher scripts auto-detect both.
• Permission denied on /dev/tty.usbmodem01 — macOS doesn't usually require special permissions for USB-CDC. If you see this, close any other terminal/Arduino IDE that might be holding the port.
• Bridge keeps logging "auto-reconnect attempt N failed" — the dongle isn't enumerating. Try a different USB-C cable (some "charging only" cables don't carry data) and a different port.
• macOS Gatekeeper blocks the launcher script — chmod +x host/run/osx/start.sh and xattr -d com.apple.quarantine host/run/osx/start.sh if needed.