Aqara Smoke Detector JY-GZ-01AQ: Zigbee2MQTT + HA Guide

Safety note — read first. A smoke detector protects you through its own onboard alarm: the built-in buzzer and sensor work independently of Home Assistant, your network, and your Zigbee coordinator. That local buzzer is the safety mechanism. The Home Assistant integration described here adds remote notifications and automation on top of that — it is supplementary, not a substitute. Do not rely on an HA automation as your primary smoke warning. Home Assistant, your coordinator, MQTT, or Wi-Fi can all fail without the detector itself failing, and at least one known bug (covered below) leaves the buzzer sounding while HA shows no alarm. Mount the detector per the manufacturer’s placement guidance and local fire codes, and keep its onboard alarm functional regardless of what HA does.

I want to get the most important thing out of the way first: there is a known firmware regression in this device that causes the buzzer to sound once and then auto-mute when smoke is detected. That is not the behavior you want from a smoke detector. Firmware version 21 was pulled from the Zigbee2MQTT OTA repository because of it, but if your unit shipped with it or updated before the pull, you need to know about this before you deploy it.

I’ll cover the workaround and the full setup walkthrough. For most people running a stable coordinator (not ConBee III before firmware v26550900), this detector pairs cleanly, exposes a solid set of entities in Home Assistant, and gives you genuinely local smoke detection. But the known-issues section of this article matters more than it does for a motion sensor or a door contact. Read it before you rely on this device.

If you’re building out a hub-free Aqara setup more broadly, our guide to running Aqara Zigbee devices in Home Assistant without the Aqara Hub covers the coordinator and Zigbee2MQTT groundwork this article assumes.

What the JY-GZ-01AQ is

The JY-GZ-01AQ (Zigbee ID: lumi.sensor_smoke.acn03) is Aqara’s current Zigbee 3.0 smoke detector. It runs on a CR17450 non-rechargeable battery, supports OTA firmware updates via Zigbee2MQTT, and pairs with any standard Zigbee coordinator. It’s sold under the “Aqara Smart Smoke Detector” branding in most markets.

What you won’t find in the marketing: it’s a Zigbee device, so it never needs to talk to the Aqara cloud during normal operation. Once paired to Z2M, all alarm events, battery reports, and configuration happen locally. The Aqara Home app and Aqara Hub are completely optional.

What you need before you start

• Zigbee2MQTT running and paired with a working coordinator
• Home Assistant with the MQTT integration configured
• The JY-GZ-01AQ detector

ConBee III users: If your ConBee III adapter is running firmware older than v26550900, stop here. There’s a confirmed incompatibility (Z2M GitHub issue #29880) where the adapter silently drops state updates from this detector, including alarm reports. The smoke entity stays false even during an active alarm. Update your ConBee III firmware first, or use a different coordinator for this device. I’ll cover this more in the Known Issues section.

ZHA users: ZHA support is broken for this device. I’ll explain what happens in the ZHA section below, but the short version is: don’t pair this to ZHA and expect it to alert you. Zigbee2MQTT is the only reliable local path.

Pairing the detector

Put your coordinator into pairing mode in the Z2M frontend. Press the button on the detector three times rapidly to trigger pairing mode. The LED should blink while it’s searching.

If it fails to join after two or three attempts, check the battery. Low battery prevents pairing reliably on this model, so a fresh CR17450 is worth trying before you spend time debugging coordinator settings. The battery compartment is on the back; pry the cover off with a fingernail at the notch.

Once paired, the device shows up in the Z2M frontend as lumi.sensor_smoke.acn03. Rename it to something useful (like smoke_detector_kitchen) and let Home Assistant pick up the MQTT discovery within a minute.

Entities in Home Assistant

The JY-GZ-01AQ exposes 13 entities via Z2M. Here’s what each one does and which ones you’ll actually use.

The ones that matter for safety:

• smoke (binary sensor) — true when smoke is detected. This is your primary alert entity for automations.
• smoke_density (numeric) — raw density reading.
• smoke_density_dbm (numeric) — density in dB/m, which is the measurement unit standard photoelectric smoke detectors use.
• battery (numeric, %) — battery percentage. Set an alert at 20% — this battery isn’t rechargeable and can go fast.
• voltage (numeric, mV) — raw battery voltage if you want more precision than percentage.

Control entities:

• selftest (button) — triggers a self-test from HA. The buzzer fires and the LED blinks. Use this to confirm the device is alive without setting off a real alarm.
• buzzer (select) — during an active alarm, you can publish mute here to silence the buzzer for 80 seconds. If smoke is still present after 80 seconds, it resumes. You cannot permanently disable the buzzer while smoke is present, which is correct behavior.
• buzzer_manual_alarm and buzzer_manual_mute (binary) — state representations of the buzzer control, useful for dashboards.

Diagnostic and linking entities:

• test (binary) — reflects whether a self-test is currently in progress.
• heartbeat_indicator (binary) — blinks periodically to confirm the device is alive and maintaining mesh connectivity. If this goes quiet for more than a day, check availability — it usually means the device has dropped off the mesh.
• linkage_alarm (toggle) — enables or disables the linkage alarm behavior. See the Linkage Alarm section below.
• linkage_alarm_state (binary) — reflects current linkage alarm state.
• power_outage_count (numeric) — counts how many times the device has lost and regained power, which is useful for detecting battery swaps or unexpected disconnections.

Running a self-test from Home Assistant

The selftest entity is a button entity in HA. Press it (or call the button.press service on it) and the detector runs through its test cycle: buzzer sounds, LED flashes. This confirms the buzzer, LED, and Z2M connection are functional. Note that the self-test exercises the device electronics and alarm path; it does not test the smoke-sensing element against actual smoke, so it isn’t a substitute for the manufacturer’s recommended physical testing.

I test mine monthly via a small automation that triggers on the 1st of each month, sends me a notification to confirm the test completed, and then checks that the test binary sensor returned to false within 60 seconds.

alias: Smoke detector monthly self-test
trigger:
  - platform: time
    at: "10:00:00"
    id: monthly_test
condition:
  - condition: template
    value_template: "{{ now().day == 1 }}"
action:
  - service: button.press
    target:
      entity_id: button.smoke_detector_kitchen_selftest
  - delay:
      seconds: 10
  - service: notify.mobile_app_your_phone
    data:
      message: "Smoke detector self-test triggered. Confirm you heard the buzzer."

Replace smoke_detector_kitchen_selftest and mobile_app_your_phone with your actual entity IDs.

Known issues — read this section

I’m going to be direct about these. This is a smoke detector. The known issues here are not the same as a switch that sometimes mis-reports state.

Firmware version 21 regression

When smoke is detected on firmware v21, the buzzer sounds once and then auto-mutes. The detector doesn’t continue alarming. This is a safety defect.

Firmware v21 was removed from the Z2M OTA repository after this was discovered (tracked in the zigbee-OTA repo, issue #938). If your device is on v21, do not let it sit — the Z2M documentation has downgrade instructions for this device. Check your current firmware version in the Z2M frontend under the device’s “About” tab.

If you’re buying this device new, check the firmware version after pairing before you mount it. Don’t assume you shipped with a safe version.

ConBee III adapter — state updates silently dropped

If you’re running a ConBee III coordinator with firmware older than v26550900 (dated around 9 December 2025), the adapter does not reliably receive state updates from this detector, including alarm reports. The smoke entity stays false even when the physical buzzer is firing. This is tracked in Z2M GitHub issue #29880.

The fix is to update your ConBee III firmware to v26550900 or later. If you can’t update immediately, use a different coordinator for this specific device until you can.

Worth emphasizing: with this bug present, you’d have a detector making noise in your home while Home Assistant shows no alarm state. Any automations you built on the smoke entity would not trigger. This is exactly why the onboard buzzer, not your HA automation, is what protects you — the buzzer fires regardless of whether the coordinator passes the state along.

Daily offline disconnections

A number of users (Z2M GitHub issue #20268) report that this device goes unavailable roughly once per day. The device is still functional, but Z2M marks it as offline until it checks back in.

The fix is to configure an availability timeout for this device in your Z2M settings. Enable availability in your Z2M configuration.yaml or in the device’s Z2M frontend settings, and set a timeout long enough that normal sleep cycles don’t trigger it. Something in the range of 75–90 minutes works for most people.

# In zigbee2mqtt/configuration.yaml
availability:
  enabled: true
  active:
    timeout: 10
  passive:
    timeout: 1500

Or override it per-device in the Z2M frontend under the device’s settings tab.

Smoke state stuck at false

Separate from the ConBee III issue, some users have observed the smoke entity remaining false during an active alarm event — the buzzer fires but Z2M doesn’t reflect it. This appears to be a state-refresh timing issue.

A partial mitigation is to periodically publish an MQTT get request for the smoke state. This forces Z2M to request a current report from the device:

Topic: zigbee2mqtt/smoke_detector_kitchen/get
Payload: {"smoke": ""}

You can do this via an HA automation that runs every few minutes, but it’s worth knowing this is a known behavior rather than something you’ve misconfigured. And again: treat HA’s view of the alarm as best-effort. The buzzer is the part that has to work.

Automations

These automations add notifications and convenience on top of the detector’s own alarm. They do not replace it.

Alert on smoke detected

alias: Smoke alarm alert
trigger:
  - platform: state
    entity_id: binary_sensor.smoke_detector_kitchen_smoke
    to: "on"
action:
  - service: notify.mobile_app_your_phone
    data:
      title: "SMOKE DETECTED"
      message: "Smoke detector in kitchen triggered."
  - service: media_player.volume_set
    target:
      entity_id: media_player.living_room_speaker
    data:
      volume_level: 1.0
  - service: tts.speak
    target:
      entity_id: tts.home_assistant_cloud
    data:
      message: "Warning: smoke detected in the kitchen."

Mute the buzzer from a dashboard

During an alarm, you may want to silence the buzzer temporarily (the 80-second mute window) without physically reaching the device. Add the buzzer entity as a dropdown to your HA dashboard, or call the service directly:

service: select.select_option
target:
  entity_id: select.smoke_detector_kitchen_buzzer
data:
  option: "mute"

The buzzer will resume after 80 seconds if smoke is still present.

Trigger a siren via HA

If you want a secondary siren to trigger alongside the built-in buzzer, wire it off the same smoke state trigger. The detector’s built-in buzzer and any HA-controlled siren will run in parallel.

Linkage alarm

When you enable linkage_alarm on this detector, it activates a Zigbee binding behavior that can cause other Aqara devices (other smoke detectors, Aqara siren hubs) to sound simultaneously when this detector fires. This is local Zigbee binding — no cloud involved.

If you have multiple JY-GZ-01AQ units or an Aqara siren hub on the same Zigbee mesh, enabling linkage lets them coordinate without routing through Home Assistant at all. The alarm propagates directly over Zigbee.

If you’re only running a single detector, leave linkage_alarm off. It doesn’t add anything in a single-device setup and introduces unnecessary chatter on the mesh.

If you’re considering Aqara’s other safety sensors, we’ve covered the Aqara natural gas detector (JT-BZ-01AQ) and its own Zigbee2MQTT setup in a separate guide, with the same local-first approach.

ZHA support is broken

When you pair the JY-GZ-01AQ to ZHA, it exposes only two entities: Identify and IasZone. The IasZone entity does not change state when the detector fires — it stays “normal” even during an active smoke alarm. The ZHA support requests, zha-device-handlers issues #1828 and #2083, are open and unresolved as of writing.

This means: if you’re on ZHA, the detector will make noise in your house but HA will not know about it. You cannot build automations on the IasZone entity for alarm detection.

Zigbee2MQTT is the only reliable local integration path for this device right now. If you need to stick with ZHA for other reasons, this is not the right smoke detector for your setup.

Frequently asked questions

Does the Aqara smoke detector work without the Aqara hub?

Yes. The JY-GZ-01AQ is a Zigbee device that pairs directly to any Zigbee coordinator running Zigbee2MQTT. The Aqara hub and Aqara Home app are not required. Once paired to Z2M, it operates entirely locally. If you’re weighing how much of the Aqara ecosystem actually needs the internet, our explainer on whether Aqara works without internet goes through it device by device.

Why does my Aqara JY-GZ-01AQ keep going offline in Home Assistant?

This is a known issue (Z2M GitHub #20268) where the device goes unavailable roughly once daily. Enable the availability timeout in your Z2M configuration (see the Known Issues section above). This is a quirk of how the device manages its sleep cycle on the mesh, not a pairing problem.

Is the Aqara smoke detector compatible with ZHA?

No, not reliably. Pairing succeeds but the alarm state entity doesn’t work — the IasZone entity stays normal even during a real alarm. Use Zigbee2MQTT for this device. The ZHA compatibility issues are tracked in zha-device-handlers issues #1828 and #2083, but there is no fix currently available.

What is the linkage alarm on the Aqara smoke detector?

It’s a Zigbee binding that causes other Aqara devices (other smoke detectors, siren hubs) on the same mesh to trigger simultaneously when this device fires. It’s entirely local — no cloud or hub required. Enable it via the linkage_alarm entity in Home Assistant if you have multiple Aqara safety devices you want to coordinate.

How do I test the Aqara smoke detector from Home Assistant?

Use the selftest button entity in HA. Press it and the detector runs its test cycle — buzzer sounds, LED flashes. This confirms the device electronics, its connection to Z2M, and the MQTT path to HA are all working. It does not test the sensor against real smoke, so follow the manufacturer’s physical testing guidance as well. Running the self-test monthly is worth building into an automation.

Before you mount it

The JY-GZ-01AQ works well with Zigbee2MQTT on a stable coordinator. The entity set is good, the self-test is genuinely useful, and local operation is solid once the known issues are dealt with.

The known issues are real, though. Before you mount this on your ceiling and forget about it: check the firmware version and confirm you’re not on v21, confirm your ConBee III firmware is current if that’s your coordinator, and set up the availability timeout so you know if the device drops off the mesh. And remember the framing from the top of this article — the integration is for notifications and automation. The detector’s own buzzer is what keeps you safe.