Humidity Intelligence V2

Deterministic Environmental Control for Home Assistant

Quick Demo (GIF)

V2 UI Gallery (PNG)

---

Contents

• What Humidity Intelligence V2 Is
• Why Environmental Stability Matters
• Season-Aware Environmental Control
• Architecture Overview
• Installation
• Dependencies
• Migration Guide - v1 to v2
• Full Configuration Flow
• Configuration Screenshots (Visual Guide)
• Post-Configuration Workflow
• How to Use Services
• Release Notes
• Design Philosophy

---

What Humidity Intelligence V2 Is

Humidity Intelligence V2 is not a collection of automations.

It is a deterministic environmental runtime engine.

It replaces stacked triggers and conflicting scripts with:

• a lane-based priority architecture
• physics-aware environmental modelling
• global gating logic
• one authoritative control state per evaluation cycle

There is no "last automation wins." There is no trigger race condition. There is one resolved outcome, every time.

This is environmental control with structure.

Positioning: environmental stability + seasonal context.

---

Why Environmental Stability Matters

Most dashboards show a number. Humidity Intelligence models behavior.

Humidity problems rarely appear as isolated spikes. They emerge as:

• drift
• imbalance
• duration
• recurring spread patterns

High Humidity Related Issues

• condensation formation
• mould growth risk
• dust mite proliferation
• sleep disruption
• structural degradation over time

Low Humidity Related Issues

• irritated airways
• dry throat and coughing
• worsened asthma symptoms
• dry skin and eye irritation
• reduced respiratory resilience

Indoor Plant Health Problems

• low humidity: leaf browning, stress, slowed growth
• excess humidity: fungal growth and pest vulnerability

Most homes oscillate between both extremes seasonally.

V2 models that instability structurally.

---

Season-Aware Environmental Control

56% is not always "high."

Humidity Intelligence v2 evaluates humidity relative to the active target profile:

• Winter defaults to a lower comfort band than summer
• Spring and autumn use intermediate bands
• Custom target profiles are supported when configured

Interpretation now follows target-relative states:

• below_target -> dry for the active profile
• in_target -> stable band for the active profile
• above_target -> elevated for the active profile
• high_risk -> materially above the active profile's safe limit

This keeps stability as the primary goal while making evaluation season-correct and explainable.

---

Architecture Overview

Humidity Intelligence V2 operates across three defined layers.

1) Intelligence Layer - Environmental Physics

Transforms raw telemetry into structured environmental signals:

• dynamic house average humidity
• 7-day mean and drift tracking
• Magnus dew point calculation
• condensation spread (temperature - dew_point)
• mould risk normalization
• worst-room detection
• binary danger states

This layer models risk and does not control hardware.

2) Control Layer - Deterministic Priority Engine

Canonical runtime order:

1. CO Emergency: highest priority automation
2. Alert Lane: best use is for when physical intervention is required
3. Zone 1: level humidity stabilisation automation
4. Zone 2: lower priority humidity level stabilisation automation
5. Air Quality: background automation with VOC PM25 & IAQ threshold triggers.
6. Normal

Humidifier lanes operate independently where safe.

Each evaluation cycle:

1. global gates evaluated
2. lanes resolved top-down
3. first valid lane wins
4. lower lanes remain blocked

Only one comfort/control lane drives outputs at a time.

This eliminates automation conflict entirely.

3) Presentation Layer - UI Truth Contract

The UI reflects runtime truth:

• active lane
• gate blocks
• override state
• reason text
• output stage transparency

The UI does not compute logic. The engine decides. The UI renders.

---

v2.0.3 Highlights

• dependency UX refined in setup and post-configuration (Dependencies is now first-class and revisitable)
• dependency status lines now include direct upstream repository links for fast install/verification
• options menu order updated to prioritize setup sequence: Dependencies -> Sensors -> Global Gates
• README dependency guidance expanded and clarified for HACS-first UI setup
• top badges updated for clearer positioning (Custom Integration) and auto-synced Home Assistant compatibility from manifest.json

Upgrade note: v2.0.3 focuses on dependency clarity, UI onboarding accuracy, and metadata consistency. No breaking schema changes are introduced.

---

Installation

Option A - HACS (Recommended)

1. Add custom repository: https://github.com/senyo888/Humidity-Intelligence Category: Integration
2. Install Humidity Intelligence
3. Restart Home Assistant
4. Go to Settings -> Devices & Services -> Add Integration
5. Search for Humidity Intelligence
6. Begin configuration

---

Dependencies

Humidity Intelligence V2 is designed to run fully at the backend level, but the UI experience depends on a small set of frontend cards.

You can complete setup without them, but if you want the full visual system (badges, charts, reason panel, mobile/tablet layouts), these are strongly recommended.

Core Recommendation

Install via HACS before anything else.

Frontend Dependencies (UI Layer)

The following projects power the visual layer of Humidity Intelligence:

• card-mod
  Advanced styling engine used for dynamic visuals, glow states, and conditional UI rendering.
• button-card
  Core building block for badges, status indicators, and interactive UI elements.
• mod-card
  Structural wrapper used to apply styling cleanly across complex card layouts.
• apexcharts-card
  Powers historical graphs, trend analysis, and environmental visualisation.

Installation Notes

• All dependencies can be installed via HACS (Frontend section).
• After installing, hard refresh your browser or use a new session to avoid caching issues.
• If you skip these, the system still runs, but UI elements may not render correctly.

Acknowledgements

Huge respect and thanks to the creators of these projects. Humidity Intelligence builds on top of their work:

• Thomas Loven for card-mod and mod-card
• Custom Cards Community for button-card
• RomRider for apexcharts-card

These tools are foundational to the Home Assistant ecosystem, and this project would not hit the same level without them.

Suggested Setup Approach

If you are unsure:

1. Install HACS
2. Install the dependencies above
3. Continue with the configuration flow

Or:

• Skip for now
• Complete backend setup first
• Add the UI layer afterwards

---

Migration Guide - v1 to v2

V1 was template-based. V2 is a structured integration with configuration flow and runtime validation.

Migration is required.

---

Important - HACS Repository Type Change

V1 was installed as a Template in HACS. V2 is a Custom Integration.

If you skip this step, HACS may continue installing files to:

/config/custom_templates/

This will break updates and prevent V2 from loading correctly.

Step 0 - Remove V1 from HACS (Required)

1. Go to HACS -> Humidity Intelligence
2. Open the menu (three dots)
3. Click Remove
4. Restart Home Assistant

Step 0.1 - Re-add Repository as Integration

1. Go to HACS -> Menu -> Custom repositories

2. Add:

   https://github.com/senyo888/Humidity-Intelligence
   

3. Set category to:

   Integration
   

4. Install Humidity Intelligence

5. Restart Home Assistant

Correct install path should now be:

/config/custom_components/humidity_intelligence/

---

Step 1 - Remove v1 Backend

Delete:

/config/custom_templates/humidity_intelligence.jinja
/config/packages/humidity_intelligence.yaml

Remove any related includes from configuration.yaml. Restart Home Assistant.

Step 2 - Remove v1 UI YAML

Delete:

/config/www/.../v1_mobile.yaml
/config/lovelace/v1_mobile.yaml

Restart if using YAML dashboards.

v1 UI Compatibility

The classic four-badge + Comfort Band layout remains compatible on the V2 engine.

• V1 UI = presentation skin
• V2 = runtime engine

No forced visual migration.

Post-Migration Check

After install, verify:

• Integration loads in Settings -> Devices & Services
• no references remain to /custom_templates/
• UI renders correctly

If needed, refresh UI:

service: humidity_intelligence.refresh_ui

Summary

• V1 = Template system (custom_templates)
• V2 = Integration (custom_components)
• HACS must be reconfigured to recognise the new structure

Skipping this step will result in:

• failed updates
• incorrect install location
• integration not loading

---

Full Configuration Flow

Follow this sequence on first install.

1) Dependencies

What to do:

• open the Dependencies step in config flow
• review installed/detected status and repo links
• continue even if some are not installed

Reference:

• see Dependencies for install guidance and acknowledgements

2) Global Gates

What to do:

• set time gate window (optional)
• select presence/alarm entities (optional)
• define explicit present and away state values

Example baseline:

• time gate enabled: 06:00 to 23:30
• outside action: safe_state
• presence entities: person.adam, person.eve, or alarm panel
• present states: home, on, disarmed
• away states: not_home, off, armed_away, away

Example:

• if everyone is away, HI enters gate hold
• Current Air Control shows gate-active mode/chips
• outputs are held or reset based on selected outside action

3) Telemetry Inputs

What to do:

• add source entities for humidity and temperature
• add optional AQ telemetry (iaq, pm25, voc, co2, co)
• added sensors will appear in the UI Chip
• assign EVERY sensor to level and room regardless of intended use

Rules:

• minimum one humidity + one temperature sensor per active level
• use level1 and level2 consistently
• keep room labels stable and human-readable

Example baseline:

• Level 1: kitchen humidity, hallway humidity, kitchen temperature
• Level 2: bedroom humidity, landing humidity, bedroom temperature
• AQ: one IAQ + one PM2.5 per level if available

Example row:

• entity: sensor.kitchen_humidity
• type: humidity
• level: level1
• room: Kitchen

4) Temperature Slope Mode

What to do:

• choose external slope sensors or HI-generated slope

Suggested baseline:

• use HI-generated slope if you do not already publish stable slope entities
• use external slope entities only when they are already validated

Example (external):

• sensor.kitchen_temp_slope
• sensor.bedroom_temp_slope

Example (HI-generated):

• source sensors selected: sensor.kitchen_temp, sensor.bedroom_temp
• slope calculated displayed and used

5) Zones (Zone 1 and Zone 2)

What to do:

• assign each zone to a level and room set
• configure output entities
• choose triggers and thresholds
• set output stage and UI label

Example baseline:

• Zone 1 label: Cooking
• Zone 1 level: level1
• Zone 1 output level: 66
• Zone 1 trigger: humidity delta high
• Zone 2 label: Bathroom
• zone 2 trigger: humidity delta high, temp slope delta...
• Zone 2 level: level2
• Zone 2 output level: 100

Example:

• Zone 1 outputs: fan.kitchen_air, fan.living_room_air
• Zone 2 outputs: fan.upstairs_air
• fan stages: auto, 33, 66, 100

6) Humidifiers

What to do:

• configure per-level humidifier outputs
• confirm on/off behavior against target band

Suggested baseline:

• enable humidifier lanes only on levels with real humidifier hardware
• validate activation below target low
• validate recovery shutoff inside the normal band

Example:

• Level 1 output: humidifier.downstairs_humidifier
• turns on when below low target
• turns off when humidity recovers to low target + 3%

7) Air Quality

What to do:

• enable AQ per level if AQ telemetry is present
• assign outputs and run duration
• set safe AQ thresholds

Suggested baseline:

• AQ output level: 66
• run duration: 15 to 30 minutes
• IAQ threshold aligned to your sensor scale and household tolerance

Example:

• Level 1 AQ output: fan.purifier_living
• trigger: IAQ below threshold
• if Zone or Alert lane is active, AQ is deferred
• if two AQ levels share one output, last trigger update wins output setting

8) Alerts and CO Emergency

What to do:

• configure alert triggers, outputs, and flash behavior
• configure CO emergency thresholds and outputs

Suggested baseline:

• keep thresholds realistic and bounded
• use dedicated lights for alerts when possible
• use optional power_entity when wiring requires separate power enable

Example alert:

• trigger type: custom binary sensor
• trigger entity: binary_sensor.bathroom_moisture_alert
• threshold: 80
• lights: light.bathroom_alert
• power entity: switch.bathroom_light_power (optional)

Example CO:

• trigger type: CO emergency
• threshold: 15
• outputs: purifier/fan entities on both levels

9) UI Deployment

What to do:

• click finish setup
• select card(s) you would like to generate
• card YAML dropped with notification of location
• if not generate mapped cards through services

Suggested baseline:

• start with one dashboard layout (v2_mobile or v2_tablet)
• verify Current Air Control, chips, and outputs
• then add second layout if needed

Service options:

• humidity_intelligence.create_dashboard
• humidity_intelligence.view_cards
• humidity_intelligence.dump_cards

Example service usage:

• create dashboard with layout: v2_mobile, title: Humidity Intelligence, url_path: humidity-intelligence

---

Configuration Screenshots (Visual Guide)

Open configuration screenshots

1) Dependencies

2) Global Gates

3) Telemetry Inputs

4) Zones

5) Humidifiers

6) Air Quality

7) Alerts

8) Sensor Management (Options)

---

Post-Configuration Workflow

When modifying options:

1. change one section at a time
2. save
3. run humidity_intelligence.refresh_ui
4. verify:
   • Current Air Control mode
   • gate chips
   • reason text
   • output behavior

Post-config sensor/lane management:

1. use Sensors to add, edit, or delete any telemetry row (humidity, temperature, IAQ, PM2.5, VOC, CO2, CO)
2. use Humidifiers to add/edit/remove humidifier lanes per level and update output entities
3. use Air Quality to add/edit/remove AQ lanes per level and update triggers/outputs
4. lane selections marked as not configured - select to add can be used to create missing lanes later without reinstalling

Alert-only toggle workflow:

1. toggle alert_only_mode in options and save
2. HI reloads and regenerates exported cards automatically
3. open the updated /config/humidity_intelligence_cards_<layout>.yaml
4. re-paste YAML into Manual card(s) so control visibility and reason text match mode

---

How to Use Services

Use Home Assistant Developer Tools:

1. Go to Developer Tools -> Actions.
2. Select service domain: humidity_intelligence.
3. Pick a service.
4. Fill service data (YAML or UI fields).
5. Run and verify result in UI/notifications/files.

Notes:

• entry_id is optional for most services. If omitted, HI uses all entries or first valid entry based on service behavior.
• File outputs are written into your HA config folder.

create_dashboard

Purpose:

• create a Lovelace dashboard from a rendered HI layout.

Example:

service: humidity_intelligence.create_dashboard
data:
  layout: v2_mobile
  title: Humidity Intelligence
  url_path: humidity-intelligence

view_cards

Purpose:

• render cards and write them to file, then push a notification with file path.

Example:

service: humidity_intelligence.view_cards
data:
  filename: humidity_intelligence_cards
  layout: v2_tablet

dump_cards

Purpose:

• render and export card YAML to file without dashboard creation.

Example:

service: humidity_intelligence.dump_cards
data:
  filename: humidity_intelligence_cards
  layout: v2_mobile

refresh_ui

Purpose:

• rebuild placeholder mapping and refresh rendered UI output after config changes.

Example:

service: humidity_intelligence.refresh_ui
data: {}

flash_lights

Purpose:

• run alert flash behavior manually for testing.

Example:

service: humidity_intelligence.flash_lights
data:
  power_entity: switch.alert_power
  lights:
    - light.bathroom_alert
  color: [255, 0, 0]
  duration: 12
  flash_count: 8

pause_control

Purpose:

• pause automation engine for a set duration.

Example:

service: humidity_intelligence.pause_control
data:
  minutes: 60

resume_control

Purpose:

• clear pause state and resume runtime immediately.

Example:

service: humidity_intelligence.resume_control
data: {}

self_check

Purpose:

• run mapping/dependency/telemetry health checks and write report JSON.

Example:

service: humidity_intelligence.self_check
data: {}

dump_diagnostics

Purpose:

• export runtime diagnostics, mapping, and card info to JSON.

Example:

service: humidity_intelligence.dump_diagnostics
data:
  filename: humidity_intelligence_diagnostics.json

purge_files

Purpose:

• remove generated HI files and attempt dashboard cleanup.

Example:

service: humidity_intelligence.purge_files
data: {}

Safety guidance:

• use purge_files only when intentionally resetting generated artifacts
• run dump_diagnostics before purge if you want a snapshot for troubleshooting

---

Release Notes

v2.0.3

• updated minimum Home Assistant version to 2026.4.3 in manifest.json
• dependency status output now includes direct repository links (card-mod, button-card, mod-card, apexcharts-card, HACS)
• added post-configuration Dependencies options step so dependency checks are accessible after initial setup
• reordered options menu for setup flow clarity (Dependencies, then Sensors, then Global Gates)
• refreshed README dependency section with clearer HACS-first install guidance and acknowledgements
• updated top badges: HACS badge wording now Custom Integration, and Home Assistant badge now auto-reads compatibility from manifest.json

v2.0.2

• humidity badge semantics corrected to target-relative states (below_target, in_target, above_target, high_risk)
• active target season/profile surfaced in UI target display
• condensation and mould risk evaluation updated to season-aware deterministic thresholds
• humidifier telemetry reason expanded with lane scope, trigger condition, measured values vs thresholds, and recovery logic
• runtime debug logs added for active target profile, seasonal adjustments, humidity badge classification, and humidifier trigger/stop events

v2.0.1

• fixed Fahrenheit telemetry normalization by converting all internal temperature math to Celsius before averages, spreads, deltas, and thresholds
• fixed aggregate behavior so IAQ/AQ averages ignore unknown, unavailable, and non-numeric states and only return unknown when no valid values exist
• added aggregate exclusion debug logging with explicit reasons (unknown, unavailable, non_numeric, unit_mismatch)
• added zone mapping duplicate warnings in setup/options and new duplicate diagnostics sensor state
• added alert_only_mode (monitor + alerts only) to suppress automation control lanes for users without output hardware
• improved UI placeholder pruning so optional outputs/controls are hidden when not configured, including alert-only control suppression
• fixed alert-only card rendering edge case by pruning invalid leftover conditional blocks after entity pruning
• updated Current Air Control reason field behavior for alert-only mode so it reports monitoring/alerts context and does not imply missing output controls
• options changes that flip alert_only_mode now trigger UI card refresh/export regeneration and a notification
• expanded options flow editing so users can revisit skipped lanes and add/edit alerts later
• expanded post-configuration lane management so humidifier and AQ lanes can be re-added after removal, and telemetry changes log explicit add/update/remove actions
• alert target lights are now fully optional end-to-end (config/options/service/runtime); alerts still trigger without flash entities
• hardened service input validation (safe filename/url path/layout checks), bounded flash parameters, and diagnostics attribute redaction for sensitive keys

Migration notes

• alert_only_mode is now available in Global Gates (setup and options). Disable it later to restore normal control entities/lane behavior.
• new computed sensor: HI Zone Mapping Duplicates (hi_<entry_id>_zone_mapping_duplicates) exposes duplicate zone mapping status and details.
• new computed sensors:
  • HI Active Target Season (hi_<entry_id>_target_season)
  • HI House Humidity State (hi_<entry_id>_house_humidity_state)
• generated V2 cards now prune unresolved optional control/output entities instead of leaving stale references.
• if your dashboard uses Manual cards, re-copy/paste the latest exported YAML after changing alert_only_mode so the UI and reason panel match the selected mode.

---

Design Philosophy

• determinism over cleverness
• transparency over magic
• one authoritative state
• explicit override hierarchy
• safe fallback over silent failure

Humidity Intelligence V2 your environmental runtime architecture.