---
title: "Room speaker controls"
description: "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."
type: "living"
source: "docs/contracts/satellite-controls.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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`.

