Getting Started Windows

Getting Started — Windows

Tested on Windows 10 and 11 (x64). Everything below uses PowerShell unless noted otherwise.

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 WSL. See Host installer downloads. This from-source build guide is for when you intend to develop Backyard Hero, or for advanced setups.

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

---

Step 1 — Install prerequisites

Docker Desktop

Download from https://www.docker.com/products/docker-desktop and install. After install, launch Docker Desktop and wait for the whale icon in the system tray to stop animating. Then verify:

docker run --rm hello-world

Docker Desktop on Windows uses WSL2 under the hood. The default install enables it; if you've never used WSL, the installer will prompt for a reboot.

Python 3

Download from https://www.python.org/downloads/windows/. Important: during install, tick "Add Python to PATH". Verify:

python --version

Git for Windows

Download from https://git-scm.com/download/win and install with defaults.

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

Easiest via Scoop or Chocolatey:

# Scoop:
scoop install arduino-cli

# Or Chocolatey:
choco install arduino-cli

Then once:

arduino-cli core update-index
arduino-cli config init
arduino-cli config set board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli core update-index
arduino-cli core install esp32:esp32

USB-to-serial driver

Most ESP32-S2 dongles enumerate as USB-CDC and don't need a separate driver on Windows 10 / 11. If your dongle uses a CP210x or CH340 USB-to-serial chip instead (older revs), grab the matching driver:

• CP210x: https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers
• CH340: https://www.wch.cn/downloads/CH341SER_EXE.html

---

Step 2 — Decide between production and development

See Production vs Development mode. Production = pull the prebuilt image. Development = build from source.

---

Step 3 — Get the source

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

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

---

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

Plug the dongle into a USB port. Open Device Manager → Ports (COM & LPT) and look for an entry like USB Serial Device (COM5) or Silicon Labs CP210x USB to UART Bridge (COM7). Note the COMn number.

Edit host\config\systemcfg.json (open in Notepad, VS Code, or whatever you have):

{
  "host_version": 0.08,
  "system": {
    "dongle_port": "COM5",
    "dongle_baud": 115200,
    "dongle_protocol": "BKYD_TS_HYBRID"
  }
}

Important: on Windows, dongle_port is a COMn string. The bridge translates this for the daemon, which sees it as a Linux-style path inside the container. You don't need to do that translation manually — the bridge handles it.

If COMn numbers shift between unplug/replug, see the troubleshooting section below.

---

Step 5 — Flash and provision your receivers

Skip if your receivers were pre-flashed.

# From the repo root:
devices\utils\build_receiver.sh                                     # bash; works under Git Bash or WSL
python devices\utils\flash_receiver.py --full --node 146           # provision RX146

flash_receiver.py is pure Python and runs natively on Windows. build_receiver.sh is a bash script — easiest to run under Git Bash (installed with Git for Windows) or WSL.

Detailed flow on Flashing a Receiver.

---

Step 6 — Start everything

Production

cd $HOME\byh
.\host\run\windows\start.bat

What you'll see:

• A second window pops up titled BYH-Bridge running the TCP-to-serial bridge.
• The main window pulls the Docker image (~few hundred MB on first run) and runs docker compose up.
• Logs from the daemon, websocket server, and Next.js app stream into the main window.

To stop everything: close the main window (or Ctrl-C it), then close the BYH-Bridge window.

Development

The Windows folder currently only ships a single start.bat that always rebuilds the image from local source. Use that for both prod-pull (just rerun and it'll pull) and dev workflows.

---

Step 7 — Open the UI and add your receivers

Browse to http://localhost:1776.

Add your receivers from the Receivers tab. Same flow as macOS — see Getting Started — macOS, Step 7.

---

Step 8 — Run a test fire

End-to-end show example walks through a full show start to finish.

---

Common problems on Windows

• "Docker daemon not running" — Docker Desktop must be open. The whale icon in the system tray should be steady (not animating).
• docker compose is unrecognized — Docker Desktop ships the docker compose plugin. Make sure your install is up to date; older docker-compose.exe standalone installs are deprecated.
• The bridge window crashes immediately — usually a wrong COM port. Double-check Device Manager and update dongle_port in host\config\systemcfg.json.
• COM port number changes after replug — Windows assigns COM numbers per USB serial number. If you have several similar dongles, the order can vary. Either always plug into the same physical USB port, or use a USB hub with stable port numbering.
• Antivirus quarantines flash_receiver.py — it talks to a USB serial device with pyserial and shells out to esptool.py, which some AVs misclassify. Add the devices\utils\ folder to your AV exclusions.
• Firewall popup the first time you run start.bat — Windows Defender Firewall prompts to allow python.exe to listen on TCP 9000 (the bridge) and 8090 (websocket server). Allow on private networks.
• Browser refuses to connect to localhost:1776 — confirm the docker container is actually up: docker ps should show firework-system. If not, scroll the main window for the failure (usually a bad serial port string in systemcfg.json).

---

Native Windows note

There is no fully native (no-Docker) Windows path today. The web app would run fine under Node directly, and the daemon under Python, but supervisord is Linux-only, and we'd need to rewrite the launchers. If you want this, see the roadmap at the bottom of README.md in the repo and feel free to contribute.