Glossary and Terms

Glossary and terms

If something in the docs or UI doesn't make sense, look here first.

Hardware

Receiver — a battery-powered, RF-attached box that takes fire commands from the host and switches power to the cue modules attached to it. In Backyard Hero, "receiver" almost always means a custom 2.4 GHz BYH receiver (BKYD_TS_24_1); legacy 433 MHz receivers (BILUSOCN_433_TX_ONLY) are also supported and are explicitly called Bilusocn / "433" when context matters.

Dongle — the USB-attached RF master. Holds both a 2.4 GHz nRF24L01+ for talking to BYH receivers and a 433 MHz transmitter for one-way Bilusocn-style fire commands. Provides the three operator switches (start/stop, arm, manual fire). One per system.

Cue module / 8-cue module — the chained PCB that physically drives e-matches. Each module has 8 cues (FET-driven outputs). Up to 16 modules can be chained per receiver, for a maximum of 128 cues per receiver. Most installs use 1–4 modules per receiver.

Cue — one fireable output. Numbered 1..N within a receiver. A real cue corresponds to one e-match.

Continuity — the receiver's ability to electrically detect that an e-match is connected and intact at a given cue. Reported per-cue in telemetry.

Show data

Show — a row in the SQL Show table. Contains a display_payload (the timeline as the editor sees it), a runtime_payload (the firing array the daemon actually fires), per-show receiver list, audio tracks, racks, optional spatial layout, and an authorization_code (a small password the operator types to load the show — a "did you really mean to load THIS show" check).

Show item / timeline item — one entry on the timeline. Has a type (SHELL, CAKE_FOUNTAIN, RACK_SHELLS, FUSED_LINE, etc.), a startTime (seconds from show start), a duration, a delay (e.g. fuse delay subtracted from the visible startTime to compute the actual fire time), a zone, and a target.

Zone — the receiver identifier the cue belongs to, e.g. RX146. (For Bilusocn it's a numeric station.) Coming from the legacy Bilusocn world, where one transmitter serves multiple "zones" of slaved receivers.

Target — the cue number within the zone. 1-indexed in the UI; converted to 0-indexed when sent over the wire (fire RX146 0 for cue 1).

Show receivers — the list of receivers a particular show uses, with their cue counts. Stored on the show row (column show_receivers). Distinct from the global Receivers table — a show "owns" its target grid so renaming or removing a global receiver doesn't silently break old shows.

Stage / staged show — the show the operator has selected in the Console as the show to load next. Persisted to localStorage as stagedShowId. Different from "loaded" — a staged show isn't on the receivers yet.

Load / loaded show — pushed to the receivers via startload + showloadn commands. The receivers store the per-cue schedule in their own RAM and report loadComplete=true when they've received every cue.

Run / running show — the daemon is in run_show and the schedule is active. Distinct from "fired" — a running show might have just been launched and be in the 25-second pre-start countdown.

Authorization code — a per-show password set when the show is created. The operator must type it to save an existing show (in the editor) and to load the show (in the Console). Lightweight protection against stomping on the wrong show during pre-event chaos.

Receivers and racks

Rack — a physical mortar rack. In the UI, a 2D grid (X rows × Y rows) of cells, each of which can be assigned a shell. Stored per-show in the racks table. A rack assigns shells to cells, optionally connects cells with fuses, and can be referenced from the timeline as a RACK_SHELLS item — a single timeline cue that lights one fuse and propagates through the chained cells.

Fuse (rack context) — a chain of cells in a rack connected by physical fuse cord. Fuses have a type (which is itself an inventory item with a burn rate, e.g. green fuse at 1 s/ft) and a lead-in (inches of fuse from ignition to first cell). The builder computes the inter-cell delays automatically from cell distance and burn rate.

Fuse (inventory context) — an inventory item of type: FUSE with a burn_rate field (seconds per foot). Used by racks and by FUSED_LINE items.

Loadout — the operator's view of "what to physically pack and bring to the field". Built from a staged show; lists every receiver, every cue, every rack, every shell. Includes a printable PDF and a satellite map of receiver positions. See UI Loadout page.

Inventory

Inventory item — a row in the inventory table representing a pyro product (cake, shell pack, single shell, fountain, fuse, etc.). Has a name, type, duration, color, optional YouTube link with start time, optional cost, and free-form metadata.

Shell pack — an inventory item that represents multiple shells of the same type. Internally still one inventory row; the UI treats it specially.

Firing profile — a row in inventoryFiringProfile containing the shot timestamps for an inventory item, derived by analyzing a YouTube video's audio. Used to render an accurate timeline preview ("at +1.4 s the third break goes off").

Catalog — a JSON dump of curated pyro products fetched from backyard-hero.com/catalog.json and cached at /data/catalog.json. Drives the Add from library flow in the inventory editor.

Protocol

BKYD_TS_HYBRID — the protocol the daemon currently speaks. "Hybrid" because the dongle handles both 2.4 GHz BYH receivers and 433 MHz Bilusocn cues over the same link. Set in systemcfg.json as system.dongle_protocol.

BKYD_TS_24_1 — the receiver type for the custom 2.4 GHz BYH receivers. Two-way, addressable, supports CONTINUITY / POWER / MESH / PRELOAD / SYNC capabilities (mesh is currently disabled — the radios are good enough to not need it).

BILUSOCN_433_TX_ONLY — the receiver type for legacy 433 MHz Bilusocn 4-channel receivers. One-way, no telemetry, no preload — every cue is timed by the host and bit-banged on the dongle's 433 MHz frontend at fire time.

Preload — the act of sending the entire show schedule to a receiver before the show starts. The receiver stores the cues in RAM and fires them autonomously from its own clock once play arrives. This is how BYH achieves precise timing even if the RF link drops mid-show.

Clock sync — a msync (host→dongle) and CLOCK_SYNC (dongle→receiver) message that aligns the receiver's millisecond clock with the host's wall clock. Sent at startup and on every poll cycle (~2 s by default). Receivers compute their clock_offset and use it to schedule cues relative to the host-supplied showStartTime.

Synchronized time — a receiver's millis() + clock_offset. Used to compute "is it time to fire cue N yet" during a running show.

ACK payload — a feature of nRF24 where each command from the dongle carries up to 32 bytes of telemetry from the receiver in the auto-ACK packet. BYH uses this for the entire RECEIVER_STATUS channel (cuts round-trip in half compared to a separate "tell me your status" frame).

Show start time — an absolute synchronized millisecond timestamp at which the show begins. Picked by the daemon as now_ms + 25 s and broadcast to every receiver via SHOW_START. Each receiver evaluates "is getSynchronizedTime() >= showStartTime + cue_offset" in its main loop to decide when to fire.

Daemon state

Mode — a single-word badge derived from daemon state and shown in the top bar. One of: Disconnected, Design, Ready, Loaded, Armed, Live, Manual fire, Pre-check, Countdown, Stopped. Derivation lives in useAppMode.js.

Delegate to client (DSTC) — a daemon flag (default ON). When enabled, clicking Launch in the UI does not actually start the show — it puts the daemon into DELEGATE_WAIT and waits for a follow-up start_show command (typically driven by the operator flipping the start switch on the dongle). This matches how big-pyrotechnic firing systems work: the operator's hand on the box is the "really start now" signal, separate from the operator's mouse on the laptop.

Pre-fire check — a battery + continuity + serial-link sanity gate run by BYHProtocolHandler.run_precheck before the show actually starts. Fails fast if any receiver's battery is below min_battery_to_fire_pct (configurable per protocol; default 30%) or if require_continuity is set and any active cue's continuity bit isn't set.

Fire check failures — the list of human-readable error strings the daemon publishes on the state file (fire_check_failures). The Console UI surfaces them as red banners and refuses to let you load/start the show until they're fixed.

Wire-level

Status frame — the dongle's per-second JSON line on USB containing aggregate telemetry for all receivers, current RF channel, command-queue depth, and the firmware-clamped clock_sync_interval_ms. See Wire protocol reference.

rxupd — a JSON line the dongle emits whenever a single receiver's state changes (faster path than waiting for the next status frame). Same key set as one element of the receivers[] array in status.

rxcfg — the dongle's reply to a rxcfg <ident> command (CONFIG_QUERY). Carries fwVersion, boardVersion, numBoards, cuesAvailable, fireDurationMs, etc. Persisted to the Receivers row.

scan_result — the dongle's reply to a scan command. Per-channel hit counts from an nRF24 RPD sweep. Used by the UI to recommend a quiet RF channel.

OTA chunk — a 29-byte payload of a flash_data line. The maximum OTA payload that fits in a 32-byte nRF24 packet after the 3-byte header.

Operator hardware terms

Start / stop switch — the master "go" switch on the dongle. UP = STOP (everything paused, nothing fires). DOWN = START (show schedule runs).

Arm switch — the safety arming switch. UP = DISARMED (fire commands rejected). DOWN = ARMED. Both arm and start need to be in the right position before anything fires.

Manual fire switch — when ON, the system enters Manual Fire mode: the show schedule is suspended and the operator can fire individual cues from the Manual page in the UI. When OFF, manual fire is rejected and the show schedule resumes (if loaded).