Configuration Walkthrough
This walkthrough is for a normal Home Assistant install where Humidity Intelligence is already installed and you are setting it up through the integration UI.
The exact form labels can change between releases. Treat this page as the practical manual, while the current README and integration UI carry the release-specific setup truth. A documentation issue helps bring the manual back into sync when wording drifts.
Have these ready:
- humidity sensors
- temperature sensors
- optional air-quality sensors
- optional presence, alarm, time, or manual gate entities
- optional fan, purifier, humidifier, ventilation, or alert-light outputs
- a rough idea of which rooms belong to each level or zone
Use stable, readable room labels. The labels are part of the explanation layer; they help the reason panel, diagnostics, and generated dashboards stay understandable.
Open Settings -> Devices & services -> Humidity Intelligence.
Use the integration entry to open the options workflow.
Humidity Intelligence setup is deliberately staged:
- frontend dependency awareness
- global gates
- telemetry inputs
- temperature slope
- zones, starting with optional level display labels
- humidifiers
- air quality
- alerts
- dashboard and post-configuration workflow
Essentials stay visible first. Expert controls sit in advanced sections so a normal setup stays approachable.
This step helps you understand which optional Lovelace cards Home Assistant can see.
Optional frontend cards can improve presentation, while the backend control engine continues to use its own runtime truth. When Home Assistant exposes limited Lovelace resource information, treat that as a UI support signal first.
If frontend dependency detection is incomplete, continue setup and use generated dashboard troubleshooting later. Optional cards must not block the backend control engine.
Global gates decide whether Humidity Intelligence is allowed to act.
Common examples:
- time windows
- presence or alarm state
- manual pause
- outside action behavior
- target profile mode
Start with recommended defaults unless you already know the home needs a different control window or target profile.
Important: gates are visible runtime truth. If a gate blocks control, the reason panel and generated dashboard should say so.
Advanced global-gate controls include the control-loop interval, startup UI mapping refresh, generated-card output detail visibility, and custom humidity target bands.
Telemetry is where HI learns what the home is doing.
At minimum, configure humidity and temperature sensors for active levels. Add air-quality telemetry only where you have suitable Home Assistant entities.
For each sensor, keep these stable:
- entity
- type
- level
- room label
Assign every sensor to a level and room, even if you mostly care about whole-house averages. That gives HI better context for diagnostics, generated cards, and alert source explanation.
When adding a telemetry sensor, choose the Home Assistant entity, sensor type, level, and room label deliberately. Use labels that will still make sense in support reports and generated dashboards.
Review comfort mode before tuning individual thresholds. Seasonal mode is the normal starting point.
Advanced threshold controls are for deliberate tuning after observing real behavior. Custom comfort values and deterministic zone thresholds should stay explainable and profile-relative.
Temperature slope helps HI understand direction alongside the current reading.
Most users should let HI calculate slope from configured temperature sensors. Use provided slope sensors only when those entities are already stable and trusted in Home Assistant.
The optional temperature chip row is a display choice. It shows backend comfort and slope truth from HI rather than dashboard-side threshold guesses.
Advanced temperature-slope options let you decide whether HI calculates slope or uses provided slope sensors. Source selection should use stable temperature entities only.
Zones connect environmental problems to output behavior.
Before editing Zone 1 or Zone 2, the Zones step includes Level display labels. Use this section only when you want friendlier names for the two level choices shown in configuration, support output, and generated dashboard text.
These labels are display-only:
- Level 1 display label writes to
level_labels.level1 - Level 2 display label writes to
level_labels.level2 - empty labels fall back to
Level 1andLevel 2 - labels do not rename entities, helpers, levels, zones, outputs, or runtime lanes
- labels do not change lane priority, zone ownership, output mapping, services, or backend control semantics
Set labels before configuring individual zones so the Zone 1 / Zone 2 forms, trigger labels, generated cards, diagnostics, and support text use the same wording. The stored keys remain global even though the editor lives in the Zones workflow. After setup, open Options -> Zones -> Level display labels to edit the same display-only labels before changing Zone 1 or Zone 2.
A useful zone has:
- a readable label
- a level
- assigned rooms
- trigger context
- configured outputs
- normal and boost output stages where relevant
Boost should normally be stronger than the normal zone stage. Normal correction handles routine imbalance. Boost is for higher-priority escalation such as condensation, mould-risk, or humidity danger.
Advanced zone controls include normal and boost fan levels plus the Current Air Control label used by generated cards. These labels are display truth only; they do not create new lane decisions.
Enable humidifier lanes only where you have real humidifier hardware.
Humidifier behavior is independent from the selected ventilation lane. That separation is intentional and keeps ventilation and humidification from competing through hidden dashboard logic.
Advanced humidifier controls include lane removal and target-band adjustment. Use them only when the humidifier should intentionally offset the active comfort band.
Enable air quality only where you have suitable telemetry and outputs.
Supported AQ telemetry can include indoor air quality, PM2.5, VOC, CO2, and CO, depending on what the current release and your configured Home Assistant entities provide.
AQ is below emergency and moisture-risk lanes in the priority order. If a higher priority issue is active, normal AQ response may wait.
Advanced AQ controls include lane removal, run duration, fan level, and trigger thresholds. Keep AQ thresholds aligned with the sensor semantics you actually trust in Home Assistant.
Alerts are derived from HI telemetry and risk logic. Humidity, mould, condensation, and carbon-monoxide behavior stays tied to that explainable model.
Where an alert can be resolved to a room and zone, HI can use the configured zone boost path. When the source mapping is incomplete, HI can explain the degraded state and keep control on a safe path.
Visual indicator rules can map internal HI alert sources to optional target lights. They are a notification surface, not a second control engine.
Advanced visual-indicator controls include thresholds, power entity selection, flash mode, and flash duration.
After setup:
- confirm the integration loads in Settings -> Devices & services
- check the main HI entities
- open the generated dashboard
- run the supported card export or refresh flow if needed
- download diagnostics if anything looks off
For UI-specific symptoms, see Troubleshooting Generated UI.
For support reports, see Getting Help.
| Previous | Next |
|---|---|
| FAQ | Understanding Control Decisions |