Coercing Zigbee, Home Assistant, ZHA, and SmartIR together

bsilvereagle

May 18, 2024 • 3 min read

Home Assistant is a great piece of software.

Zigbee Home Automation (ZHA) is a great piece of software.

SmartIR is a great piece of software.

So why is it so difficult to get them to control a Mitsubish Mini-Split HVAC system? Newish hardware, that's why.

Several Zigbee IR blasters have entered the Home Automation scene in recent years. Some are battery powered (Moes UFO-R11), some are powered via USB (ZS06), but all of them use the Tuya TS1201 (Zigbee) platform under the hood. Until the Zigbee blasters appeared, Broadlink was the main player in the automation space, but it only supports Wi-Fi networking. None of the upstream software packages have caught up with the proliferation of Zigbee IR blasters.

Note: This post will hopefully not age gracefully as these patches get absorbed into upstream projects

ZHA

Getting Home Assistant (via ZHA) to recognize the TS1201 chipset requires installing a custom quirk.

# Make a directory for quirks if none exists
$ mkdir /config/quirks
# Inform Home Assistant about it
$ cat /config/configuration.yaml
...
zha:
  custom_quirks_path: quirks/
...
# Download the quirk
$ cd /config/quirks
$ wget https://raw.githubusercontent.com/ferehcarb/zha-device-handlers/dev/zhaquirks/tuya/ts1201.py
# Restart Home Assistant

After performing the above steps, ZHA should recognize the device:

Click "Zigbee Info" in this panel and record the IEEE address for the device.

Verifying the device is functioning is performed by clicking the kebab menu and selecting "Manage Device". From there, set the Zigbee Cluster to ZosungIRControl and the Command to IRLearn.

Issue the command and record a signal from an IR emitter. Click Attributes and read the last_learned_ir_code attribute. Copy and paste this string back into the IRSend command and verify that the device is receiving and transmitting values.

Note: On my system, I had to fully reboot the Home Assistant server and power cycle the Zigbee IR blaster to actually send IR data.

For simpler IR devices the ride ends here - record values and play them back via Home Assistant scriipts. For more complicated devices, like Mitsubishi HVAC units with a complex payload, SmartIR is the better path forward.

SmartIR

Once the device is communicating with ZHA properly, install a forked version of SmartIR with ZHA support.

Clone davidrpfarinha's fork of SmartIR and extract the contents into the custom_components directory of the Home Assistant configuration.

$ git clone https://github.com/davidrpfarinha/SmartIR
$ mkdir /config/custom_components
$ cp -r SmartIR/custom_components /config/custom_components

Next, modify the Home Assistant configuration.yaml for this device:

...
zha:
  custom_quirks_path: quriks/

smartir:

climate:
  - platform: smartir
    name: Office AC
    unique_id: office_ac
    device_code: <YOUR_DEVICE_CODE>
    controller_data: <YO:UR:DE:VI:CE:MA:CA:DR>
    temperature_sensor: sensor.office_ac_temperature
    humidity_sensor: sensor.office_ac_humidity
    power_sensor: binary_sensor.office_ac_power

Set controller_data equial to the IEEE address reported in the ZHA Device Info panel above.

Find the "device code" number for the HVAC system you are trying to control in the SmartIR database.

Note that nearly all of the devices only have support for "Broadlink" blasters. This is problematic. Broadlink and the TS1201 both store data in a different format. Thankfully, the TS1201 protocol has been mostly reverse engineered and scripts exist to convert from the Broadlink protocol to the TS1201 protocol.

$ wget https://gist.githubusercontent.com/svyatogor/7839d00303998a9fa37eb48494dd680f/raw/66cba20e653f84aab0b9a31ea5b9ca497d038d8a/broadlink_to_tuya.py
$ python3 broadlink_to_tuya.py your_device_code.json > /config/custom_components/smartir/codes/climate/your_device_code.json

The device codes in the new JSON file should be different from those in the original file:

Broadlink: "31": "JgBMAmw5DisOKg0PDg4NEA8pDg4ODw4qDioNDw0rDhANDg..."

Tuya: "31": "ENkMyAarAR4FqwEABYwByQGrIAECjAH..."

There is still more work to do! These converted files are still marked as being for the Broadlink. Set the supportedController field in the file to "ZHA" and restart Home Assistant.

With some luck the climate panel should have automatically loaded and allow control of the device.

Did this save you hours of debugging? Say thanks and help keep this site ad & analytic free by using my Amazon Affilliate URL. I'll receive a small portion of any purchases made within 24 hours.