Skip to content

Add proactive readiness alerts, maintenance timer, and bundled bluepr… - #327

Merged
binarydev merged 1 commit into
mainfrom
feat/readiness-and-blueprints
Nov 18, 2026
Merged

binarydev merged 1 commit into
mainfrom
feat/readiness-and-blueprints

Conversation

@binarydev

Copy link
Copy Markdown
Owner

Summary

Adds proactive generator readiness tracking persisted in Home Assistant storage (Store), expands Home Assistant Repairs alerts for battery, exercise, maintenance, and subscription health, exposes Hours Until Service, Missed Exercise, and Reset Maintenance Timer entities per generator, and bundles three validated automation blueprints that install automatically on integration setup.

Motivation

  • Standby generators can silently fail due to weak starting batteries, missed weekly/biweekly exercise runs, overdue oil/filter service intervals, or past-due Mobile Link subscriptions.
  • Persisting readiness state in ConfigEntry.data would trigger unnecessary reloads on every poll; using homeassistant.helpers.storage.Store keeps persistence completely reload-free.
  • Home Assistant users benefit from ready-to-use automation blueprints tailored to Generac status transitions, dealer contact details, and pre-storm readiness digests without writing Jinja2 templates from scratch.

Key Changes

  • Configuration Options & Translations (custom_components/generac/const.py, config_flow.py, translations/{en,fr,nb,pt}.json):
    • Added BUTTON = "button" to PLATFORMS ([BINARY_SENSOR, SENSOR, WEATHER, IMAGE, BUTTON]).
    • Added options CONF_SERVICE_INTERVAL_HOURS = "service_interval_hours" (default 100, int), CONF_EXERCISE_INTERVAL_DAYS = "exercise_interval_days" (default 16, int; 0 disables missed-exercise alerts), and CONF_LOW_BATTERY_THRESHOLD = "low_battery_threshold" (default 12.2, float) to CONF_OPTIONS.
    • Updated GeneracOptionsFlowHandler with _option_validator (non-negative int / vol.Coerce(float) ranges) and safe entry_options mapping reads.
    • Added option translations in en.json, fr.json, nb.json, and pt.json, plus Repairs issues entries (low_battery_voltage, missed_exercise, maintenance_due, subscription_dunning) in translations/en.json.
  • Readiness Persistence & Coordinator (custom_components/generac/readiness.py, coordinator.py, utils.py):
    • Extracted shared entry_options, get_detail_property_value, and safe_float helpers into utils.py (reused by sensor.py, readiness.py, issues.py, coordinator.py, config_flow.py, and __init__.py).
    • Created ReadinessTracker backed by Store(hass, 1, f"{DOMAIN}.{entry.entry_id}.readiness") (instantiated only when entry.entry_id is a str).
    • Tracks per-generator {"last_exercise_ts": float, "last_run_time": float | None, "service_baseline_hours": float}: initializes service_baseline_hours = current_run_time or 0.0 on first sight to prevent day-1 false alarms, detects exercise activity via apparatusStatus in (2, 3) (Running/Exercising) or positive run_time deltas between polls, and exposes hours_since_service, hours_until_service, days_since_exercise, is_missed_exercise, and async_reset_service_timer on both ReadinessTracker and GeneracDataUpdateCoordinator.
  • Proactive Repairs Alerts (custom_components/generac/issues.py, __init__.py):
    • Added async_update_device_health_issues and async_delete_all_entry_issues (invoked alongside async_remove_readiness_store in async_remove_entry):
      1. low_battery_voltage (low_battery_voltage_{entry_id}_{device_id}): raised when generator detail property 70 satisfies 0 < voltage < low_battery_threshold; cleared when >= threshold, 0, or None.
      2. missed_exercise (missed_exercise_{entry_id}_{device_id}): raised when exercise_interval_days > 0 and (now - last_exercise_ts) > exercise_interval_days * 86400; cleared on exercise/run activity or when set to 0.
      3. maintenance_due (maintenance_due_{entry_id}_{device_id}): raised when service_interval_hours > 0 and hours_since_service >= service_interval_hours or detail.hasMaintenanceAlert is True; cleared once timer is reset and hasMaintenanceAlert is falsy.
      4. subscription_dunning (subscription_dunning_{entry_id}_{device_id}): raised when detail.subscription is not None and detail.subscription.isDunning is True; cleared otherwise.
    • Sweeps stale device issues when devices leave coordinator payloads without affecting other config entries.
  • Generator Readiness Entities (custom_components/generac/sensor.py, binary_sensor.py, button.py):
    • Added HoursUntilServiceSensor (sensor.py, entity_key = "hours_until_service", entity_label = "Hours Until Service", SensorDeviceClass.DURATION, unit UnitOfTime.HOURS ("h"), SensorStateClass.MEASUREMENT, _attr_icon = "mdi:wrench-clock").
    • Updated binary_sensor.py sensors(item: Item | None = None) and added GeneracMissedExerciseSensor (entity_key = "missed_exercise", entity_label = "Missed Exercise", BinarySensorDeviceClass.PROBLEM) for generators (DEVICE_TYPE_GENERATOR).
    • Added custom_components/generac/button.py with ResetServiceTimerButton (entity_key = "reset_service_timer", entity_label = "Reset Maintenance Timer", _attr_icon = "mdi:wrench-check"), resetting service_baseline_hours to current run_time, re-evaluating Repairs issues, and updating entity listeners immediately.
  • Bundled Automation Blueprints & Installer (custom_components/generac/blueprints.py, blueprints/automation/*.yaml, __init__.py, .pre-commit-config.yaml, README.md):
    • Added three automation blueprints: generac_outage_load_shedding.yaml, generac_fault_dealer_alert.yaml, and generac_storm_readiness_digest.yaml.
    • Added install_bundled_blueprints (idempotent, writes only when missing or modified) called via await hass.async_add_executor_job(...) in async_setup_entry (logging a warning on OSError).
    • Updated .pre-commit-config.yaml check-yaml hook with args: [--unsafe] for !input tags and documented readiness alerts, maintenance timer, and bundled blueprints in README.md.
  • Tests (tests/):
    • Added tests/test_blueprints.py (validating all 3 YAML blueprints against Blueprint(..., expected_domain="automation", schema=AUTOMATION_BLUEPRINT_SCHEMA), BlueprintInputs substitution + _async_validate_config_item, and install_bundled_blueprints), tests/test_button.py, and tests/test_readiness.py.
    • Expanded tests/test_issues.py, tests/test_sensor.py, tests/test_binary_sensor.py, tests/test_init.py, tests/test_config_flow.py, and tests/test_entity_registry.py (len(classes) == 37, NEW_SUFFIXES updated).

User Configuration / Migration Notes

  • No breaking changes to existing entity unique_ids or entity_keys.
  • Existing generators initialize service_baseline_hours to their current run_time and last_exercise_ts to first-poll time on upgrade/first setup, avoiding day-1 false maintenance or missed-exercise alarms.
  • Readiness thresholds (Maintenance service interval, Missed exercise alert interval, Low battery voltage alert threshold, and Buttons enabled) can be adjusted under Settings → Devices & services → Generac MobileLink → Configure.
  • Bundled blueprints are automatically copied to <config>/blueprints/automation/generac/ on integration setup.

Test Plan

  • Ran /Users/binarydev/Projects/ha-generac/.venv/bin/pytest --maxfail=3 --disable-warnings: 155 passed across all 16 test files (test_api.py, test_auth.py, test_binary_sensor.py, test_blueprints.py, test_button.py, test_config_flow.py, test_coordinator.py, test_diagnostics.py, test_entity.py, test_entity_registry.py, test_image.py, test_init.py, test_issues.py, test_readiness.py, test_sensor.py, test_weather.py).
  • Ran /opt/homebrew/bin/pre-commit run --all-files --show-diff-on-failure: all 8 hooks passed cleanly with zero remaining diffs.
  • Verified Hassfest invariants: JSON validity across manifest.json and translations/{en,fr,nb,pt}.json, and exact {placeholder} parity between issues.py and translations/en.json.

@binarydev
binarydev merged commit 5ae9d7c into main Nov 18, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant