Discovering and Adopting Devices

Devices appear on their own, but a discovered device fires no triggers and refuses every command until you adopt it. Open pairing, put the device in pairing mode, adopt it and give it a name and a room.

Adoption decides what is part of your system

A coordinator hears every device in radio range that has ever been paired to its network, including the ones somebody paired to test and forgot. A second-hand Z-Wave stick inherits whatever the previous owner left in its NVM. Without an explicit adopt, "when any sensor activates" means "when anything within thirty metres twitches".

The gate is enforced in the trigger dispatcher and the command path rather than in each block, so a new trigger block cannot forget it. The one exception is device discovered, which fires for unadopted devices because noticing them is its purpose.

The onboarding loop

1. Open the radio for joining

   The pairing open block, or POST /_system/homeassist/pair. The duration you ask for is clamped to the node's pairing_window, so a request for an hour becomes two minutes rather than being refused. Pass 0 to close pairing immediately.

2. Put the device into pairing mode

   Usually a long press, sometimes a specific number of taps. Check the vendor's instructions.

3. It appears as discovered

   The device discovered trigger fires, once, the first time that device is ever seen.

4. Adopt it, with a name and a room

   From that moment its triggers fire and blocks can command it.

The last step can be automated: wire device discovered into device adopt, which takes optional name and room pins. See Example Flows. For a bench mesh, auto_adopt = true in the config skips the gate entirely; keep it off anywhere real.

Adopting by hand

List what is waiting, then take it into service:

# Everything the radio has heard that you have not taken into service.
curl -s 'https://<node>/_system/homeassist/devices?unadopted=1' \
  -H 'Authorization: Bearer <token>'

# Adopt it, naming it and placing it in one call.
curl -X POST 'https://<node>/_system/homeassist/devices/zigbee:0x00158d0007e1a2b3/adopt' \
  -H 'Authorization: Bearer <token>' \
  -d '{"name":"Hallway motion","room":"Hallway"}'

• The default list returns adopted devices only; unadopted=1 asks for the rest.
• Adoption is idempotent. Adopting an already-adopted device succeeds and reports newly = false, so a flow can call it without checking first.

Pairing means something different on every radio

The pairing open block takes an adapter name and a duration.

Every device has two identifiers, a name and a room

Any block that addresses a device accepts the platform id, the native id or the exact name, case-insensitively. A name must match exactly: a prefix match would make renaming one device silently re-point another's flows.

• Your name and room are yours. Once set, a re-announce from the radio never overwrites them, even though a Zigbee re-pair resets the vendor's friendly name to the model number. Everything else merges: newly reported capabilities are added, a blank manufacturer or model is filled in.
• Renaming in RUAL does not rename at the radio. The Zigbee2MQTT friendly name and the Hue bridge name are unchanged, so those apps keep showing the old name.

Rooms are free text

There is no room registry. A room exists because at least one device is assigned to it, and get rooms returns the distinct non-empty room names across all adopted devices, sorted. Room filters compare case-insensitively, so "Hallway" and "hallway" are the same room, but "Hall" is a different one.

A trigger with an empty device pin and room = Hallway is "any matching device in the hallway": one block instead of one flow per sensor.

Device knowledge comes off the wire

Zigbee2MQTT publishes its full device definition, the exposes tree covering every attribute a device reports with its type, unit and range, on zigbee2mqtt/bridge/devices, refreshed whenever the mesh changes. It covers roughly 4,000 devices and arrives already matched to the device on your mesh. Z-Wave JS does the same through its own config index.

A small profile table sits on top for devices whose exposes tree is correct but produces a bad default. Aqara sensors are the clearest case, reporting battery, voltage, link quality and device temperature alongside the one attribute anybody automates on. A profile:

• guarantees the useful capabilities are present before the first report of that kind arrives;
• normalises the vendor string ("LUMI" becomes "Aqara");
• overrides the derived type where derivation is wrong, such as a button that would otherwise classify as a sensor.

A device with no profile gets exactly what its exposes tree said, which is almost always right. Profiles are applied on discovery and on adopt, so a device paired before its profile existed picks it up the next time somebody adopts it.

Forget is not unpair

device forget, and DELETE /_system/homeassist/devices/<id>, drop the device from RUAL: its name, room and adoption are discarded. It does not unpair the device from the Zigbee, Z-Wave or Matter network. The device stays on the mesh and reappears, unadopted, on its next report.

• Unpairing is done in Zigbee2MQTT or Z-Wave JS UI, and is not exposed as a block.
• A device that leaves the mesh on its own is marked unavailable and kept registered, so a dead battery does not discard its name, room and adoption.

Identity and state both survive a restart

They live in two different places, for two different reasons.

Keeping state out of the document store stops a motion sensor in a busy hallway from becoming the node's dominant write load. One Zigbee message routinely carries occupancy, illuminance, battery and link quality: four changed capabilities and one write.

A restored value is a belief, not an observation

• Restoring state does not set available or touch last_seen. available stays false until the device actually reports.
• Momentary capabilities are excluded from the restored map: replaying the last button press as current state would make it look freshly pressed.
• Forgetting a device deletes its stored state too, so re-adopting one later does not restore a belief from before it was removed.

Why a restart does not fire every sensor

State is restored before the adapters connect, so the first real report has something to compare against and an unchanged re-announce stays unchanged. Independently of that, an unknown previous value seeds silently rather than firing, except for smoke, gas and water_leak, where a missed event is worse than a repeated one. The full rule is on the trigger reference.

In RUAL Studio

The device list, the per-device state and the history charts live under Devices, then Home Automation. That screen covers the onboarding view (which uses the unadopted query), adopt, rename, forget, and a one-capability command, so that having adopted a bulb you can check it responds without building a blueprint.

Every trigger and action block that addresses a single device carries the metadata for an in-editor device picker: which device type to offer, so light on offers lights and not thermostats.

The screen does not poll. Device events are pushed onto the WebSocket bus as they arrive, on the homeassistdevices:updates:<device id> channel for one device and homeassistdevices:updates:all for the fleet. Unlike the trigger dispatcher, the broadcast does not filter on adoption, because the onboarding screen has to show devices that are not adopted yet.

The device API

All of it is under /_system/homeassist and all of it requires the blueprints / simulating scope.

GET /capabilities needs no running service and therefore no node with a radio, because the studio has to populate capability dropdowns while editing a blueprint that will run somewhere else. Units, decimals and chart types come from here too.

Next steps