tony99nyr/open-brx

An open-source (MIT) platform that turns **Battle Company BRX** laser taggers into one connected laser tag
system: hosted game modes, live scoring, custom weapons, objectives and a laptop Mission Control, on stock
guns with stock firmware. It is a self-hosted alternative to Battle Company's Edge software: no subscription,
no location lock, and it is designed for large fields with no venue Wi-Fi. The same repo is the source of two
public doors built from one static-site generator: the platform landing/docs (docs/platform/) at
, and **The Ultimate BRX Manual**, the public reference for the tagger
and headset, built from docs/manual/ and served at .
Today a laptop runs a full scored Team Deathmatch on real taggers over Bluetooth LE (Tier 0), and the
per-player phone app (the BRX Combat HUD) plus the Mission Control console have run two whole multi-phone
matches outdoors on real hardware (2026-08-30 and 2026-09-01). The phone-node path is what lifts the laptop's
BLE-range limit.
**Start here: docs/README.md**, the documentation index. It points to
docs/architecture-topology.md (how it is wired and what is proven),
the manual, the spec of record (docs/spec/), the ADRs and the open-work list.
> **Credit:** Protocol discovery and the tagger-rider ESP32 concept originate with
> **LaserTagMods** (JEDGE / JBOX projects). This project is a fresh,
> independent implementation, no code copied, but it stands on that discovery work.
**Prime directives**
1. Stock BRX firmware is **never modified**. All control is via the documented Bluetooth serial protocol
(protocol/brx-protocol.md). Power-cycling always restores a tagger; Battle Company's USB updater is the
factory-restore path.
2. Store-and-forward everywhere: every node buffers timestamped events locally and syncs when in coverage.
Live feed is best-effort; final results are always complete.
3. Each per-player **node** runs its own gun's game loop autonomously (offline-capable); **Mission Control**
(a laptop) authors games and aggregates the scoreboard over the local LAN. It is not a live BLE hub
(ADR-0001 / 0002).
4. Everything is a subscriber: scoreboard, lights, smoke, announcer are peers on the event stream.
Repo layout
| Path | What |
|---|---|
| docs/ | **docs/README.md** index: the platform pages (docs/platform/), the manual (docs/manual/, canonical BRX facts), the spec of record (docs/spec/), ADRs, followups, reference notes, the lab notebook |
| protocol/ | The serial command reference (brx-protocol.md), the IR word (brx-ir-protocol.md), the Callsign APK teardown (callsign-extract/: command/field maps, $WEAP token map) and the decoded captures |
| mcp/ | **brx-mcp**, the MCP server + CLI that drives taggers over BLE, and **mcp/brx_mcp/mc/**, the Mission Control server (game modes, scoring, the frame compiler; API.md is the server⇄UI contract) |
| app/ | **BRX Combat HUD**, the native per-player phone app (Capacitor: one codebase → Android + iOS, native BLE). See app/README.md |
| webapp/ | The site generator's output lands here, git-ignored (built from docs/platform/ + docs/manual/ by site/). webapp/mc/ (the Mission Control console, Vite/React) and webapp/download/build.json (the Android build sidecar, which points at the GitHub Release) are hand-kept and tracked |
| site/ | The static-site generator (two doors, one source: docs/site/FORMAT.md) and its Playwright verification suite |
| hardware/ | esp32-ir-bridge/ and m5sticks3/ (built ESP32 rigs), the Companion and Station specs, print-file notes |