Room — room

Not a device — the unit of user intent, and the primary handle for both keypads and the AI.

A room owns its bindings, its sinks (which consumer connection is the display, which is the audio endpoint), and its authored context. Room commands resolve through the pathfinder into device commands; nobody programs a button sequence by hand.

Rooms are created by the project, not by a driver. This proxy exists so that rooms are addressable through exactly the same contract as everything else.

Capabilities

Declared in the driver manifest under [[proxy]] capabilities. Anything not declared takes the default below.

Capability	Type	Default	Meaning
has_audio	bool	false	An audio sink is bound
has_climate	bool	false
has_lighting	bool	false
has_shades	bool	false
has_video	bool	false	A display sink is bound
volume_owner	u32	0	Binding whose volume is the room's volume. Resolved by the pathfinder.

Commands

activate_scene

Put the room into a state somebody named — "Relax", "Reading". A scene is a set of levels and colors, one per light, kept by the project and applied together.

This was declared here once before with nothing behind it, and core answered it with an error. It is back because the thing it needed now exists: somewhere to keep "these five lights, each at its own level", which is what a scene is and what no amount of all_lights_on could express.

Not gated on has_lighting. A scene is a set of device states and there is nothing about it that has to be a light, even though every one anybody writes will be.

Parameter	Type	Notes
name	string

all_lights_off

Only present when has_lighting is declared true.

No parameters.

all_lights_on

Only present when has_lighting is declared true.

Every light in the room to one level, or to full when none is given. A switch, having no level of its own, simply comes on.

Implemented all along and never declared — the same drift as activate_scene, in the opposite direction. Between them the editor offered the room command that fails and hid the one that works.

Parameter	Type	Notes
level	u8 0–100 (optional)

dim_down

Only present when has_lighting is declared true.

Every light in the room a step dimmer. The same as dim_up, downward.

Parameter	Type	Notes
step	u8 1–100 (optional)

dim_up

Only present when has_lighting is declared true.

Every light in the room a step brighter, relative to wherever each already is.

Relative, and that is the whole point of it. A keypad's brighter button does not mean "go to 70%", it means "more than now" — and "now" differs per light and changes every time somebody touches one. Absolute levels cannot say that, which is why a four-button dimmer had nothing to map its middle two buttons onto.

Holding comes free. A remote that repeats while it is held down triggers this again on every repeat, so a single rule gives a step per click and a ramp per hold.

Parameter	Type	Notes
step	u8 1–100 (optional)

listen

Only present when has_audio is declared true.

Select an audio source and solve the path to this room's audio endpoint

Parameter	Type	Notes
source	u32

off

Tear the room down: release its path and power off devices no other room is using

No parameters.

set_mute

Parameter	Type	Notes
mute	bool

set_volume

Parameter	Type	Notes
level	u8 0–100

volume_down

No parameters.

volume_up

No parameters.

watch

Only present when has_video is declared true.

Select a video source and solve the path to this room's display

Parameter	Type	Notes
source	u32	Binding id of a media_player or other video source

Notifications

button_action

A keypad or remote press arriving at the room level, before it is routed to a device

Parameter	Type	Notes
action	one of press · release · click · double · hold
button	string

mute_changed

Parameter	Type	Notes
mute	bool

power_changed

Parameter	Type	Notes
on	bool

source_changed

Parameter	Type	Notes
kind	one of video · audio
source	u32

volume_changed

Parameter	Type	Notes
level	u8

State

Last-known values core keeps for a binding of this proxy.

Key	Type	Meaning
audio_source	u32
mute	bool
on	bool
video_source	u32
volume	u8