Sensor — sensor v1

A measurement or detection. One binding per measured quantity — a multi-sensor declares several bindings of this proxy rather than one binding with several values, so an automation can trigger on exactly one thing.

Read-only for almost every device, and the commands below exist because presence sensors are the exception. An mmWave sensor decides for itself how long to keep saying somebody is there after it stops seeing them, and that hold is the difference between a lighting rule that works and one that switches off on a person sitting still — so it has to be reachable. It is gated, like everything else here: a temperature probe resolves to no commands at all and stays exactly as read-only as it was.

The line these commands sit on is worth stating, because it is the same line requires draws everywhere. A hold is a property of presence sensing, which every vendor's presence sensor has, so it belongs in this contract. Opening a Zigbee mesh for joining is a property of one particular bridge, so it is an action and not in any contract.

Capabilities

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

Capability	Type	Default	Meaning
auto_clear_seconds	u32	0	Boolean sensors: how long until it self-clears. 0 = it reports its own clear.
has_adjustable_hold	bool	false	Its hold can be set — see set_hold_seconds
has_adjustable_sensitivity	bool	false
has_battery	bool	false
hold_max	u32	0	Longest hold this device accepts
hold_min	u32	0	Shortest hold this device accepts
is_boolean	bool	false	Reports detected/clear rather than a number
kind	string	"generic"	temperature
unit	string	""	Display unit; empty for boolean sensors
value_max	f32	0.0
value_min	f32	0.0

Commands

set_hold_seconds

Only present when has_adjustable_hold is declared true.

How long the device keeps reporting a detection after it stops seeing anything.

The setting that decides whether a presence sensor is useful. Factory defaults are short — fifteen seconds is common — because a short hold demonstrates well on a shelf, and it is far too short for anything that switches a light: the room reads as empty while somebody is still sitting in it.

Bounded per device by hold_min/hold_max, because the accepted range is a property of the hardware and a value outside it is silently clamped rather than refused.

Parameter	Type	Notes
seconds	u32

set_sensitivity

Only present when has_adjustable_sensitivity is declared true.

How readily the device decides something is there. Turned down where it sees through a wall or picks up a curtain, and up where somebody sitting still stops registering.

Three steps rather than a number, because the underlying scale is arbitrary, vendor-specific and not comparable between devices — offering "47" would imply a precision that does not exist.

Parameter	Type	Notes
level	one of low · medium · high

Notifications

battery_changed

Only present when has_battery is declared true.

Parameter	Type	Notes
percent	u8 0–100

detected_changed

Only present when is_boolean is declared true.

Parameter	Type	Notes
detected	bool

hold_changed

Only present when has_adjustable_hold is declared true.

What the device's hold is now. Sent after a set, and when it is first read.

Parameter	Type	Notes
seconds	u32

online_changed

Parameter	Type	Notes
online	bool

value_changed

Parameter	Type	Notes
value	f32

State

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

Key	Type	Meaning
battery	u8
detected	bool
hold_seconds	u32
online	bool
value	f32