Local Home Automation

A RUAL node is the gateway itself, not a client of somebody else's cloud. Zigbee, Thread/Matter, Z-Wave, Philips Hue, Daikin and UniFi devices become one vocabulary that blueprints automate, and it keeps working when the internet does not.

This section is the working reference. New here? Start at Setting Up a RUAL Nano, or read the shorter Local Home Automation tutorial first.

The node is the gateway

The ordinary way to reach a smart device from software is the vendor's cloud API: your flow talks to a server in another country, that server talks to a bridge in your hallway, and the bridge talks to a lamp two metres away. That costs hundreds of milliseconds, an account and a rate limit, and it fails whenever any hop does.

Here the devices talk to the node. Radios are attached to the machine, the protocol daemons run beside the node, and a motion event reaches your flow over a loopback socket.

Aqara is the clearest case. Aqara devices are Zigbee devices. Reached through Aqara's cloud API, turning on a lamp is a request to Germany and back; paired to a coordinator on your own machine, they are just devices on your mesh. That is why the older aqaraconnection_* blocks are deprecated in favour of these.

The node does not drive the radios itself

A native Zigbee stack means owning EZSP and Z-Stack framing, the ZCL cluster library, mesh routing, OTA updates and a device quirks database. So the node sits behind the reference daemon for each protocol and translates.

There is no device list inside RUAL to update. Zigbee2MQTT publishes a complete machine-readable description of every device on your mesh: every attribute it reports, with type, unit and range, for roughly 4,000 devices. The node reads that directly, so pairing a sensor released after your RUAL version still gives you a fully described device.

Hue is a separate adapter from Zigbee, even though a Hue bridge is a Zigbee coordinator. Re-pairing bulbs to your own stick breaks the Hue app, the dimmer switches and the scenes the household already uses; talking to the bridge leaves all of that working. A bulb paired directly to your own coordinator arrives through the Zigbee adapter instead, and neither path knows about the other.

One vocabulary, whatever the radio

Four vendors describe the same physical event four different ways. A motion sensor is occupancy: true on Zigbee2MQTT, a Notification command class carrying "Home Security, Motion sensor status" on Z-Wave JS, motion.motion: true on a Hue bridge, and bit 0 of an OccupancySensing bitmap on Matter.

So every adapter funnels into one closed set of capabilities, and a flow is written against those. A sensor activated trigger behaves identically whether the sensor is an Aqara on Zigbee, a Fibaro on Z-Wave or an Eve on Thread, because by the time the trigger sees it, all of them are occupancy = true.

A capability earns its place by being something an automation would branch on. Anything not listed here still survives on the device's raw map, so it is readable without being promoted into the vocabulary.

Binary capabilities: true is always the active state

A blueprint never has to ask whether true means open or closed.

The "counts as a sensor" column is what sensor activated and get active sensors mean by a sensor: the binary capabilities that describe the world, minus the ones that describe the device.

• power is excluded because a bulb turning on is not a sensor activating. Folding it in would make every whole-house sensor flow fire on its own lighting changes and livelock.
• tamper and battery_low are excluded because an author asking about presence does not want a flat battery in the same stream.

Numeric capabilities

Text and enum capabilities

Access control and cameras

These come with the UniFi adapter. A door controller is a lock, a position sensor, a card reader and a doorbell at once, and "the front door" is one thing people automate rather than four.

• nfc is separate from access_entry because "a card was swiped" and "entry was granted" are different automations: a swipe may be refused.
• motion_event is separate from occupancy because a camera reports motion as discrete detections, while a PIR or radar sensor reports a state that stays true while somebody is there. Use camera motion detected for the first and presence detected for the second.

Two vendor quirks are corrected for you

Device types are derived from capabilities

Every device is classified into one of ten types from the capabilities it exposes, not from what the vendor calls it. Vendor device classes are frequently wrong: Zigbee plugs that meter power routinely announce themselves as lights.

The order in that table is the order the checks run, because capabilities overlap:

• A Hue bulb has power and brightness, a metering plug has power and power_watts. Testing brightness before plain power keeps the plug out of the lights list.
• Testing climate first keeps a thermostat with a display backlight from being classified as a lamp.
• A UniFi door has a lock state, a door-position sensor and usually a reader and a bell, so any access-control capability wins and the whole thing classifies as one door.

Type decides what fires: light turned on fires only for devices classified as lights, switch turned on only for switches, and the studio's device picker offers only the right type per block.

Nothing is in service until you adopt it

Devices appear on their own: a coordinator hears everything ever paired to its network, and the node records each one as it reports. But a discovered device fires no triggers and refuses every command until you adopt it.

Without that gate, "when any sensor activates" means "when anything within thirty metres twitches", including the sensor somebody paired to test three years ago and whatever a second-hand Z-Wave stick inherited from its previous owner. The full onboarding loop is on Discovering and Adopting Devices.

What you need to own

• A machine. A RUAL Core Nano: one box in the building, wired, on an SSD. 16 GB of RAM is the comfortable number once the radio daemons are running beside the node. See RUAL Core Nano for the specifications and the reference builds.
• A radio per protocol. Zigbee, Thread and Z-Wave are three radios on different frequency bands. Nothing bridges them and no single dongle does all three at once. The tutorial covers which to buy.
• The daemons. Redis and an MQTT broker for the node itself, plus Zigbee2MQTT, Z-Wave JS UI or Matter Server depending on what you own. Setting Up a RUAL Nano is the runbook.
• The devices. Hue, Aqara, IKEA, Eve, Fibaro, Aeotec, Shelly Wave, a Daikin air conditioner and a UniFi console running Access or Protect are all covered. Anything Zigbee2MQTT supports works, which is most of what is sold.

The blocks arrive with Core v15.0.0, and the feature is opt-in.

What to know before you commit

• Restored state is a belief, not an observation. Last-known device state survives a restart, but available stays false and last_seen is untouched until the device actually reports.
• Triggers are not durable. Device triggers dispatch in process rather than through the queue, which is what makes a light come on before you have finished walking through the door. A restart drops anything in flight.
• Smoke, gas and leak triggers are a supplement, not a certified alarm. They depend on a mesh, a broker and a node all being up.
• Daikin is polled. Its local API has no event channel, so poll_interval (30s by default) is the resolution of every climate trigger.
• Matter endpoints collapse. A Matter device with two endpoints, such as a two-gang switch, currently appears as one device whose power state is whichever endpoint reported last.
• UniFi emergency controls are not exposed. Siren, lockdown and evacuation have no capability and no command. A flow can react to the console's alarm state; it cannot raise one.
• Daikin Onecta temperatures are best-effort. Power on and off is reliable; the temperature and mode decoding follows community reverse engineering, the hex encoding varies by model, and it is unverified against a live unit. The full raw /dsiot tree is on the device's raw map.
• The Daikin Onecta cloud allows 200 requests a day, writes included. One poll covers every unit, and the 15 minute default spends 96.
• History is sampled by design. It answers trends and totals well and forensic questions poorly. See Device History and Energy.

A restart does not re-fire everything

Without care, a window that was open all night would announce itself as "just opened" at 03:00, run the alarm flow and switch the lights on. Two mechanisms prevent that.

An unknown previous value seeds silently rather than firing. When the node has never seen a capability before, an incoming reading is recorded without counting as a transition. The exceptions are:

• smoke, gas and water_leak, where a missed event is worse than a repeated one. A node that comes back up to an alarm already sounding says so.
• Buttons, because a press is an event with no persistent state to seed.

Last-known state is persisted and restored before the adapters connect, so the first real report has something to compare against and an unchanged re-announce stays unchanged.

• It lives in Redis, because it is hot, small, rewritten constantly and worthless once stale.
• Writes coalesce per device on a two-second flush (one Zigbee message carrying four capabilities is one write), and a clean shutdown flushes.
• Entries expire after 30 days, so a node restored from a backup does not seed year-old beliefs.
• Momentary capabilities are excluded: replaying the last button press as current state would make it look freshly pressed.

Next steps