TapHome

Aqara Sensore di Movimento (RTCGQ11LM)

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

Richiede gateway esterno

Zigbee2MQTT Zigbee2MQTT bridge (any supported Zigbee coordinator — e.g. Sonoff ZBDongle-E/P, CC2652, ConBee II) — pagina prodotto

Aqara Sensore di Movimento (RTCGQ11LM)

L’Aqara RTCGQ11LM (venduto in alcuni mercati come Xiaomi Mi Motion Sensor) è un sensore PIR di occupazione Zigbee 3.0 compatto e a batteria, alimentato da una pila a bottone CR2450. Comunica con TapHome in modo indiretto — il sensore si abbina a un coordinatore Zigbee2MQTT (es. Sonoff ZBDongle-P/E o uno stick basato su CC2652), che traduce i messaggi Zigbee in topic MQTT. TapHome si iscrive a tali topic tramite un modulo PacketParser MQTT.

Il template mappa il sensore come ingresso di occupazione binario (movimento / nessun movimento) ed espone percentuale batteria, tensione grezza della batteria e qualità del collegamento Zigbee come attributi di servizio.

Configurazione

Configurazione Zigbee2MQTT

Prima di importare il template in TapHome, il RTCGQ11LM deve essere abbinato a un coordinatore Zigbee2MQTT:

  1. Aprire la UI web di Zigbee2MQTT e abilitare la modalità di abbinamento (Permit join)
  2. Sul RTCGQ11LM tenere premuto il pulsante di reset per circa 5 secondi, finché il LED blu non inizia a lampeggiare
  3. Il dispositivo apparirà nell’elenco dei dispositivi Zigbee2MQTT con un indirizzo IEEE (es. 0x00158d00036cd3e2). Opzionalmente assegnargli un friendly name nelle impostazioni del dispositivo in Zigbee2MQTT.

Se l’abbinamento non riesce, provare una singola pressione breve al posto della pressione lunga. Sui coordinatori basati su CC2531 di solito aiuta rimuovere e reinserire la chiavetta USB prima di riavviare Zigbee2MQTT.

Variabile del modulo

Dopo aver importato il template in TapHome, impostare la variabile personalizzata XiaomiRTCGQ11LM per identificare il dispositivo sul broker MQTT:

VariabileDescrizioneCome ottenerlaEsempio
XiaomiRTCGQ11LMfriendly name Zigbee2MQTT o indirizzo IEEE di questo RTCGQ11LMZigbee2MQTT web UI → Devices → trova RTCGQ11LM → copia IEEE o friendly name0x00158d00036cd3e2

Il segnaposto predefinito nel template (0x00158d00036cd3e2) è solo un esempio e deve essere sostituito con l’indirizzo reale del sensore. Lo script listener si iscrive a zigbee2mqtt/{XiaomiRTCGQ11LM} e analizza il payload JSON dello stato.

L’uso di un friendly name (es. corridoio_movimento) al posto dell’indirizzo IEEE grezzo rende la configurazione più leggibile e resta stabile anche se il sensore viene riabbinato.

Capacità del dispositivo

Rilevamento del movimento

Il template mappa il sensore come dispositivo Reed Contact in TapHome. La denominazione “reed contact” è solo una convenzione del template; il comportamento è un normale ingresso PIR di occupazione. Gli eventi di movimento arrivano sul topic zigbee2mqtt/{id} in formato JSON e vengono mappati su uno stato numerico:

Payload Zigbee2MQTTValore TapHome
"occupancy": true1 (movimento)
"occupancy": false0 (fermo)
altro / mancanteNaN

Il primo messaggio occupancy: true viene pubblicato solo al primo evento di movimento dopo l’ingresso in rete del dispositivo — non al termine dell’abbinamento.

L’hardware del RTCGQ11LM impone una zona morta di 60 secondi dopo ogni rilevamento: una volta segnalato il movimento, il sensore ignora ulteriori movimenti per 60 secondi. L’opzione occupancy_timeout di Zigbee2MQTT va quindi lasciata sul valore predefinito di 90 s (o superiore) — valori inferiori a 60 s genererebbero un messaggio occupancy: false mentre la persona è ancora presente. Questo limite non può essere aggirato senza una modifica hardware.

Batteria, tensione e qualità del collegamento

L’istanza del sensore espone tre attributi di servizio in sola lettura, estratti dallo stesso messaggio JSON di stato:

  • Battery — percentuale residua della batteria (0–100 %), formattata come "N%". Il primo valore può essere segnalato anche dopo 24 ore dall’abbinamento. Finché non arriva il primo messaggio viene mostrato "-".
  • Voltage — tensione grezza della batteria in millivolt (tipicamente ~3000 mV su una CR2450 nuova), formattata come "N mV". Utile come indicatore indipendente di batteria debole — la percentuale può sembrare ancora sana mentre la cella è già troppo debole per trasmissioni Zigbee affidabili.
  • LinkQuality — indicatore della qualità del collegamento Zigbee (0–255 LQI), formattato come "N lqi". Valori sotto 20 indicano in genere un collegamento inaffidabile.
Capacità attualmente non mappate

Il RTCGQ11LM pubblica via Zigbee2MQTT anche le seguenti entità che il template non analizza — possono essere aggiunte estendendo lo script listener in una futura revisione del template:

  • illuminance / illuminance_lux — livello di luce ambientale in lux (utile per automazioni di movimento filtrate dalla luce)
  • device_temperature — temperatura interna del chip in °C (solo diagnostica, non la temperatura ambiente)
  • power_outage_count — contatore di eventi di rimozione batteria

Il topic di disponibilità di Zigbee2MQTT (zigbee2mqtt/{id}/availability) e l’opzione di configurazione occupancy_timeout (zigbee2mqtt/bridge/request/device/options) non sono gestiti dal template; come indicatore di vitalità per questo dispositivo in modalità sleep si consigliano LinkQuality e Battery.

Risoluzione dei problemi

Il sensore non segnala alcuno stato
  1. Verificare che il RTCGQ11LM appaia nell’elenco dei dispositivi Zigbee2MQTT con stato verde.
  2. Controllare che la variabile XiaomiRTCGQ11LM corrisponda esattamente al friendly name o all’indirizzo IEEE — per i friendly name conta maiuscole/minuscole.
  3. Attivare il movimento davanti al sensore. Il primo messaggio di stato viene pubblicato solo al primo rilevamento dopo l’ingresso in rete.
  4. Con un client MQTT (es. MQTT Explorer) iscriversi a zigbee2mqtt/# e verificare che al movimento arrivino messaggi sul topic zigbee2mqtt/{tuo_nome}.
Il movimento rimane attivo a lungo dopo l’uscita dalla stanza

È la zona morta hardware di 60 secondi attesa combinata con occupancy_timeout di Zigbee2MQTT (predefinito 90 s). Il sensore non segnala occupancy: false finché il timer non scade senza ulteriori movimenti. Timeout più brevi non sono affidabili — il sensore ignora semplicemente ogni movimento nei primi 60 s dopo il rilevamento.

Disconnessioni casuali

Cause comuni della caduta di dispositivi finali Aqara/Xiaomi dalla rete Zigbee:

  1. Segnale debole — controllare LinkQuality; valori sotto 20 di solito significano che al sensore serve un router Zigbee alimentato a rete più vicino.
  2. Bassa tensione della batteria — l’attributo Voltage è un indicatore migliore della percentuale. Zigbee2MQTT segnala espressamente che il sensore può uscire dalla rete anche quando la percentuale appare ancora sana: osservate quindi un calo evidente rispetto ai ~3000 mV di una cella nuova e sostituite la CR2450 non appena il collegamento diventa inaffidabile.
  3. Router incompatibili — router di Centralite, General Electric, Iris, Ledvance, Legrand, OSRAM, Sylvania, SmartThings e Securifi sono noti per “buttare fuori” dal mesh i vecchi dispositivi Xiaomi/Aqara. Spesso aiuta abbinare il sensore direttamente al coordinatore (reset del sensore tenendolo vicino al coordinatore).

I dispositivi finali Aqara Zigbee non supportano il ping standard in modalità availability di Zigbee2MQTT e possono apparire erroneamente offline anche funzionando correttamente. Non affidarsi al topic di availability per la vitalità — usare LinkQuality e Battery come indicatori di stato.

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 Motion Sensor (RTCGQ11LM) Modulo
Variabili personalizzate
XiaomiRTCGQ11LM (string) = 0x00158d00036cd3e2Friendly name Zigbee2MQTT o indirizzo IEEE (0x… 16-hex) di questo RTCGQ11LM — usato come suffisso del topic MQTT zigbee2mqtt/{this}. Il segnaposto predefinito deve essere sostituito con l'indirizzo reale del sensore dopo l'abbinamento.
Sensore di movimento Contatto reed Solo lettura

Rilevamento PIR di occupazione — segnala movimento (1) al rilevamento, fermo (0) dopo lo scadere della zona morta hardware di 60 s e del occupancy_timeout di Zigbee2MQTT.

boolean JSON (PARSEJSON on occupancy key)
Attributi di servizio
BatteriaPercentuale residua della batteria (pila a bottone CR2450, 0–100 %). Formattata come 'N%'; il primo valore dopo l'abbinamento può essere segnalato anche dopo 24 ore.
TensioneTensione grezza della batteria in millivolt (~3000 mV su una CR2450 nuova). Indicatore di batteria scarica più preciso della percentuale.
LinkQualityIndicatore della qualità del collegamento Zigbee (0–255 LQI). Valori sotto 20 indicano in genere un collegamento inaffidabile e disconnessioni frequenti.

Sensore di movimento

Lettura (modulo)
# Simple HTTP Request:
# VAR response := SENDHTTPREQUEST("/example/getValue");
# IF response.IsSuccess
#  VAR content := response.Content;
#  VAR responseHeaders := response.Headers;
#  RETURN(PARSEXML(content, "//element1/value1"));
# ELSE
#  ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
#  RETURN(NaN);
# END
#
# Set Http request method, body and headers
# VAR response := SENDHTTPREQUEST("/example/getValue", "GET", "some data", "header1:value1", "header2:value2", ...);
# OR
# VAR request := HTTPREQUEST("/example/getValue", "POST", "some data");
# request.headers := { "header1:value1", "header2:value2", ...};
# request.method := "GET";
# request.data := null;
# VAR response := SENDHTTPREQUEST(request);
#
#
# Send TCP, UDP data:
# VAR data1 := BYTECOLLECTION("0a bb ea df 01");
# SENDDATA(data1);
# VAR data2 := "{\"name\":\"John\", \"age\":32}";
# SENDDATA(data2);
# VAR data3 := TOBYTES("{\"name\":\"John\", \"age\":32}", "iso-8859-1");
# SENDDATA(data3);
# Process received TCP or UDP data and set device values in the Listener script
#
#
# Download data from FTP:
# FTPDOWNLOAD("filePath");
Listener
IF (COMPARE(RECEIVEDMSG.TOPIC, "zigbee2mqtt/"+ XiaomiRTCGQ11LM, CompareOptions.IgnoreCase) = 0)
    VAR value := TOSTRING(PARSEJSON(RECEIVEDMSG.PAYLOAD, "occupancy")); 
    IF (COMPARE(value, "true", CompareOptions.IgnoreCase) = 0)
        Rc := 1; 
    ELSEIF (COMPARE(value, "false", CompareOptions.IgnoreCase) = 0)
        Rc := 0;
    ELSE
        Rc := NaN;
    END   
    battery := PARSEJSON(RECEIVEDMSG.PAYLOAD,"battery", true);
    voltage := PARSEJSON(RECEIVEDMSG.PAYLOAD,"voltage", true);
    link := PARSEJSON(RECEIVEDMSG.PAYLOAD,"linkquality", true);
END;
Attributi di servizio
Battery
IF(ISNAN(battery),"-",battery+"%");
Voltage
IF(ISNAN(voltage),"-",voltage+"mV");
LinkQuality
IF(ISNAN(link),"-",link+"lqi");
Connessione: Packet Parser → MQTT
Possibili miglioramenti (5)
  • Illuminance — illuminance / illuminance_lux JSON key (unit lx, 0+). Ambient light level reported alongside occupancy. Could drive lux-gated motion automations (e.g. only switch lights below 50 lx). Not parsed by the current listener script — would require an additional PARSEJSON call plus a service_attribute entry.
  • Device Temperature — device_temperature JSON key (unit °C). Internal chip temperature — not ambient room temperature. Useful for diagnostic alerts (overheating, direct sunlight on the sensor) but not for climate control. Not parsed by the current listener script.
  • Power Outage Count — power_outage_count JSON key (integer). Increments when the battery is removed/reinserted or the device loses power. Could detect tampering or battery swaps. Not parsed by the current listener script.
  • Availability (LWT) — online / offline string payload published by Z2M if availability is enabled globally or per device (availability: true in configuration.yaml). Could detect dropped sensors. Not subscribed by the current template.
  • Occupancy Timeout Configuration — occupancy_timeout (seconds, minimum 60, default 90) controls how long after motion the sensor waits before reporting occupancy: false. Currently set via Z2M frontend / configuration.yaml — TapHome template does not expose this as a setting and does not publish to bridge/request topics.

Fonti

Hai trovato un problema con questo template?

Dicci cosa non funziona, cosa manca o come dovrebbe comportarsi il template. Il tuo feedback ci aiuta a mantenere il catalogo accurato.

Verificato da TapHome

Vuoi usarlo nel tuo TapHome Core?

Apri questo template nel Customer Portal per applicarlo a una delle tue case, o crea una proposta di modifica e inviala al catalogo.

Apri nel portale