# Aqara Dual Relay T2 in Home Assistant: Complete Zigbee2MQTT Integration Guide
## Introduction
If you have an existing wall switch you want to make smart without replacing the faceplate, or you need local relay control for motors, shutters, and gate openers, the **Aqara Dual Relay T2** (also known by its model numbers LLKZMK12LM or DCM-K01) is a powerful in-wall solution. Unlike traditional smart switches that replace your existing hardware, relay modules mount behind walls and leave your original switches intact—giving you a familiar physical interface while gaining full automation control through Home Assistant.
This guide walks you through everything: wiring the relay, pairing it with Zigbee2MQTT, configuring operating modes, and building automations. We’ll cover decoupled mode (separating your switch from the relay), interlock mode (essential for motor safety), power monitoring, and troubleshooting. By the end, you’ll understand how to operate this relay in every configuration—whether you’re retrofitting a light circuit, controlling roller shutters, or monitoring appliance power locally without any cloud involvement.
## Hardware Overview: Specs & Wiring
### Key Specifications
The Aqara Dual Relay T2 is a two-channel, dual-relay module designed for DIN rail or wall-box mounting:
– **Channels:** 2 independent relay channels (L1 and L2)
– **Voltage Rating:** AC 100–240V, 50/60 Hz
– **Max Load per Relay:** 10A @ 250V AC
– **Neutral Wire:** **Required** (unlike the Aqara H1 no-neutral switch)
– **Zigbee Standard:** Zigbee 3.0, 2.4 GHz IEEE 802.15.4
– **Power Consumption (idle):** <2W
– **Entities Exposed:** 2 switches (state_l1, state_l2) + shared power monitoring (power, current, energy, voltage, device_temperature)
– **Firmware Updates:** OTA via Zigbee2MQTT—no Aqara Hub required
### Pinout & Wiring
The relay terminals are:
“`
N — Neutral (blue wire)
L — Live input (brown/black)
L1' — Relay 1 output (switched)
L2 — Relay 2 output (switched)
S1 — Switch input 1
S2 — Switch input 2
“`
**Standard wiring for a single light switch retrofit:**
1. Connect mains **L (live)** to the **L input**
2. Connect mains **N (neutral)** to the **N terminal**
3. Connect your light's **live** to **L1' (relay 1 output)**
4. Load **neutral** connects to the main neutral rail
5. Wire your existing physical switch between **S1 and N**
The physical switch now sends input signals; the relay handles load switching. This separation is fundamental to decoupled mode.
### Power Monitoring
The relay includes built-in metering:
– **Power:** watts (W)
– **Current:** amperes (A)
– **Energy:** kilowatt-hours (kWh)
– **Voltage:** RMS voltage (V)
– **Device Temperature:** °C (for thermal monitoring)
These entities are **shared across both channels**, so you get a single reading for the entire device. You can track individual circuit consumption by temporarily disabling one relay while measuring.
## Pairing with Zigbee2MQTT
### Prerequisites
– **Zigbee2MQTT running** with a coordinator (Sonoff, Conbee, etc.)
– **Network functioning:** coordinator can reach other devices
– **Reset procedure known:** factory reset = hold reset button 10 seconds while powered
### Pairing Steps
1. **Start Zigbee2MQTT in pairing mode:**
“`bash
mosquitto_pub -h localhost -t 'zigbee2mqtt/bridge/request/permit_join' \
-m '{"value": true, "time": 60}'
“`
2. **Power up the relay.** The LED will blink during pairing.
3. **Watch Zigbee2MQTT logs:**
“`
[zigbee2mqtt] New device joined with ID: 0x001d1234abcd
[zigbee2mqtt] Device LLKZMK12LM interviewed successfully
“`
4. **Verify entities** in Zigbee2MQTT. Once paired, the relay exposes:
– `state_l1` (switch for relay 1)
– `state_l2` (switch for relay 2)
– `power`, `current`, `energy`, `voltage`, `device_temperature` (shared sensors)
– `operation_mode_l1` and `operation_mode_l2` (decoupled vs. control_relay)
– `interlock` (motor safety mode)
– `mode` (power / pulse / dry)
– `pulse_length` (impulse duration in ms)
– `switch_type` (toggle / momentary / none)
– `power_on_behavior` (on / previous / off / toggle)
– `action` (single_l1, single_l2 events)
### Common Pairing Issues
| Issue | Solution |
|——-|———-|
| Device doesn't appear | Power cycle relay; ensure permit_join active for 60 seconds |
| Pairing times out | Move relay closer to coordinator or router device |
| Entities incomplete | Update Zigbee2MQTT; check device firmware version |
| Shows "unknown" | Update Zigbee2MQTT to latest version |
## Configuring Switch Type to Match Your Hardware
The `switch_type` must match your physical switch so Home Assistant receives correct events.
### Switch Types Explained
**Toggle Switch (default):**
– Behavior: press once to flip state (on→off or off→on)
– Electrical: momentary contact closure
– Config: `switch_type: toggle`
– Use: standard wall light switches
**Momentary Button:**
– Behavior: press to trigger an event (doesn't change state directly)
– Electrical: momentary contact
– Config: `switch_type: momentary`
– Use: door buzzers, gate openers, garage door buttons
**None:**
– Behavior: switch input ignored
– Use: disable physical switch input entirely
### Setting Switch Type in Zigbee2MQTT
“`bash
# Set relay to toggle switch
mosquitto_pub -h localhost \
-t 'zigbee2mqtt/kitchen_relay/set' \
-m '{"switch_type": "toggle"}'
# Set relay to momentary button
mosquitto_pub -h localhost \
-t 'zigbee2mqtt/kitchen_relay/set' \
-m '{"switch_type": "momentary"}'
# Disable physical switch input
mosquitto_pub -h localhost \
-t 'zigbee2mqtt/kitchen_relay/set' \
-m '{"switch_type": "none"}'
“`
Verify:
“`bash
mosquitto_sub -h localhost -t 'zigbee2mqtt/kitchen_relay' | grep switch_type
“`
## Decoupled Mode: Separating Physical Switch from Relay
### What Is Decoupled Mode?
**Standard mode (control_relay):** Physical switch directly controls the relay
– Press switch → relay toggles → light on/off
**Decoupled mode:** Physical switch sends an event; Home Assistant decides the outcome
– Press switch → Home Assistant receives MQTT event → automation responds
This enables:
– Disabling lights from Home Assistant while keeping physical switch functional
– Multi-tap automations (double-press = different scene)
– Same switch controlling multiple devices
– Manual overrides without Home Assistant
### Enabling Decoupled Mode
“`bash
mosquitto_pub -h localhost \
-t 'zigbee2mqtt/kitchen_relay/set' \
-m '{"operation_mode_l1": "decoupled"}'
“`
Or for the second relay:
“`bash
mosquitto_pub -h localhost \
-t 'zigbee2mqtt/kitchen_relay/set' \
-m '{"operation_mode_l2": "decoupled"}'
“`
Now the physical switch sends MQTT events (`action: single_l1` or `single_l2`) instead of directly toggling the relay.
### Building a Home Assistant Automation (HA 2024.10+)
For Home Assistant 2024.10 and later, use the new plural syntax for triggers, conditions, and actions:
“`yaml
automation:
– alias: "Kitchen light toggle via decoupled switch"
description: "Physical switch S1 triggers automation"
triggers:
– platform: mqtt
topic: "zigbee2mqtt/kitchen_relay"
value_template: "{{ value_json.action }}"
payload: "single_l1"
conditions: []
actions:
– service: light.toggle
target:
entity_id: light.kitchen_main
“`
For **Home Assistant versions prior to 2024.10**, use the singular form:
“`yaml
automation:
– alias: "Kitchen light toggle via decoupled switch (HA States panel to verify the correct entity IDs.
## Momentary Pulse Mode for Gates & Buzzers
Devices like gate openers need a **short pulse** (~500ms), not sustained closure.
### Setting Pulse Mode
“`bash
# Enable pulse mode (requires mode: pulse)
mosquitto_pub -h localhost \
-t ‘zigbee2mqtt/kitchen_relay/set’ \
-m ‘{“mode”: “pulse”}’
# Set pulse length (200–2000 ms)
mosquitto_pub -h localhost \
-t ‘zigbee2mqtt/kitchen_relay/set’ \
-m ‘{“pulse_length”: 500}’
# Activate (relay pulses 500ms then returns to OFF)
mosquitto_pub -h localhost -t ‘zigbee2mqtt/kitchen_relay/set’ \
-m ‘{“state_l1”: “ON”}’
“`
### Gate Opener Automation (HA 2024.10+)
“`yaml
automation:
– alias: “Open driveway gate”
description: “Trigger gate opener relay with safety checks”
triggers:
– platform: state
entity_id: input_button.gate_open
to: “pressed”
conditions:
– condition: state
entity_id: input_boolean.gate_lock
state: “on”
actions:
– service: switch.turn_on
target:
entity_id: switch.kitchen_relay_l1
– service: persistent_notification.create
data:
title: “Gate”
message: “Gate opener activated”
“`
## Using Power Monitoring Locally
### Alert on High Power Consumption
“`yaml
automation:
– alias: “High power alert”
description: “Alert if load exceeds 2000W for 1 minute”
triggers:
– platform: numeric_state
entity_id: sensor.kitchen_relay_power
above: 2000
for:
minutes: 1
conditions: []
actions:
– service: notify.mobile_app_iphone
data:
title: “⚠️ High Power”
message: “Kitchen relay using {{ states(‘sensor.kitchen_relay_power’) }}W”
“`
### Energy Dashboard Integration
To enable energy tracking in Home Assistant 2024+, the relay’s energy sensor must be set up with proper device class:
1. **Verify your sensor in Developer Tools > States.**
2. **Add to energy dashboard:**
– Go to Settings > Dashboards > Energy
– Click “Add Grid Consumption”
– Select your relay’s energy sensor (typically `sensor.kitchen_relay_energy`)
### Tracking Consumption per Relay
Create a template sensor that logs power when each relay is active:
“`yaml
template:
– sensor:
– name: “Relay L1 Power Usage”
unique_id: relay_l1_power_usage
unit_of_measurement: “W”
device_class: power
state: >
{%- if is_state(‘switch.kitchen_relay_l1’, ‘on’) -%}
{{ states(‘sensor.kitchen_relay_power’) | float(0) }}
{%- else -%}
0
{%- endif -%}
“`
## Power-On Behavior: Surviving Power Outages
Configure what the relay does after losing and regaining power:
“`bash
# Always restore last state (default: ‘previous’)
mosquitto_pub -h localhost \
-t ‘zigbee2mqtt/kitchen_relay/set’ \
-m ‘{“power_on_behavior”: “previous”}’
# Always turn OFF after power restoration (safe default)
mosquitto_pub -h localhost \
-t ‘zigbee2mqtt/kitchen_relay/set’ \
-m ‘{“power_on_behavior”: “off”}’
# Always turn ON after power restoration
mosquitto_pub -h localhost \
-t ‘zigbee2mqtt/kitchen_relay/set’ \
-m ‘{“power_on_behavior”: “on”}’
# Toggle state after power restoration
mosquitto_pub -h localhost \
-t ‘zigbee2mqtt/kitchen_relay/set’ \
-m ‘{“power_on_behavior”: “toggle”}’
“`
**Best practices:**
– Use `off` for circuits that must default to safe (e.g., heating elements, outdoor relays)
– Use `previous` (or `restore`) for lights and general loads to maintain user expectations
– Avoid `on` unless the circuit requires default-on behavior
Note: This setting applies to **both relays** unless you need per-endpoint control (advanced topic).
## Troubleshooting Common Issues
### Relay doesn’t toggle
**Cause:** Zigbee connection lost or operation mode is set to “decoupled”
**Solution:**
1. Verify MQTT messages reach the relay: `mosquitto_sub -h localhost -t ‘zigbee2mqtt/kitchen_relay’`
2. Check operation_mode: `mosquitto_pub -h localhost -t ‘zigbee2mqtt/kitchen_relay/get’ -m ‘{“operation_mode_l1”: “”}’`
3. If decoupled, switch to control_relay: `mosquitto_pub -h localhost -t ‘zigbee2mqtt/kitchen_relay/set’ -m ‘{“operation_mode_l1”: “control_relay”}’`
### Entities not appearing in Home Assistant
**Cause:** Zigbee2MQTT integration not properly configured or device not discovered
**Solution:**
1. Ensure Zigbee2MQTT is running and MQTT integration is enabled in Home Assistant
2. Check device appears in Zigbee2MQTT (`mosquitto_sub -h localhost -t ‘zigbee2mqtt’`)
3. Restart Home Assistant to force MQTT discovery refresh
### Power entities missing
**Cause:** Older firmware or incomplete pairing
**Solution:**
1. Trigger an OTA update via Zigbee2MQTT: `mosquitto_pub -h localhost -t ‘zigbee2mqtt/bridge/request/device/ota_update/check’ -m ‘{“id”: “kitchen_relay”}’`
2. Re-pair if needed by factory resetting the relay
### Physical switch has no effect
**Cause:**
– Operation mode set to “decoupled” (switch sends events, doesn’t toggle relay)
– switch_type mismatch with actual hardware
– Relay offline
**Solution:**
1. Verify switch_type: `mosquitto_pub -h localhost -t ‘zigbee2mqtt/kitchen_relay/get’ -m ‘{“switch_type”: “”}’`
2. Set to match hardware: `mosquitto_pub -h localhost -t ‘zigbee2mqtt/kitchen_relay/set’ -m ‘{“switch_type”: “toggle”}’`
3. Check relay online: verify `link_quality` > 0 in MQTT output
4. Set operation mode: `mosquitto_pub -h localhost -t ‘zigbee2mqtt/kitchen_relay/set’ -m ‘{“operation_mode_l1”: “control_relay”}’`
### LED Behavior Indicating Errors
| LED State | Meaning | Action |
|———–|———|——–|
| Steady OFF | No power supplied | Check mains L and N connection |
| Steady ON | Powered, relays idle | Normal operation |
| Blinking slowly | Pairing/interview mode | Device joining network |
| Blinking rapidly | Relay overload or fault | Check load amperage, reduce load |
| No LED | Device failure | Contact support, may need replacement |
### Resetting the Relay
**Factory reset (clears all settings, requires re-pairing):**
“`bash
# Hold reset button for 10 seconds while powered
# Relay LED will flash, indicating reset in progress
# Device will be ready to pair again
“`
**Soft restart (keeps settings):**
“`bash
# Power cycle: turn off mains for 30 seconds, then restore
“`
## Advanced: Calibrating Power Monitoring
The relay’s power sensors may drift over time or due to environmental factors. Zigbee2MQTT allows calibration of power, current, and energy via percentual offsets.
### Calibrating Against a Reference Meter
1. Install a known reference meter (e.g., extension cord with built-in display) in series with your relay load.
2. Turn on a stable resistive load (e.g., 1000W heater) and let it stabilize for 2–3 minutes.
3. Record both the reference meter reading and the relay’s reported power:
“`bash
mosquitto_sub -h localhost -t ‘zigbee2mqtt/kitchen_relay’ | grep ‘”power”‘
“`
4. Calculate the calibration offset (percentual):
– Example: Reference reads 1000W, relay reads 950W
– Offset = ((1000 – 950) / 950) × 100 = 5.26%
– Round to 5 or apply 5.26 depending on precision needed
5. Apply the calibration via MQTT:
“`bash
mosquitto_pub -h localhost \
-t ‘zigbee2mqtt/kitchen_relay/set’ \
-m ‘{“power_calibration”: 5}’
“`
6. Repeat the measurement to verify the correction.
**Calibration tips:**
– Use a resistive load (incandescent bulbs or heaters are best) rather than motors or switching power supplies, which distort readings
– Take multiple readings at different power levels (e.g., 500W, 1000W, 2000W) for best accuracy
– Most installations tolerate ±5% error without calibration—only calibrate if you’re tracking billing or require high precision
– Current and voltage can also be calibrated with `current_calibration` and `voltage_calibration`
## Firmware Updates via OTA
One major advantage of Zigbee2MQTT integration is **firmware updates without a hub or cloud service**. OTA updates are delivered locally over Zigbee.
### Checking and Triggering OTA Updates
“`bash
# Check if an update is available for the relay
mosquitto_pub -h localhost \
-t ‘zigbee2mqtt/bridge/request/device/ota_update/check’ \
-m ‘{“id”: “kitchen_relay”}’
# Monitor Zigbee2MQTT logs for update availability
mosquitto_sub -h localhost -t ‘zigbee2mqtt’ | grep -i ‘ota\|update’
# Once update is detected, trigger it
mosquitto_pub -h localhost \
-t ‘zigbee2mqtt/kitchen_relay/set’ \
-m ‘{“update”: {“installed_version”: 0, “latest_version”: 1}}’
“`
### During OTA Update
– **Do NOT power off** the relay
– **Do NOT disable Zigbee connectivity** or restart Zigbee2MQTT
– Update typically takes 1–5 minutes
– Relay may become briefly unresponsive
– LED behavior may change (check Zigbee2MQTT logs for status)
### If OTA Stalls or Fails
1. Check Zigbee2MQTT logs for errors
2. Ensure relay has strong Zigbee signal (LQI > 150)
3. Wait 5 minutes, then retry the update command
4. If still failing, power-cycle relay and try again
5. Contact Aqara support if update consistently fails
## Networking & Reliability
### Ensuring Strong Zigbee Routing
The relay will automatically route through other Zigbee devices (routers) if it loses direct contact with the coordinator. To optimize your mesh:
1. **Place router devices strategically** (Sonoff ZBDongle-E, Philips Hue bridges, TRADFRI gateway, etc.)
– Position one within 15 meters of the relay
– Avoid walls, metal, and water barriers
– Stagger routers for redundancy
2. **Monitor link quality in Zigbee2MQTT:**
“`bash
mosquitto_sub -h localhost -t ‘zigbee2mqtt/kitchen_relay’ | grep -i ‘link_quality\|lqi’
“`
– **LQI > 150:** Excellent signal
– **LQI 80–150:** Good signal
– **LQI < 80:** Weak signal (consider adding routers)
– **LQI 0 or null:** Device offline
3. **Avoid 2.4 GHz interference:**
– Keep relay away from microwave ovens (especially while in use)
– WiFi interference: use 5 GHz WiFi when possible, or change WiFi channel away from Zigbee channels 15–20
– Cordless DECT phones emit strong interference
– Bluetooth devices (though usually less problematic)
### Handling Temporary Disconnections
**If the relay becomes unreachable:**
1. **Check mains power first** (multimeter on L and N terminals)
2. **Check Zigbee2MQTT is running:**
“`bash
systemctl status zigbee2mqtt
“`
3. **Check MQTT broker connectivity:**
“`bash
mosquitto_sub -h localhost -t 'zigbee2mqtt' -v | head
“`
4. **Power-cycle the relay** (30 seconds off)
5. **Move relay closer to coordinator or router** (temporary troubleshooting)
6. **Check Zigbee2MQTT logs** for errors:
“`bash
journalctl -u zigbee2mqtt -f
“`
7. **Re-pair if necessary** by factory resetting and re-pairing
### Persistent Notifications on Offline Devices (HA 2024.10+)
Create an automation that alerts when the relay goes offline:
“`yaml
automation:
– alias: "Relay offline alert"
description: "Alert if relay loses Zigbee connection"
triggers:
– platform: state
entity_id: sensor.kitchen_relay_link_quality
to: null
for:
seconds: 30
conditions: []
actions:
– service: persistent_notification.create
data:
title: "⚠️ Relay Offline"
message: "Kitchen relay lost Zigbee connection"
“`
## FAQ: Frequently Asked Questions
**Q: Does the Aqara Dual Relay T2 require a neutral wire?**
A: Yes. Unlike the Aqara H1 no-neutral switch, this relay requires a neutral connection to the mains supply. Do not attempt to install it without a neutral wire; it will not function and may pose a safety risk.
**Q: Can I use both relays on a single light, or must each relay control a separate load?**
A: Each relay is independent and should control a separate load. If you want to switch a single light with dual relays (e.g., 2-way switching), you would use them in an OR configuration, which requires additional external wiring logic. Most users reserve each relay for its own circuit.
**Q: What happens if I enable interlock mode but still try to activate both relays via MQTT?**
A: Interlock mode automatically deactivates the previously active relay when you activate a new one. The device handles this internally; you cannot override it without disabling interlock mode.
**Q: Can I update the relay's firmware without Zigbee2MQTT?**
A: No. The relay's firmware updates are delivered only through Zigbee2MQTT via OTA. If you do not use Zigbee2MQTT, you cannot update the firmware. You would need an Aqara Hub, but that requires cloud connectivity. Local-only users must use Zigbee2MQTT.
**Q: The physical switch sometimes doesn't register when Home Assistant is offline. Why?**
A: In decoupled mode, the relay still sends MQTT events even when Home Assistant is offline. However, those events are lost if MQTT is not persisting them. In standard mode (non-decoupled), the relay toggles directly without needing Home Assistant, so the switch always works. Check your MQTT configuration to enable message persistence if needed.
**Q: Can I mix decoupled and non-decoupled relays on the same module?**
A: Yes. Each relay channel has its own `operation_mode` setting. You can set relay L1 to `control_relay` (standard) and relay L2 to `decoupled` (event-based). This is useful when you want one relay to always respond to its physical switch, while the other sends events to Home Assistant for conditional logic.
**Q: How accurate is the power monitoring?**
A: Typical accuracy is ±5% under stable load, based on manufacturer specifications. For most users (lighting, heating), this is sufficient. If you need better accuracy (e.g., for billing), calibrate against a reference meter or use a dedicated power monitoring device.
**Q: The relay seems unresponsive. What are the first steps to debug?**
A: (1) Check mains power (multimeter on L, N terminals). (2) Check Zigbee2MQTT logs for the relay's online status. (3) If offline, move the relay closer to the Zigbee coordinator or a router device. (4) Power-cycle the relay (30 seconds off). (5) Re-pair if the relay does not return online after restart.
**Q: Can I use the relay for high-current loads like a large water heater?**
A: The maximum load per relay is 10A @ 250V AC, which equals 2.5 kW on a 250V circuit or 2.3 kW on a 230V circuit. Many water heaters exceed this; check your load amperage. For loads above 10A, you would need a larger relay, not this module.
## Conclusion
The Aqara Dual Relay T2 is a versatile, locally-controlled relay module that brings smart home capabilities to existing wall switches without requiring rewiring or central hubs. By pairing it with Zigbee2MQTT and Home Assistant, you gain full control over relay operation modes—toggle, momentary, decoupled, interlock—while maintaining local power monitoring, OTA firmware updates, and detailed networking diagnostics.
Whether you're retrofitting a single light circuit, controlling a roller shutter safely, or implementing a gate opener, this guide provides the configuration and automation examples you need. The key is matching your `switch_type` to your physical hardware, understanding when to use decoupled mode, and always enabling interlock for motor safety. Advanced users can calibrate power measurements, monitor Zigbee link quality, and leverage offline notifications to maintain reliability.
With this relay installed and configured, you'll have a truly local, cloud-free relay solution that responds instantly to Home Assistant automations and physical switch presses—exactly what a smart home should do. Keep your firmware updated via OTA, monitor power consumption for early detection of faults, and trust your Zigbee mesh to keep everything connected.
Leave A Comment