{"id":37702047,"url":"https://github.com/uspass/hysen2pfc","last_synced_at":"2026-01-16T13:00:54.933Z","repository":{"id":305257696,"uuid":"391907158","full_name":"uspass/hysen2pfc","owner":"uspass","description":"Support for Hysen 2 Pipe Fan Coil Controller. Hysen HY03AC-1-Wifi device and derivative.","archived":false,"fork":false,"pushed_at":"2025-08-15T21:45:40.000Z","size":182,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-15T23:38:37.375Z","etag":null,"topics":["airconditioning","home-assistant","home-automation","homeassistant","hysen","thermostat-controller"],"latest_commit_sha":null,"homepage":"","language":"Python","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/uspass.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}},"created_at":"2021-08-02T10:34:07.000Z","updated_at":"2025-08-15T21:38:56.000Z","dependencies_parsed_at":"2025-07-19T07:00:37.300Z","dependency_job_id":"815de674-b159-4e54-ac9c-afd677e829f1","html_url":"https://github.com/uspass/hysen2pfc","commit_stats":null,"previous_names":["uspass/hysen2pfc"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/uspass/hysen2pfc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uspass%2Fhysen2pfc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uspass%2Fhysen2pfc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uspass%2Fhysen2pfc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uspass%2Fhysen2pfc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uspass","download_url":"https://codeload.github.com/uspass/hysen2pfc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uspass%2Fhysen2pfc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478886,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: 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":["airconditioning","home-assistant","home-automation","homeassistant","hysen","thermostat-controller"],"created_at":"2026-01-16T13:00:54.056Z","updated_at":"2026-01-16T13:00:54.919Z","avatar_url":"https://github.com/uspass.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hysen 2 Pipe Fan Coil Controller Integration for Home Assistant\n\nThis Home Assistant integration provides support for the Hysen HY03AC-1-Wifi 2 Pipe Fan Coil Controller and its derivatives, which are based on Broadlink technology (not Tuya). It enables control and monitoring of HVAC modes, fan modes, temperature settings, scheduling, and other advanced features through Home Assistant.\n\n## Features\n\n- **Climate Control**: Supports HVAC modes (`heat`, `cool`, `fan_only`, `off`), fan modes (`low`, `medium`, `high`, `auto`), and temperature settings (10–40°C).\n- **Binary Sensor**: Monitors valve state (`open` or `closed`).\n- **Button**: Synchronizes the device time to the current system time, including seconds.\n- **Number**: Adjusts temperature calibration (-5.0 to 5.0°C) and dynamic min/max temperatures based on HVAC mode.\n- **Select**: Configures hysteresis (0.5°C or 1.0°C) and key lock (Unlocked, Locked Except Power, Locked).\n- **Sensor**: Monitors room temperature, firmware version, valve on duration, and device time/weekday.\n- **Switch**: Controls fan enable/disable, frost protection, and schedule slot enable states.\n- **Time**: Sets start/stop times for two programmable schedule slots.\n- **Advanced Features**:\n  - Key lock (Unlocked, Locked Except Power, Locked).\n  - Temperature calibration (-5.0 to 5.0°C).\n  - Hysteresis settings (0.5°C or 1.0°C).\n  - Frost protection and fan control (on/off).\n  - Weekly scheduling with two programmable time slots.\n  - Device time and weekday synchronization.\n- **Custom Services**: Provides services to set HVAC mode, fan mode, preset mode, temperature, and other device parameters.\n- **Zeroconf Discovery**: Automatically detects Hysen devices on the network using Broadlink's protocol. (work in progress)\n- **Local Polling**: Uses local network communication via Broadlink protocol for reliable control and updates.\n- **Lovelace Thermostat Card**: Integrates seamlessly with the default Home Assistant Thermostat card in Lovelace, providing a user-friendly interface to control HVAC modes, set temperatures, and adjust fan modes directly from the dashboard.\n\n## Installation\n\n1. **Via HACS (Home Assistant Community Store)**:\n   - Add this repository as a custom repository in HACS:\n     - URL: `https://github.com/uspass/hysen2pfc`\n     - Category: Integration\n   - Search for \"Hysen 2 Pipe Fan Coil\" in HACS and install it.\n   - Restart Home Assistant after installation.\n\n2. **Manual Installation**:\n   - Copy the `hysen2pfc` folder to your Home Assistant `custom_components` directory (e.g., `config/custom_components/hysen2pfc`).\n   - Restart Home Assistant.\n\n## Configuration\n\n### Via Home Assistant UI\n1. After installation, go to **Settings \u003e Devices \u0026 Services** in Home Assistant.\n2. Click **Add Integration** and search for \"Hysen 2 Pipe Fan Coil\".\n3. If the device is discovered via Zeroconf (using Broadlink protocol), confirm the device details (host, MAC, name).\n4. Alternatively, manually enter the device's IP address, MAC address, name, and timeout (default: 10 seconds).\n5. Submit the configuration to add the device.\n\n### Example Configuration\n```yaml\nhysen2pfc:\n  host: \"192.168.1.100\"\n  mac: \"00:1A:2B:3C:4D:5E\"\n  name: \"Living Room Hysen\"\n  timeout: 10\n```\n\n## Supported Platforms\n\n- **Climate**: Main entity for controlling HVAC modes, fan modes, temperature, and presets.\n- **Binary Sensor**: Valve state sensor (`open` or `closed`).\n- **Button**: Device time synchronization to current system time.\n- **Number**: Temperature calibration and dynamic min/max temperature settings based on HVAC mode.\n- **Select**: Key lock and hysteresis settings.\n- **Sensor**: Room temperature, firmware version, valve on duration, and device time/weekday.\n- **Switch**: Fan control, frost protection, and schedule slot enable states.\n- **Time**: Scheduling slots for start/stop times.\n\n## Lovelace Thermostat Card\n\nThe integration works out-of-the-box with the default Home Assistant Thermostat card in Lovelace. To add the Thermostat card to your dashboard:\n\n1. Go to your Lovelace dashboard and click **Edit Dashboard**.\n2. Click **Add Card** and select **Thermostat**.\n3. Configure the card by selecting the Hysen climate entity (e.g., `climate.living_room_hysen`).\n4. Customize the card settings as needed (e.g., show/hide fan modes or temperature controls).\n5. Save the card to display the thermostat interface, allowing you to adjust the target temperature, HVAC mode, and fan mode directly from the dashboard.\n\nExample Lovelace configuration:\n```yaml\ntype: thermostat\nentity: climate.living_room_hysen\nname: Living Room Thermostat\n```\n\n## Additional Lovelace Cards for Other Entities\n\nTo fully leverage the integration's features, you can add Lovelace cards for the additional entities:\n\n- **Entities Card for Switches and Selects**:\n  Display and control switches (e.g., fan control, frost protection, schedule slots) and select entities (e.g., key lock, hysteresis).\n  ```yaml\n  type: entities\n  entities:\n    - entity: switch.living_room_hysen_fan_control\n    - entity: switch.living_room_hysen_frost_protection\n    - entity: select.living_room_hysen_key_lock\n    - entity: select.living_room_hysen_hysteresis\n    - entity: switch.living_room_hysen_slot1_start_enable\n    - entity: switch.living_room_hysen_slot1_stop_enable\n    - entity: switch.living_room_hysen_slot2_start_enable\n    - entity: switch.living_room_hysen_slot2_stop_enable\n  title: Hysen Controls\n  ```\n\n- **Entities Card for Time Entities**:\n  Configure schedule slot start/stop times.\n  ```yaml\n  type: entities\n  entities:\n    - entity: time.living_room_hysen_slot1_start_time\n    - entity: time.living_room_hysen_slot1_stop_time\n    - entity: time.living_room_hysen_slot2_start_time\n    - entity: time.living_room_hysen_slot2_stop_time\n  title: Hysen Schedule\n  ```\n\n- **Entities Card for Sensors and Button**:\n  Monitor sensor values (e.g., valve on duration, device time) and trigger the time synchronization button.\n  ```yaml\n  type: entities\n  entities:\n    - entity: sensor.living_room_hysen_time_valve_on\n    - entity: sensor.living_room_hysen_device_time\n    - entity: button.living_room_hysen_device_time_now\n  title: Hysen Sensors\n  ```\n\n- **Number Slider for Calibration and Temperature Limits**:\n  Adjust temperature calibration and min/max temperatures.\n  ```yaml\n  type: entities\n  entities:\n    - entity: number.living_room_hysen_sensor_calibration\n      name: Calibration\n    - entity: number.living_room_hysen_max_temp\n      name: Max Temperature\n    - entity: number.living_room_hysen_min_temp\n      name: Min Temperature\n  title: Hysen Temperature Settings\n  ```\n\n## Services\n\nThe integration provides custom services to control the device. Below are some key services:\n\n- **`hysen2pfc.set_hvac_mode`**:\n  - Sets the HVAC mode (`off`, `heat`, `cool`, `fan_only`).\n  - Example:\n    ```yaml\n    service: hysen2pfc.set_hvac_mode\n    target:\n      entity_id: climate.living_room_hysen\n    data:\n      hvac_mode: heat\n    ```\n\n- **`hysen2pfc.set_fan_mode`**:\n  - Sets the fan mode (`low`, `medium`, `high`, `auto`).\n  - Example:\n    ```yaml\n    service: hysen2pfc.set_fan_mode\n    data:\n      entity_id: climate.living_room_hysen\n      fan_mode: low\n    ```\n\n- **`hysen2pfc.set_temperature`**:\n  - Sets the target temperature (10–40°C).\n  - Example:\n    ```yaml\n    service: hysen2pfc.set_temperature\n    target:\n      entity_id: climate.living_room_hysen\n    data:\n      temperature: 22\n    ```\n\n- **`hysen2pfc.set_preset_mode`**:\n  - Sets the preset mode (`Today`, `Workdays`, `Sixdays`, `Fullweek`).\n  - Example:\n    ```yaml\n    service: hysen2pfc.set_preset_mode\n    data:\n      entity_id: climate.living_room_hysen\n      preset_mode: Workdays\n    ```\n\n- **`hysen2pfc.set_time`**:\n  - Sets the device time and weekday.\n  - Example:\n    ```yaml\n    service: hysen2pfc.set_time\n    data:\n      entity_id: button.living_room_hysen_device_time_now\n      device_time: \"14:30:00\"\n      device_weekday: 1\n    ```\n\n- **`hysen2pfc.set_hysteresis`**:\n  - Sets the hysteresis value (`0.5` or `1.0`).\n  - Example:\n    ```yaml\n    service: hysen2pfc.set_hysteresis\n    data:\n      entity_id: select.living_room_hysen_hysteresis\n      hysteresis: \"0.5\"\n    ```\n\n- **`hysen2pfc.set_slot1_start_time`**:\n  - Sets the start time for schedule slot 1.\n  - Example:\n    ```yaml\n    service: hysen2pfc.set_slot1_start_time\n    data:\n      entity_id: time.living_room_hysen_slot1_start_time\n      slot1_start_time: \"08:00\"\n    ```\n\nFor a full list of services, refer to `services.yaml` in the repository.\n\n## Requirements\n\n- Home Assistant 2025.1 or later.\n- Python package: `hysen==0.4.12` (automatically installed).\n\n## Known Limitations\n\n- The integration relies on local network communication via Broadlink protocol and requires the device to be accessible on the network.\n- The `fan_only` HVAC mode is not supported when the fan mode is set to `auto`. Set the fan mode to `low`, `medium`, or `high` first.\n- The `auto` fan mode is not supported when the HVAC mode is set to `fan_only`. Set the HVAC mode to `heat` or `cool` first.\n- The integration polls the device every 30 seconds to update the state.\n- This integration is designed for Hysen devices using Broadlink protocol (e.g., HY03AC-1-Wifi). Hysen models with Tuya firmware (e.g., HY03AC-4-Wifi) are not supported.\n\n## Debugging\n\nTo enable debug logging for this integration:\n1. Add the following to your Home Assistant `configuration.yaml`:\n   ```yaml\n   logger:\n     default: info\n     logs:\n       custom_components.hysen2pfc: debug\n   ```\n2. Restart Home Assistant to apply the changes.\n\n## Contributing\n\nContributions are welcome! Please:\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature/your-feature`).\n3. Commit your changes (`git commit -m 'Add your feature'`).\n4. Push to the branch (`git push origin feature/your-feature`).\n5. Open a pull request.\n\n## Issues\n\nReport bugs or request features via the [GitHub Issues page](https://github.com/uspass/hysen2pfc/issues).\n\n## License\n\nThis integration is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Credits\n\nDeveloped by [@uspass](https://github.com/uspass). Thanks to the Home Assistant community for their support and contributions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuspass%2Fhysen2pfc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuspass%2Fhysen2pfc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuspass%2Fhysen2pfc/lists"}