{"id":27173769,"url":"https://github.com/lumixen/esphome-hlink-ac","last_synced_at":"2026-02-28T20:05:03.851Z","repository":{"id":283659970,"uuid":"952169539","full_name":"lumixen/esphome-hlink-ac","owner":"lumixen","description":"A climate component for ESPHome to control Hitachi AC units using the H-Link serial protocol","archived":false,"fork":false,"pushed_at":"2026-02-28T12:27:58.000Z","size":98,"stargazers_count":31,"open_issues_count":0,"forks_count":7,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-02-28T16:24:44.521Z","etag":null,"topics":["airconditioner","airconditioning","esp32","esp32-arduino","esphome","esphome-component","h-link","heatpumps","hi-kumo","hitachi","home-assistant"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lumixen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-20T21:01:16.000Z","updated_at":"2026-02-28T12:27:54.000Z","dependencies_parsed_at":"2025-05-05T11:23:34.393Z","dependency_job_id":"377ce5cf-78c8-4478-bfc9-af500b0e2614","html_url":"https://github.com/lumixen/esphome-hlink-ac","commit_stats":null,"previous_names":["lumixen/esphome-hlink-ac"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/lumixen/esphome-hlink-ac","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lumixen%2Fesphome-hlink-ac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lumixen%2Fesphome-hlink-ac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lumixen%2Fesphome-hlink-ac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lumixen%2Fesphome-hlink-ac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lumixen","download_url":"https://codeload.github.com/lumixen/esphome-hlink-ac/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lumixen%2Fesphome-hlink-ac/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29951115,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T18:42:55.706Z","status":"ssl_error","status_checked_at":"2026-02-28T18:42:48.811Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["airconditioner","airconditioning","esp32","esp32-arduino","esphome","esphome-component","h-link","heatpumps","hi-kumo","hitachi","home-assistant"],"created_at":"2025-04-09T11:23:22.707Z","updated_at":"2026-02-28T20:05:03.843Z","avatar_url":"https://github.com/lumixen.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Overview\n\nThis ESPHome component is designed to control compatible Hitachi air conditioners using serial H-Link protocol. It serves as a replacement for proprietary cloud-based [SPX-WFGXX cloud adapters](https://www.hitachiaircon.com/ranges/iot-apps-controllers/ac-wifi-adapter-aircloud-home), enabling native Home Assistant climate integration through ESPHome. The list of supported AC units appears to be quite extensive. Several examples of this project's adoption can be found in the [hardware implementation examples list](#hardware-implementation-examples).\n\n## Table of Contents\n\n- [H-link protocol](#h-link-protocol)\n- [Hardware](#hardware)\n- [ESPHome configuration](#esphome-configuration)\n  - [LibreTiny configuration](#libretiny-configuration)\n  - [Supported features](#supported-features)\n- [H-link protocol reverse engineering](#h-link-protocol-reverse-engineering)\n  - [Debug sensors](#debug-sensors)\n  - [Debug discovery sensor](#debug-discovery-sensor)\n  - [Actions and triggers](#actions-and-triggers)\n- [Building locally](#building-locally)\n- [Credits](#credits)\n- [Hardware implementation examples](#hardware-implementation-examples)\n\n## H-link protocol\n\nH-link is a serial protocol designed to enable communication between climate units and external adapters, such as a central station managing multiple climate devices in commercial buildings or SPX-WFGXX cloud adapters. It allows reading the status of a climate unit and send commands to control it.\n\nThe protocol supports two types of communication frames:\n1. Status inquiry from adapter, initiated with the `MT` prefix:\n```\n\u003e\u003e MT P=XXXX C=YYYY\n\u003c\u003c OK P=XXXX C=YYYY\n```\nwhere `MT P=XXXX` is 16-bit numerical command and `C=YYYY` is a 16-bit XOR checksum. The AC unit returns `OK P=XXXX`, where `XXXX` is the dynamic-length value of the requested \"feature\" (e.g. power state, climate mode, swing mode etc).\n\n2. Status change request, initiated with the `ST` prefix:\n```\n\u003e\u003e ST P=XXXX,XX(XX) C=YYYY\n\u003c\u003c OK\n``` \nwhere `P=XXXX,XX(XX)` specifies the function to modify and the new value, `C=YYYY` - 16-bit XOR checksum. The response `OK` confirms successful execution.\n\n## Hardware\n\nFor my Hitachi RAK-25PEC, I used the Lolin D32 ESP32 dev board.\n\nThe H-Link port, often referred to as `CN7` in Hitachi manuals, operates at 5V logic levels and provides a 12V power line. Therefore, you need to step down the 12V power lane to 5V for the ESP dev board 5V input and use a 3.3V-to-5V logic level shifter for the Tx/Rx communication lines:\n\n\u003cimg width=\"350\" alt=\"hlink_connector\" src=\"https://github.com/user-attachments/assets/fbedf5c1-f7b6-42a3-8e0d-7b35d1b10b6c\" /\u003e\n\nAn example of wiring diagram with cheapo aliexpress building blocks that worked for me (pay attention to the h-link control line on pin 6, it should be connected to ground):\n\n\u003cimg width=\"500\" alt=\"wiring_diagram\" src=\"https://github.com/user-attachments/assets/2cb0cb2e-880b-4b07-accb-a8271d7da15c\" /\u003e\n\nH-link connector is a JST 6-pin PA-6P-TOP with 2.0 mm pitch. \n\n\u003cimg width=\"135\" alt=\"image\" src=\"https://github.com/user-attachments/assets/7b9b47dd-26e3-4733-a2ff-2601d4fdb389\" /\u003e\n\nIf you're struggling to find a female connector in your local shop (like I did), you can find a similar 6-pin connector with 2.0mm pitch and do some shaping with a needle file. I managed to adapt a HY2.0 plug:\n\n\u003cimg width=\"360\" alt=\"image\" src=\"https://github.com/user-attachments/assets/c3a940ff-2fc4-4db0-8c6e-d144ddded614\" /\u003e\n\nMy AC unit had more than enough space to fit the dev board inside.\n\n\u003cimg width=\"250\" alt=\"image\" src=\"https://github.com/user-attachments/assets/55a9ab5a-a88e-4778-b0ce-15a5f2e5225c\" /\u003e\n\u003cimg width=\"299\" alt=\"image\" src=\"https://github.com/user-attachments/assets/035ad807-4ec6-48c6-948b-3311f392a0a6\" /\u003e\n\u003cimg width=\"236\" alt=\"image\" src=\"https://github.com/user-attachments/assets/af76570f-3b65-477b-97b3-73b63646a645\" /\u003e\n\n**Be very careful when working with wiring. Always disconnect the AC from the mains before performing any manipulations. Double-check the pinout and voltages to prevent damage to the electronics.**\n\n## ESPHome configuration\n\n```yml\nesphome:\n  name: \"hitachi-ac\"\n\nesp32:\n  board: XXXX # Replace with the valid board.\n  framework:\n    type: esp-idf\n\nuart:\n  id: hitachi_bus\n  tx_pin: GPIOXX\n  rx_pin: GPIOXX\n  baud_rate: 9600\n  parity: ODD\n\nexternal_components:\n  - source:\n      type: git\n      url: https://github.com/lumixen/esphome-hlink-ac.git\n      ref: 2026.02.0\n    components: [hlink_ac]\n\nclimate:\n  - platform: hlink_ac\n    name: \"SNXXXXXX\"\n    hvac_actions: true # Remove or set to false if you don't need HVAC actions.\n    supported_presets: # Presets are disabled by default. Remove this if your AC does not support Leave Home mode.\n      - AWAY\n    supported_swing_modes: # Could be removed if your AC does not support horizontal swinging. By default only vertical mode is exposed.\n      - \"OFF\"\n      - VERTICAL\n      - HORIZONTAL\n      - BOTH\n\nswitch:\n  - platform: hlink_ac\n    remote_lock:\n      name: Remote Lock\n    beeper:\n      name: Beeper\n\nsensor:\n  - platform: hlink_ac\n    auto_target_temp_offset:\n      name: Auto Mode Temp Offset\n  - platform: hlink_ac\n    outdoor_temperature:\n      name: Outdoor Temperature # Available only when device is active\n\nbinary_sensor:\n  - platform: hlink_ac\n    air_filter_warning:\n      name: Air Filter Cleaning Required\n\nbutton:\n  - platform: hlink_ac\n    reset_air_filter_warning:\n      name: \"Reset Air Filter Warning\"\n\ntext_sensor:\n  - platform: hlink_ac\n    model_name:\n      name: Model\n\nnumber:\n  - platform: hlink_ac\n    auto_target_temperature_offset:\n      name: Auto Mode Temp Offset\n```\n\nWithout additional configuration the `hlink_ac` climate device provides all features supported by h-link protocol. If your device does not support some climate traits, you can adjust the ESPHome configuration explicitly:\n\n```yml\nclimate:\n  - platform: hlink_ac\n    name: \"SNXXXXXX\"\n    supported_modes:\n      - \"OFF\"\n      - COOL\n    supported_swing_modes:\n      - \"OFF\"\n      - VERTICAL\n      - HORIZONTAL\n      - BOTH\n    supported_fan_modes:\n      - AUTO\n      - LOW\n      - HIGH\n    visual:\n      min_temperature: 16.0\n      max_temperature: 28.0\n```\n\n### LibreTiny configuration\n\nAs of mid-2025, LibreTiny is known to have issues with its serial stack implementation, which may [completely corrupt the UART RX buffer](https://github.com/lumixen/esphome-hlink-ac/issues/25). A possible workaround is to use the patched `RingBuffer` implementation:\n```yml\nesphome:\n  name: hitachi-ac\n  friendly_name: hitachi-ac\n  platformio_options:\n    platform_packages:\n      - framework-arduino-api @ https://github.com/hn/ArduinoCore-API#RingBufferFix\n      # https://github.com/libretiny-eu/libretiny/issues/154\n```\n\n### Supported features:\n1. Climate\n    - HVAC mode:\n      - `OFF`\n      - `HEAT`\n      - `COOL`\n      - `DRY`\n      - `FAN_ONLY`\n      - `HEAT_COOL`\n    - Fan mode:\n      - `QUIET`\n      - `LOW`\n      - `MEDIUM`\n      - `HIGH`\n      - `AUTO`\n    - Swing mode:\n      - `OFF`\n      - `VERTICAL`\n      - `HORIZONTAL`\n      - `BOTH`\n    - HVAC actions:\n      - `OFF`\n      - `COOLING`\n      - `HEATING`\n      - `DRYING`\n      - `FAN`\n    - Presets:\n      - `AWAY`  \n2. Switch\n    - Remote IR control lock\n    - Beeper sounds\n3. Sensor\n    - Outdoor temperature\n    - Temperature offset in auto mode\n4. Binary Sensor\n    - Indoor unit air filter cleaning reminder\n5. Text sensor\n    - Model name\n    - Debug\n    - Debug discovery\n6. Number\n    - Temperature offset in auto mode\n7. Button\n    - Reset indoor unit air filter cleaning reminder\n\n## H-link protocol reverse engineering\n\nThe H-link specifications are not publicly available, and this component was developed using reverse-engineered data. As a result, it may not cover all possible scenarios and combinations of features offered by different Hitachi climate devices.\n\nIf you are interested in exploring the protocol communication on your own, this component provides several text sensors to help monitor H-link addresses dynamically. \n\n### Debug sensors\n\nFor instance, you can add multiple `debug` text sensors that will be polled repeatedly:\n\n```yaml\ntext_sensor:\n  - platform: hlink_ac\n    debug:\n      name: P0005\n      address: 0x0005\n  - platform: hlink_ac\n    debug:\n      name: P0201\n      address: 0x0201\n```\n\nEach sensor sends an `MT P=address C=XXXX` request. If the unit returns an `OK` response with a payload, it will be rendered as a text sensor value. For example, the address `0201` most likely returns [error codes](https://github.com/lumixen/esphome-hlink-ac/blob/main/docs/hlink_alarm_codes.csv) if something is wrong with the AC. However, I haven't yet seen reliable proof to add it as an established sensor (fortunately I guess). Debug sensors can help monitor unknown addresses and their behavior throughout the Hitachi unit lifecycle.\n\n### Debug discovery sensor\n\nAnother helpful debug text sensor is called `debug_discovery`. It repeatedly scans the entire range of addresses (0-65535) and prints every non-NG response as a text sensor value (e.g., `0001:8010`/`0304:00000000`/`0302:00`), where the value before the colon is the polled address (P=XXXX), and the value after the colon is the response from the AC. The full range scan takes more than a few hours.\n\n```yaml\ntext_sensor:\n  - platform: hlink_ac\n    debug_discovery:\n      id: debug_discovery_sensor\n      name: H-link addresses scanner\n```\n\nSince scanning should not begin before the device connects to Home Assistant, debug discovery must be started using the `text_sensor.hlink_ac.start_debug_discovery` action and can be stopped with the `text_sensor.hlink_ac.stop_debug_discovery` action. You can tie these actions to Wi-Fi connection events or control them manually through template buttons, for example:\n\n```yaml\nbutton:\n  - platform: template\n    name: \"Start debug discovery\"\n    on_press:\n      then:\n        - text_sensor.hlink_ac.start_debug_discovery:\n            id: debug_discovery_sensor\n  - platform: template\n    name: \"Stop debug discovery\"\n    on_press:\n      then:\n        - text_sensor.hlink_ac.stop_debug_discovery:\n            id: debug_discovery_sensor\n```\n\n### Actions and triggers\n\nDebug sensors can be paired with the `hlink_ac.send_hlink_cmd` action, which allows you to directly send `MT P=address C=XXXX` or `ST P=address,value C=XXXX` frames to AC. Below is an example of an ESPHome configuration that connects to an MQTT broker and sends H-link commands upon receiving JSON MQTT messages like:\n```json\n{\n  \"messages\": [\n    {\"cmd_type\": \"ST\", \"address\": \"0006\", \"data\": \"01\"},\n    {\"cmd_type\": \"MT\", \"address\": \"0006\"}\n  ]\n}\n```\n in the `hlink_ac/send_hlink_frame` topic:\n```yaml\nmqtt:\n  broker: 1.1.1.1\n  ...\n  on_json_message:\n    topic: hlink_ac/send_hlink_frame\n    then:\n      - lambda: |-\n          if (x[\"messages\"].is\u003cJsonArrayConst\u003e()) {\n            for (auto message : x[\"messages\"].as\u003cJsonArrayConst\u003e()) {\n              std::string cmd_type = \"\";\n              std::string address = \"\";\n              optional\u003cstd::string\u003e data = {};\n              if (message[\"cmd_type\"].is\u003cconst char*\u003e()) {\n                cmd_type = std::string(message[\"cmd_type\"].as\u003cconst char*\u003e());\n              }\n              if (message[\"address\"].is\u003cconst char*\u003e()) {\n                address = std::string(message[\"address\"].as\u003cconst char*\u003e());\n              }\n              if (message[\"data\"].is\u003cconst char*\u003e()) {\n                data = std::string(message[\"data\"].as\u003cconst char*\u003e());\n              }\n              id(hitachi_ac).send_hlink_cmd(cmd_type, address, data);\n            }\n          }\n```\n\nThe `send_hlink_cmd` results can be handled using the `on_send_hlink_cmd_result` trigger. For example with MQTT you can use the hlink device essentially as a low level proxy for h-link communication:\n```yaml\nclimate:\n  - platform: hlink_ac\n    ...\n    on_send_hlink_cmd_result:\n      then:\n        - mqtt.publish:\n            topic: hlink_ac/send_hlink_frame_result\n            payload: !lambda |-\n              JsonDocument doc;\n              doc[\"result_status\"] = result.result_status;\n              doc[\"request_address\"] = result.request_address;\n              if (result.request_data.has_value())\n                doc[\"request_data\"] = result.request_data.value();\n              if (result.response_data.has_value())\n                doc[\"response_data\"] = result.response_data.value();\n              std::string out;\n              serializeJson(doc, out);\n              return out;\n```\n\nH-link UART serial communication could be monitored using this snippet:\n\n```yaml\nuart:\n  id: hitachi_bus\n  tx_pin: GPIOXX\n  rx_pin: GPIOXX\n  baud_rate: 9600\n  parity: ODD\n  debug:\n    direction: BOTH\n    dummy_receiver: false\n    after:\n      delimiter: \"\\n\"\n    sequence:\n      - lambda: UARTDebug::log_string(direction, bytes);\n```\n\n## Building locally\n\nProject includes a test [dev configurations](build/) that can be used for compilation.\nRun from the project root folder (docker is required):\n```bash\ncd build/\n./compile\n```\n\n## Credits\n\n- Florian did a fantastic detective investigation to reverse engineer H-Link connection in his [Let me control you: Hitachi air conditioner](https://hackaday.io/project/168959-let-me-control-you-hitachi-air-conditioner) hackaday project.\n- More protocol sniffing in Vince's [hackaday project](https://hackaday.io/project/179797-hitachi-hvac-controler-for-homeassistant-esp8266)\n- [hi-arduino project](https://github.com/farom57/hi-arduino/)\n\n## Hardware implementation examples\n- [RAS-70YHA2](https://github.com/shardshunt/H-Link-Docks)\n- [RAK-DJ18RHAE](https://github.com/lumixen/esphome-hlink-ac/discussions/10#discussioncomment-13095591)\n- [Flashing native Hitachi AirHome 400 module RAK-DJ18RH/RAK-DJ50RH](https://github.com/clsergent/hitachi_altwifi)\n- [RAK-25PEC](#hardware)\n- [RAK-18RPD](https://github.com/lumixen/esphome-hlink-ac/discussions/24)\n- [RAK-18RPE](https://community.home-assistant.io/t/hitachi-ac-h-link-with-esphome/869303/11)\n- [RAF-50RXE](https://community.home-assistant.io/t/hitachi-ac-h-link-with-esphome/869303/12)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flumixen%2Fesphome-hlink-ac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flumixen%2Fesphome-hlink-ac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flumixen%2Fesphome-hlink-ac/lists"}