Subsystem Config

Subsystem: Configuration

host/config/systemcfg.json is the one-and-only configuration file an operator needs to touch (and even then, only the dongle port). Everything else is in SQLite, edited from the UI.

Schema

{
  "host_version": 0.08,
  "system": {
    "dongle_port": "/dev/tty.usbmodem01",
    "dongle_baud": 115200,
    "dongle_protocol": "BKYD_TS_HYBRID"
  },
  "DONT FUCK WITH ANYTHING UNDER HERE": "OKAY, I WONT",
  "protocols": {
    "BKYD_TS_HYBRID": {
      "label": "Backyard Hero v0.1",
      "config": {
        "min_battery_to_fire_pct": 30,
        "require_continuity": false
      }
    }
  },
  "types": {
    "BILUSOCN_433_TX_ONLY": {
      "supported_protocols": ["BKYD_TS_HYBRID"],
      "label": "Bilusocn 4ch",
      "isOneWay": true,
      "checks": ["TX"],
      "frequency": 0.4339,
      "canTransmit": false,
      "addressable": false,
      "capabilties": [],
      "configs": {}
    },
    "BKYD_TS_24_1": {
      "label": "BYH v0.2",
      "supported_protocols": ["BKYD_TS_HYBRID"],
      "isOneWay": false,
      "checks": ["TX", "CONTINUITY", "MIN_POWER"],
      "frequency": 2.49,
      "canTransmit": true,
      "addressable": true,
      "capabilties": ["CONTINUITY", "POWER", "MESH", "PRELOAD", "SYNC"]
    }
  }
}

Field-by-field

Top level

• host_version (number) — semver-ish. Used by build_and_push_docker.sh to tag the Docker image (:v<version>). Bumped by maintainers when shipping a release.

system block

• dongle_port (string) — the host serial path of the dongle:
  • macOS: /dev/tty.usbmodem01 (or /dev/tty.usbmodem1101 etc.)
  • Linux: /dev/ttyACM0 (or a stable name from a udev rule)
  • Windows: COM5 (or whatever Device Manager reports)
• dongle_baud (number) — fixed at 115200. Don't change it; the dongle hardware is wired for this rate.
• dongle_protocol (string) — which protocol to load. Currently only BKYD_TS_HYBRID is supported.

protocols block

A map of available protocols. Each protocol has:

• label — human-readable name shown in the UI.
• config — runtime parameters the daemon re-reads on every run_precheck:
  • min_battery_to_fire_pct (number 0–100) — receivers below this percent are rejected by precheck. Default 30.
  • require_continuity (bool) — if true, every cue's continuity bit must be set before the show can run. If false (the default), continuity is informational only. Many users keep this off for convenience and watch the UI's continuity colors instead.

types block

A map of receiver types. Each type advertises:

• label — human-readable name in the UI.
• supported_protocols — which protocols this type can speak.
• isOneWay — true for receivers without uplink (e.g. Bilusocn).
• checks — list of pre-fire checks the system can apply (TX, CONTINUITY, MIN_POWER).
• frequency — radio frequency in GHz (used for UI display).
• canTransmit — whether the type can transmit back to the dongle (false for one-way).
• addressable — whether the type has an addressable identity (false for broadcast-only systems).
• capabilties [sic, typo preserved] — feature flags the UI uses to show/hide controls. CONTINUITY, POWER, MESH, PRELOAD, SYNC.

Editing the file

You can edit systemcfg.json directly with any text editor. Changes to:

• system.dongle_port — take effect when you restart the daemon (or hit "Restart dongle" in the status bar).
• protocols.<x>.config.* — re-read on every run_precheck. No restart needed.
• types.* — re-read on UI page refresh. The UI does not modify these.

The Next.js API route GET /api/system/config returns this file overlaid with the live Receivers table from SQLite (so the UI always has both in one fetch). POST /api/system/config writes back, stripping any receivers block before saving (so SQLite stays the source of truth for receivers).

The legacy receivers block

You'll see this in the example file at host/config/systemcfg_bilusocn.json:

{
  "receivers": {
    "RX161": { "label": "Main Receiver", "type": "BKYD_TS_24_1", "cues": { "RX161": [1,2,3,4,5,6,7,8] } },
    "BSC1": { "label": "Bilusocn 1", "type": "BILUSOCN_433_TX_ONLY", "cues": { "1": [1,2,3,4] } }
  }
}

This is the legacy format from before the Receivers SQL table existed. It's only used to seed the SQL table the very first time the database is empty (seedReceiversFromSystemCfgIfEmpty() in sqldb.js). After that:

• All edits go through the UI (which writes to Receivers).
• POST /api/system/config strips this block.
• Adding a receiver to the file by hand has no effect on a database that already has any rows.

If you want to bulk-import receivers from a fresh start, edit systemcfg.json, delete host/data/backyardhero.db, and start the system. The seed will run once.

Files in this directory

File	Purpose
systemcfg.json	The active config.
systemcfg_bilusocn.json	An example config showing what a Bilusocn-only fleet looks like, with the legacy receivers block populated.

You can keep multiple configs around and copy whichever you want into systemcfg.json before starting the stack.

Other configurable knobs (not in this file)

These all live in the SQL Receivers table or the daemon's LED state file (/data/leddata) and are edited from the UI:

• LED brightness — Settings → Dongle → Brightness.
• Fire repetition count — Settings → Dongle → Transmit repetition. How many times to send each 433fire to overcome 433 MHz noise.
• Receiver inactivity timeout — Settings → Debug → Daemon → Receiver timeout. The dongle's "no contact = offline" threshold (default 30 s).
• Command response timeout — Settings → Debug → Daemon → Response timeout.
• Clock sync interval — Settings → Debug → Daemon → Clock sync. Default 2000 ms.
• Debug mode — Settings → Dongle → Debug mode. Enables verbose logging on both daemon and dongle.
• Per-receiver fire duration — Receivers → (edit) and Settings → Receivers → Broadcast. Default 1000 ms; range 50–5000 ms.
• Default map location — Settings → Show config → Default location. Used as the initial center of the spatial layout map for new shows.