Skip to content

Configuration Walkthrough

Senyo edited this page Nov 8, 2026 · 22 revisions

Humidity Intelligence Wiki

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.

Version-specific labels

v2.1.2 is the current Stable release, published on 8 November 2026. The labels below match its configuration flow. Check the version offered in Settings → Marketplace on Home Assistant 2026.11 or later, or in HACS on earlier supported versions, before updating.

Earlier label Current v2.1.2 label
Frontend Dependencies Dashboard add-ons
Global Gates Operating schedule & limits
Telemetry Inputs / Telemetry Options Sensors / Sensor settings
Temperature Slope Temperature change settings
Thresholds & Comfort Comfort and thresholds
Humidifiers (options menu) Humidifier control
Air Quality (options menu) Air quality control
Finish (final options action) Save changes

The configuration screenshots below show an earlier layout. The written guidance reflects the v2.1.2 configuration options. Existing saved keys remain compatible. The built-in Autumn target is 50–60%, with humidity danger at 64%; optional output monitoring retains its own saved rules. Screenshot values are examples, not current profile defaults. The first-run welcome page still supports starting with a small sensor set and returning to settings for further configuration. Advanced sections remain collapsible.

Before You Start

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.

Finding the Integration

Open Settings -> Devices & services -> Humidity Intelligence.

Humidity Intelligence integration overview

Earlier layout; written guidance reflects current options.

Use the integration entry to open the options workflow.

The Setup Shape

Humidity Intelligence setup is deliberately staged:

  1. welcome and setup strategy
  2. Dashboard add-ons
  3. Operating schedule & limits
  4. Sensors
  5. Temperature change settings
  6. zones, starting with optional level display labels
  7. humidifiers
  8. air quality
  9. alerts
  10. UI Cards: choose which Manual-card layouts to export

Essentials stay visible first. Expert controls sit in advanced sections so a normal setup stays approachable. V2 Tablet is the default export; V2 Mobile, the retained deprecated V1 Mobile skin and the View Cards Button are also choices. HI exports card fragments; create or open the dashboard in Home Assistant and paste a complete fragment into a Manual card. Setup does not create or replace a dashboard.

Humidity Intelligence options menu

Earlier menu layout. Current settings include Output monitoring and Save changes.

After setup, Configure opens Settings with these sections: Dashboard add-ons, Sensors, Operating schedule & limits, Comfort and thresholds, Zones, Humidifier control, Air quality control, Alerts, Temperature change settings, Output monitoring, and Save changes. Section edits stay in the session until Save changes.

When first-run or options regeneration writes card YAML, HI posts the exact /config/humidity_intelligence/ui/... paths in a notification. Multi-entry installations use entry-qualified filenames. Open the notified file rather than guessing a name, then copy its full YAML into the relevant Manual card.

If you are upgrading from the older config-root writer, do not reuse a retained file such as /config/humidity_intelligence_cards_v2_mobile.yaml. HI no longer refreshes that root file. Refresh File Editor after export and use only the new notified /config/humidity_intelligence/ui/... path.

Dashboard add-ons

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.

Operating schedule & limits

This page configures operating schedules, presence conditions and target profiles. CO Emergency remains independent and highest priority; these settings are not a promise that emergency ventilation stops outside ordinary operating conditions.

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.

For the v2.1.1 built-in Autumn profile, 50–60% is in target, readings above 60% are above target, and 64% or higher meets the humidity-danger threshold. Automatic mode selects Autumn during September–November; explicit Autumn selection uses the same profile. The target band affects humidifier start/recovery and target-relative mould interpretation. No new danger-threshold setting is added.

Use Custom only when you want its separate profile calculation. Under advanced settings, a custom low of 50% and high of 60% derives high risk at 67.5%, rather than the built-in Autumn value. Return to the settings menu and use Save changes to persist the staged settings. Existing custom bands keep their derivation. HI profile boundaries are not universal safe humidity cutoffs; current readings, temperature, condensation/mould context and backend reasons remain relevant.

Important: gates are visible runtime truth. If a gate blocks control, the reason panel and generated dashboard should say so.

Global gates essential options

Earlier layout; written guidance reflects current options.

Advanced global-gate controls include the control-loop interval, startup UI mapping refresh, generated-card output detail visibility, and custom humidity target bands.

Global gates advanced tuning options

Earlier layout; written guidance reflects current options.

Sensors

Telemetry is where HI learns what the home is doing.

For useful environmental control, configure humidity and temperature sensors for active levels. Setup can save a small initial sensor set; missing evidence remains explicit until configured inputs are available. Add air-quality telemetry only where you have suitable Home Assistant entities.

For each sensor, keep these stable:

  • entity
  • type
  • level
  • friendly area name (the stored 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.

Telemetry inputs before sensors are added

Earlier layout; written guidance reflects current options.

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.

Add telemetry sensor form

Earlier layout; written guidance reflects current options.

Comfort and thresholds

This options page sets Temperature comfort mode and its custom temperature band. Its advanced section also edits the two zones' saved trigger thresholds. Humidity seasonal/custom profile selection and custom humidity bands are under Operating schedule & limits. Keep seasonal profiles unless a deliberate custom band is needed.

Thresholds and comfort essential options

Earlier layout; written guidance reflects current options.

Advanced threshold controls are for deliberate tuning after observing real behavior. Custom comfort values and deterministic zone thresholds should stay explainable and profile-relative.

Thresholds and comfort advanced tuning options

Earlier layout; written guidance reflects current options.

Temperature change settings

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. If an Advanced source list is collapsed and submits empty, HI falls back to the configured temperature sensors or saved source defaults instead of trapping setup in a hidden validation error.

Temperature slope advanced options

Earlier layout; written guidance reflects current options.

Zones

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 1 and Level 2
  • entity IDs, helpers, levels, zones, outputs, and runtime lanes keep their existing identities
  • lane priority, zone ownership, output mapping, services, and backend control semantics stay backend-owned

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.

After updating an existing install, review these labels if your household uses custom floor or level names. Changing them updates display text after options are saved and generated cards are refreshed; entity IDs and runtime behavior keep their existing contracts.

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.

Zone essential options

Earlier layout; written guidance reflects current options.

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.

Zone advanced tuning options

Earlier layout; written guidance reflects current options.

Humidifiers

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.

Humidifier lane essential options

Earlier layout; written guidance reflects current options.

Advanced humidifier controls include lane removal and target-band adjustment. Use them only when the humidifier should intentionally offset the active comfort band.

Humidifier lane advanced tuning options

Earlier layout; written guidance reflects current options.

Air Quality

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.

Air quality lane essential options

Earlier layout; written guidance reflects current options.

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.

Air quality lane advanced tuning options

Earlier layout; written guidance reflects current options.

Alerts

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.

Visual indicator rule essential options

Earlier layout; written guidance reflects current options.

Advanced visual-indicator controls include thresholds, power entity selection, flash mode, and flash duration.

Visual indicator rule advanced tuning options

Earlier layout; written guidance reflects current options.

Output monitoring and reusable meanings

Open Configure -> Output monitoring -> Monitoring and dashboard view to enable optional monitoring and choose native or adaptive Outputs presentation. Use Add a monitoring rule to select an output, source, meaning and exact rule. Numeric rules use strict below/above comparisons: equality does not match and units are not converted. HI does not infer a filter threshold from the source name.

A saved Filter replacement meaning is neutral. Filter replacement suggested appears only when its rule matches. Faults stay explicit, and absent or unavailable readings do not establish device health. For current details and resource setup, see the canonical output-monitoring guide.

Monitoring starts disabled with native presentation. Adaptive presentation needs the packaged /humidity_intelligence/hi-adaptive-output-card.js dashboard resource registered as a JavaScript module, plus a fresh card export and complete YAML replacement. Monitoring never commands devices or changes lane priority.

Manage reusable meanings opens the entry's Reusable monitoring meanings library. Add a plain-text name, an existing classification and optional What to do guidance; each source keeps its own exact detection rule. Names allow up to 80 characters, guidance up to 240 characters and the library up to 32 meanings. Rename, reclassification and deletion show affected rules for review. An in-use meaning needs an explicit replacement or removal of its rules. Missing definitions and unavailable sources remain incomplete evidence, never clear monitoring.

Import companion rules is an explicit, previewed import from an eligible companion bound to this HI entry. It does not modify or disable the companion and does not import its pending historical observation custody. Validate any migration before separately changing companion operation.

Saving and cancelling

Sensor Keep sensor changes and rule confirmation stage edits only. Monitoring Keep changes and return retains its draft in the main settings session. Only Save changes persists the options. Discard this visit's monitoring edits discards that visit's edits while preserving earlier staged settings.

On sensor Cancel confirmation, Keep editing returns to the originating form with entered values retained. Close without saving discards the unsaved session. Home Assistant's own close button bypasses this custom confirmation. Saving options uses the existing integration reload, which resets in-memory history; it does not restart Home Assistant.

Return without changing cancels a nested meaning editor. Leaving the monitoring preview confirmation unchecked discards only that proposed change. Renamed entities or changed registry identities need explicit review; a saved meaning cannot confer another device's identity or rule.

Stability has no frontend score-setting form. It reads configured environmental evidence and saved thresholds; the Stability guide explains its baseline, availability, rounding and caps. Neither a custom monitoring meaning nor its guidance changes that calculation. To change only the badge display, hold the Stability badge itself. The preference belongs to your signed-in account and HI entry, rather than this settings form; tap details and backend collection continue.

See Output Monitoring for resource setup, source recovery and rollback with custom meanings.

Stability Input Coverage

Stability Score uses existing seasonal/custom targets, room/level humidity, risk/drift telemetry and configured AQ conditions. Formula 4 uses individual AQ measurements before composite IAQ. Missing hardware, unmapped conditions and unavailable evidence remain distinct. Restart/reload requires a new baseline of at least 303 valid samples plus the other evidence requirements; rolling coverage uses 432 ten-minute buckets. No V2 configuration migration is required.

House Humidity Drift 7d

Create or verify the Home Assistant Statistics helper using the actual registered HI House Average Humidity entity, a mean characteristic and seven-day max age. The expected helper entity is sensor.house_humidity_mean_7d; do not create a duplicate if it already exists. See the helper setup details. Allow real history to accumulate; unknown, unavailable and insufficient coverage stay explicit in Diagnostics and Repairs.

After Setup

After setup:

  1. confirm the integration loads in Settings -> Devices & services
  2. check the main HI entities
  3. open the notified YAML export and add or replace a Manual card in your dashboard
  4. refresh/export and replace the complete pasted YAML after relevant mapping or UI changes
  5. download diagnostics if anything looks off

For UI-specific symptoms, see Troubleshooting Generated UI.

For support reports, see Getting Help.

The current flow is defined by repository config_flow.py, monitoring options and form labels. Those sources own behavior; this walkthrough is support guidance.


Previous Next
FAQ Understanding Control Decisions

Clone this wiki locally