SmartThings Edge Driver (aqara-fp300-zigbee)
The most(ly) complete Zigbee integration for the Aqara FP300 (lumi.sensor_occupy.agl8 / PS-S04D) on SmartThings.
This community Edge Driver unlocks the full feature set of the FP300’s dual mmWave + PIR sensor, environmental sensors (temperature, humidity, illuminance), battery monitoring, and advanced manufacturer-specific configuration — all running locally on your SmartThings hub.
The FP300 is not a “normal” Zigbee presence sensor. Aqara exposes the basic environmental data through standard Zigbee clusters, but many of the interesting controls — presence mode, sensitivity, absence delay, AI features, target-distance actions, detection range, LED schedule, and various reporting parameters — live in Aqara’s manufacturer-specific cluster 0xFCC0. That is why generic integrations usually expose only a subset of the device until device-specific handling is added.
See: Zigbee2MQTT device page, ZHA support request.
Features
- Dual detection — Separate
presenceSensor(mmWave presence) andmotionSensor(PIR motion) capabilities - Environmental sensors — Temperature, relative humidity, and illuminance with user-configurable offsets, sampling, and reporting modes
- Battery — Voltage + percentage reporting (multi-source handling, including Aqara/Xiaomi-style packed reports)
- Advanced configuration (via device preferences):
- Presence detection mode (Both / mmWave only / PIR only)
- Motion sensitivity (Low / Medium / High)
- Absence delay (10–300 s)
- PIR detection interval (2–300 s)
- AI adaptive sensitivity & AI interference identification (fans, AC units, etc.)
- One-shot actions: target distance tracking, spatial learning, device restart
- Full control over temperature / humidity / illuminance sampling & reporting (off / low / medium / high / custom + thresholds, intervals, modes)
- LED behavior: disabled at night + custom schedule (HH:MM)
- Detection range mask — raw 24-bit (0.25 m resolution) and coarse 1 m band toggles (0–6 m)
- Robust Zigbee handling:
- Manufacturer-specific cluster
0xFCC0(LUMI/Aqara manufacturer code0x115F) - Write-and-verify logic with readback + timeout protection
- Debounced
infoChangedhandling for rapid preference saves - Safe command sending with error guards
- Manufacturer-specific cluster
- Target distance — Read and logged internally (ready for future custom capability exposure)
- Zero cloud dependency — All logic runs locally on the hub
The underlying hardware combines PIR + 60 GHz mmWave radar, offers a 120° field of view, and up to 6 m detection range. Aqara also markets it as a 5-in-1 sensor because it adds temperature, humidity, and ambient light sensing on top of presence detection.
See: Aqara FP300 product page.
Supported Devices
| Manufacturer | Model | Device Label | Profile |
|---|---|---|---|
| Aqara / LUMI | lumi.sensor_occupy.agl8 |
Aqara Presence Sensor FP300 | aqara-fp300 |
Fingerprint IDs (both Aqara and LUMI variants) are included.
Firmware note: The sensor must be switched to Zigbee mode in the Aqara app before pairing with this driver. Aqara’s official product documentation confirms that some exclusive/advanced settings are tied to Zigbee mode, and the SmartThings community thread confirms the practical workflow: reset the device, open the Aqara app, switch it to Zigbee firmware, then pair it in SmartThings. Using the latest available Zigbee firmware is recommended.
See: Aqara product page, Aqara forum note on Zigbee firmware 0.0.0_5841.
Installation
-
Install the Aqara FP300 Presence Sensor driver from this channel.
-
In the SmartThings app:
- Go to Devices → + → Add device → Scan for devices
- Select Aqara Presence Sensor FP300
-
The driver will automatically match via fingerprints and run the initial configuration.
Practical pairing note: Once the FP300 has been switched to Zigbee firmware, pairing usually works via normal SmartThings Zigbee discovery (+ → add device → scan) after putting the sensor into pairing mode.
Device Preferences (Full List)
All preferences are exposed in the SmartThings app under the device settings. Changes are applied safely with verification.
Detection & Presence
| Preference | Type | Range / Options | Default | Description |
|---|---|---|---|---|
| Presence detection mode | Enum | both, mmwave, pir |
both |
Select which sensing method is used for presence detection |
| Motion sensitivity | Enum | low, medium, high |
medium |
Main sensitivity control for presence detection |
| Absence delay (s) | Integer | 10–300 | 30 | Time before not present is reported after no presence is detected |
| PIR detection interval (s) | Integer | 2–300 | 30 | PIR timing / cadence parameter; higher detection frequency improves accuracy but costs battery |
| AI adaptive sensitivity | Boolean | On / Off | Off | Lets the device adapt sensitivity to the room over time |
| AI interference identification | Boolean | On / Off | Off | Helps filter or identify fans, AC units, curtains, and similar moving interference sources |
| Start target distance tracking | Boolean | On (triggers) → Off | Off | One-shot maintenance/action trigger for target-distance tracking |
| Start spatial learning | Boolean | On (triggers) → Off | Off | One-shot action that runs Aqara AI spatial learning |
| Restart device | Boolean | On (triggers) → Off | Off | One-shot reboot of the FP300 |
Notes:
presenceSensorandmotionSensorare intentionally separate. The FP300 has both a mmWave presence signal and a PIR motion signal, and they are not equivalent.- In
bothmode, the PIR path may go inactive while mmWave presence remains active. That is normal for this class of device and one of the reasons the driver exposes two separate capabilities. - Aqara specifically positions AI adaptive sensitivity and spatial learning as part of the FP300’s interference handling / room adaptation logic.
See: Zigbee2MQTT device page, Aqara product page.
Detection Range (Advanced)
| Preference | Type | Range / Default | Description |
|---|---|---|---|
| Detection range mask (advanced) | Integer | 0–16,777,215 (0xFFFFFF) |
Raw 24-bit mask for 24 quarter-meter segments |
| Detect 0–1 m / 1–2 m / … / 5–6 m | Boolean | On / Off (default On) | Coarse 1 m band toggles derived from the finer native mask |
How this works:
- The FP300’s native detection-range model is finer-grained than the SmartThings UI. Zigbee2MQTT exposes 24 separate 0.25 m slices from
0.00 mto6.00 m. - This driver offers both a raw 24-bit mask and a friendlier 1 m abstraction.
- Depending on firmware / integration path, the underlying detection-range payload may appear as a legacy integer-style value or as a manufacturer-specific octet string / buffer that contains a prefix plus the actual 24-bit mask.
See: Zigbee2MQTT device page, ZHA FP300 quirk/gist reference.
Environmental Sensors
Temperature / Humidity / Illuminance each have:
- Sampling mode:
off/low/medium/high/custom - Custom sampling period (s)
- Reporting interval (s)
- Reporting threshold (delta)
- Reporting mode:
threshold/interval/both
What these obscure settings actually do:
- Sampling mode controls how frequently the FP300 samples that sensor internally. Higher frequency improves responsiveness but costs battery.
- Custom mode unlocks manual control of period / interval / threshold.
- Reporting interval is the maximum periodic update time.
- Reporting threshold is the minimum delta before the sensor reports early.
- Reporting mode decides whether the device reports on threshold change, periodic interval, or both.
Temperature offsets and Humidity offsets are also available (global preferences). These are standard SmartThings-style calibration adjustments exposed through device preferences.
Power / battery notes:
- Aqara rates the FP300 for up to 3 years in Zigbee mode and up to 2 years in Thread mode, depending on settings and usage.
- Higher PIR frequency and more aggressive environmental sampling/reporting can reduce battery life.
- The sensor uses two replaceable CR2450 cells.
See: Aqara product page.
How It Works (Technical Highlights)
- Manufacturer cluster
0xFCC0— All advanced config lives here. The driver uses safewrite_attribute+ immediateread_attributeverification with token-based deduplication and 4-second timeouts. - Detection range — The driver handles both a user-friendly coarse mask and the device’s native fine-grained detection-range format.
- Debounced preference application — Rapid changes in the app are coalesced (1-second delay + generation counter).
- Battery handling — Prefers direct percentage report from packed Aqara/Xiaomi-style
0x00F7; falls back to voltage linear mapping. - Lifecycle — Proper binding, reporting configuration,
prevent_leave, initial preference sync, and delayed full refresh on configure.
Why this device is tricky / non-standard
The FP300 is one of the more unusual consumer Zigbee sensors because it mixes standard clusters and a large manufacturer-specific cluster in ways that generic drivers cannot interpret correctly out of the box.
What makes it tricky:
- Two different detection concepts — mmWave presence and PIR motion are both exposed and need to be handled separately.
- Private Aqara controls — Presence mode, motion sensitivity, absence delay, AI features, target-distance actions, detection range, LED scheduling, and detailed environmental reporting all sit in
0xFCC0instead of standard Zigbee clusters. - Odd data encodings — Some attributes are straightforward integers, others are booleans, and others arrive as Aqara/Xiaomi-style packed buffers such as
0x00F7battery reports or octet-string-style detection-range payloads. - Silent / partial responses — Some manufacturer-specific writes and reads can be quiet or inconsistent, so a robust driver benefits from explicit write verification, timeouts, deduplication, and defensive logging.
- Firmware behavior matters — Community reports around firmware
0.0.0_5841show that the FP300 can send duplicate or rounded temperature/humidity reports and that real-world presence behavior can be influenced heavily by placement, interference, and sensitivity settings.
See: ZHA support request, Aqara firmware discussion, Aqara forum discussion on placement / sensitivity.
Known Limitations & Future Improvements
- Target distance (
0x015F) is read and logged but not yet exposed as a capability (easy future addition). - Battery percentage can occasionally read low on fresh CR2450 cells (firmware-dependent; voltage range may need tuning).
- One-shot action preferences (
Track,Learn,Restart) require manual toggle-off after use (SmartThings limitation). - No built-in firmware version display or OTA support in SmartThings; firmware management remains an Aqara-app workflow.
- Placement still matters more than settings. Community experience suggests that correct placement and a sensible detection range often matter more than endlessly tweaking preferences.
Planned / Suggested enhancements:
- Custom capability for target distance
- Optional custom capability for diagnostic / engineering values
- Debug logging toggle
- Firmware version exposure
Battery Reporting Caveat
The FP300’s battery reporting is currently one of the least reliable parts of the device across multiple platforms.
Testers have reported that the battery value can jump between very low and high readings, and in some cases SmartThings may even show “no battery”. Unfortunately, this does not appear to be a SmartThings-only problem. Similar behavior has also been reported in the Aqara app, Home Assistant / ZHA, and Zigbee2MQTT-related investigations:
- Aqara forum: “FP300 Empty Battery After 3 Days!?”
- Aqara forum: “Aqara FP300 Battery life”
- zigbee2mqtt issue #28672 (FP300 interview / battery fields)
- ZHA FP300 quirk / attribute mapping reference
What seems to be happening
The FP300 does not behave like a simple standard Zigbee battery device.
In particular:
-
The standard Zigbee battery cluster (
genPowerCfg.batteryPercentageRemaining) has been observed as 0 even while Aqara’s manufacturer-specific payload still contains battery-related data. -
Aqara-specific battery information is embedded in the packed manufacturer attribute
0x00F7. -
Current cross-platform implementations indicate that:
0xff01-23maps to battery voltage (mV)0xff01-24maps to battery percentage remaining
That means the most reliable battery source for the FP300 is usually Aqara’s packed 0x00F7 report, not the standard Zigbee battery percentage field.
What this driver does
This driver is designed to prefer Aqara-specific battery data where available and to avoid blindly trusting inconsistent standard battery reports.
Even with that, occasional wrong readings may still occur, because there is evidence that at least part of the problem is device-side / firmware-side, not just integration-side.
Practical recommendations
If battery reporting looks wrong:
- Make sure the FP300 is on the latest available Zigbee firmware
- Try a battery reseat / restart
- Give the device some time after pairing or reconfiguration before judging the battery value
- Treat sudden one-off drops or jumps with caution unless they repeat consistently
Community reports suggest that some units recover after a restart or battery reseat, while others appear to have firmware-related reporting quirks:
- Aqara forum: battery reading returns to normal / fluctuates
- Aqara forum: firmware and early battery-drain discussion
Bottom line
Battery reporting on the FP300 should currently be treated as best effort, not as a perfectly trustworthy health indicator.
The sensor itself may continue to work normally even while the reported battery percentage is temporarily misleading.
Troubleshooting
- Presence stays stuck → Increase absence delay, reduce sensitivity, narrow the detection range, and run spatial learning.
- No advanced options → Ensure the device is in Zigbee mode (not Thread / Matter).
- Battery drains fast → Lower PIR interval / sampling rates
- Preferences not applying → Check driver logs in SmartThings (search for
[FP300],queued verification,sending readback,verified, andtimed out). - Device not discovered → Factory reset, switch to Zigbee firmware in Aqara Home, then re-pair after installing the driver.
- Slow / unreliable detection → Placement and interference matter. Fans, AC airflow, curtains, and similar moving objects can confuse the sensor; adaptive sensitivity and a tighter detection range often help.
Logs: In the SmartThings mobile app → Device → ⋮ → View logs (filter for FP300).
Helpful references:
Changelog
Latest (revised build):
- Separated main presence from PIR motion
- Fixed preference ID handling and debouncing
- Improved detection range handling (fine-grained native model + coarse SmartThings UI)
- Added coarse 1 m band toggles
- Added one-shot actions for target-distance tracking, spatial learning, and restart
- Enhanced verification & safe-send logic
Credits & Community
- Inspired by Zigbee2MQTT, ZHA quirks, and Hubitat implementations
- Thanks to everyone testing, logging, and providing feedback!
Sources & Further Reading
- Aqara Presence Multi-Sensor FP300 product page
- Zigbee2MQTT: Aqara PS-S04D / FP300
- SmartThings Community: ST Edge Aqara FP300 (Zigbee)
- zigpy / ZHA device support request for the FP300
- Community ZHA FP300 quirk / attribute mapping reference
- Aqara forum: Zigbee firmware
0.0.0_5841 - Aqara forum: duplicate temp/humidity reports on Zigbee firmware
(only Matter).