--- title: "Aqara Single Switch Module T1 (With Neutral)" description: "Controllo relè on/off del modulo Zigbee Aqara SSM-U01 via gateway Tasmota. Alimentazione di rete, neutro richiesto, max 10A/2500W. Comando ZbSend Power." url: "https://taphome.com/it/compatibility/zigbee2tasmota-aqara-single-switch-module-t1-with-neutral/" language: it lastmod: 2026-03-29 generator: hugo ai: topics: ["mqtt","smart-plug","zigbee","zigbee2tasmota","switch","relay","mains-powered"] questions: ["Come integrare l'Aqara Single Switch Module T1 con TapHome?","Come controllare il relè Aqara SSM-U01 tramite TapHome?","Come accoppiare il modulo switch Aqara con un gateway Zigbee2Tasmota?","Perché il mio modulo switch Aqara non risponde ai comandi di TapHome?","L'Aqara SSM-U01 richiede il filo neutro?","Qual è il carico massimo del modulo switch Aqara SSM-U01?"] --- # Aqara Single Switch Module T1 (With Neutral) Comunicazione: Packet Parser → MQTT - [Pagina prodotto Aqara — SSM-U01](https://www.aqara.com/en/product/single-switch-module-t1-with-neutral/) > Indirizzo di rete > > Con il broker MQTT integrato in TapHome, inserisci `127.0.0.1` come indirizzo del broker in TapHome. Nel dispositivo inserisci l’indirizzo IP del TapHome Core e assegna al Core una prenotazione IP nel router. > > [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/) ## Guida all'integrazione > [!IMPORTANT] > Questo dispositivo comunica via **Zigbee** attraverso un gateway Tasmota. Assicurati di avere > il template [Zigbee2Tasmota Gateway](https://taphome.com/it/compatibility/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](https://taphome.com/it/compatibility/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: | Parametro | Descrizione | Esempio | |-----------|-------------|---------| | **MQTT Broker IP Address** | IP del broker MQTT | `192.168.1.10` | | **MQTT Broker Port** | Porta del broker (predefinita 1883) | `1883` | | **Gateway name** | Topic MQTT Tasmota (Configuration → MQTT → Topic) | `tasmota_XXXXX` | | **Device ID** | Indirizzo Zigbee breve dall'accoppiamento | `0x1234` | 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: | Morsetto | Collegamento | |----------|--------------| | **L** | Ingresso filo di fase (linea) | | **N** | Filo neutro | | **L1** | Uscita carico (luce o apparecchio) | > [!WARNING] > 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`: | Attributo | Descrizione | |-----------|-------------| | **IEEEAddr** | Identificatore hardware univoco a 64 bit | | **ModelId** | ID modello Zigbee (`lumi.switch.n0agl1`) | | **Manufacturer** | Stringa del produttore riportata dal dispositivo | | **Endpoints** | Endpoint Zigbee attivi | | **Config** | Configurazione 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 > [!TIP] > 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](https://tasmota.github.io/docs/Getting-Started/) 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:** per il broker integrato, l'indirizzo IP del TapHome Core (con una prenotazione IP nel router → [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/)), altrimenti l'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](https://tasmota.github.io/docs/Zigbee/). ### Passaggio 2 — Importare il template del gateway in TapHome 1. Scarica il template del gateway dalla pagina di compatibilità [Zigbee2Tasmota Gateway](https://taphome.com/it/compatibility/zigbee2tasmota-gateway/) 2. In TapHome, vai su **Impostazioni** → **Hardware** → **Packet Parser** → **Import** 3. Importa il template con questi parametri: - **MQTT Broker IP Address:** `127.0.0.1` per il broker integrato di TapHome, altrimenti l'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 1 Questi dispositivi compaiono in TapHome dopo l'importazione. Aqara Single Switch Module T1 (With Neutral) Modulo Attributi di servizio | | | |--------------|------------------------------------------------------------------| | IEEEAddr | Indirizzo 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) = 0xC0B4 Indirizzo 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 Listener ```taphome 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 ```taphome MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", ID) ``` ModelId ``` ``` Manufacturer ``` ``` Endpoints ``` ``` Config ``` ``` Interruttore Interruttore Lettura e scrittura Relè on/off controllato tramite comando ZbSend Power — commuta l'uscita carico L1 boolean Valori / Stati: ON · OFF Scrittura stato interruttore ```taphome MQTTPUBLISH("cmnd/" + GWname+ "/ZbSend", "{\"device\":\" " + ID + "\",\"send\":{\"Power\":" + St + "}}") ``` Listener ```taphome 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. ## Parametri di importazione Inserisci questi valori quando importi l'XML. | Richiesto nell'app | Predefinito | |-------------------------------------------------------------|-----------------| | Mqtt Broker Indirizzo IP | `192.168.0.1` | | Mqtt Broker port | `1883` | | Gateway name (Tasmota->Configuration->MQTT->Topic) | `tasmota_XXXXX` | | Device ID | `0xFFFF` | ## Fonti - Tasmota Zigbee Documentation [tasmota.github.io](https://tasmota.github.io/docs/Zigbee/) - Zigbee Compatible Devices Database - Aqara Product Page — SSM-U01 [www.aqara.com](https://www.aqara.com/en/product/single-switch-module-t1-with-neutral/) 2026-03-29 - Blakadder Device Entry — Aqara SSM-U01 [zigbee.blakadder.com](https://zigbee.blakadder.com/Aqara_SSM-U01.html) 2026-03-29 ## Documentazione correlata - [MQTT Integration](https://taphome.com/it/compatibility/mqtt-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/it/docs/integration/packet-parser/) - [Funzioni Packet parser](https://taphome.com/it/docs/script/packet-parser/) - [Funzioni di parsing](https://taphome.com/it/docs/script/parsing-functions/) - [Broker MQTT](https://taphome.com/it/docs/integration/packet-parser/mqtt-broker/) - [Script listener](https://taphome.com/it/docs/script/listener-scripts/)