Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Room speaker controls

A satellite's physical controls on the wire: the satellite_control frame (button_press single/double/long, dial delta/value, mute on), what the gateway maps each to by the turn machine's state (over, cancel, start_over, mute_toggle, mute_set, room_volume), the dial's clamp, rate limit and settle, and the satellite_control / satellite_over / room_volume_set rows. Back to the satellite: the satellite_state {volume?, muted?} event (on bind, when a dial settles, when the mute changes), its fan-out to every satellite in the same room (room_peer), the mute and last state carried across an over-and-out rotation, and the Sonos clip taking the gateway's room volume below 5.

Living doc, checked against the code 2026-11-14

satellite-controls.v1 — a satellite’s button, dial and mute switch on the wire

  • Status: live on protocol 5, additive. A gateway without the control refuses the frame as invalid_json. The bridge sends it only with --controls gateway (env VULPINE_SATELLITE_CONTROLS). The default, local, keeps the bridge’s own mapping.
  • Scope: what a satellite sends when its physical controls are touched, what the gateway maps each control to, and the trace rows. The puck’s firmware and ESPHome entities are out of scope.

Client → gateway

One frame, satellite_control, whose control is tagged by kind (ClientControl::SatelliteControl, SatelliteInput, SatellitePress in crates/protocol/src/lib.rs):

control fields from the puck
{"kind": "button_press", "press": "single"} press: single, double or long single_press, double_press, long_press event telemetry
{"kind": "dial", "delta": 1} delta (clicks, clockwise positive) or value (0-100), both optional dial_clockwise / dial_anticlockwise: one click each
{"kind": "mute", "on": true} on: the switch’s new position the Mute switch entity

The frame says what was touched, never what it means. A dial with neither field is traced and ignored. The puck’s on-device “Stop” word is not a satellite control. The bridge keeps it as its own cancel.

What the gateway does

map_press (crates/voice_gateway/src/satellite_controls.rs) reads the session’s state when the frame arrives:

control state mapped_to effect
single press a reply sounds (its TTS is unfinished, a client reports it playing, or its shipped audio has not yet played out) cancel Interrupted {UserCancel}: the TTS stops, audio_reset follows, the turn stays closed as spoken
single press the request ear is armed over the live hold releases now, or the recognizer flushes what is open; the final commits (satellite_over {path})
single press the operator’s committed request is with the brain (not a warmup, not a speculative generation) cancel as above: the pending reply is canceled before it speaks
single press at rest none nothing; the row shows the press arrived
double press any start_over the spoken “start over” verb’s own path (GatewayReport::StartOver, request_restart)
long press any mute_toggle the session’s muted state flips; presence mic_muted / mic_unmuted
mute {on} any mute_set the muted state is set to on; presence as above
dial the session has a room and the room speakers store room_volume the room’s pending volume moves (below)
dial no room, or no room speakers none nothing (reason: no_room / room_speakers_off)

The rows are read in order. A sounding reply wins over an armed ear, and an armed ear wins over a request still with the brain. Muted, a bound session’s presence rests in idle instead of listening. A turn in flight keeps its phase and rests muted when it ends.

The dial:

  • Each click moves the room’s volume by 3 points. At most 5 clicks count from one frame.
  • A frame within 40 ms of the last accepted one is dropped.
  • The volume is clamped to 0-60. A room never set starts at 25 (roomctl’s default).
  • After the dial rests 700 ms, the volume goes to the gateway-wide room store and is traced once.

Every roomctl speak to that room then carries it as --volume: a direct speak {room} and a reply routed to the room. The puck’s own replies sound through the bridge’s output, which follows the room volume through satellite_state. There is one volume, not two.

Gateway → satellite

One event, satellite_state (ServerEvent::SatelliteState, additive on protocol 5), sent only to a frontend whose hello said kind: satellite:

field meaning
volume the satellite room’s volume, 0-60 (roomctl’s scale); absent when the session has no room or no room speakers
muted the session’s mic mute; absent until a mute {on} or a long press has set it in this session

It is queued on bind (after session_started), when a dial turn settles and when the mute changes, and only when the pair differs from the last one sent. When the device reports back the switch position the gateway asked for, nothing is sent again. This is the gateway half of the loop guard.

The volume belongs to the room, not the session. When a dial settles on any session, the gateway-wide RoomSpeakerStore wakes every satellite bound to that room and sends it the new volume. The session whose dial moved traces reason: room_volume. Each other satellite in the room traces reason: room_peer on its own trace. A satellite in another room gets nothing. A radio rotation (over and out) keeps the satellite’s mute, the last pair sent and the watch. While the switch is on, presence rests in idle on the successor, and the device is not re-told what it already has.

The bridge applies the event with SatelliteStateMirror (apps/satellite-esphome/src/gateway-link.ts) under --controls gateway only. local ignores it.

  • The reply output’s volume follows volume. This is the Sonos clip volume, clamped 0-80 by the clip. Once the gateway has sent a volume, a dial click goes to the gateway only and does not move the clip locally. The bridge adds no floor under the gateway’s volume: Sonos’s loadAudioClip takes 0-100 and applies the device’s own limits, so a room volume under 5 passes through as roomctl’s --volume does. The local dial (--controls local) moves the clip within 5-80.
  • The puck’s own Mute switch entity is set to muted when it differs from the switch’s last position.
  • The switch then reports the position it was set to. The bridge swallows that one report (satellite_mute_echo_suppressed) instead of sending a mute {on} control. This is the bridge half of the loop guard. A later hand flip is sent.

The Admin’s Mute and Off

Each satellite has two switches in the Gateway window (Vulpine Gateway.app). The Controls page’s Satellites card asks for confirmation at each press, like every gateway op. The menu-bar items Puck: Mute mic / Puck: Turn off show a check while on, and a pick acts at once. The op is AdminRequest::SatelliteOp {satellite, op: mute | unmute | off | on, stage}: additive on the Admin protocol, plan then apply, admin_core command admin_satellite_op. A satellite is named by the room it declared at hello (living-room). Two satellites in one room share their switches.

switch what the gateway does risk
Mute drops the satellite’s audio at admission (one atomic load per binary frame; the first dropped frame is a satellite_audio_dropped row), publishes mic_muted, and sends satellite_state {muted: true}; replies and notices still play on it R0
Off refuses its hello with satellite_off before owner admission; a bound session is sent error {code: satellite_off} and closed, so no wake, listening, turn, reply or notice reaches it until On R1 (the one device named; not behind [admin] controls = "all")

Both switches are kept in <state>/satellite-switches.json (crate::satellite_switches). They survive a gateway restart, and a session keeps them across rebuilds and the radio rotation. The file is 0600 in a 0700 folder, written as a temp file and a rename. An absent file means every satellite is on and unmuted, so deleting it is the rollback. An unreadable file is never overwritten and refuses a switch.

A press bumps a watch that every bound satellite session waits on, so the change reaches it at once. The admission gate (SatelliteSwitches::gate) is set in the same lock as the switch, so a frame that arrives first is already dropped. The device’s own switch (a hand flip or a long press, mute {on}) is the satellite’s mute too. The store keeps it, so the Admin row and a restart agree with the device. Every apply, refusals included, is an admin_write row on the Controls page’s Receipts card.

  • Bridge --controls gateway: the puck’s Mute switch follows the gateway’s mute both ways through the mirror, so a muted puck does not wake. --controls local: the bridge ignores satellite_state and the gateway cannot flip the switch. Mute holds at the gateway (no audio reaches the recognizer), but the puck lights on its wake word and listens until its own cap.
  • Off at the bridge (apps/satellite-esphome/src/off-park.ts): a satellite_off refusal parks the bridge before it connects the device. It writes one satellite_off_parked row, sends a quiet hello every 30 s, and writes one satellite_off_cleared row when the Admin turns it on. A bound bridge closed with satellite_off exits for launchd, as on any lost link, and parks at its next start.

Trace rows

row fields
satellite_control kind, mapped_to; a press adds press, playback, thinking, armed; a mute on; a dial delta, value, room, pending_volume, outcome (moved, rate_limited, empty)
satellite_over path: hold_released, flushed, flush_failed or no_recognizer
room_volume_set room, from, volume, clicks, dropped, source: satellite_dial; one per settle
presence_transition event: mic_muted / mic_unmuted
satellite_state_sent volume, muted, reason (bind, mute, room_volume, room_peer); one per satellite_state queued
satellite_switch muted, off, source (bind: a kept mute applied; store: an Admin press or another session)
satellite_audio_dropped bytes, switch (muted, off); the first frame dropped since the gate closed
satellite_off_refused satellite; a hello refused satellite_off
satellite_switch_unwritten muted, reason; the device’s mute could not be kept (the session’s mute stands)

A frame before start_session is refused session_required and traced with mapped_to: none.

Was this page helpful?