Version v1.1.2
Smart humidity intelligence for Home Assistant — insights, not just numbers.
Humidity Intelligence is an opinionated Home Assistant package that transforms raw humidity and temperature readings into actionable building insight.
It doesn’t just show percentages — it answers the real questions:
Am I heading toward condensation or mould? Where is the risk coming from? And what should I actually do right now?
This Advanced Edition reflects the system I run at home and is designed to be:
- Vendor-agnostic
- Sensor-driven
- UI-friendly
- Automation-ready
Humidity Intelligence builds a decision-making layer on top of your existing room sensors.
- Dynamic house average humidity
- Season-aware comfort band
- 7-day humidity drift (current vs historical mean)
- Plain-language ventilation suggestion
- Binary danger flags for automations
For every mapped room:
- Dew point calculation (Magnus formula)
- Condensation spread (°C above dew point)
- Condensation risk: OK / Watch / Risk / Danger
- Mould risk (humidity + spread scoring)
- 7-day room-level drift
- Worst room for condensation
- Worst room for mould
- Worst-case risk levels exposed as sensors
- Stable
sensor.*andbinary_sensor.*entities - ApexCharts-ready Humidity Constellation series
- Designed to power badge-based and dropdown-mod UIs
This is not a graph pack. It’s an analysis engine with a clean public API.
- Home Assistant 2024.x+
- YAML mode or package support enabled
templatestatistics
- HACS (recommended) for easy frontend installation
- Frontend cards:
config-template-card
The backend works without these. The provided UI and Constellation chart require them.
This repository follows the HACS custom template layout:
| Path | Purpose |
|---|---|
humidity_intelligence.jinja |
Core package (all sensors & logic) |
lovelace/ |
Optional prebuilt dashboard card |
assets/ |
README assets |
hacs.json |
HACS metadata |
LICENSE |
MIT licence |
HACS uses the .jinja file as the install source.
Humidity Intelligence is distributed via HACS as a managed template package.
This means:
- HACS does not write directly to your
configuration.yamlor/packages/ - You explicitly decide how the package is deployed into your config
- This keeps your setup predictable and update-safe
Follow the steps below carefully.
-
Open HACS
-
Go to Integrations
-
Click ⋮ → Custom repositories
-
Add this repository as:
- Category: Template
- Name: Humidity Intelligence https://github.com/senyo888/Humidity-Intelligence
-
Install
-
Restart Home Assistant
After this step, HACS installs the managed source file here:
/config/custom_templates/humidity_intelligence.jinja
Do not edit it directly.
If you are not already using packages, add the following to configuration.yaml:
homeassistant:
packages: !include_dir_merge_named packagesor
homeassistant:
packages: !include_dir_named packages
Restart Home Assistant.
This only needs to be done once.
At this point, nothing is active yet. You must now choose how Humidity Intelligence is wired into your config.
Create the file:
/config/packages/humidity_intelligence.yaml
Then copy the entire contents of:
custom_templates/humidity_intelligence.jinja
into that file.
Use this option if you want:
- Full control over the YAML
- To freely modify logic
- To avoid possible changes on HACS update
Trade-off:
- You must manually update your copy when new versions are released
Reference the HACS-managed file directly:
packages:
humidity_intelligence: !include jinja/humidity_intelligence.jinjaRestart Home Assistant again.
This is the recommended approach.
What this means:
- You receive fixes and improvements automatically via HACS
- The backend remains canonical and consistent
- You do not duplicate logic
If you choose Option B, any changes you make to entity IDs, names, or logic inside the package could be reset to the canonical defaults on some HACS update.
This is intentional.
Option B treats Humidity Intelligence as a library, not user-owned config.
| If you want… | Choose |
|---|---|
| Automatic updates | Option B |
| Canonical entity IDs | Option B |
| Minimal maintenance | Option B |
| To freely customise backend logic | Option A |
| No risk of updates overwriting changes | Option A |
Most users should choose Option B.
Once deployed:
- Restart Home Assistant
- Proceed to Configuration below to map your room sensors (this is the only part you are expected to edit)
All defaults are placeholders.
Humidity Intelligence is built around a stable public entity API (see below). To connect your sensors, you have two supported approaches:
You keep your existing entity IDs and just point Humidity Intelligence at them.
If you want the reference UI + gallery UIs to work with minimal/no edits, you can choose to align your entity naming to the examples used here (e.g. sensor.living_room_humidity, sensor.living_room_temperature).
This is optional — the backend works either way.
Practical tip: alias/rename in your integrations where possible, rather than creating lots of extra template sensors. Keep it tidy.
Edit the Humidity Intelligence Config room map:
'Living Room': 'sensor.living_room_humidity'
'Kitchen': 'sensor.kitchen_humidity'- Replace the entity IDs with your real humidity sensors
- Add/remove rooms freely
- Invalid/unavailable sensors are ignored automatically
This map drives:
- House averages
- Constellation chart
- Worst-room logic
Each room has a statistics sensor like:
entity_id: sensor.living_room_humidityChange only the entity_id.
Don’t rename the statistics sensors unless you also update downstream templates.
For each room, the dew point logic expects:
sensor.living_room_temperature
sensor.living_room_humidityOnce mapped, everything else is automatic.
If you installed using Option B (Include), the source file is managed by HACS and could be overwritten on update.
That means:
- ✅ Changes you make to your sensor mapping (in your own config) persist
- ❌ Changes you make inside the HACS-managed
.jinjafile do not persist
If you need a fully editable copy you can change freely, use Option A (Copy) instead.
These entity IDs are intentionally stable and used by the UI and gallery submissions:
sensor.house_average_humidity
sensor.house_humidity_mean_7d
sensor.house_humidity_drift_7d
sensor.worst_room_condensation
sensor.worst_room_condensation_risk
sensor.worst_room_mould
sensor.worst_room_mould_risk
sensor.humidity_constellation_series
binary_sensor.humidity_danger
binary_sensor.condensation_danger
binary_sensor.mould_danger
input_boolean.humidity_constellation_expanded
Think of these as the public interface. If you keep them unchanged, most UIs “just work”.
Humidity Intelligence is backend-first.
The package exposes a stable set of sensors and binary sensors designed to be consumed by any dashboard, automation, or card style you prefer.
This repository includes a reference Lovelace UI to demonstrate what the data can do — not what it must look like.
The included UI demonstrates:
- A badge-first overview (Humidity / Condensation / Mould / Drift)
- A contextual Comfort Band summary
- A chevron-controlled dropdown-mod
- A dynamic 24-hour Humidity Constellation chart
The chart and dropdown are fully driven by backend sensors — no room entities are hard-coded.
The example Lovelace card is located in:
lovelace/humidity_intelligence_card.yaml
To use it:
- Install the required frontend cards (see below)
- Add a Manual card to your dashboard
- Paste the YAML
- Save
If you keep the public entity IDs unchanged, you maybe required to edit entity ID for the humidity constelltion.
The reference UI uses the following custom cards:
button-cardapexcharts-cardcard-modconfig-template-card
The backend works without any of these. They are only required if you want the example UI.
The Constellation chart is controlled by:
input_boolean.humidity_constellation_expanded
The Comfort Band card toggles this helper via a chevron.
This pattern is deliberate and reusable — you can attach the same helper to any UI element you like.
You are encouraged to:
- Re-style the badges
- Replace ApexCharts
- Build mobile-first or wall-panel layouts
- Skip dashboards entirely and use automations instead
As long as you use the public entity API, the backend will support you.
There is no canonical UI.
Humidity Intelligence is designed to support many visual interpretations.
The UI Gallery showcases ** defult & community-built dashboards, badges and cards** built on top of the Humidity Intelligence backend, including:
- Mobile-first layouts
- Tablet and wall-panel dashboards
- Minimal or graph-heavy designs
- Automation-centric or insight-driven views
All gallery submissions must follow the project’s canonical UI rules to ensure portability, clarity, and compatibility.
Gallery entries are reviewed and validated before inclusion.
👉 See CONTRIBUTING.md for:
- required folder structure
- preview image rules
- canonical entity and helper usage
- PR and review expectations
- Dew point calculated per room
- Condensation risk derived from spread
- Mould risk combines humidity + spread
- Seasonal comfort band adjusts thresholds
- Ventilation guidance is intentionally conservative
This biases toward early warning, not late alarm.
1.2.x
- More logic driven from the dynamic room map
- Optional outdoor reference inputs
- Easier onboarding
- Compact more UI variant
Future
- Predictive condensation warnings
- Energy-aware ventilation hints
- Automation hooks
- Seasonal humidity health reports
Values show unknown
- Check entity IDs exist and are numeric
- Drift sensors need history (up to 7 days)
Constellation chart blank
- Inspect
sensor.humidity_constellation_series - One or more room entities are invalid
Ventilation feels aggressive
- This is intentional
- Tune thresholds if your building behaves differently
Some users may see a warning similar to:
patternWarning yaml-schema: http://schemas.home-assistant.io/configuration
This typically appears in VS Code when using:
homeassistant:
packages: !include_dir_merge_named packagesImportant: This is not a Home Assistant runtime error.
!include_dir_merge_namedis a valid and supported Home Assistant feature.- Home Assistant will start normally and the sensors will function as expected.
- The warning comes from the VS Code Home Assistant schema validator, which does not fully understand all advanced YAML directives.
✅ If Home Assistant starts and the Humidity Intelligence sensors appear, this warning can be safely ignored.
In v1.0.2, there was a known issue in the House Average Humidity template caused by yaml variable scoping inside a loop.
This could result in the sensor returning unknown even when valid humidity data existed.
- This issue only affects v1.0.2
- It has been fixed in later versions using a
namespace()approach - Upgrading resolves the problem
If you encounter this behaviour, please confirm which version you are running before opening an issue.
To help diagnose problems quickly, please include:
-
Humidity Intelligence version
-
Home Assistant version
-
Whether the issue is:
- a runtime error in Home Assistant or
- an editor/schema warning (e.g. VS Code)
This helps distinguish real bugs from tooling limitations.
Humidity Intelligence exists because:
“65% isn’t helpful. Tell me if it’s bad here, now, and what to do.”
If it helps you understand your building better, a ⭐ or a screenshot in Discussions is always appreciated.
