UI Settings Page

UI: Settings page

System knobs. Organized into top-level sub-tabs along the underline-style tab strip; tabs hide themselves when not applicable (the Network tab only appears on a Raspberry Pi install).

📷 Screenshot placeholder: the Settings page with the Dongle sub-tab open, showing brightness slider and serial config.

Tab	Pi-only?	What lives here
Dongle	no	Physical-box knobs: LEDs, retransmit count, serial connection, debug-mode toggle.
Receivers	no	Fleet-wide receiver runtime config (broadcast fire-pulse width, etc.).
Network	yes	WiFi access point + UI-driven system update.
Debug	no	RF spectrum scan, daemon timing, OTA flash, dongle firmware update.
Show config	no	Pre-fire safety checks + default show location.

The Network tab is gated on host.is_raspberry_pi reported in /api/system/config. On a dev laptop or non-Pi server the tab is hidden entirely so the operator doesn't dead-end into a "this needs the host-side byh-ap-apply systemd service" empty pane.

---

Tab 1 — Dongle

Knobs for the physical dongle box.

Brightness slider

Sets the LED brightness on the dongle (0–100). Saved persistently — survives daemon restart.

Transmit repetition count

How many times each 433fire command is bit-banged on the 433 MHz line. Default 6. Higher = more reliable on noisy channels but adds latency. Doesn't affect 2.4 GHz BYH receivers (those use auto-ACK with retries).

TX config (serial)

• Serial port — same as system.dongle_port in systemcfg.json. Edit and save → daemon writes the config back, posts select_serial to itself, the bridge reconfigures. On a Pi install the default is /dev/byh_dongle (the install-script udev symlink); on macOS something like /dev/tty.usbmodem01; on Windows COM5 (varies).
• Baud — fixed at 115200.
• Protocol — currently only BKYD_TS_HYBRID.

Debug mode toggle

When on, both the daemon and dongle emit verbose logs. The dongle prints every received frame; the daemon echoes every serial line. Useful for diagnosing problems; expensive to leave on in production because it generates a lot of log volume.

---

Tab 2 — Receivers

Fleet-wide receiver configuration.

Broadcast fire duration

Set a fire_duration_ms (50–5000) and click Apply to all. Triggers fetch_receiver_config with fire_duration_ms set, without an ident — the daemon broadcasts to every connected BKYD_TS_24_1 receiver. Each receiver writes the new value to its NVS and ACKs.

The default fire duration is 1000 ms (one second). Shorter (~250–500 ms) saves battery but might not reliably ignite some e-matches; longer (~2000+) wastes battery and slows pause/resume. 1000 ms is a reasonable starting point.

Refresh all configs

Click Refresh to fetch every receiver's config (FW version, board version, fire duration, etc.) and update the SQL Receivers rows. Useful after firmware updates to confirm what's flashed where.

---

Tab 3 — Network (Pi-only)

The Pi-specific surface for talking to the on-board WiFi and the host-side update pipeline. Only appears on a Pi install (host.is_raspberry_pi === true); on macOS / Windows hosts this whole tab is hidden.

WiFi access point

The form for changing the AP's SSID, password, channel, and country. Reads the current state from /data/byh_ap_current.json and writes new requests to /data/byh_ap_request.json for the host-side byh-ap-apply.py service to pick up.

Field	Validation
SSID	1–32 printable ASCII characters.
Password	8–63 printable ASCII characters (WPA2-PSK constraint).
Channel	1–14, with the regulatory domain constraining what's actually legal.
Country	2-letter ISO code (US, GB, DE, etc.).

After Save, the UI shows a "Connection will drop in ~3 s — reconnect to <new SSID> with password <new password>" dialog before the radio actually flips. The 3-second deferred restart exists so the API response reaches the operator's phone before the AP is severed.

If the new config fails to apply (illegal channel for the country, hostapd crash, etc.), byh-ap-apply.py rolls back to the previous hostapd.conf and reports the error back through /data/byh_ap_status.json. The UI shows the error and the AP keeps running on the old credentials.

The full mechanics are on the WiFi Access Point page.

System update

A "Check for updates" / "Apply update" flow that runs host/run/pi/update.sh -y on the host without the operator having to SSH in.

• Check for updates — queries Docker Hub for the latest image digest and git ls-remote for the latest commit on main, compares to what's running, and shows a summary of what would change.
• Apply update — POSTs /api/system/update. The Next.js route writes /data/byh_update_request.json, the byh-update.path watcher fires byh-update.service, which shells out to update.sh and streams progress to /data/byh_update_status.json. The UI polls that and renders a live phase indicator (pulling source → pulling image → re-applying state → restarting). The whole flow takes 1–3 minutes depending on network speed; the UI's WS reconnects automatically when byh-host comes back.

See Updating the Pi for the full flow and the CLI equivalent.

---

Tab 4 — Debug

Diagnostics surface — "you only touch this if something is wrong".

RF Scan panel

Triggers an RF spectrum scan via scan_radio daemon command. Shows results as a histogram of channels (0–125) with hit count per channel. The recommended channel is highlighted.

Click Apply next to the recommended channel to update the dongle's rf_channel (refused if a show is loaded or armed).

Daemon settings

• Receiver inactivity timeout — how long without contact = offline (default 30 s, range 60 s – 6 hr). Affects when the dongle marks a receiver offline in its internal state.
• Command response timeout — per-command response window (default 100 ms, range 5–500 ms).
• Clock sync interval — how often the dongle sends CLOCK_SYNC to receivers (default 2000 ms, range 50–30000 ms). Shorter = tighter clock alignment + more RF traffic.

The dongle clamps each value to its supported range; the post-clamp value is reported back as csim and shown next to your input so you can see if your request got bounded.

OTA Flash panel

The OTA flow for receivers. See OTA flashing for the full procedure.

Controls:

• Receiver dropdown (online BKYD_TS_24_1 only).
• File picker for the .bin.
• Rate selector (250 kbps / 1 Mbps / 2 Mbps).
• Start flash / Abort buttons.
• Progress bar with phase, chunk count, throughput.

Dongle firmware update

UI-driven flash of the host's connected dongle, using whatever .bin is staged at devices/os4_dongle/bin/. The full flow lives on Flashing a Dongle → From the UI.

Controls:

• Reads devices/os4_dongle/bin/ and surfaces the highest-version os4_dongle_v<N>.bin as the candidate.
• Update dongle kicks off the flash. The daemon POSTs to the host-side flash server at :9001, the bridge pauses, esptool runs, the bridge resumes.
• Live status badge cycles through queued → connecting → erasing → writing → verifying → rebooting → done.
• Continue button appears if both auto-reset attempts fail and the chip really does need a manual BOOT+RESET — uncommon in practice now that the auto-no_reset retry catches the lolin_s2_mini's typical reset quirks.
• Abort kills the esptool subprocess. Don't abort mid-write.

---

Tab 5 — Show config

Pre-fire safety + show defaults.

Pre-fire safety (protocol config)

For each protocol (currently only BKYD_TS_HYBRID):

• Min battery to fire (%) — the daemon's precheck rejects any cue whose target receiver has battery below this. Default 30%. Bump to 50%+ for important shows.
• Require continuity — when on, every cue's continuity bit must be set or precheck fails. Most operators leave this off and watch the UI's continuity colors instead — false negatives on continuity (e.g. high-resistance bridges in cold weather) shouldn't block a show.

These changes write to protocols.BKYD_TS_HYBRID.config in systemcfg.json and are re-read on every run_precheck.

Default show location

Sets the default lat/lng + zoom that the spatial layout map opens to for new shows. Useful if you always launch from the same site — saves you from panning across the world every time. The value is stored under show.default_location in systemcfg.json.

---

Implementation

src/components/settings/
├── SettingsPanel.jsx              # top-level tabs (dongle, receivers, network, debug, show)
├── BrightnessSlider.jsx
├── DebugModeToggle.jsx
├── TransmitRepetitionCount.jsx
├── TxConfig.jsx
├── ReceiverConfigSettings.jsx     # broadcast fire_duration_ms
├── AccessPointSettings.jsx        # WiFi AP form (Network tab)
├── UpdateSettings.jsx             # UI-driven system update (Network tab)
├── DaemonSettings.jsx             # the three daemon timeouts
├── RFScanPanel.jsx
├── OtaFlashPanel.jsx              # receiver OTA flash
├── DongleFlashPanel.jsx           # dongle firmware flash (host-side)
├── ProtocolConfig.jsx             # min battery, require continuity
└── DefaultLocationSettings.jsx