Skip to content

add THERMOSTAT_FAN_ONLY_HVAC - #5093

Closed
vmvarga wants to merge 1 commit into
zigpy:devfrom
vmvarga:dev
Closed

add THERMOSTAT_FAN_ONLY_HVAC#5093
vmvarga wants to merge 1 commit into
zigpy:devfrom
vmvarga:dev

Conversation

@vmvarga

@vmvarga vmvarga commented Jun 15, 2026

Copy link
Copy Markdown

Add THERMOSTAT_FAN_ONLY_HVAC exposed-feature quirk id

Summary

Adds a new exposed-feature id, THERMOSTAT_FAN_ONLY_HVAC, to zhaquirks/quirk_ids.py.
It is a hint a quirk can place in device.exposes_features to tell ZHA that the
thermostat actually implements SystemMode.Fan_only (0x07), so the climate entity
may expose HVACMode.FAN_ONLY.

# Hint that the thermostat actually implements SystemMode.Fan_only, so the
# climate entity may expose HVACMode.FAN_ONLY
THERMOSTAT_FAN_ONLY_HVAC = "thermostat_fan_only_hvac"

It lives in the existing # Exposed features section, next to SE_POLL_SUMMATION
and SIREN_BASIC, and follows the same convention.

Why

ZHA's Thermostat climate entity derives its hvac_modes from
controlSequenceOfOperation, which per the ZCL spec only covers heating/cooling
combinations and never includes FAN_ONLY. Enabling FAN_ONLY purely because a
device advertises the Fan Control cluster (0x0202) is unreliable: many devices
expose the cluster but silently ignore SystemMode.Fan_only (e.g. some Tuya HVAC
thermostats).

The companion ZHA change therefore gates HVACMode.FAN_ONLY behind an explicit
opt-in: the climate entity only exposes it when this feature id is present in
device.exposes_features. Per maintainer feedback on that PR, the feature id itself
belongs here in zha-quirks (where all other exposed-feature ids live and are
imported from), not in the zha repo.

Companion PR

  • ZHA: zigpy/zha — switches the climate entity to
    from zhaquirks.quirk_ids import THERMOSTAT_FAN_ONLY_HVAC and bumps the
    zha-quirks pin to the release containing this change. That PR depends on this
    one being merged and released first.

Usage

A device quirk declares support by exposing the feature, e.g. with the v2 quirk
builder:

from zhaquirks.quirk_ids import THERMOSTAT_FAN_ONLY_HVAC

(
    QuirkBuilder(...)
    ...
    .exposes_feature(THERMOSTAT_FAN_ONLY_HVAC)
    .add_to_registry()
)

A follow-up PR will add this opt-in to known-good fan-capable thermostats.

Test plan

  • THERMOSTAT_FAN_ONLY_HVAC is importable: from zhaquirks.quirk_ids import THERMOSTAT_FAN_ONLY_HVAC
  • Value is "thermostat_fan_only_hvac" (matches the string ZHA previously used,
    so no behavioral change for any already-shipped quirk metadata)
  • Lint/format passes

@codecov

codecov Bot commented Jun 15, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.07%. Comparing base (f3e619e) to head (b1041a6).

Additional details and impacted files
@@           Coverage Diff           @@
##              dev    #5093   +/-   ##
=======================================
  Coverage   93.07%   93.07%           
=======================================
  Files         401      401           
  Lines       13306    13307    +1     
=======================================
+ Hits        12385    12386    +1     
  Misses        921      921           

☔ 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.

@vmvarga vmvarga closed this Jun 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant