Troubleshooting Home Automation

Symptom first: no devices, a trigger that will not fire, a door sensor that reads backwards, an empty chart. Most of these look identical from the outside, so each entry starts with the check that tells them apart.

A home-automation stack is four processes, and three of them are not RUAL. That is why the first move is almost always to find out which layer is quiet, rather than to change a setting and see.

The Three Checks That Localise Almost Everything

Run these in order. Each one clears a layer.

mosquitto_sub -h 127.0.0.1 -t '#' -v

# Expect zigbee2mqtt/bridge/state -> online
# and zigbee2mqtt/bridge/devices -> a JSON array

curl -s https://<node>/_system/homeassist/status \
  -H 'Authorization: Bearer <token>'

curl -s 'https://<node>/_system/homeassist/devices?include_unadopted=1' \
  -H 'Authorization: Bearer <token>'

No Devices Appear

In order of how often it is each one:

1. base_topic does not match. The node subscribes under the base topic in [homeassist.zigbee]; Zigbee2MQTT publishes under mqtt.base_topic in its own configuration. Both default to zigbee2mqtt, so a mismatch only happens when somebody changed one. The failure is silent and total: the node connects to the broker happily and sees nothing. Compare the two files; do not trust memory.
2. The adapter was never constructed. An adapter with no configuration section, or with an empty broker, is not created at all. Check the boot line: HomeAssist: enabled for entity 1, adapters: [zigbee] lists exactly what exists. If it says adapters: [], you also had the warning [homeassist] enabled but no adapter is configured.
3. Home automation is off. Blocks report HOMEASSIST_NOT_AVAILABLE and the API answers 503 with a hint. Set [homeassist] enabled = true.
4. The coordinator has no devices. A fresh stick genuinely has an empty mesh, and zigbee2mqtt/bridge/devices is an empty array. Pair something.
5. Broker credentials. If the broker requires a username and password, both the node and each daemon need it. One side unconfigured looks exactly like a broken radio.

Note that the Zigbee coordinator itself is deliberately excluded from the device list: it is not something an automation addresses, and letting it through would put a permanently unadoptable "Coordinator" entry at the top of every picker. Z-Wave node 1 is skipped for the same reason, it is the controller stick.

Bridge Offline Is Not the Same as Broker Unreachable

Both present as "no devices", and the fix is completely different, so the node logs them separately.

The adapter status pin tracks the broker connection, not the bridge. get status reporting connected: true means RUAL has an MQTT session, which is a weaker statement than "the radio works". That is why check 1 exists.

Two Nodes, One Broker

If a second RUAL node shares the broker, give each one its own client_id. Two MQTT connections with the same client identifier kick each other off, forever, and the resulting symptom is a device list that appears and disappears every few seconds on both nodes.

A Trigger Does Not Fire

The device is not adopted. That is the answer most of the time. An unadopted device is tracked and visible, its state is followed, and it fires nothing. The gate is enforced centrally, so no trigger is exempt except device discovered.

After that, in order:

1. The blueprint is not saved, or the block is not active. The trigger index only contains active trigger blocks from saved blueprints. It rebuilds on save, so no restart is needed, but an unsaved edit does not exist as far as the dispatcher is concerned.
2. The device pin does not resolve. It accepts the platform id, the native id or the exact name, case-insensitively. A near-miss on the name silently matches nothing. Paste the id from get all devices when in doubt.
3. The room does not match. Room comparison is case-insensitive but not fuzzy: "Hall" and "Hallway" are different rooms, and a device with no room set matches no room filter.
4. The device is the wrong type. light turned on fires only for devices classified as lights and switch turned on only for switches. A metering plug is a switch even if the vendor calls it a light. Check the type field in get device.
5. The value did not change. Transition triggers require a change. If a sensor is already true and re-reports true, nothing fires, by design.
6. The threshold was not crossed. "Above 25" fires when the reading passes 25 from at or below it. If the room has been at 27 all day, it fired once this morning and will not fire again until it drops below 25 and comes back up.
7. The capability is not the one you think. sensor activated with a sensor type set fires only for that capability. Read the device's actual capability list with get device; a sensor that reports occupancy will not fire a trigger narrowed to contact.
8. The concurrency cap. At most 16 device flows run at once, and beyond that events are dropped with a warning naming the trigger type and device. If you see that line, something in your flows is slow: a delay inside a device flow holds a slot for its whole duration.

A quick way to isolate steps 3 to 7: temporarily put a device state changed trigger with no device and no room in front of a debug block. If that fires and your specific trigger does not, the problem is a filter, not the plumbing.

A Contact Sensor Reads Backwards

It should not, and if it does, look at your flow before you look at the sensor.

Zigbee's contact attribute is true when the magnet is present, which is when the door is closed. Matter's BooleanState is the same way round. The platform inverts both at the adapter, so in RUAL contact = true means OPEN, everywhere, on every protocol. This is the single most common source of backwards door automation in every home automation system there is, which is exactly why it is corrected once, at the boundary, rather than left to each flow.

So if a door flow behaves backwards, the usual causes are:

• The flow uses contact closed where it meant contact opened, on the assumption that it had to compensate.
• The flow reads contact through get device state and inverts it by hand, double-correcting.
• The magnet is mounted the wrong way round, or on the frame rather than the door, so the sensor genuinely reports the opposite of what the door is doing. Open the door and watch the value with get device or in Zigbee2MQTT: the sensor is the authority on its own wiring.

Colour temperature has the same shape of correction: RUAL speaks kelvin, the wire speaks mireds. If a lamp goes cold when you asked for warm, check you passed 2700 and not 370.

Z-Wave Devices Never Appear

The gateway type must be "ValueID topics". Z-Wave JS UI can publish under two topic layouts and only one of them is machine-parseable.

"Named topics" interpolates your own location and node names into the path, so zwave/kitchen/ceiling/switch_binary/... cannot be told apart from a node whose name contains a slash. ValueID topics are zwave/<nodeId>/<commandClass>/<endpoint>/<property>, which always parses. The node cannot work with the other layout and does not try.

Set it in Z-Wave JS UI under Settings, Gateway, Gateway type. Then check the topics directly:

mosquitto_sub -h 127.0.0.1 -t 'zwave/#' -v

# Right:  zwave/12/49/0/Air_temperature {"time":...,"value":21.5}
# Wrong:  zwave/kitchen/ceiling/49/0/Air_temperature {...}

Also check gateway_name. It is the ZWAVE_GATEWAY-<name> suffix on the API topics and must match the MQTT name configured in Z-Wave JS UI, default zwave-js-ui. With it wrong, values still arrive and get parsed, but the node inventory request goes nowhere: devices appear with names like "Z-Wave node 12" instead of the names you gave them, and with fewer capabilities than they should have.

A Daikin Unit Reports Nothing, or Reports Odd Temperatures

Both firmware generations are supported and the node picks the dialect itself: the legacy BRP069 and BRP072 units speak a flat k=v API at /aircon/*, and the newer BRP069C4x "Onecta" firmware speaks a nested JSON tree at /dsiot/*. A unit that answers 404 on the legacy endpoint is detected as Onecta on the first poll, and the node remembers which dialect each host speaks.

So a Daikin unit that reports nothing at all is usually a network problem rather than a firmware one: wrong IP, the unit on a different VLAN, or a DHCP lease that moved. Confirm with curl http://<ip>/common/basic_info.

Odd temperatures on an Onecta unit are a known limitation, not a fault. Power on and off is reliable; the temperature and mode decoding follows community reverse engineering, the hex encoding varies by model, and it has not been verified against a live unit. If a reading looks wrong, read the untranslated tree instead: the full /dsiot response is on the device's raw map under dsiot, reachable through get device. A report of which model produced which wrong value is the thing that fixes this properly.

Other Daikin specifics worth knowing:

• It is polled, not pushed. The default 30 second poll_interval is the resolution of every climate trigger on that unit, and the state you read can be up to one interval old.
• Hosts are configured, not discovered. Daikin adapters do not advertise reliably over mDNS. Put the IP in [homeassist.daikin] hosts, and give it a DHCP reservation so it does not move.
• Pairing does not apply. pairing open on the Daikin adapter returns HOMEASSIST_PAIRING_UNSUPPORTED. The unit is on the WiFi or it is not.
• A unit that is off reports mode off, not its last mode. The unit itself remembers "heat" all summer; reporting that verbatim would make hvac_mode == "heat" true for a switched-off air conditioner.

UniFi Connects but Reports Nothing

Almost always the keys. Access and Protect are separate apps on the same console, with separate integration APIs and separate keys. Enabling one does not enable the other, and a key issued by one does not authenticate to the other.

• No doors, NFC or entry events: the Access half. Enable the API in Access, then Security, then Advanced, then API, and put that key in access_key.
• No cameras, doorbells or motion: the Protect half. Enable it in Protect, then Settings, then Control Plane, then Integrations, and put that key in protect_key.
• Neither: check the host. Consoles do not have stable hostnames, so use the IP with a DHCP reservation.

A field decodes to the wrong thing. Possible, and expected to be found this way: the adapter follows Ubiquiti's documented APIs but its field decoding has not been confirmed end to end against a live console. Every payload is also carried untranslated on the device's raw map, so read that through get device and use the raw value while the mapping is corrected. A report naming the console version and the raw payload is what fixes it.

RUAL does not appear inside the UniFi app, and cannot. UniFi has no third-party integrator surface that renders in its own UI. The integration APIs are read and command only, so the node is a client of the console rather than a plugin to it.

An NFC trigger fires once and then stops for the same card. The NFC value is the card token, so presenting the same card twice in a row with nothing in between is not a change and does not re-fire. Use access granted or access denied when you need every attempt, since those carry the full event.

Hue and Matter Specifics

A Command Does Nothing

Do not diagnose by comparing the returned device state. Radio adapters return the pre-command snapshot: the bulb has been told, and its own report arrives a moment later. Only Hue and Daikin confirm synchronously. ok is the pin that answers "did this land".

What a Restart Does and Does Not Restore

Last-known device state is persisted to Redis and restored before the adapters connect, so get lights that are on and get active sensors answer sensibly immediately after a restart rather than returning nothing.

What is not restored is reachability. A restored value is a belief about what the device was doing, not evidence that it is still there, so available stays false and last_seen is untouched until the device actually reports. A device list read immediately after a restart therefore looks like a house of unreachable hardware with plausible values, which is exactly what it is. It fills in as devices report, within a polling interval for mains-powered devices and considerably longer for sleepy battery ones.

A flow that runs at boot and depends on knowing a device is really there should read available rather than inferring it from the presence of a value.

A History Chart Is Empty

Read the recording pin first. It separates two very different situations that look identical:

• recording = false: this node stores no history for that capability. Either [homeassist.analytics] enabled = false, or the capability is one that is not recorded at all (color_hex is the notable one).
• recording = true with no readings: nothing was stored in that window. For an alarm capability that genuinely means the door never moved. For a measurement it can also mean the value never moved beyond its deadband, in which case you should still see heartbeat rows.

Then check the obvious ones: the device was not adopted during that window (unadopted devices record nothing, including retrospectively), the window is longer than the 90 day retention, or the capability name is not the canonical one.

Gaps in a chart are real. Empty buckets are omitted rather than zero-filled, because drawing a missing temperature reading as 0 °C invents a cold snap. A gap means the device did not report.

A single missing bar on an energy chart is usually a meter reset: a device replaced or firmware reflashed makes the counter go backwards, and that bucket reports no delta rather than a large negative one that would poison every total above it.

Devices Drop Out Intermittently

This is nearly always physical, and nearly always the same two causes.

• The coordinator is plugged straight into the machine. USB 3 ports and NVMe drives emit broadband noise across 2.4 GHz. Use the extension cable that came with the dongle, half a metre, away from the case. On a hub the same rule applies: dongles on their cables, not packed into adjacent ports.
• The mesh has no routers where it needs them. Battery devices do not route. A mains-powered plug or bulb in the middle of a long run does more for reliability than anything in software.

link_quality is recorded for exactly this: "this sensor stopped working" is nearly always a mesh problem, and the shape of the decline is the evidence. Chart it over 7 days for the device that drops, with get device history and capability link_quality.

A device that leaves the mesh is marked unavailable and kept registered, with its name, room and adoption intact. It is not forgotten, because a dead battery is not you saying "remove this".

A Button Trigger Fires but the Branch Never Matches

The strings on the value pin are the device's own, not a RUAL vocabulary. Aqara sends single, double, hold; a Hue dimmer sends initial_press, short_release, long_release; multi-button remotes prefix the button number.

Press the button once and read state.action through get device, or watch the broker, and branch on what it actually sends. Note that Zigbee2MQTT clears the action by publishing an empty string immediately after; that empty value is dropped rather than reported, so it does not double every press.

Next Steps

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem