Aqara Motion Sensor T1 (RTCGQ12LM): Zigbee2MQTT Setup

Affiliate disclosure: This post may contain affiliate links. If you purchase through them I earn a small commission at no extra cost to you.

The RTCGQ12LM is Aqara’s wall-mount Motion and Illuminance Sensor T1: a 170-degree horizontal detection angle, up to 7m range, a built-in lux sensor, and Zigbee 3.0 on the radio. It pairs directly to a Zigbee2MQTT coordinator without needing an Aqara hub, and once it’s paired there is zero ongoing cloud dependency. That combination of wide-angle coverage, ambient light sensing, and hub-free operation is what makes this sensor worth covering separately from the newer P1 (RTCGQ14LM) or the ceiling-mount high-precision variant (RTCGQ13LM).

This guide covers pairing, every entity Z2M exposes, the detection interval and occupancy timeout behavior that trips up most people, how to use the lux sensor in conditional automations, and the ZHA path for those not running Zigbee2MQTT.

If you’re new to running Aqara hardware fully offline, our guide on whether Aqara works without internet covers the broader picture.

What Home Assistant Sees After Pairing

Zigbee2MQTT exposes seven entities for the RTCGQ12LM. Here’s what each one does:

(Z2M also publishes a linkquality value for every device, so you’ll see that alongside the seven above.)

The lux and occupancy pairing is the main reason to choose this sensor over a motion-only device. A motion sensor that also knows whether the room is bright enough avoids the common annoyance of lights switching on at noon when the sun is already doing the job.

One thing to clarify upfront: device_temperature is the chip temperature, not ambient room temperature. I’ve seen people try to build thermostats off it. Don’t. If you want temperature readings, use a dedicated temperature sensor.

Pairing to Zigbee2MQTT

Prerequisites

You need a Zigbee coordinator (any ConBee, HUSBZB-1, or Sonoff Zigbee Dongle-E running Zigbee2MQTT), and Z2M running and reachable. The sensor itself takes a single CR2450 button cell. If you’re starting from a used unit, do a factory reset first: hold the reset button for 5 seconds until the LED flashes three times.

The Pairing Procedure

1. Open the Zigbee2MQTT dashboard and enable join mode (the “Permit join” toggle, or the equivalent MQTT publish to zigbee2mqtt/bridge/request/permit_join).
2. On the sensor, press the reset button once. It should flash and begin advertising.
3. Keep pressing the reset button every second until Z2M confirms a successful join.

That third step is where most pairing failures happen. The RTCGQ12LM, like most Aqara sensors, aggressively enters sleep mode between presses to conserve battery. If you press once and then wait, the device is likely asleep before Z2M has finished the handshake. Pressing repeatedly keeps it awake long enough for Z2M to complete the join. Once you see the device appear in the Z2M device list with model RTCGQ12LM, you can stop pressing.

Z2M will log something like Device 'RTCGQ12LM' joined in its output. At that point the device is fully paired, all seven entities will appear in Home Assistant within a few seconds, and you’re done with cloud dependencies permanently.

Battery Percentage After Pairing

Expect the battery entity to show a stale or zero value for up to 24 hours after pairing. This is normal: the sensor reports battery percentage infrequently. If you want an immediate sanity check that the battery is good, look at the voltage entity instead. A fresh CR2450 typically reads 2900–3000 mV; below 2500 mV the sensor will start behaving erratically.

Configuring the Detection Interval

This is the section that generates the most confusion, so I’ll spell it out clearly.

The detection_interval setting controls how long the sensor waits, after detecting motion, before it’s willing to report motion again. The occupancy timeout (the time until occupancy flips back to false) is detection_interval + 2 seconds.

So with the default 60-second detection interval:
– Motion detected → occupancy: true
– 62 seconds of no further motion → occupancy: false

With a 5-second detection interval:
– Motion detected → occupancy: true
– 7 seconds of no further motion → occupancy: false

This is intentional design, not a bug. The detection interval prevents the sensor from hammering the Zigbee mesh with repeated motion reports every time someone walks through a room. The side effect is that it directly sets your occupancy hold time.

What Range You Can Actually Set

The Aqara app exposes a detection period range of roughly 1–200 seconds. Through Zigbee2MQTT, the detection_interval property accepts a minimum of 2 seconds and a maximum of 65535 seconds. In practice you’ll never want anything close to the upper bound, but it’s worth knowing the real limit if you’re scripting the configuration and expecting the app’s tighter numbers to apply.

Setting the Detection Interval

You can adjust it from the Z2M frontend: open the device, go to the “Exposes” tab, and use the number input next to detection_interval. Or publish directly via MQTT:

Topic: zigbee2mqtt/[friendly_name]/set
Payload: {"detection_interval": 30}

Three configurations I use depending on context:

• Fast-reset mode (5s): detection_interval: 5 gives a 7-second occupancy window — tight enough to register brief activity without holding a stale occupancy state. Useful where you want fast resets.
• General motion (30s): detection_interval: 30 gives a 32-second hold. Good for hallways or stairwells where occupancy-based lighting can reset relatively quickly.
• Occupancy-based lighting (60s): The default. A 62-second hold is long enough that lights don’t flicker off while someone is reading quietly in a chair.

Using Illuminance in Automations

Lux is a measure of ambient light intensity. 1 lux is roughly candlelight, 400 lux is a well-lit office, and 10,000+ lux is direct sunlight. For automation purposes, 50 lux is a reasonable threshold between “dark enough to need a light” and “bright enough not to bother.”

The T1’s illuminance entity updates each time the sensor detects motion, which makes it practical for conditional automations without needing a separate ambient light sensor.

Example: Trigger Lights Only in Low-Light Conditions

alias: "Motion light - low light only"
description: "Turn on light when motion detected and room is dim"
trigger:
  - platform: state
    entity_id: binary_sensor.rtcgq12lm_occupancy
    to: "on"
condition:
  - condition: numeric_state
    entity_id: sensor.rtcgq12lm_illuminance
    below: 50
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room
mode: single

The condition block checks the lux value at the moment occupancy triggers. If the room is already bright — daytime with natural light, for instance — the automation skips the action entirely. This is cleaner than a time-of-day check because it responds to actual light conditions rather than a fixed schedule.

Calibration

If the lux readings seem consistently off, Zigbee2MQTT exposes a calibration offset for the illuminance entity. You can set it via MQTT:

Topic: zigbee2mqtt/[friendly_name]/set
Payload: {"illuminance_calibration": 10}

I’d recommend using a reference device — a phone light meter app, or a dedicated lux meter — to establish whether the readings are reasonable before deciding you need calibration. The sensor isn’t lab-grade, but for automation thresholds it’s usually close enough without adjustment.

The ZHA Path

If you’re running ZHA (Zigbee Home Automation) rather than Zigbee2MQTT, the RTCGQ12LM works without custom quirks. Pairing is the same keep-alive technique described above.

What you lose on ZHA is easy access to the detection_interval configuration. ZHA may not surface it in the standard device card UI, which means adjusting the occupancy timeout requires either developer tools or direct Zigbee attribute writes, neither of which is convenient. For full feature access, including the detection interval configuration and calibration offsets, Z2M is the better path for this sensor.

If you’re already running ZHA and don’t want to migrate, the sensor will function correctly for basic occupancy and lux detection. You’ll just be stuck with the 60-second default occupancy timeout unless you’re comfortable with lower-level Zigbee attribute writes.

Choosing Between T1, P1, and the High-Precision Variant

If you’re deciding which Aqara motion sensor to buy:

• T1 (RTCGQ12LM, this guide): Wall-mount, 170-degree wide angle, built-in lux sensor. Best for wide-coverage rooms where you want a single sensor covering the whole space, and where you want lux-conditional automations.

• P1 (RTCGQ14LM): Later model with adjustable sensitivity levels. Slightly different feature set and different entity layout in Z2M. No lux sensor. We have a separate full local-setup walkthrough for the P1 if you’re weighing it against the T1.

• High Precision (RTCGQ13LM, Zigbee ID lumi.motion.agl001): Ceiling-mount, narrower detection angle. No lux sensor. Better for doorways or confined spaces where you want directional detection.

• FP1E (RTCZCGQ13LM): If you need presence detection rather than motion detection, the FP1E stays true while someone is stationary in the room, not just when they’re moving. It’s a different device class entirely, and we cover its local setup in its own dedicated guide.

The T1 is a Zigbee router, which means it extends your Zigbee mesh as well as sensing. End-device sensors (like the P1) don’t relay traffic — something worth knowing if you’re placing sensors in areas where mesh coverage is thin.

OTA Updates and Maintenance

Zigbee2MQTT handles OTA updates for the RTCGQ12LM. Trigger a check from the device card in the Z2M frontend, or publish to zigbee2mqtt/bridge/request/device/ota_update/check with the device’s IEEE address. If a firmware update is available, Z2M will handle the download and install.

To replace the battery, remove the sensor from its mount (it clips off the wall bracket), then open the case with a fingernail or thin pry tool at the seam. The CR2450 is in a standard holder: remove and replace, reassemble, and the sensor will re-join the network automatically. No re-pairing needed.

The power_outage_count entity is a lightweight diagnostic. If you see it incrementing and you’re not cutting power intentionally, it may point to a loose battery connection or an intermittent power issue in your setup.

Privacy and Local Operation

Once the RTCGQ12LM is paired to Zigbee2MQTT, it operates entirely on your local network. There are no Aqara servers involved.

You can verify this by watching your firewall logs (or running a quick tcpdump on the coordinator’s host) after pairing. You should see Zigbee traffic going to your coordinator and MQTT traffic staying on your LAN, and nothing outbound to Aqara’s endpoints. The only time you’d see outbound traffic is if you explicitly trigger an OTA update, which requires Z2M to fetch firmware from the Zigbee Alliance OTA server.

If you’re putting your IoT devices on a VLAN and only allowing the minimum necessary outbound traffic, a paired RTCGQ12LM needs the Zigbee radio link to your coordinator and MQTT on your local network. No DNS lookups for Aqara domains, no periodic phone-home. The sensor is genuinely offline from the vendor’s perspective once it leaves the pairing window. For the wider context on running Aqara gear this way, see our guide on whether Aqara works without internet, linked above.

For anyone setting up this sensor as part of a broader Aqara Zigbee stack without a hub, this is the same zero-cloud posture you get across the rest of the local Z2M Zigbee device lineup.