{"id":49994177,"url":"https://github.com/thozza/homeassistant-atrea-rd5-modbus","last_synced_at":"2026-05-19T06:44:14.149Z","repository":{"id":354047152,"uuid":"1039265283","full_name":"thozza/homeassistant-atrea-rd5-modbus","owner":"thozza","description":"Homeassistant integration for Atrea RD5 Ventilation via Modbus TCP","archived":false,"fork":false,"pushed_at":"2026-04-26T21:17:33.000Z","size":719,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T23:21:01.856Z","etag":null,"topics":["atrea","hacs","home-assistant","modbus"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thozza.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-08-16T20:45:34.000Z","updated_at":"2026-04-26T21:17:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thozza/homeassistant-atrea-rd5-modbus","commit_stats":null,"previous_names":["thozza/homeassistant-atrea-rd5-modbus"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/thozza/homeassistant-atrea-rd5-modbus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thozza%2Fhomeassistant-atrea-rd5-modbus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thozza%2Fhomeassistant-atrea-rd5-modbus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thozza%2Fhomeassistant-atrea-rd5-modbus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thozza%2Fhomeassistant-atrea-rd5-modbus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thozza","download_url":"https://codeload.github.com/thozza/homeassistant-atrea-rd5-modbus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thozza%2Fhomeassistant-atrea-rd5-modbus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33204738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"online","status_checked_at":"2026-05-19T02:00:06.763Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["atrea","hacs","home-assistant","modbus"],"created_at":"2026-05-19T06:44:13.374Z","updated_at":"2026-05-19T06:44:14.140Z","avatar_url":"https://github.com/thozza.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"icon@2x.png\" alt=\"homeassistant-atrea-rd5-modbus\" width=\"200\"\u003e\n\u003c/p\u003e\n\n# Atrea RD5 Modbus — Home Assistant Integration\n\n[![CI](https://github.com/thozza/homeassistant-atrea-rd5-modbus/actions/workflows/ci.yml/badge.svg)](https://github.com/thozza/homeassistant-atrea-rd5-modbus/actions/workflows/ci.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\nMonitor and control your **Atrea RD5 ventilation unit** from Home Assistant using Modbus TCP.\n\n## Features\n\n- 🌡️ **5 temperature sensors**: outdoor air (T-ODA), supply air (T-SUP), extract air (T-ETA), exhaust air (T-EHA), indoor air (T-IDA)\n- 🔄 **Ventilation mode**: tracks current mode (Off / Automatic / Ventilation / Circulation / Night cooling / ...)\n- 💨 **Ventilation power**: current requested fan power (0–100%)\n- 🌐 **BMS temperature source selects**: choose between internal sensor or BMS-supplied value for T-ODA and T-IDA\n- 📡 **BMS setpoint write**: push outdoor / indoor temperature values from HA automations to the HVAC\n- 🍂 **Heating season control**: view the active season (Heating / Non-heating), configure the switching mode (TS / NTS / T-TODA / T-TODA+), and set the temperature threshold\n- Efficient batch Modbus reads — consecutive registers are merged into a single Modbus request per poll cycle\n- Zero-YAML setup via Home Assistant UI config flow\n- Configurable poll interval (5–300 s) editable post-setup without re-adding the integration\n\n## Requirements\n\n- Home Assistant 2024.1.0 or newer\n- Atrea RD5 unit with Modbus TCP enabled and accessible on the network (default port: 502)\n- Python package `pymodbus \u003e= 3.10.0` (installed automatically by HA)\n\n## Installation\n\n### Manual\n\n1. Copy the `custom_components/atrea_rd5_modbus/` folder into your Home Assistant config directory:\n   ```\n   \u003cconfig\u003e/custom_components/atrea_rd5_modbus/\n   ```\n2. Restart Home Assistant.\n3. Go to **Settings → Devices \u0026 Services → Add Integration**.\n4. Search for **Atrea RD5 Modbus** and follow the setup wizard.\n\n### HACS\n\n1. In HACS, go to **Integrations → ⋮ → Custom repositories**.\n2. Add `https://github.com/thozza/homeassistant-atrea-rd5-modbus` as type **Integration**.\n3. Click **Download** on the Atrea RD5 Modbus card.\n4. Restart Home Assistant.\n5. Go to **Settings → Devices \u0026 Services → Add Integration** and search for **Atrea RD5 Modbus**.\n\n## Configuration\n\nThe integration is configured entirely through the UI. During setup you will be asked for:\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| Host | — | IP address of the Atrea RD5 device |\n| Port | `502` | Modbus TCP port |\n| Unit ID | `1` | Modbus unit ID |\n| Scan interval | `30` | Poll frequency in seconds |\n\nThe connection is validated before the entry is saved — if the device is unreachable an error is shown in the form.\n\n## Entities\n\n| Entity | Unit | Description |\n|--------|------|-------------|\n| T-ODA Outdoor Air | °C | Outdoor air temperature (sensor T-ODA) |\n| T-SUP Supply Air | °C | Supply air temperature after heat recovery (sensor T-SUP) |\n| T-ETA Extract Air | °C | Room exhaust air entering the unit (sensor T-ETA) |\n| T-EHA Exhaust Air | °C | Air leaving the unit to the outside (sensor T-EHA) |\n| T-IDA Indoor Air | °C | Indoor/room air temperature (sensor T-IDA) |\n| Ventilation Power | % | Current requested ventilation fan power (0–100%) |\n| Ventilation Mode | — | Current operation mode (Off, Automatic, Ventilation, Circulation, ...) |\n| T-ODA Source | — | Select: choose outdoor temp source (Internal / BMS) |\n| T-IDA Source | — | Select: choose indoor temp source (CP / T-ETA / TRKn / BMS) |\n| BMS T-ODA Setpoint | °C | BMS-supplied outdoor temp (write-only, −50–130 °C) |\n| BMS T-IDA Setpoint | °C | BMS-supplied indoor temp (write-only, −50–130 °C) |\n| Heating Season | — | Current season state (Heating / Non-heating) — diagnostic |\n| Season Switch Mode | — | Select: season switching logic (TS / NTS / T-TODA / T-TODA+) |\n| Season Temperature Threshold | °C | Outdoor temp threshold for automatic season switching (0–30 °C) |\n\n## BMS Setpoints (T-ODA / T-IDA from external sensors)\n\nThe Atrea RD5 can use temperatures supplied by Home Assistant in place\nof its own outdoor (T-ODA) or indoor (T-IDA) sensors. This integration\nexposes the relevant device registers as four entities:\n\n| Entity | Type | Purpose |\n|--------|------|---------|\n| `select.atrea_rd5_t_oda_source` | select | Choose internal sensor or BMS-supplied T-ODA |\n| `select.atrea_rd5_t_ida_source` | select | Choose CP / T-ETA / TRKn / BMS for T-IDA |\n| `number.atrea_rd5_bms_t_oda_setpoint` | number | T-ODA value pushed to the HVAC |\n| `number.atrea_rd5_bms_t_ida_setpoint` | number | T-IDA value pushed to the HVAC |\n\n### 90-second watchdog\n\nThe HVAC declares a temperature-sensor fault if a BMS-sourced value is\nnot refreshed within **90 seconds**. The integration writes to the\ndevice every time the number entity is set, but it does **not** run an\ninternal periodic push — that's left to your automation. Keep your\nupdate cadence comfortably below 90 s (we recommend ≤60 s).\n\nAfter a Home Assistant restart, each BMS setpoint number entity\nrestores its last known value and immediately writes it back to the\nHVAC, so the watchdog window starts fresh before your automation's\nnext trigger.\n\n### Example automation\n\n```yaml\nautomation:\n  - alias: \"Atrea: push outdoor temperature from weather sensor\"\n    trigger:\n      - platform: time_pattern\n        seconds: \"/30\"\n    action:\n      - service: number.set_value\n        target:\n          entity_id: number.atrea_rd5_bms_t_oda_setpoint\n        data:\n          value: \"{{ states('sensor.outdoor_temperature') | float }}\"\n```\n\nPair this with `select.atrea_rd5_t_oda_source` set to `BMS` so the\nHVAC actually consumes the supplied value.\n\n## Heating Season\n\nThe Atrea RD5 can switch between heating season (TS) and non-heating\nseason (NTS) automatically or on demand. This integration exposes three\nentities for this feature:\n\n| Entity | Type | Purpose |\n|--------|------|---------|\n| `sensor.atrea_rd5_heating_season` | sensor | Read-only diagnostic: current season (Heating / Non-heating) |\n| `select.atrea_rd5_season_switch_mode` | select | Configure the switching mode: TS / NTS / T-TODA / T-TODA+ |\n| `number.atrea_rd5_season_temperature_threshold` | number | Outdoor temp threshold used by the T-TODA / T-TODA+ modes (0–30 °C) |\n\n**Switching modes:**\n\n| Mode | Behaviour |\n|------|-----------|\n| `TS` | Force heating season |\n| `NTS` | Force non-heating season |\n| `T-TODA` | Auto: switch to NTS when T-ODA ≥ threshold |\n| `T-TODA+` | Auto with hysteresis: switch to NTS when T-ODA ≥ threshold, back to TS when T-ODA falls below it |\n\n### Polling interval\n\nThe polling interval (default 30 s) is editable post-setup via\n**Configure** on the integration tile in **Settings → Devices \u0026\nServices**. Allowed range: 5–300 s.\n\n## Architecture\n\nThe integration uses a single `DataUpdateCoordinator` (`AtreaCoordinator`) that owns a persistent `AsyncModbusTcpClient` TCP connection. On each poll cycle, registers are read in **contiguous batches** — consecutive same-type addresses are merged into a single Modbus request automatically. This minimises network round-trips and scales well as more sensors are added.\n\n```\ncustom_components/atrea_rd5_modbus/\n├── __init__.py       # Integration setup, coordinator + client lifecycle\n├── coordinator.py    # DataUpdateCoordinator, batched Modbus reads\n├── const.py          # Register map, signed10() conversion, batch grouping\n├── sensor.py         # 8 read-only sensor entities (temperatures, power, mode, season)\n├── select.py         # 3 select entities (T-ODA / T-IDA source, season switch mode)\n├── number.py         # 3 number entities (BMS setpoints, season temp threshold)\n└── config_flow.py    # UI config flow with live connection validation\n```\n\nTo add a new sensor in the future: add one entry to `REGISTER_MAP` in `const.py` and one entry to `SENSOR_DESCRIPTIONS` in `sensor.py`. Batch grouping is recomputed automatically.\n\n## Troubleshooting\n\nEnable debug logging in `configuration.yaml`:\n\n```yaml\nlogger:\n  default: warning\n  logs:\n    custom_components.atrea_rd5_modbus: debug\n```\n\n**Common issues:**\n\n- *Cannot connect* — verify the device IP, port (default 502), and that Modbus TCP is enabled on the unit\n- *Entities unavailable* — check HA logs for Modbus errors; ensure the unit ID is correct (usually 1)\n- *Stale/missing values* — increase the scan interval if the device reports protocol errors on rapid polling\n\n## Disclaimer\n\nThis is an unofficial community integration. It is not sponsored by, affiliated with, or endorsed by ATREA s.r.o. in any way. Use it at your own risk.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthozza%2Fhomeassistant-atrea-rd5-modbus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthozza%2Fhomeassistant-atrea-rd5-modbus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthozza%2Fhomeassistant-atrea-rd5-modbus/lists"}