https://github.com/derabbink/ha_hacs_ventilation_assistant
A Home Assistant HACS integration to assist with building ventilation
https://github.com/derabbink/ha_hacs_ventilation_assistant
hacs hacs-integration home-assistant home-assistant-custom-component home-assistant-integration humidity indoor-air-quality temperature ventilation
Last synced: 13 days ago
JSON representation
A Home Assistant HACS integration to assist with building ventilation
- Host: GitHub
- URL: https://github.com/derabbink/ha_hacs_ventilation_assistant
- Owner: derabbink
- License: mit
- Created: 2026-06-28T09:26:45.000Z (22 days ago)
- Default Branch: main
- Last Pushed: 2026-07-05T14:41:41.000Z (14 days ago)
- Last Synced: 2026-07-05T15:08:55.863Z (14 days ago)
- Topics: hacs, hacs-integration, home-assistant, home-assistant-custom-component, home-assistant-integration, humidity, indoor-air-quality, temperature, ventilation
- Language: Python
- Homepage:
- Size: 163 KB
- Stars: 47
- Watchers: 1
- Forks: 3
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Ventilation Assistant
Ventilation Assistant is a Home Assistant custom integration for HACS. It creates virtual ventilation devices from existing indoor sensors, outdoor sensors, and door/window contacts.
## Model
The integration is fully configurable from the Home Assistant UI. Configuration is stored by Home Assistant as config entries in `.storage/core.config_entries`; it does not create Home Assistant Helpers.
Use the config flow to create:
- one global defaults entry for the shared comfort temperature band, comfort relative-humidity band, and decision priority
- one or more ventilation device subentries under that entry
`priority` can be `TEMPERATURE` or `HUMIDITY`. Each device can override any global default, or leave that field empty to inherit the global setting.
Each ventilation device creates a Home Assistant device containing:
- Indoor temperature average
- Indoor relative humidity average
- Indoor absolute humidity
- Indoor projected absolute humidity
- Indoor projected relative humidity
- Indoor projected relative-humidity difference
- Indoor projected temperature difference
- Outdoor temperature average
- Outdoor relative humidity average
- Outdoor absolute humidity
- Any doors/windows open
- Door/window open percentage
- Temperature advice: `KEEP_CLOSED`, `OPEN`, `KEEP_OPEN`, or `CLOSE`
- Humidity advice: `KEEP_CLOSED`, `OPEN`, `KEEP_OPEN`, or `CLOSE`
- Advice: `KEEP_CLOSED`, `OPEN`, `KEEP_OPEN`, or `CLOSE`
## Availability
Calculated entities return unavailable when their required inputs are missing or unavailable:
- Averages require at least one available source entity.
- Absolute humidity requires temperature and relative humidity.
- Projected indoor absolute humidity requires indoor temperature and outdoor absolute humidity.
- Projected indoor relative humidity requires indoor temperature and projected absolute humidity.
- Door/window sensors require at least one available contact sensor.
- Advice requires either available indoor/outdoor temperature values or available
indoor/projected relative-humidity values. Without an available contact sensor,
advice is limited to `OPEN` or `CLOSE`.
## HACS installation during development
Copy or symlink this repository into Home Assistant, or add it as a HACS custom repository with category `Integration`. After installing, restart Home Assistant and add **Ventilation Assistant** from **Settings > Devices & services**.
Complete the global defaults form during first setup. After that, use **Add device** to add each ventilation device directly. Use the gear icon on the **Ventilation Assistant** integration entry to change the global defaults later. Use the configure action on a ventilation device subentry to change the input entities for that virtual device.
## Local CI
Create the local development environment with:
```sh
pipenv install --dev
```
Run the Python CI jobs individually with:
```sh
pipenv run lint
pipenv run typecheck
pipenv run test
```
Run the GitHub Action backed checks with Docker running:
```sh
pipenv run hacs-validate
pipenv run hassfest
```
Run the full local CI sequence with:
```sh
pipenv run ci
```