TapHome

Aqara Door and Window Sensor

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

Richiede gateway esterno

tasmota zigbee2tasmota-gateway — pagina prodotto

Aqara Door and Window Sensor

Questo dispositivo comunica tramite Zigbee attraverso un gateway Tasmota. Assicurati di aver importato il template 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
ParametroDescrizioneEsempio
MQTT Broker IP AddressIP del tuo broker MQTT192.168.1.10
MQTT Broker PortPorta del broker (predefinita 1883)1883
Gateway nameTopic MQTT Tasmota (Configuration → MQTT → Topic)tasmota_XXXXX
Device IDIndirizzo breve Zigbee dall’accoppiamento0x1234

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:

AttributoDescrizione
IEEEAddrIdentificatore hardware univoco a 64 bit
ModelIdID modello Zigbee (lumi.sensor_magnet.aq2)
ManufacturerStringa del produttore segnalata dal dispositivo
EndpointsEndpoint Zigbee attivi
ConfigConfigurazione Zigbee del dispositivo
Link QualityIntensità 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).

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

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 Door and Window Sensor Modulo
Attributi di servizio
IEEEAddrIndirizzo IEEE Zigbee — identificatore hardware univoco a 64 bit del sensore
ModelId
Produttore
Endpoints
Config
Qualità del segnaleIntensità del segnale Zigbee — 0% (nessun segnale) a 100% (ottimo)
Tensione batteriaTensione della cella CR1632 in volt
Livello batteriaLivello 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

Aqara - Door and Window Sensor

Lettura (modulo)
MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", ID)
Listener
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
MQTTPUBLISH("cmnd/" + GWname+ "/ZbInfo", ID)
ModelId
Manufacturer
Endpoints
Config
Link Quality
Battery Voltage
BatteryVoltage + " V"
Battery Percentage
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

Sensore porta

Listener
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

Sensore finestra

Listener
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.

Fonti