TapHome

Aqara Single Switch Module T1 (With Neutral)

Packet Parser → MQTT
Submitted by
Last updated: 03. 2026

Requires external gateway

tasmota zigbee2tasmota-gateway — product page

Aqara Single Switch Module T1 (With Neutral)

This device communicates via Zigbee through a Tasmota gateway. Make sure you have the Zigbee2Tasmota Gateway template imported and your device paired before proceeding.

The Aqara Single Switch Module T1 (With Neutral) is a compact Zigbee 3.0 relay module (model SSM-U01) designed for behind-switch installation. It converts a traditional wall switch into a smart switch while keeping the original switch plate. TapHome controls the relay over MQTT through a Zigbee2Tasmota gateway using ZbSend commands — no cloud connection required.

The module requires a neutral wire and supports loads from 3W to 2500W (10A resistive) at 100-250 VAC. Its compact dimensions (42.9 x 40 x 19.9 mm) allow installation inside most wall switch boxes.

As a mains-powered device, the module acts as a Zigbee router — it strengthens the Zigbee mesh network and extends range for nearby battery-powered sensors.

Configuration

Pairing the module
  1. Ensure the Zigbee2Tasmota Gateway is set up and the Permit Join switch is ON in TapHome
  2. On the module, long press the button until the blue LED starts blinking rapidly, then release
  3. Wait for the Devices Found counter to increment — the module’s Device ID (e.g., 0x1234) appears in the gateway service attributes
  4. Import this device template using the Device ID from pairing
Template import parameters

The device template requires 4 parameters:

ParameterDescriptionExample
MQTT Broker IP AddressIP of your MQTT broker192.168.1.10
MQTT Broker PortBroker port (default 1883)1883
Gateway nameTasmota MQTT topic (Configuration → MQTT → Topic)tasmota_XXXXX
Device IDZigbee short address from pairing0x1234

After import, a single Switch device appears in TapHome for on/off control.

Wiring

The module requires a neutral wire connection with three terminals:

TerminalConnection
LLive wire input (line)
NNeutral wire
L1Load output (light or appliance)

This module requires a neutral wire. It cannot be installed in switch boxes that only have live and switched-live conductors. Maximum load is 10A / 2500W for resistive loads, minimum load is 3W. Installation must be performed by a qualified electrician.

Device capabilities

Switch control

The template creates one Switch device that reads and writes the Power field:

  • Read: The module listens on the tele/{GWname}/SENSOR topic for ZbReceived.{ID}.Power messages. When the physical button is pressed or the relay state changes, the module publishes its new state.
  • Write: TapHome sends a ZbSend command to cmnd/{GWname}/ZbSend with Power: true (ON) or Power: false (OFF) to control the relay remotely.

The switch responds to both physical button presses and TapHome commands, and TapHome always reflects the current relay state — regardless of how it was toggled.

Service attributes

The module exposes diagnostic Zigbee metadata retrieved via ZbInfo polling:

AttributeDescription
IEEEAddrUnique 64-bit hardware identifier
ModelIdZigbee model ID (lumi.switch.n0agl1)
ManufacturerManufacturer string reported by the device
EndpointsActive Zigbee endpoints
ConfigDevice Zigbee configuration
Additional capabilities

The Aqara SSM-U01 also supports real-time power monitoring (watts), cumulative energy consumption tracking, internal device temperature reporting, decoupled mode (button can trigger scenes without switching the relay), and overload/overheating protection. These capabilities are available in the hardware but are not currently mapped in the TapHome template — they can be added in a future template update.

Troubleshooting

Switch not responding to TapHome commands
  1. Verify the Device ID in the template matches the Zigbee short address assigned during pairing (e.g., 0xC0B4)
  2. Check that the Gateway name matches between the gateway template and this device template
  3. Test the physical button on the module — if it toggles the relay but TapHome does not update, the read path (tele/{GWname}/SENSOR topic) may have an issue
  4. Use an MQTT client (e.g., MQTT Explorer) to subscribe to tele/{GWname}/SENSOR and verify the module publishes ZbReceived messages with a Power field when toggled
Switch state out of sync
  1. If TapHome shows a different state than the actual relay, press the physical button to trigger a state report
  2. The template does not actively poll the switch state — it relies on the device reporting changes. If the module briefly loses Zigbee connectivity, the state may become stale until the next physical toggle or command
Module not pairing
  1. Ensure the module is powered (neutral wire and live wire must both be connected)
  2. Long press the button until the blue LED blinks rapidly — a short press will not enter pairing mode
  3. Move the gateway closer during initial pairing if the module is far from the coordinator
  4. If the module was previously paired with another Zigbee coordinator, it may need a factory reset before joining a new network — hold the button for 10+ seconds until the LED flashes three times

How to install in TapHome

Prerequisites

  • Zigbee gateway with Tasmota firmware (e.g., Sonoff ZBBridge, eWeLink ZB-GW03)
  • MQTT broker running on your local network (TapHome built-in broker or external)
  • TapHome CCU on the same network

TapHome has a built-in MQTT broker — enable it in Settings → Hardware → MQTT Broker. No additional software is needed.

Step 1 — Set Up the Tasmota Zigbee Gateway

  1. Flash Tasmota firmware on a supported Zigbee coordinator (e.g., Sonoff ZBBridge, eWeLink ZB-GW03)
  2. Connect the gateway to your Wi-Fi network via the Tasmota web UI
  3. Navigate to Configuration → Configure MQTT and set:
    • Host: your MQTT broker IP (e.g., 192.168.1.10)
    • Port: 1883
    • Topic: note down the topic name (e.g., tasmota_XXXXX) — you will need it during template import

For detailed instructions, see the Tasmota Zigbee documentation.

Step 2 — Import the Gateway Template in TapHome

  1. Download the gateway template from the Zigbee2Tasmota Gateway compatibility page
  2. In TapHome, go to Settings → Hardware → Packet Parser → Import
  3. Import the template with these parameters:
    • MQTT Broker IP Address: your broker IP (e.g., 192.168.1.10)
    • MQTT Broker Port: 1883
    • Gateway name: the Tasmota MQTT topic from Step 1 (e.g., tasmota_XXXXX)

After import, you will see two devices: Permit Join (switch) and Devices Found (counter).

Step 3 — Pair a Zigbee Device

  1. In TapHome, turn on the Permit Join switch — this opens a 60-second pairing window
  2. On the Zigbee device, start the pairing procedure (typically hold the reset button for 5 seconds until the LED blinks)
  3. Watch the Devices Found counter — it increments when a new device joins
  4. Check the Service Attributes of the gateway to see the new device’s ID (e.g., 0x1234), manufacturer, and model
  5. The pairing mode deactivates automatically after the timeout

Step 4 — Import the Device Template

  1. Download the device-specific template from the corresponding compatibility page
  2. Import the template with these parameters:
    • MQTT Broker IP Address: same as the gateway
    • MQTT Broker Port: 1883
    • Gateway name: same Tasmota MQTT topic as above
    • Device ID: the short address from pairing (e.g., 0x1234)

Available devices

Aqara Single Switch Module T1 (With Neutral) Module
Service Attributes
IEEEAddrZigbee IEEE address — unique 64-bit hardware identifier
ModelId
Manufacturer
Endpoints
Config
Custom Variables
GWname (string)Tasmota MQTT topic name of the Zigbee gateway (found in Configuration → MQTT → Topic)
ID (string) = 0xC0B4Zigbee short address of the Aqara Single Switch Module T1 (assigned during pairing)
After pairing the device via Permit Join, find the device short address in the gateway's Devices Found service attribute or via Tasmota console command ZbStatus

Aqara - Single Switch Module T1 (With Neutral)

Listener
if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0
	var ZbReceived := PARSEJSON(TOSTRING(RECEIVEDMSG.Payload), "ZbReceived." + ID, true);
    var val := PARSEJSON(ZbReceived, ".LinkQuality", true);
    if(!ISNULL(val), LinkQuality := val);
    
    var deviceInfo := PARSEJSON(TOSTRING(RECEIVEDMSG.Payload), "ZbInfo." + ID, true);
    if !ISNULL(deviceInfo)
        COMPLETESERVICEATTRIBUTE("IEEEAddr", PARSEJSON(deviceInfo, "IEEEAddr"));
        COMPLETESERVICEATTRIBUTE("ModelId", PARSEJSON(deviceInfo, "ModelId"));
        COMPLETESERVICEATTRIBUTE("Manufacturer", PARSEJSON(deviceInfo, "Manufacturer"));
        COMPLETESERVICEATTRIBUTE("Endpoints", PARSEJSON(deviceInfo, "Endpoints"));
        #COMPLETESERVICEATTRIBUTE("Config", PARSEJSON(deviceInfo, "Config"));
    end
end
Service Attributes
IEEEAddr
MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", ID)
ModelId
Manufacturer
Endpoints
Config
Switch Switch

On/off relay controlled via ZbSend Power command — switches the L1 load output

boolean
Values / States: ON · OFF

Switch

Write switch state
MQTTPUBLISH("cmnd/" + GWname+ "/ZbSend", 
    "{\"device\":\" " + ID + 
    "\",\"send\":{\"Power\":" + St + "}}")
Listener
VAR json := tostring(RECEIVEDMSG.Payload);
VAR topic := RECEIVEDMSG.Topic;

if INDEXOF(topic, "SENSOR") > 0
    var val := PARSEJSON(json, "ZbReceived." + ID + ".Power", true);
    if(!ISNULL(val), St := val);
end
Connection: Packet Parser → MQTT
Possible improvements (5)
  • Power Monitoring — Real-time power measurement in watts — hardware supports it but not mapped in XML template
  • Energy Monitoring — Cumulative energy consumption tracking — available in hardware but not mapped in XML template
  • Device Temperature — Internal temperature sensor — hardware supports it but not mapped in XML template
  • Decoupled Mode — Button can be decoupled from relay for scene triggering — not mapped in XML template
  • Overload / Overheating Protection — Built-in safety features — max 10A / 2500W resistive load. Not exposed in template.

Sources