ZS05 with SmartIR: setup in Zigbee2MQTT

Integrating the ZS05 Zigbee IR Controller with SmartIR via Zigbee2MQTT

The ZS05 Zigbee IR controller connects to Home Assistant using Zigbee2MQTT and the SmartIR integration. The main challenge is correctly configuring MQTT topics and converting IR commands from Broadlink format to Raw MQTT. This enables control of climate devices, TVs, and projectors without the typical errors found with ZHA.

System Requirements

You'll need:

• Home Assistant, up-to-date version.
• Zigbee2MQTT as an add-on or in Docker.
• SmartIR via HACS.
• A ZS05 controller or compatible alternative.

Adding the Device in Zigbee2MQTT

• Enable Permit Join in Zigbee2MQTT.
• Reset the ZS05 by holding the button until the LED flashes.
• The device will appear in the Z2M interface.
• Assign a Friendly Name, such as ir_livingroom — this determines the MQTT topic zigbee2mqtt/ir_livingroom.

Check the logs: the device should publish and receive messages. Topics like zigbee2mqtt/ir_livingroom confirm the connection.

Installing SmartIR

In HACS, search for the SmartIR repository, install it, and restart HA. The integration creates entities like climate and media_player, which use MQTT to send IR signals.

Correct Configuration in configuration.yaml

A common error in SmartIR documentation is the wrong subtopic in controller_data. For the ZS05, use /set/ir_code_to_send, not /command.

Example for a climate entity:

smartir:

climate:
  - platform: smartir
    name: Living Room AC IR
    unique_id: living_room_ac_ir
    device_code: 1200
    controller_data: zigbee2mqtt/ir_livingroom/set/ir_code_to_send
    temperature_sensor: sensor.temperature
    humidity_sensor: sensor.humidity
    power_sensor: binary_sensor.ac_power
    power_sensor_restore_state: true

Key parameters:

• controller_data: zigbee2mqtt/{friendly_name}/set/ir_code_to_send — the exact path for ZS05 commands.
• device_code: Numeric code from the SmartIR library (smartir/codes/climate). For rare brands, match by protocol (e.g., Gree, Midea).
• Temperature/humidity/power sensors — optional for full automation.

Converting IR Codes to Raw MQTT

The SmartIR library stores codes in Broadlink format. The ZS05 requires Base64 Raw MQTT. Convert the files:

• Download JSON from the smartir/codes/{type} repository.
• Use an online Broadlink → Raw MQTT converter or a Python script.
• Place the converted file in /config/custom_components/smartir/codes/climate via Samba.

In device_code, specify only the number from the filename (e.g., 9990).

Example converted commands for Tosot T09H-SNa/I (heat, low, 16°C):

{
  "manufacturer": "Tosot",
  "supportedModels": ["T09H-SJ"],
  "supportedController": "MQTT",
  "commandsEncoding": "Raw",
  "minTemperature": 16,
  "maxTemperature": 30,
  "precision": 1,
  "operationModes": ["heat", "cool", "dry", "fan_only", "heat_cool"],
  "fanModes": ["low", "medium", "high", "auto"],
  "commands": {
    "off": "CRgjnBElAm0GJQLgCwHgAxfAC+APK+ALO8AD4A9X4AtfAQpO4B1j4AdX4B+X4Bur",
    "heat": {
      "low": {
        "16": "BRgjnBElAsABAW0G4AEDwA/gLwHgB0vgBxvgB1/AawEKTuAdd+AHV+Azq+AHRw=="
      }
    }
  }
}

Full commands for all modes/temperatures are available in the library after conversion.

Testing and Debugging

• Restart HA.
• In the climate interface, change the temperature or mode.
• In Developer Tools → MQTT or Z2M logs, check for publications to zigbee2mqtt/ir_livingroom/set.
• LED flashing on the ZS05 and device response confirm success.

Key Points

• Use the exact topic /{friendly_name}/set/ir_code_to_send in controller_data.
• Convert codes to Raw MQTT for compatibility with the ZS05.
• Match device_code by protocol, testing on similar models.
• Z2M and MQTT logs are the primary debugging tools.
• Zigbee2MQTT is more stable than ZHA for IR controllers.

— Editorial Team