How to Manually Specify Supported Features of a Zigbee Thermostat in ZHA?

Configuration Zigbee
, ,
1

I recently got air conditioning installed in my house and since it doesn't support any smart features on its own, I'm developing a custom ESP32-H2 based interface to integrate it into my Home Assistant via the already existing Zigbee mesh running ZHA. This isn't my first rodeo developing Zigbee devices, but it's the first time they're complex enough that the HA entities ZHA creates by default don't cut it, but no matter how much I try with changing the cluster configs or writing quirks, I can't seem to find a way to let ZHA know which features my AC supports.

The setup

The AC supports the following:

  • switching on/off
  • louver swing on/off
  • cool/heat/fan only/auto system modes
  • low/medium/high/auto fan speed modes
  • setting temperature

I've modeled this using the following Zigbee clusters on the same endpoint:

  • On/Off (used for louver swing)
  • Thermostat
    • control sequence of operation = SEQ_OF_OPERATION_COOLING_ONLY (since I don't really need heating)
  • Fan Control
    • fan mode sequence = FAN_MODE_SEQUENCE_LOW_MED_HIGH_AUTO

The results

With the above setup, upon connecting the device to ZHA, a thermostat does show up in the UI, but the only AC operation modes it shows are Cool and Off. If I change the control sequence of operation to heating and cooling, Heat mode does show up, but the Fan Only or Auto modes are still nowhere to be seen.
Fan speed has a similar issue, the thermostat only allows me to set it to Auto or Off, completely ignoring what fan mode sequence have I specified in the Fan Control cluster.
Louver swing does seem to work with the On/Off cluster, but if there's a way to integrate it with the rest of fan controls in the thermostat UI, I'd like to know of it.

I tried to find an example of a quirk that would be doing something similar to use as an example, but couldn't really find any, is an AC really this uncommon of a device to be connecting via Zigbee?

Environment

HAOS 17.3 running HA 2026.5.4 on a Raspberry Pi 3B.
ZHA running via a Sonoff USB dongle.

TL;DR: HA thermostat UI won't pick up correct modes just from the Zigbee device's cluster layout, how can I specify them manually?

2

Have a look at the Z2M device database. There's been a few AC control devices added in the past year. A bunch were added last release. I know it's not a straight 1-1 translation to ZHA, but it's a start.

Mostly, yes. Zigbee AC control is pretty much in its infancy & the few devices there are are hard to source &/or cost major money. Not sure if any of these use ESP

Depending on your goals, there are cheap working devices for Midea, Daikin (using Faikin or Faikout) & others using esphome over WiFi.
I know it's not zigbee, but again, it's a good start until someone comes up with working code

3

Seems like the core of the issue is that ZHA doesn't seem to read out the available modes properly. EDIT: Yup. Fan control interface does not display options correctly · Issue #226 · zigpy/zha · GitHub

Even directly setting the current HVAC mode to Fan Only in ESP firmware won't let ZHA figure out that it's a supported HVAC mode, leading to this contradicting UI combination:

image
image559×609 31.4 KB

I also tried manually editing the thermostat entity's state to add the missing HVAC modes, which does allow them to show up in the UI, but will show an error popup that it's an unsupported mode as soon as you select it.

Due to all that, I unfortunately don't think that Z2M device configs will help very much here.

Interesting, given how everyone seems to be switching to Matter lately, I'd have thought that this was more mature in Zigbee, thanks for the info.

I'm trying to avoid any IP based networking for IoT devices, since I'm not willing to deal with the security implications of exposing them to the internet - hence the choice of Zigbee. I've seen that ESPHome does have some basic zigbee support, but it mostly only supports simple devices, which a thermostat seems not to be.