Skip to content

Conversation

@cemizm
Copy link

@cemizm cemizm commented Nov 19, 2025

Proposed change

This PR adds a custom quirk for the Aqara FP300 presence sensor
(manufacturer: LUMI, model: lumi.sensor_occupy.agl8) to xiaomi.

Key points:

  • Implements an AqaraFP300ManuCluster based on XiaomiAqaraE1Cluster for the manufacturer-specific cluster 0xFCC0.
  • Adds support for parsing Aqara TLV attribute 0x00F7 so that:
    • 0xff01-23 is mapped to BATTERY_VOLTAGE_MV
    • 0xff01-24 is mapped to BATTERY_PERCENTAGE_REMAINING_ATTRIBUTE
    • Battery is then exposed via XiaomiPowerConfigurationPercent, reusing the existing Xiaomi battery logic.
  • Implements an FP300DetectionRangeCluster as a LocalDataCluster to handle the detection range for the FP300:
    • Reads and writes the manufacturer attribute 0x019A (type octet string) on cluster 0xFCC0
    • Decodes/encodes the 5-byte payload (prefix + 24-bit range mask)
    • Exposes the 24 × 0.25 m detection slices as six 1 m configuration switches in Home Assistant
  • Exposes the FP300 configuration options as entities (e.g. absence delay, motion sensitivity, AI adaptive sensitivity, interference source self-identification, etc.) via the v2 QuirkBuilder API.
  • Does not modify any existing device handlers and should be non-breaking.

This allows ZHA to support the FP300 with:

  • presence detection
  • proper battery reporting
  • configurable detection range in a HA-friendly way (6 config switches instead of 24 individual bits).

Additional information

Fixes #4487

Device diagnostics

zha-bb791876a15e4fd9b338fdb8a62f7a7c-Aqara lumi.sensor_occupy.agl8-c0ba404a3f7cc423c2650a543896d981.json

Checklist

  • The changes are tested and work correctly (see linked issue)
  • pre-commit checks pass / the code has been formatted using Black
  • Tests have been added to verify that the new code works
  • Device diagnostics data has been attached

@codecov
Copy link

codecov bot commented Nov 19, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.36%. Comparing base (bf73aa9) to head (c14435e).
⚠️ Report is 3 commits behind head on dev.

Additional details and impacted files
@@            Coverage Diff             @@
##              dev    #4504      +/-   ##
==========================================
+ Coverage   92.24%   92.36%   +0.11%     
==========================================
  Files         369      372       +3     
  Lines       12094    12280     +186     
==========================================
+ Hits        11156    11342     +186     
  Misses        938      938              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@TheJulianJES TheJulianJES added Xiaomi Request/PR regarding a Xiaomi or Aqara device priority: medium This should be addressed or looked at soon labels Nov 19, 2025
@TheJulianJES TheJulianJES changed the title add fp300 (lumi agl8) quirk Aqara FP300 presence sensor quirk Nov 19, 2025
@TheJulianJES TheJulianJES changed the title Aqara FP300 presence sensor quirk Add Aqara FP300 presence sensor quirk Nov 19, 2025
@cemizm cemizm marked this pull request as draft November 19, 2025 20:23
@cemizm cemizm marked this pull request as ready for review November 20, 2025 20:11
@TheJulianJES TheJulianJES self-requested a review November 20, 2025 20:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

priority: medium This should be addressed or looked at soon Xiaomi Request/PR regarding a Xiaomi or Aqara device

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Device Support Request] Aqara FP300 (lumi.sensor_occupy.agl8)

2 participants