--- title: "Aqara Sensore di Movimento (RTCGQ11LM)" description: "Sensore PIR Zigbee Aqara RTCGQ11LM via Zigbee2MQTT e PacketParser MQTT. Movimento, batteria, tensione e qualità del collegamento in TapHome." url: "https://taphome.com/it/compatibility/zigbee2mqtt-xiaomi-rtcgq11lm/" language: it lastmod: 2026-04-24 generator: hugo ai: topics: ["mqtt","sensor","zigbee","zigbee2mqtt","battery-powered","motion-detection"] questions: ["Come integrare il sensore di movimento Aqara RTCGQ11LM in TapHome tramite Zigbee2MQTT?","Cosa segnala il template RTCGQ11LM in TapHome?","Come impostare il friendly name Zigbee2MQTT o l'indirizzo IEEE del RTCGQ11LM in TapHome?","Perché il mio RTCGQ11LM mantiene il movimento attivo per 60 secondi dopo una singola rilevazione?","Il template RTCGQ11LM segnala lo stato batteria e la qualità del collegamento?","Perché il mio RTCGQ11LM si disconnette a volte da Zigbee2MQTT?"] --- # Aqara Sensore di Movimento (RTCGQ11LM) Comunicazione: Packet Parser → MQTT - [Zigbee2MQTT — pagina del dispositivo RTCGQ11LM](https://www.zigbee2mqtt.io/devices/RTCGQ11LM.html) > 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 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: | Variabile | Descrizione | Come ottenerla | Esempio | |-----------|-------------|----------------|---------| | `XiaomiRTCGQ11LM` | friendly name Zigbee2MQTT o indirizzo IEEE di questo RTCGQ11LM | Zigbee2MQTT web UI → Devices → trova RTCGQ11LM → copia IEEE o friendly name | `0x00158d00036cd3e2` | 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. > [!TIP] > 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 Zigbee2MQTT | Valore TapHome | |---------------------|----------------| | `"occupancy": true` | 1 (movimento) | | `"occupancy": false` | 0 (fermo) | | altro / mancante | NaN | 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. > [!IMPORTANT] > 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). > [!WARNING] > 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 > [!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 Motion Sensor (RTCGQ11LM) Modulo Variabili personalizzate | | | |-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `XiaomiRTCGQ11LM` (string) = 0x00158d00036cd3e2 | Friendly 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 | | | |-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Batteria | Percentuale 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. | | Tensione | Tensione grezza della batteria in millivolt (~3000 mV su una CR2450 nuova). Indicatore di batteria scarica più preciso della percentuale. | | LinkQuality | Indicatore della qualità del collegamento Zigbee (0–255 LQI). Valori sotto 20 indicano in genere un collegamento inaffidabile e disconnessioni frequenti. | Lettura (modulo) ```taphome # 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 ```taphome 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 ```taphome IF(ISNAN(battery),"-",battery+"%"); ``` Voltage ```taphome IF(ISNAN(voltage),"-",voltage+"mV"); ``` LinkQuality ```taphome 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. ## 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` | ## Fonti - Aqara RTCGQ11LM — Zigbee2MQTT device page [www.zigbee2mqtt.io](https://www.zigbee2mqtt.io/devices/RTCGQ11LM.html) 2026-04-24 - Aqara Motion Sensor — official product specs [www.aqara.com](https://www.aqara.com/en/product/human-motion-sensor/specs/) 2026-04-24 - Aqara Motion Sensor — user manual [www.aqara.com](https://www.aqara.com/en/product/human-motion-sensor/) 2026-04-24 ## 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/)