--- title: "Aqara Door and Window Sensor" description: "Sensore di contatto Zigbee per porte e finestre via gateway Tasmota. Rileva apertura/chiusura, monitora la batteria con avvisi batteria scarica e offline." url: "https://taphome.com/it/compatibility/zigbee2tasmota-aqara-door-and-window-sensor/" language: it lastmod: 2026-03-29 generator: hugo ai: topics: ["mqtt","sensor","zigbee","zigbee2tasmota","battery-powered","security"] questions: ["Come integrare il sensore porta e finestra Aqara con TapHome?","Cosa rileva il template Aqara MCCGQ11LM in TapHome?","Come accoppiare il sensore porta Aqara con un gateway Zigbee2Tasmota?","Perché il mio sensore porta Aqara non segnala lo stato di contatto?","Il template del sensore porta Aqara monitora il livello batteria in TapHome?","Come un singolo template crea sia un sensore porta che un sensore finestra?"] --- # Aqara Door and Window Sensor Comunicazione: Packet Parser → MQTT - [Sensore porta e finestra Aqara](https://www.aqara.com/en/product/door-and-window-sensor) > 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 tramite **Zigbee** attraverso un gateway Tasmota. Assicurati di aver > importato il template [Zigbee2Tasmota Gateway](https://taphome.com/it/compatibility/zigbee2tasmota-gateway/) > e di aver accoppiato il dispositivo prima di procedere. L'Aqara Door and Window Sensor (MCCGQ11LM) è un sensore di contatto Zigbee compatto e alimentato a batteria. Rileva se una porta o finestra è aperta o chiusa tramite un contatto magnetico reed. TapHome comunica con il sensore via MQTT attraverso un gateway Zigbee2Tasmota — il sensore pubblica il suo stato di contatto nel payload JSON `ZbReceived` ad ogni cambio di stato. Questo template crea **due dispositivi** da un singolo sensore fisico: un **Sensore porta** e un **Sensore finestra**. Entrambi leggono lo stesso campo `Contact` dal messaggio Zigbee. L'utente può così assegnare un dispositivo come contatto porta e l'altro come contatto finestra in TapHome, oppure usare solo quello che corrisponde all'installazione reale. I dispositivi non utilizzati possono essere nascosti nelle impostazioni di TapHome. ## Configurazione ### Accoppiamento del sensore 1. In TapHome, attiva l'interruttore **Permit Join** nel modulo Zigbee2Tasmota Gateway 2. Sul sensore, tieni premuto il piccolo pulsante finché il LED blu inizia a lampeggiare, quindi rilascia 3. Attendi che il contatore **Devices Found** si incrementi — il Device ID del sensore (es. `0x1234`) appare negli attributi di servizio del gateway 4. Importa questo template dispositivo utilizzando il Device ID dall'accoppiamento ### Parametri di importazione | Parametro | Descrizione | Esempio | |-----------|-------------|---------| | **MQTT Broker IP Address** | IP del tuo 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 breve Zigbee dall'accoppiamento | `0x1234` | ## Funzionalità del dispositivo ### Rilevamento contatto porta e finestra Il template fornisce due dispositivi a contatto reed — **Sensore porta** e **Sensore finestra** — entrambi mappati come `PacketParserReedContact` con funzione di sicurezza. Ogni dispositivo analizza il campo `Contact` da `ZbReceived.{DeviceID}` nel messaggio MQTT SENSOR: - **Contact = true** → chiuso (porta/finestra chiusa) - **Contact = false** → aperto (porta/finestra aperta) Il sensore segnala lo stato di contatto istantaneamente ad ogni cambio, consentendo trigger di automazione in tempo reale (es. accendere le luci all'apertura della porta, inviare un avviso in caso di apertura finestra inaspettata). ### Monitoraggio batteria Il modulo monitora lo stato della batteria tramite due attributi di servizio: - **Battery Percentage** — livello di carica stimato; un **avviso batteria scarica** si attiva quando il livello scende sotto il 30% - **Battery Voltage** — tensione grezza della cella CR1632 in volt I dati della batteria vengono analizzati dai campi `BatteryPercentage` e `BatteryVoltage` nel payload `ZbReceived`. ### Rilevamento offline Il template monitora la disponibilità del dispositivo utilizzando il timestamp `LastSeenEpoch` dal polling `ZbInfo` (ogni ora): - **Avviso** — il dispositivo non è stato rilevato per più di **12 ore** - **Errore** — il dispositivo non è stato rilevato per più di **24 ore** Questo aiuta a individuare situazioni in cui il sensore ha perso la connettività Zigbee o la batteria è completamente scarica. ### Attributi di servizio diagnostici Il modulo espone ulteriori metadati Zigbee recuperati tramite il polling `ZbInfo`: | Attributo | Descrizione | |-----------|-------------| | **IEEEAddr** | Identificatore hardware univoco a 64 bit | | **ModelId** | ID modello Zigbee (`lumi.sensor_magnet.aq2`) | | **Manufacturer** | Stringa del produttore segnalata dal dispositivo | | **Endpoints** | Endpoint Zigbee attivi | | **Config** | Configurazione Zigbee del dispositivo | | **Link Quality** | Intensità del segnale scalata da 0–100% | ### Funzionalità aggiuntive L'Aqara MCCGQ11LM segnala anche la temperatura interna del dispositivo tramite Zigbee. La qualità del collegamento (LQI) per messaggio è disponibile in ogni payload SENSOR, ma attualmente è esposta solo a livello di modulo tramite il polling orario `ZbInfo`. Queste funzionalità potranno essere aggiunte in un futuro aggiornamento del template. ## Risoluzione dei problemi ### Il sensore non segnala lo stato di contatto 1. Verifica che il sensore sia accoppiato con il gateway Zigbee2Tasmota — controlla `ZbStatus` nella console Tasmota 2. Conferma che il **Device ID** nel template corrisponda all'indirizzo breve dall'accoppiamento (es. `0x1234`) 3. Apri e chiudi la porta/finestra per attivare un cambio di stato — il sensore pubblica solo al cambio, non continuamente 4. Usa un client MQTT (es. MQTT Explorer) per sottoscrivere il topic `tele/{GWname}/SENSOR` e verifica che il sensore pubblichi messaggi `ZbReceived` con il campo `Contact` ### Avviso offline nonostante sensore funzionante 1. Il rilevamento offline si basa sul polling `ZbInfo` (orario). Se il sensore non ha inviato messaggi entro 12 ore, appare un avviso 2. I dispositivi Zigbee alimentati a batteria dormono tra un evento e l'altro — è un comportamento normale. L'avviso si cancella generalmente dopo il successivo cambio di stato di contatto o polling `ZbInfo` 3. Se l'avviso persiste oltre le 24 ore, controlla la batteria (CR1632) e, se necessario, riaccoppia il dispositivo ### Sensore porta e sensore finestra mostrano lo stesso stato Questo è previsto — entrambi i dispositivi leggono il campo `Contact` dello stesso sensore fisico. Nascondi il dispositivo non utilizzato in TapHome (**Settings** → **Devices** → seleziona il dispositivo → **Hide**). > [!WARNING] > L'Aqara MCCGQ11LM utilizza una batteria a bottone CR1632. La durata della batteria è tipicamente di 2+ anni in condizioni di utilizzo normale. Cambi di stato frequenti (es. porte ad alto traffico) o segnale Zigbee debole (che richiede ritrasmissioni di messaggi) possono ridurre la durata della batteria. ## 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 2 Questi dispositivi compaiono in TapHome dopo l'importazione. Aqara Door and Window Sensor Modulo Attributi di servizio | | | |---------------------|------------------------------------------------------------------------------| | IEEEAddr | Indirizzo IEEE Zigbee — identificatore hardware univoco a 64 bit del sensore | | ModelId | | | Produttore | | | Endpoints | | | Config | | | Qualità del segnale | Intensità del segnale Zigbee — 0% (nessun segnale) a 100% (ottimo) | | Tensione batteria | Tensione della cella CR1632 in volt | | Livello batteria | Livello batteria stimato — avviso sotto il 30% | Variabili personalizzate `GWname` (string) Nome del topic MQTT Tasmota del gateway Zigbee (in Configuration → MQTT → Topic) `ID` (string) Indirizzo breve Zigbee del sensore (assegnato durante l'accoppiamento) After pairing the sensor via Permit Join, find the device short address in the gateway's Devices Found service attribute or via Tasmota console command ZbStatus Lettura (modulo) ```taphome MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", ID) ``` Listener ```taphome if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0 var ZbReceived := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID, true); var bat := PARSEJSON(ZbReceived, "BatteryPercentage", true); if(!ISNULL(bat), BatteryPercentage := bat); var volt := PARSEJSON(ZbReceived, "BatteryVoltage", true); if(!ISNULL(volt), BatteryVoltage := volt); var deviceInfo := PARSEJSON(RECEIVEDMSG.Payload, "ZbInfo." + ID, true); if !ISNULL(deviceInfo) LastSeenEpoch := PARSEJSON(deviceInfo, "LastSeenEpoch"); 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")); COMPLETESERVICEATTRIBUTE("Link Quality", ROUND(LINEAR(PARSEJSON(deviceInfo, "LinkQuality"), 0,0, 254, 100)) + "%"); end end if BatteryPercentage < 30 ADDWARNING("Low battery (<30%)"); end if !ISNAN(LastSeenEpoch) DATETIME now := NOW(); var secondsSeen := now.UNIXTIME - LastSeenEpoch; if secondsSeen > 12 * 60 * 60 if secondsSeen > 24 * 60 * 60 ADDERROR("Device is offline > 24H"); else ADDWARNING("Device is offline > 12H"); end end end ``` Attributi di servizio IEEEAddr ```taphome MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", ID) ``` ModelId ``` ``` Manufacturer ``` ``` Endpoints ``` ``` Config ``` ``` Link Quality ``` ``` Battery Voltage ```taphome BatteryVoltage + " V" ``` Battery Percentage ```taphome BatteryPercentage + "%" ``` Sensore porta Contatto reed Solo lettura Contatto reed per il rilevamento apertura/chiusura porta — legge il campo Contact dal messaggio del sensore Zigbee boolean Listener ```taphome if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0 var val := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID + ".Contact", true); if(!ISNULL(val), Rc := val); end ``` Sensore finestra Contatto reed Solo lettura Contatto reed per il rilevamento apertura/chiusura finestra — legge il campo Contact dal messaggio del sensore Zigbee boolean Listener ```taphome if INDEXOF(RECEIVEDMSG.Topic, "SENSOR") > 0 var val := PARSEJSON(RECEIVEDMSG.Payload, "ZbReceived." + ID + ".Contact", true); if(!ISNULL(val), Rc := val); end ``` **Connessione:** Packet Parser → MQTT Possibili miglioramenti (3) - Device Temperature — Blakadder lists device temperature measurement as an exposed feature. The Aqara MCCGQ11LM reports internal temperature via Zigbee, but the TapHome template does not parse it. - Link Quality (device-level) — LinkQuality is available per SENSOR message but only exposed as a module-level service attribute via ZbInfo polling. - Sensor Calibration — Some Zigbee platforms support per-sensor calibration offsets. Not configurable in TapHome 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 - Blakadder Device Entry — Aqara MCCGQ11LM [zigbee.blakadder.com](https://zigbee.blakadder.com/Aqara_MCCGQ11LM.html) 2026-03-29 - Aqara Product Page — Door and Window Sensor [www.aqara.com](https://www.aqara.com/en/product/door-and-window-sensor) 2026-03-29 - Aqara MCCGQ11LM — Product Specifications Datasheet [cdn-reichelt.de](https://cdn-reichelt.de/documents/datenblatt/R800/AQARA_MCCGQ11LM_DB-EN.pdf) 2026-03-29 I documenti del produttore sono © dei rispettivi proprietari. Sono forniti così come pubblicati dal produttore, solo a titolo informativo. ## 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/)