Skip to content

Add Tuya ZS-300TF / ZS-301 soil fertility sensor quirk - #5276

Open
zichul wants to merge 1 commit into
zigpy:devfrom
zichul:feat/add-zs-300tf-soil-sensor-quirk
Open

Add Tuya ZS-300TF / ZS-301 soil fertility sensor quirk#5276
zichul wants to merge 1 commit into
zigpy:devfrom
zichul:feat/add-zs-300tf-soil-sensor-quirk

Conversation

@zichul

@zichul zichul commented Aug 24, 2026

Copy link
Copy Markdown

Summary

Adds a quirk for the Excellux ZS-300TF Tuya TS0601 soil fertility sensor (commonly sold as the ZS-301). The device pairs with ZHA but exposes no entities without a quirk, because its datapoints are only mapped by a Zigbee2MQTT converter, not by zha-quirks.

The device reports a corrupted manufacturer ID (_TZE2841000000_hdml1aav), so the quirk matches both the clean (_TZE284_hdml1aav) and corrupted form, following the same pattern already used for the Giex GX04.

Exposed entities

Entity DP Conversion
Soil moisture 3 raw (%)
Temperature 5 /10 (°C)
Humidity 101 raw (%)
Illuminance 102 raw (lx)
Electrical conductivity (soil fertility) 112 raw (µS/cm)
Battery 15 raw (%)

Notes

  • The datapoint map is sourced from the authoritative Zigbee2MQTT converter for this device (zigbee-herdsman-converters, model ZS-300TF, vendor Excellux), see tuya.ts fingerprint ["_TZE284_hdml1aav", "_TZE2841000000_hdml1aav"].
  • Illuminance uses a raw (lambda x: x) converter rather than the tuya_illuminance log10 default, because this device reports actual lux (matching the Z2M tuya.valueConverter.raw converter for DP 102).
  • The battery is mapped via the Tuya datapoint (DP 15) for accuracy, consistent with the other TS0601 soil-sensor quirks in this file.

Verification

Tested on Home Assistant Yellow (Core 2026.8.x, ZHA). After enabling the quirk and reconfiguring the device, the data-query spell produced real values on cluster 0xEF00:

  • DP 3 = 48 → 48.00 % soil moisture
  • DP 5 = 226 → 22.60 °C
  • DP 101 = 68 → 68.00 % humidity
  • DP 102 = 0 → 0 lx (night)
  • DP 15 = 94 → 94 % battery
  • DP 112 = 856 → 856 µS/cm

pytest tests/test_tuya_sensor.py tests/test_quirks_v2.py tests/test_quirks_v2_builder.py passes (81 tests), and ruff check / ruff format --check are clean.

Refs: zigbee2mqtt#32196, home-assistant discussion #2172.

Add support for the Excellux ZS-300TF (sold as ZS-301) Tuya TS0601 soil
fertility sensor, matched on both the clean (_TZE284_hdml1aav) and the
corrupted (_TZE2841000000_hdml1aav) manufacturer ID.

Exposes soil moisture (DP 3), temperature (DP 5, /10), humidity (DP 101),
illuminance (DP 102, raw lux), electrical conductivity / soil fertility
(DP 112) and battery (DP 15).

Datapoint map sourced from the Zigbee2MQTT converter for the same device
(zigbee-herdsman-converters, model ZS-300TF, vendor Excellux).
@codecov

codecov Bot commented Aug 24, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.60%. Comparing base (b139f81) to head (415190d).
⚠️ Report is 2 commits behind head on dev.

Additional details and impacted files
@@           Coverage Diff           @@
##              dev    #5276   +/-   ##
=======================================
  Coverage   92.60%   92.60%           
=======================================
  Files         424      424           
  Lines       14667    14668    +1     
=======================================
+ Hits        13582    13583    +1     
  Misses       1085     1085           

☔ View full report in Codecov by Harness.
📢 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.

@zigpy-review-bot zigpy-review-bot added bot: needs changes PR needs changes per LLM bot: 2.0 migration done PR is on the ZHA/quirks 2.0.0 API (migrated or written for 2.0) per LLM new quirk Adds support for a new device Tuya Request/PR regarding a Tuya device bot: needs maintainer PR does something questionable that needs a maintainer decision per LLM labels Aug 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bot: needs changes PR needs changes per LLM bot: needs maintainer PR does something questionable that needs a maintainer decision per LLM bot: 2.0 migration done PR is on the ZHA/quirks 2.0.0 API (migrated or written for 2.0) per LLM new quirk Adds support for a new device Tuya Request/PR regarding a Tuya device

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants