{"id":36990688,"url":"https://github.com/darius1907/ha_vmc_helty_flow","last_synced_at":"2026-04-02T18:34:38.773Z","repository":{"id":326528198,"uuid":"1064134346","full_name":"darius1907/ha_vmc_helty_flow","owner":"darius1907","description":"Home assistant integration for VMC Helty flow devices","archived":false,"fork":false,"pushed_at":"2025-12-31T10:41:26.000Z","size":1228,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-04T15:39:41.874Z","etag":null,"topics":["custom-component","hacs","helty","home-assistant","home-automation","homeassistant","integration","ventilation","vmc"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/darius1907.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","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-09-25T15:33:17.000Z","updated_at":"2025-12-31T10:41:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/darius1907/ha_vmc_helty_flow","commit_stats":null,"previous_names":["darius1907/ha_vmc_helty_flow"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/darius1907/ha_vmc_helty_flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darius1907%2Fha_vmc_helty_flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darius1907%2Fha_vmc_helty_flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darius1907%2Fha_vmc_helty_flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darius1907%2Fha_vmc_helty_flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darius1907","download_url":"https://codeload.github.com/darius1907/ha_vmc_helty_flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darius1907%2Fha_vmc_helty_flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399366,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"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":["custom-component","hacs","helty","home-assistant","home-automation","homeassistant","integration","ventilation","vmc"],"created_at":"2026-01-13T23:38:58.058Z","updated_at":"2026-04-02T18:34:38.756Z","avatar_url":"https://github.com/darius1907.png","language":"Python","funding_links":["https://www.buymeacoffee.com/darius1907"],"categories":[],"sub_categories":[],"readme":"# 🌬️ VMC Helty Flow - Home Assistant Integration\n\n[![hacs][hacsbadge]][hacs]\n[![GitHub Release][releases-shield]][releases]\n[![GitHub Activity][commits-shield]][commits]\n[![License][license-shield]][license]\n\n[![Project Maintenance][maintenance-shield]][user_profile]\n[![BuyMeCoffee][buymecoffeebadge]][buymecoffee]\n\n[![Discord][discord-shield]][discord]\n[![Community Forum][forum-shield]][forum]\n\nComplete integration for Helty Flow Mechanical Ventilation (VMC) systems with Home Assistant.\n\n\u003e **🇮🇹 Versione Italiana**: [README_IT.md](README_IT.md)\n\n## 🧩 Blueprints\n\n- Blueprint catalog: [blueprints/README.md](blueprints/README.md)\n- Full guide (IT): [blueprints/BLUEPRINT_GUIDE.md](blueprints/BLUEPRINT_GUIDE.md)\n- Full guide (EN): [blueprints/BLUEPRINT_GUIDE_EN.md](blueprints/BLUEPRINT_GUIDE_EN.md)\n\n## 🚀 Quick Installation\n\n### Via HACS (Recommended)\n\n1. **Install the Integration**:\n   - Open HACS in Home Assistant\n   - Go to **Integrations**\n   - Click the **Explore \u0026 Download Repositories** button in the bottom right\n   - Search for \"**VMC Helty Flow**\"\n   - Click \"**Download**\"\n   - Restart Home Assistant\n\n   \u003e **Note**: If you can't find the integration in the search, it may take a few hours after publication. Alternatively, you can add it as a custom repository using the badge below:\n\n   [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=darius1907\u0026repository=ha_vmc_helty_flow\u0026category=integration)\n\n2. **Configure the Integration**:\n   - Go to **Settings** → **Devices \u0026 Services**\n   - Click \"**Add Integration**\"\n   - Search for \"**VMC Helty Flow**\"\n   - Follow the guided configuration procedure\n\n### Manual Installation\n\n1. Copy the `custom_components/vmc_helty_flow` folder into your `custom_components/` directory\n2. Restart Home Assistant\n3. Add the integration from the interface\n\n## ✨ Main Features\n\n### 🔍 **Advanced Device Discovery**\n\n- **Incremental Scanning**: Find and configure devices one at a time with full user control\n- **Smart Validation**: Automatic verification of subnet format, ports, and timeouts\n- **Error Management**: Informative messages and error recovery capabilities\n\n### 🎛️ **Complete VMC Control**\n\n- **Fan Control**: Variable speed and operating modes\n- **Environmental Monitoring**: Indoor/outdoor temperature, humidity, CO2, VOC\n- **Filter Management**: Usage hours monitoring and filter reset\n- **Lighting**: Integrated light control with timer\n- **Network Configuration**: WiFi management and network parameters\n\n## 🏠 Available Entities\n\n### 🌪️ **Ventilation Control**\n\n- **Fan**: Fan speed control and operating modes\n- **Mode Switch**: Operating modes (hyperventilation, night, free_cooling)\n- **Sensors Switch**: Enable/disable environmental sensors\n\n### 📊 **Environmental Sensors**\n\n- **Indoor/Outdoor Temperature**: Real-time temperature monitoring\n- **Humidity**: Environmental humidity levels\n- **CO2**: Carbon dioxide concentration (ppm)\n- **VOC**: Volatile organic compounds\n- **Air Quality**: Overall environmental quality indicators\n\n### 🔧 **System Management**\n\n- **Filter Hours**: Filter operating hours\n- **Reset Filter Button**: Filter counter reset\n- **Last Response**: Last communication timestamp\n- **Panel LED Switch**: Front panel LED control\n\n### 💡 **Lighting**\n\n- **Light**: Integrated light control\n- **Light Timer**: Automatic light shutdown timer\n\n### 🌐 **Network Configuration**\n\n- **IP Address**: Device IP address\n- **Subnet Mask/Gateway**: Network parameters\n- **SSID/Password**: WiFi configuration\n- **Network Settings**: Complete network parameter management\n\n### 📈 **Advanced Sensors**\n\n- **Absolute Humidity**: Calculated absolute humidity in g/m³ *(EASC-enabled)*\n- **Dew Point**: Dew point calculation for condensation prevention *(EASC-enabled)*\n- **Comfort Index**: Comfort index based on temperature and humidity *(EASC-enabled)*\n- **Dew Point Delta**: Difference between indoor and outdoor dew point *(EASC-enabled)*\n- **Air Exchange Time**: Air exchange time based on fan speed\n- **Daily Air Changes**: Number of daily air changes\n- **Filter Life Percentage**: Remaining filter life based on filter working hours\n- **Power Sensor**: Instantaneous power estimate based on fan speed\n- **Daily Energy Estimate**: Daily estimated energy consumption\n\n\u003e 🔗 **EASC-enabled sensors** support external data sources. See [External Advanced Sensor Configuration](docs/EXTERNAL_ADVANCED_SENSORS.md) for setup details.\n\n### 🚨 **Alert Binary Sensors**\n\n- **Air Quality Alert**: ON when CO2 stays above threshold for configured duration\n- **Condensation Risk Alert**: ON when dew-point delta indicates condensation risk\n- **Offline Alert**: ON when the coordinator detects communication failures\n\n## 🎨 **Custom Dashboard**\n\n### 📱 **VMC Helty Control Card**\n\nCustom Lovelace card for complete VMC system control:\n\n- **🎛️ Fan Control**: Intuitive interface with speed buttons (0-4)\n- **📊 Environmental Monitor**: Sensor visualization with color indicators\n- **🔄 Real-time Updates**: Real-time fan and sensor status\n- **📱 Responsive Design**: Optimized for mobile, tablet, and desktop\n- **🎨 Multiple Themes**: Default, Compact, Minimal\n- **⚙️ Visual Configuration**: Integrated graphical editor in Lovelace\n\n#### Card Installation\n\n```bash\n# Copy card files to www/\n/config/www/vmc-helty-card/\n├── vmc-helty-card.js              # Main card\n└── vmc-helty-card-editor.js       # Configuration editor\n```\n\nAdd to Lovelace resources:\n\n```yaml\nresources:\n  - url: /local/vmc-helty-card/vmc-helty-card.js\n    type: module\n  - url: /local/vmc-helty-card/vmc-helty-card-editor.js\n    type: module\n```\n\n**Note**: Translation files are loaded automatically and should NOT be added to resources.\n\nCard configuration:\n\n```yaml\ntype: custom:vmc-helty-card\nentity: fan.vmc_helty\nname: \"VMC Living Room\"\nshow_temperature: true\nshow_humidity: true\nshow_co2: true\nshow_voc: true\n```\n\n## 🚀 Guided Configuration\n\n### 📡 **Incremental Scanning**\n\n1. **Start Configuration**\n   - Open Home Assistant → Settings → Devices \u0026 Services\n   - Click \"Add Integration\" → Search for \"VMC Helty Flow\"\n\n2. **Scan Configuration**\n   - **Subnet**: Enter the network to scan (e.g., `192.168.1.0/24`)\n   - **Port**: VMC device TCP port (default: `5001`)\n   - **Timeout**: Connection timeout in seconds (1-60)\n   - **Mode**: Select \"Incremental scan\"\n\n3. **Incremental Process**\n   - The scan starts and automatically stops at each device found\n   - For each discovered VMC device, you can choose:\n     - **➕ Add and continue**: Adds the device and continues scanning\n     - **⏭️ Skip and continue**: Ignores this device and continues\n     - **✅ Add and finish**: Adds the device and terminates\n     - **🛑 Stop scan**: Stops everything without adding\n\n4. **Immediate Feedback**\n   - Real-time display of found devices\n   - Detailed information (name, IP, model) for each device\n   - Progressive counter and scan position indicator\n\n### 🔧 **Validations and Security**\n\n- **Subnet Format**: Automatic CIDR format validation\n- **IP Limit**: Maximum 254 addresses per scan (for performance)\n- **Port Check**: Port range validation (1-65535)\n- **Smart Timeout**: Balance between speed and reliability\n- **Duplicate Management**: Automatic duplicate configuration prevention\n\n## 📋 **Configuration Examples**\n\n### Basic Configuration\n\n```text\nSubnet: 192.168.1.0/24\nPort: 5001\nTimeout: 10 seconds\n```\n\n### Custom Network Configuration\n\n```text\nSubnet: 10.0.0.0/24\nPort: 8080\nTimeout: 5 seconds\nMode: Full scan\n```\n\n### Extended Network Configuration\n\n```text\nSubnet: 192.168.0.0/23\nPort: 5001\nTimeout: 15 seconds\n```\n\n## 🔬 **External Advanced Sensor Configuration (EASC)**\n\nEASC lets the four calculated sensors read temperature and humidity from **any Home Assistant entity** instead of the VMC's built-in sensors — useful when you want to use a room thermostat, a Netatmo weather station, or an ESPHome sensor for more accurate calculations.\n\n### Quick setup\n\n1. Go to **Settings → Devices \u0026 Services → VMC Helty Flow → Configure**\n2. Enable **\"Configure advanced sensors (EASC)\"** → **Submit**\n3. For each sensor, enter an entity_id (e.g. `sensor.living_room_temperature`) or keep `vmc`\n4. Select the calculation formula: `magnus` (Magnus-Tetens, default) or `custom` (August-Roche-Magnus, WMO)\n\nWhen an external entity is unavailable, the sensor **automatically falls back** to VMC data.\n\n### Example — use Netatmo room sensor\n\n```text\nDew Point → temperature source: sensor.netatmo_living_room_temperature\nDew Point → humidity source:    sensor.netatmo_living_room_humidity\n```\n\n📖 **Full documentation**: [docs/EXTERNAL_ADVANCED_SENSORS.md](docs/EXTERNAL_ADVANCED_SENSORS.md)\n\n---\n\n## 🔄 **Automations and Integrations**\n\nAll entities are fully integrated with Home Assistant:\n\n### Air Quality Automation\n\n```yaml\nautomation:\n  - alias: \"VMC Boost on High CO2\"\n    trigger:\n      platform: numeric_state\n      entity_id: sensor.vmc_helty_living_room_co2\n      above: 800\n    action:\n      service: fan.set_percentage\n      target:\n        entity_id: fan.vmc_helty_living_room\n      data:\n        percentage: 80\n```\n\n### Custom Dashboard\n\n```yaml\ncards:\n  - type: entities\n    title: \"Living Room VMC Control\"\n    entities:\n      - fan.vmc_helty_living_room\n      - sensor.vmc_helty_living_room_indoor_temperature\n      - sensor.vmc_helty_living_room_co2\n      - switch.vmc_helty_living_room_mode\n      - light.vmc_helty_living_room_light\n```\n\n## 🛠️ **Troubleshooting**\n\n### Common Issues\n\n**Devices not found?**\n\n- Verify that VMC devices are powered on and connected to the network\n- Check that the subnet is correct\n- Try increasing the connection timeout\n- Verify that port 5001 is not blocked by firewall\n\n**Slow scanning?**\n\n- Reduce the subnet (e.g., from /23 to /24)\n- Decrease timeout for fast networks\n- Use incremental mode for granular control\n\n**Connection errors?**\n\n- Verify the VMC device network configuration\n- Check that Home Assistant can reach the specified subnet\n- Try restarting the VMC device\n\n### Logging and Debug\n\nTo enable detailed logging, add to `configuration.yaml`:\n\n```yaml\nlogger:\n  default: info\n  logs:\n    custom_components.vmc_helty_flow: debug\n```\n\n## 🔮 **Future Developments**\n\nWe have an active development roadmap with exciting features planned!\n\n### 📋 Development Resources\n\n- **[Project Roadmap](PROJECT_ROADMAP.md)** - Detailed development plan with milestones, tasks, and progress tracking\n- **[Improvement Plan](IMPROVEMENT_PLAN.md)** - Complete analysis and proposed improvements for upcoming versions\n- **[Blueprint Guide](blueprints/BLUEPRINT_GUIDE.md)** - Comprehensive automation blueprint documentation\n\n### 🎯 What's new in v1.2.0 (in progress)\n\n**Already shipped**:\n- 🔬 **EASC — External Advanced Sensor Configuration**: Connect Absolute Humidity, Dew Point, Comfort Index, and Dew Point Delta to any HA entity with automatic VMC fallback. Supports Magnus-Tetens and August-Roche-Magnus formulas. See [docs/EXTERNAL_ADVANCED_SENSORS.md](docs/EXTERNAL_ADVANCED_SENSORS.md).\n- 🚨 **Filter Warning Binary Sensor**: Alerts when filter hours exceed 90% of maximum life.\n\n**Upcoming**:\n- 🔔 **Notification System**: Complete alerting for critical events (filter, air quality, offline)\n- 📘 **Automation Blueprints**: Air quality adaptive, humidity control, filter reminders\n- 📦 **Ready-to-Use Dashboard Package**: Complete importable package with helpers, automations, and views\n\n**Medium Priority** (v1.3.0):\n- ⭐ **Quality Scale Gold**: Upgrade from Silver to Gold certification\n- ⚡ **Energy Dashboard Integration**: Track VMC power consumption in Home Assistant Energy\n- 🎭 **Predefined Scenes**: Night mode, boost, energy saving scenarios\n\n**Community Requests**:\n- 🤖 Machine Learning air quality predictions\n- 🗣️ Voice assistant advanced integrations\n- 📱 Mobile companion app\n- 🌐 Multi-zone VMC coordination\n\nSee the [full roadmap](PROJECT_ROADMAP.md) for detailed timeline and task breakdown.\n\n## 📞 **Support**\n\nFor issues, feature requests, or contributions:\n\n- 🐛 [Open an issue](https://github.com/darius1907/ha_vmc_helty_flow/issues) on GitHub\n- 💬 Join the [community discussion](https://community.home-assistant.io/)\n\n### How to Contribute\n\nWe welcome contributions! See our [Contributing Guidelines](CONTRIBUTING.md) and [Project Roadmap](PROJECT_ROADMAP.md) for current priorities.\n\n1. 🍴 Fork the repository\n2. 🌱 Create a branch for the feature\n3. ✅ Add tests for changes (coverage \u003e95%)\n4. 📝 Update documentation\n5. 🎯 Check [PROJECT_ROADMAP.md](PROJECT_ROADMAP.md) for priority tasks\n5. 🔄 Submit a pull request\n\n---\n\n## 📊 **Project Status**\n\n![GitHub release (latest by date)][releases-shield]\n![GitHub Release Date][release-date-shield]\n![GitHub commits since latest release][commits-since-shield]\n![GitHub last commit][last-commit-shield]\n\n**Version**: 1.1.1\n**Compatibility**: Home Assistant 2024.1+\n**License**: MIT\n**HACS Status**: ✅ Available in the official HACS repository\n\n---\n\n**⭐ If this integration is useful to you, star the repository!**\n\n**☕ Do you like this integration? Buy me a coffee!**\n\n[![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/darius1907)\n\nYour support helps me maintain and improve this integration!\n\n[hacs]: https://github.com/hacs/integration\n[hacsbadge]: https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge\n[discord]: https://discord.gg/Qa5fW2R\n[discord-shield]: https://img.shields.io/discord/330944238910963714.svg?style=for-the-badge\n[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=for-the-badge\n[forum]: https://community.home-assistant.io/\n[license]: https://github.com/darius1907/ha_vmc_helty_flow/blob/main/LICENSE\n[license-shield]: https://img.shields.io/github/license/darius1907/ha_vmc_helty_flow.svg?style=for-the-badge\n[maintenance-shield]: https://img.shields.io/badge/maintainer-%40darius1907-blue.svg?style=for-the-badge\n[releases-shield]: https://img.shields.io/github/release/darius1907/ha_vmc_helty_flow.svg?style=for-the-badge\n[releases]: https://github.com/darius1907/ha_vmc_helty_flow/releases\n[commits-shield]: https://img.shields.io/github/commit-activity/y/darius1907/ha_vmc_helty_flow.svg?style=for-the-badge\n[commits]: https://github.com/darius1907/ha_vmc_helty_flow/commits/main\n[user_profile]: https://github.com/darius1907\n[buymecoffee]: https://www.buymeacoffee.com/darius1907\n[buymecoffeebadge]: https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?style=for-the-badge\n[release-date-shield]: https://img.shields.io/github/release-date/darius1907/ha_vmc_helty_flow?style=for-the-badge\n[commits-since-shield]: https://img.shields.io/github/commits-since/darius1907/ha_vmc_helty_flow/latest?style=for-the-badge\n[last-commit-shield]: https://img.shields.io/github/last-commit/darius1907/ha_vmc_helty_flow?style=for-the-badge\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarius1907%2Fha_vmc_helty_flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarius1907%2Fha_vmc_helty_flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarius1907%2Fha_vmc_helty_flow/lists"}