Daemon Command Reference

Daemon command reference

The daemon receives commands by polling /tmp/d_cmd/*.json at 2 Hz. Each file is one command — a single JSON object. The web app's /api/system/cmd_daemon route is the standard way to drop these.

echo '{"type":"reload_receivers"}' > /tmp/d_cmd/$(date +%s%N).json

(works fine from inside the container if you want to test directly).

The daemon reads, deletes the file, dispatches by type, and runs the matching handler. Unknown types are logged and ignored. All values not marked optional are required.

Show lifecycle

load_show

Load a show from SQLite onto the receivers.

{ "type": "load_show", "id": 42 }

Field	Type	Notes
id	int	The Show.id.

Side effects: starts BYHProtocolHandler.load_show(id). Sets LOAD_STATE to LOADING, then LOADED once all async receivers report loadComplete.

unload_show

Clear the loaded show from receivers and local state.

{ "type": "unload_show" }

start_show

Begin running the loaded schedule. Subject to delegate-to-client (DSTC) gating.

{ "type": "start_show" }

If delegate_start_to_client is on (default) and not currently waiting for client start: enters DELEGATE_WAIT. If already waiting: actually begins run_show via start_schedule(from_delegate=True).

stop_show

Stop the running schedule. Sends stop to all receivers.

{ "type": "stop_show" }

pause_show

Pause the running schedule. In delegate mode also sets waiting_for_client_start.

{ "type": "pause_show" }

manual_fire

Fire one cue immediately (with arm + start + manual fire interlocks).

{ "type": "manual_fire", "data": { "zone": "RX146", "target": 1 } }

Field	Type	Notes
data.zone	string	Receiver ident.
data.target	int	1-based cue number.

delegate_launch

Toggle the delegate-to-client flag.

{ "type": "delegate_launch", "do_it": true }

When do_it = false, clicking Launch in the UI starts the show immediately without waiting for hardware confirmation.

schedule

Override the current schedule (debug; rare).

{ "type": "schedule", "schedule": [ ... ] }

stop_schedule

Same as stop_show.

{ "type": "stop_schedule" }

Receivers

reload_receivers

Re-read the Receivers table; reconcile the dongle's poll list (forget removed; sync new).

{ "type": "reload_receivers" }

Refused while a show is loaded (silently — the UI gates this with the unlock button).

retry_receiver

Re-send sync to one receiver.

{ "type": "retry_receiver", "ident": "RX146" }

fetch_receiver_config

Request a RECEIVER_CONFIG_RESPONSE for one receiver, or broadcast to all.

{ "type": "fetch_receiver_config", "ident": "RX146", "fire_duration_ms": 250 }

Field	Type	Notes
ident	string|null	If null/missing, broadcasts to all connected BKYD_TS_24_1 receivers.
fire_duration_ms	int (50–5000), optional	If present, the receiver writes this to NVS before responding.

Refused for BILUSOCN_433_TX_ONLY (no uplink) or offline receivers.

OTA

ota_flash_start

Begin OTA flash for one receiver.

{
  "type": "ota_flash_start",
  "ident": "RX146",
  "image_path": "/tmp/ota_staging/os4_receiver_v23.bin",
  "rate": 2
}

Field	Type	Notes
ident	string	Target receiver.
image_path	string	Path to the .bin file inside the container. The Next.js handler stages this.
rate	int (0–2)	0 = 250 kbps, 1 = 1 Mbps, 2 = 2 Mbps.

Refused if a show is loaded, the system is armed, the receiver is offline, the receiver is BILUSOCN_433_TX_ONLY, or the image file is unreadable.

ota_flash_abort

Abort an in-flight OTA flash.

{ "type": "ota_flash_abort" }

RF

set_rf_channel

Hot-swap the dongle's RF channel.

{ "type": "set_rf_channel", "channel": 76 }

Field	Type	Notes
channel	int (0–125)	The new channel.

Refused if a show is loaded or the system is armed (mid-show channel changes would deafen all receivers — they don't auto-rediscover the channel).

scan_radio

Trigger an RF spectrum scan.

{ "type": "scan_radio", "passes": 10, "ch_start": 0, "ch_end": 125 }

Field	Type	Default	Notes
passes	int	10	Capped at 50 by the dongle.
ch_start	int	0
ch_end	int	125

Refused if a show is loaded or armed (the scan blocks RF for ~250 ms – 1 s).

Settings

set_brightness

Set the dongle's LED brightness.

{ "type": "set_brightness", "brightness": 50 }

Field	Type	Notes
brightness	int (1–100)	0 is silently bumped to 1.

set_receiver_timeout

Set the dongle's "no contact = offline" threshold.

{ "type": "set_receiver_timeout", "timeout_ms": 30000 }

Field	Type	Notes
timeout_ms	int (60000–21600000)	Default 30000. Clamped by the dongle.

set_command_response_timeout

Set the per-command response window on the dongle.

{ "type": "set_command_response_timeout", "timeout_ms": 100 }

Field	Type	Notes
timeout_ms	int (5–500)	Default 100.

set_clock_sync_interval

Set the dongle's clock-sync poll cadence.

{ "type": "set_clock_sync_interval", "interval_ms": 2000 }

Field	Type	Notes
interval_ms	int (50–30000)	Default 2000.

set_debug_mode

Toggle debug verbosity on both daemon and dongle.

{ "type": "set_debug_mode", "debug_mode": 1 }

Field	Type	Notes
debug_mode	int (0 or 1)

set_fire_repeat

Set the per-cue fire-repeat count for 433 MHz cues.

{ "type": "set_fire_repeat", "repeat_ct": 6 }

Field	Type	Notes
repeat_ct	int	0 is silently set to 6 (the default).

select_serial

Reconfigure the serial bridge to use a different port.

{ "type": "select_serial", "device": "/dev/tty.usbmodem01", "baud": 115200 }

Field	Type	Notes
device	string	New port path.
baud	int	Always 115200.

Debug / raw

serial

Send a raw serial line to the dongle. Mostly for low-level debugging.

{ "type": "serial", "data": "scan 10 0 125" }

db_query

Run a raw SQL query against the SQLite database. Mostly for low-level debugging.

{ "type": "db_query", "query": "SELECT id, name FROM Show LIMIT 5" }

Results are printed to the daemon's stdout, not returned anywhere.

State the daemon publishes (not commands)

Independent of the command interface, the daemon publishes a JSON state snapshot to /data/state (and to the WS server via /tmp/byh_state.sock). The full schema is documented in Subsystem: PC daemon → State publishing.

Top-level keys consumed by the UI:

Key	Meaning
device_running	Has the daemon seen serial traffic in the last 10 s?
show_loaded, loaded_show_id, loaded_show_name	Show load state.
show_running	Are any timer threads alive?
device_is_armed, manual_fire_active, start_sw_active	Switch states.
fire_check_failures	List of pre-fire check error strings.
proto_handler_status	Protocol handler's Status enum name.
dstc, waiting_for_client_start	Delegate-to-client state.
sst	Show start time (epoch ms).
receivers	Per-receiver dict (label, type, cues, status).
ota	OTA flash state snapshot.
settings	LED brightness, timeouts, RF info, last scan summary.