TapHome

Aqara Single Switch Module T1 (With Neutral)

Packet Parser → MQTT
Inviato da
Ultimo aggiornamento: 03. 2026

Richiede gateway esterno

tasmota zigbee2tasmota-gateway — pagina prodotto

Aqara Single Switch Module T1 (With Neutral)

Questo dispositivo comunica via Zigbee attraverso un gateway Tasmota. Assicurati di avere il template Zigbee2Tasmota Gateway importato e il dispositivo accoppiato prima di procedere.

L’Aqara Single Switch Module T1 (With Neutral) è un modulo relè Zigbee 3.0 compatto (modello SSM-U01) progettato per l’installazione dietro l’interruttore. Trasforma un tradizionale interruttore a parete in un interruttore smart mantenendo la placca originale. TapHome controlla il relè via MQTT attraverso un gateway Zigbee2Tasmota usando comandi ZbSend — senza connessione cloud.

Il modulo richiede il filo neutro e supporta carichi da 3 W a 2500 W (10 A carico resistivo) a 100 – 250 VAC. Le dimensioni compatte (42,9 x 40 x 19,9 mm) consentono l’installazione nella maggior parte delle scatole da incasso.

Come dispositivo alimentato dalla rete, il modulo funziona come router Zigbee — rafforza la rete mesh Zigbee ed estende la portata per i sensori a batteria nelle vicinanze.

Configurazione

Accoppiamento del modulo
  1. Assicurati che il Zigbee2Tasmota Gateway sia configurato e l’interruttore Permit Join sia attivo in TapHome
  2. Sul modulo, tieni premuto il pulsante finché il LED blu non lampeggia rapidamente, poi rilascia
  3. Attendi che il contatore Devices Found si incrementi — il Device ID del modulo (es. 0x1234) appare negli attributi di servizio del gateway
  4. Importa il template di questo dispositivo usando il Device ID ottenuto dall’accoppiamento
Parametri di importazione del template

Il template del dispositivo richiede 4 parametri:

ParametroDescrizioneEsempio
MQTT Broker IP AddressIP del broker MQTT192.168.1.10
MQTT Broker PortPorta del broker (predefinita 1883)1883
Gateway nameTopic MQTT Tasmota (Configuration → MQTT → Topic)tasmota_XXXXX
Device IDIndirizzo Zigbee breve dall’accoppiamento0x1234

Dopo l’importazione, in TapHome appare un singolo dispositivo Interruttore per il controllo on/off.

Cablaggio

Il modulo richiede il collegamento del filo neutro con tre morsetti:

MorsettoCollegamento
LIngresso filo di fase (linea)
NFilo neutro
L1Uscita carico (luce o apparecchio)

Questo modulo richiede il filo neutro. Non può essere installato in scatole che hanno solo fase e ritorno lampada. Il carico massimo è 10 A / 2500 W per carichi resistivi, il carico minimo è 3 W. L’installazione deve essere eseguita da un elettricista qualificato.

Funzionalità del dispositivo

Controllo interruttore

Il template crea un dispositivo Interruttore che legge e scrive il campo Power:

  • Lettura: Il modulo ascolta sul topic tele/{GWname}/SENSOR i messaggi ZbReceived.{ID}.Power. Quando il pulsante fisico viene premuto o lo stato del relè cambia, il modulo pubblica il nuovo stato.
  • Scrittura: TapHome invia un comando ZbSend a cmnd/{GWname}/ZbSend con Power: true (ON) o Power: false (OFF) per controllare il relè da remoto.

L’interruttore risponde sia alla pressione del pulsante fisico che ai comandi di TapHome, e TapHome riflette sempre lo stato attuale del relè — indipendentemente da come è stato commutato.

Attributi di servizio

Il modulo espone metadati diagnostici Zigbee recuperati tramite polling ZbInfo:

AttributoDescrizione
IEEEAddrIdentificatore hardware univoco a 64 bit
ModelIdID modello Zigbee (lumi.switch.n0agl1)
ManufacturerStringa del produttore riportata dal dispositivo
EndpointsEndpoint Zigbee attivi
ConfigConfigurazione del dispositivo Zigbee
Funzionalità aggiuntive

L’Aqara SSM-U01 supporta anche il monitoraggio della potenza in tempo reale (watt), il tracciamento del consumo energetico cumulativo, la segnalazione della temperatura interna del dispositivo, la modalità disaccoppiata (il pulsante può attivare scene senza commutare il relè) e la protezione da sovraccarico/surriscaldamento. Queste funzionalità sono disponibili nell’hardware ma attualmente non sono mappate nel template TapHome — potranno essere aggiunte in un futuro aggiornamento del template.

Risoluzione dei problemi

L’interruttore non risponde ai comandi di TapHome
  1. Verifica che il Device ID nel template corrisponda all’indirizzo Zigbee breve assegnato durante l’accoppiamento (es. 0xC0B4)
  2. Controlla che il Gateway name corrisponda tra il template del gateway e il template di questo dispositivo
  3. Testa il pulsante fisico sul modulo — se commuta il relè ma TapHome non si aggiorna, il problema potrebbe essere nel percorso di lettura (topic tele/{GWname}/SENSOR)
  4. Usa un client MQTT (es. MQTT Explorer) per iscriverti al topic tele/{GWname}/SENSOR e verificare che il modulo pubblichi messaggi ZbReceived con un campo Power quando viene commutato
Stato dell’interruttore non sincronizzato
  1. Se TapHome mostra uno stato diverso dal relè effettivo, premi il pulsante fisico per attivare un rapporto di stato
  2. Il template non interroga attivamente lo stato dell’interruttore — si basa sulle segnalazioni di cambio stato del dispositivo. Se il modulo perde brevemente la connettività Zigbee, lo stato potrebbe essere obsoleto fino alla successiva commutazione fisica o comando
Il modulo non si accoppia
  1. Assicurati che il modulo sia alimentato (il filo neutro e il filo di fase devono essere entrambi collegati)
  2. Tieni premuto il pulsante finché il LED blu non lampeggia rapidamente — una pressione breve non avvia la modalità di accoppiamento
  3. Avvicina il gateway durante il primo accoppiamento se il modulo è lontano dal coordinatore
  4. Se il modulo era precedentemente accoppiato con un altro coordinatore Zigbee, potrebbe essere necessario un ripristino alle impostazioni di fabbrica — tieni premuto il pulsante per 10+ secondi finché il LED lampeggia tre volte

Come installare in TapHome

Prerequisiti

  • Gateway Zigbee con firmware Tasmota (es. Sonoff ZBBridge, eWeLink ZB-GW03)
  • Broker MQTT in esecuzione nella rete locale (broker integrato TapHome o esterno)
  • TapHome CCU sulla stessa rete

TapHome ha un broker MQTT integrato — attivalo in Impostazioni → Hardware → MQTT Broker. Non è necessario alcun software aggiuntivo.

Passaggio 1 — Configurare il gateway Tasmota Zigbee

  1. Installa il firmware Tasmota su un coordinatore Zigbee supportato (es. Sonoff ZBBridge, eWeLink ZB-GW03)
  2. Connetti il gateway alla tua rete Wi-Fi tramite l’interfaccia web Tasmota
  3. Vai su Configuration → Configure MQTT e imposta:
    • Host: indirizzo IP del tuo broker MQTT (es. 192.168.1.10)
    • Port: 1883
    • Topic: annota il nome del topic (es. tasmota_XXXXX) — ti servirà durante l’importazione del template

Per istruzioni dettagliate, consulta la documentazione Tasmota Zigbee.

Passaggio 2 — Importare il template del gateway in TapHome

  1. Scarica il template del gateway dalla pagina di compatibilità Zigbee2Tasmota Gateway
  2. In TapHome, vai su Impostazioni → Hardware → Packet Parser → Import
  3. Importa il template con questi parametri:
    • MQTT Broker IP Address: indirizzo IP del tuo broker (es. 192.168.1.10)
    • MQTT Broker Port: 1883
    • Gateway name: il topic MQTT Tasmota dal passaggio 1 (es. tasmota_XXXXX)

Dopo l’importazione vedrai due dispositivi: Permit Join (interruttore) e Devices Found (contatore).

Passaggio 3 — Associare un dispositivo Zigbee

  1. In TapHome, attiva l’interruttore Permit Join — si apre una finestra di associazione di 60 secondi
  2. Sul dispositivo Zigbee, avvia la procedura di associazione (tipicamente tieni premuto il pulsante reset per 5 secondi finché il LED non lampeggia)
  3. Osserva il contatore Devices Found — aumenta quando un nuovo dispositivo si connette
  4. Controlla i Service Attributes del gateway per vedere l’ID del nuovo dispositivo (es. 0x1234), il produttore e il modello
  5. La modalità di associazione si disattiva automaticamente allo scadere del timeout

Passaggio 4 — Importare il template del dispositivo

  1. Scarica il template specifico del dispositivo dalla pagina di compatibilità corrispondente
  2. Importa il template con questi parametri:
    • MQTT Broker IP Address: lo stesso del gateway
    • MQTT Broker Port: 1883
    • Gateway name: lo stesso topic MQTT Tasmota di cui sopra
    • Device ID: l’indirizzo breve ottenuto dall’associazione (es. 0x1234)

Dispositivi disponibili

Aqara Single Switch Module T1 (With Neutral) Modulo
Attributi di servizio
IEEEAddrIndirizzo IEEE Zigbee — identificatore hardware univoco a 64 bit
ModelId
Manufacturer
Endpoints
Config
Variabili personalizzate
GWname (string)Nome del topic MQTT Tasmota del gateway Zigbee (in Configuration → MQTT → Topic)
ID (string) = 0xC0B4Indirizzo Zigbee breve dell'Aqara Single Switch Module T1 (assegnato durante l'accoppiamento)
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
Attributi di servizio
IEEEAddr
MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", ID)
ModelId
Manufacturer
Endpoints
Config
Interruttore Interruttore

Relè on/off controllato tramite comando ZbSend Power — commuta l'uscita carico L1

boolean
Valori / Stati: ON · OFF

Interruttore

Scrittura stato interruttore
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
Connessione: Packet Parser → MQTT
Possibili miglioramenti (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.

Fonti