Skip to content

Services Reference

Senyo edited this page Nov 8, 2026 · 19 revisions

Humidity Intelligence Wiki

Services Reference

Current Stable guidance: v2.1.2 release and upgrade steps.

Humidity Intelligence services are available from Home Assistant Developer Tools -> Actions under the humidity_intelligence domain.

Use this page as a practical manual. The current repository services.yaml, runtime code, diagnostics, and release notes remain the source of truth for exact service schemas and behavior in a release.

Before You Run A Service

  1. Open Developer Tools -> Actions.
  2. Select a humidity_intelligence service.
  3. Fill the service data using the UI fields or YAML.
  4. Run the service.
  5. Verify the result in notifications, generated files, diagnostics, or the dashboard.

Notes:

  • entry_id is optional for most services.
  • When entry_id is omitted, HI uses all entries or the first valid entry according to that service's behavior.
  • Report JSON from dump_diagnostics, self_check, and v205_release_check is written under /config/humidity_intelligence/exports/.
  • Generated card YAML from dump_cards, view_cards, trusted setup/options regeneration, and release-check test exports is written under /config/humidity_intelligence/ui/.
  • Registered dashboard YAML remains under /config/dashboards/<url_path>.yaml.
  • Native Home Assistant diagnostics are the preferred public GitHub support attachment.
  • Default generated V2 dashboards are status/read-only surfaces where appropriate. Runtime-changing actions belong in explicit Home Assistant service/admin workflows.

Dashboard And Card Services

Service Use
create_dashboard Compatibility-only admin action that performs no writes and returns Manual-card guidance.
view_cards Admin-only single-layout export plus an exact file-path notification.
dump_cards Admin-only generated card export for Manual dashboards.
refresh_ui Rebuild entity mapping and the rendered in-memory card cache.

Export Manual Card YAML

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

Omit layout to export all cached layouts. Supply a layout such as v2_mobile or v2_tablet when you only want one layout. Single-entry installations use unqualified default names such as /config/humidity_intelligence/ui/humidity_intelligence_cards_v2_mobile.yaml. Multi-entry installations add an entry-qualified token before the layout so entries do not overwrite each other.

dump_cards writes the files but does not post a completion path notification. Open /config/humidity_intelligence/ui/ in File Editor after the action. Use view_cards when you want the exact written path in a persistent notification. First-run and relevant options regeneration also post every exact path. After adding or removing an entry or using a custom basename, prefer one of those notified paths instead of inferring a filename.

After changing options, output-detail visibility, optional card rows, or mappings, export fresh YAML and replace the complete YAML in the relevant Manual card. For the v2.1.2 update, revisions 1–15, including beta.1 revision 14, require fresh revision-16 exports and complete saved-card replacement. Existing revision-16 cards remain compatible. See the card update sequence.

External dump_cards, view_cards, and create_dashboard calls require an authenticated admin user context. Contextless background automations/scripts are rejected. Trusted first-run/options regeneration uses the integration's internal export path and does not route through the public service handler.

Create A Dashboard

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

This retained service no longer creates, registers, replaces, or removes a dashboard. It fails safely with guidance for the supported Manual-card flow. Run refresh_ui, export with dump_cards or view_cards, then paste the complete YAML into a Home Assistant Manual card. Existing dashboards and legacy identifiers are retained.

Refresh Rendered UI

service: humidity_intelligence.refresh_ui
data: {}

refresh_ui rebuilds mappings and the rendered in-memory card cache. HI can also run this shortly after Home Assistant startup when the startup refresh option is enabled. It does not write YAML; use dump_cards or view_cards for files, then re-copy already-pasted Manual cards.

See Generated Dashboards and Troubleshooting Generated UI.

Runtime Control Services

Service Use
pause_control Pause the automation engine for a set number of minutes.
resume_control Resume the automation engine by clearing the pause timer.
service: humidity_intelligence.pause_control
data:
  minutes: 60
service: humidity_intelligence.resume_control
data: {}

Use these when you intentionally want HI to stand down or return to normal operation. The reason panel and diagnostics are the best places to verify the current runtime state.

Every scoped and unscoped pause_control / resume_control call requires an authenticated admin user context. Supplying entry_id keeps the action scoped to the selected config entry; it does not bypass authorization.

Alert Light Test Service

flash_lights is an admin-only external action for testing configured visual-alert lights. Invoke it from an authenticated admin UI or API session. Non-admin, unknown-user, and contextless background calls are rejected before light or optional power-circuit work begins.

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

Runtime humidity, mould, and condensation visual alert rules use a separate trusted internal helper only after the deterministic engine selects the active alert lane. The public service does not select, reorder, or override a control lane. Carbon-monoxide emergency stays the highest-priority safety lane.

Diagnostics And Validation Services

Service Use
self_check Validate mappings, telemetry setup, drift-helper status, frontend dependency status, and local HI snapshot status.
v205_release_check Validate the installed package without controlling devices; rebuild the in-memory mapping/card cache and write a private report and notification.
dump_diagnostics Export fuller local diagnostics for maintainer/debug workflows.
service: humidity_intelligence.self_check
data: {}

self_check writes its fixed entity-bearing report to /config/humidity_intelligence/exports/humidity_intelligence_self_check.json. Treat it as local/private until reviewed or sanitized.

service: humidity_intelligence.v205_release_check
data:
  write_test_exports: false
  require_local_hi_snapshot: false
  filename: humidity_intelligence_v205_release_check.json

In v2.1.2, v205_release_check keeps its historical service name while validating v2.0.5-v2.0.12 and the v2.1.0, v2.1.1 and v2.1.2 beta/rc/stable lines. It can verify generated-card visibility, cached layout coverage, placeholder sanity, card text sanity, configured entity availability, drift-helper status, optional frontend dependency status, and local HI snapshot status. It writes its validation report under /config/humidity_intelligence/exports/. With write_test_exports: true, it also writes scoped and unscoped test card exports under /config/humidity_intelligence/ui/ to confirm export-scope behavior. It is runtime/device read-only: output service calls, helper changes, dashboard mutation, and Home Assistant reloads stay outside this validation service.

The report-only example disables test exports and the local snapshot requirement. The check still rebuilds its in-memory mapping/card cache, writes its private report and posts a notification. Preserve existing fixed-name reports before recollecting; generated exports do not replace saved Manual cards automatically.

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

Use native Home Assistant diagnostics for public GitHub issues first. Use dump_diagnostics for deeper local maintainer/debug workflows after reviewing the export. Caller-selectable report filenames must use the exact lowercase humidity_intelligence_*.json pattern and are written under /config/humidity_intelligence/exports/.

External self_check, v205_release_check, and dump_diagnostics calls require an authenticated admin user context. Non-admin, unknown-user, and contextless calls are rejected before work begins.

See Diagnostics and Support Bundle and Release Validation for Users.

Local HI Snapshot Services

Service Use
create_local_backup Admin-only creation of a package-local HI snapshot for advanced validation and rollback preparation.
list_saved_versions Admin-only read of finalized local HI snapshots and invalid snapshot folders.
service: humidity_intelligence.create_local_backup
data:
  retain_count: 2
  max_total_bytes: 52428800
service: humidity_intelligence.list_saved_versions
data: {}

These snapshots are local to the Humidity Intelligence package. Home Assistant backups remain the right tool for whole-instance protection, and HACS continues to own HACS-managed updates.

External create_local_backup and list_saved_versions calls require an authenticated admin user context. Non-admin, unknown-user, and contextless calls are rejected before snapshot creation, retention cleanup, or inventory disclosure begins. list_saved_versions remains read-only; its admin boundary protects the snapshot inventory exposed through Home Assistant persistent notifications.

Cleanup Service

purge_files is an admin-only, exact-owned-artifact cleanup service. It posts a blocking preview before deletion and reports partial failures instead of treating them as success.

service: humidity_intelligence.purge_files
data: {}

Use dump_diagnostics first when you want a troubleshooting snapshot before cleanup.

Ownership is deliberately narrow:

  • an entry_id-scoped purge may remove that entry's exact default/release-test card exports, but no reports or Home Assistant dashboards
  • only an unscoped all-entry purge may additionally remove the exact default diagnostics report and fixed self-check report
  • custom card exports, custom reports, release-check reports, and legacy config-root JSON/YAML remain retained

Config-entry removal has a separate exact cleanup path: it removes only the deleted entry's default/release-test card exports. It does not remove Home Assistant dashboards, reports, custom exports, or legacy root files.

Manually Remove A Retained File

Manual cleanup is appropriate only for an exact legacy or custom file that HI intentionally leaves outside purge ownership:

  1. generate and validate the replacement in /config/humidity_intelligence/exports/ or /config/humidity_intelligence/ui/
  2. back up and update every file sensor, shell command, script, or support tool that consumes the old path
  3. confirm the old file is no longer being read
  4. use File Editor, Studio Code Server, Samba, or SSH to delete only that exact regular file
  5. refresh the file view and verify the current artifact and dashboard

Do not delete either owned directory, use wildcard deletion, follow a symlink/non-regular object, or manually delete registered dashboard YAML. Use HI's previewed cleanup or Home Assistant dashboard management for registered dashboards. Removing an unused retained file does not itself require a restart.


Previous Next
UI Gallery HACS and Updates

Clone this wiki locally