haier-esphome

The communication between the Haier air conditioner and the ESP follows a specific packet structure. For hOn devices, the flags byte is typically 0x40 (indicating a CRC16 checksum is present), whereas smartAir2 devices use 0x00 (no CRC16).

Packet Structure

• FF FF: Packet start indicator
• 1 byte: Length
• 1 byte: Flags
• 5 bytes: Reserved (usually zeros for hOn; zeros with 01 at the end for smartAir2)
• 1 byte: Packet type
• n bytes: Data
• 1 byte: Checksum (modulo 256 sum of all packet bytes)
• 2 bytes: CRC16 (if specified by flags)

Packet Types (hOn focus)

Requests typically use odd IDs, and responses use even IDs:

• 0x01: Status request or control
• 0x02: Status response

Common Subcommands (Data for type 0x01)

• 0x4D01: Request normal data
• 0x4DFE: Request extended data (big data)
• 0x5C01: Send state to the air conditioner (control)

To debug or view complete packets, enable logs at the VERBOSE level in ESPHome.

The Haier ESPHome component controls HVAC units using either the smartair2 or hOn protocols. Hardware requirements depend on your AC model:

Older Models (SmartAir2 / KZW-W002)

These models use a KZW-W002 module that cannot be reused. You must replace it with an ESP8266, ESP32, or RPi Pico W. The USB connector on the original board is actually a UART port. You can connect your new ESP board by cutting a USB Type-A cable and wiring it to the climate connector.

Haier UART Pinout (KZW-W002):

Newer Models (hOn / ESP32-for-Haier)

These use an ESP32-based module.

⚠️ WARNING: Some newer ESP32-Haier modules have encryption enabled. If you attempt to flash these with ESPHome, the board will enter a boot loop with the error: rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT). These boards cannot be used with ESPHome. Always create a backup image before experimenting. If you use a different ESP32/ESP8266/Pico W, you will need to use the JST SM04B-GHS-TB connector or modify the original wiring.

The Haier Climate component provides several triggers to react to AC state changes or incoming status packets. These triggers can be used within ESPHome automation blocks (e.g., on_...: then:) and allow access to specific variables via lambdas.

on_alarm_start

Triggered when a new alarm is activated by the AC.

• Variables available:
  • code (uint8_t): The error code of the alarm.
  • message (const char *): The error message.

on_alarm_end

Triggered when a previously active alarm is deactivated.

• Variables available:
  • code (uint8_t): The error code of the alarm.
  • message (const char *): The error message.

on_status_message

Triggered when the component receives a new status packet from the AC. This is useful for implementing model-specific features not covered by standard components.

• Variables available:
  • data (const char *): Raw message binary (excluding header and checksum).
  • data_size (uint8_t): Length of the message.

climate:
  - protocol: hon
    on_alarm_start:
      then:
        - logger.log:
            level: WARN
            format: "Alarm activated. Code: %d. Message: \"%s\""
            args: [ 'code', 'message' ]

    on_status_message:
      then:
        - logger.log:
            level: INFO
            format: "New status message received, size=%d, subcmd=%02X%02X"
            args: [ 'data_size', 'data[0]', 'data[1]' ]

The haier climate platform allows you to control Haier HVAC units using either the older smartair2 protocol or the newer hon protocol. This component requires a configured UART Bus to communicate with the AC unit.

Hardware Requirements

• Older models (SmartAir2): These use the KZW-W002 module. This module cannot be reused; you must replace it with an ESP8266, ESP32, or RPI Pico W. You can connect your ESP board by cutting a USB type A cable and wiring it to the climate connector.
• Newer models (hOn): These use an ESP32-for-Haier module.
  • Warning: Some newer modules have encryption enabled. If you attempt to flash these with ESPHome, the board will enter a boot loop with the error rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT). You must flash the original image to recover. Always make a backup before experimenting.
• Alternative Boards: You can use any ESP32, ESP8266, or RPI Pico W. If using these, you may need to use the JST SM04B-GHS-TB connector or custom wiring.

UART Pinout (KZW-W002 to ESP8266)

# Example configuration entry
climate:
  - platform: haier
    id: haier_ac
    protocol: hon
    name: Haier AC
    uart_id: ac_port
    wifi_signal: true
    display: true
    visual:
      min_temperature: 16 °C
      max_temperature: 30 °C
      temperature_step: 1 °C
    supported_modes:
    - 'OFF'
    - HEAT_COOL
    - COOL
    - HEAT
    - DRY
    - FAN_ONLY
    supported_swing_modes:
    - 'OFF'
    - VERTICAL
    - HORIZONTAL
    - BOTH
    supported_presets:
    - AWAY
    - BOOST
    - SLEEP
    on_alarm_start:
      then:
        - logger.log:
            level: WARN
            format: "Alarm activated. Code: %d. Message: \"%s\""
            args: [ code, message]
    on_alarm_end:
      then:
        - logger.log:
            level: INFO
            format: "Alarm deactivated. Code: %d. Message: \"%s\""
            args: [ code, message]
    on_status_message:
      then:
        - logger.log:
            level: INFO
            format: "New status message received, size=%d, subcmd=%02X%02X"
            args: [ 'data_size', 'data[0]', 'data[1]' ]

A complete configuration for a Haier hOn device includes advanced features such as visual temperature constraints, supported modes, swing modes, presets, alarm automation, and integration with other components like buttons, sensors, and switches.

Key configuration options include:

• uart_id: Links the climate component to a specific UART instance.
• wifi_signal: Enables WiFi signal strength reporting.
• visual: Defines min_temperature, max_temperature, and temperature_step (for both target_temperature and current_temperature).
• supported_modes: List of operational modes (e.g., OFF, HEAT_COOL, COOL, HEAT, DRY, FAN_ONLY).
• supported_swing_modes: List of swing directions (e.g., OFF, VERTICAL, HORIZONTAL, BOTH).
• supported_presets: List of presets (e.g., BOOST, SLEEP).
• on_alarm_start / on_alarm_end: Automation triggers that provide alarm_code and alarm_message via lambdas.

uart:
  baud_rate: 9600
  tx_pin: 17
  rx_pin: 16
  id: haier_uart

api:
  services:
    - service: turn_on
      then:
      - climate.haier.power_on: haier_ac
    - service: turn_off
      then:
      - climate.haier.power_off: haier_ac

climate:
  - platform: haier
    id: haier_ac
    protocol: hon
    name: Haier hOn Climate
    uart_id: haier_uart
    wifi_signal: true
    visual:
      min_temperature: 16 °C
      max_temperature: 30 °C
      temperature_step: 
        target_temperature: 1
        current_temperature: 0.5
    supported_modes:
      - 'OFF'
      - HEAT_COOL
      - COOL
      - HEAT
      - DRY
      - FAN_ONLY
    supported_swing_modes:
      - 'OFF'
      - VERTICAL
      - HORIZONTAL
      - BOTH
    supported_presets:
      - BOOST
      - SLEEP
    on_alarm_start:
      then:
        - homeassistant.service:
            service: logbook.log
            data:
              domain: climate
              name: Haier hOn Climate
            data_template:
              message: "Alarm activated ({{ alarm_code }}): {{alarm_message}}" 
            variables:
              alarm_message: !lambda "return message;"
              alarm_code: !lambda "return code;"
    on_alarm_end:
      then:
        - homeassistant.service:
            service: logbook.log
            data:
              domain: climate
              name: Haier hOn Climate
            data_template:
              message: "Alarm deactivated ({{ alarm_code }}): {{alarm_message}}" 
            variables:
              alarm_message: !lambda "return message;"
              alarm_code: !lambda "return code;"