Skip to content

Add state-aware adaptive polling and outage boost trigger - #328

Open
binarydev wants to merge 1 commit into
mainfrom
feat/adaptive-polling
Open

binarydev wants to merge 1 commit into
mainfrom
feat/adaptive-polling

Conversation

@binarydev

Copy link
Copy Markdown
Owner

Summary

Implements state-aware adaptive cloud polling (idle, active, cooldown, and boost modes) for GeneracDataUpdateCoordinator, introduces the generator Outage Boost Poll (button) platform entity, registers the generac.boost_polling service (documented in services.yaml and translations/en.json), and exposes active_scan_interval configuration across the UI options and reconfigure flows.

Motivation

  • Polling Generac's rate-limited cloud API at a single fixed interval forces a trade-off between API friendliness during normal standby (900 s default) and timely updates during generator runs, exercises, warnings, or utility power outages.
  • Automatically tightening polling to active_scan_interval (120 s default) when devices are active—with a 300 s cooldown back to idle—gives responsive live telemetry without hammering the API during standby.
  • Providing an Outage Boost Poll button per generator and a generac.boost_polling action lets users and automations trigger immediate fast polling on grid power loss.

Key Changes

  • Constants & Platforms (custom_components/generac/const.py):
    • Added BUTTON = "button" to PLATFORMS ([BINARY_SENSOR, SENSOR, WEATHER, IMAGE, BUTTON]).
    • Added CONF_ACTIVE_SCAN_INTERVAL = "active_scan_interval", DEFAULT_ACTIVE_SCAN_INTERVAL = 120, ACTIVE_COOLDOWN_SECONDS = 300, DEFAULT_BOOST_DURATION_MINUTES = 30, and SERVICE_BOOST_POLLING = "boost_polling".
    • Added CONF_ACTIVE_SCAN_INTERVAL (and button via PLATFORMS) to CONF_OPTIONS.
  • Adaptive Coordinator (custom_components/generac/coordinator.py):
    • Reads idle_scan_interval (CONF_SCAN_INTERVAL, default 900) and active_scan_interval (CONF_ACTIVE_SCAN_INTERVAL, default 120) safely via collections.abc.Mapping, clamping both >= 10 s and computing fast_scan_interval = min(idle_scan_interval, active_scan_interval).
    • Added _is_fleet_active(items) detecting generator apparatusStatus in (2, 3, 4, 5) (Running, Exercising, Warning, Stopped), isConnecting is True, showWarning is True, or any apparatus property with isRunning is True.
    • Tracks _cooldown_until (300 s) and _boost_until via time.monotonic(), exposes polling_mode ("boost" | "active" | "cooldown" | "idle") and is_fast_polling properties, dynamically adjusts update_interval, and adds async_trigger_boost(duration_seconds=DEFAULT_BOOST_DURATION_MINUTES * 60) to set boost duration, switch to fast polling, and request an immediate refresh.
  • Button Platform (custom_components/generac/button.py):
    • Added OutageBoostButton(GeneracEntity, ButtonEntity) for each generator (DEVICE_TYPE_GENERATOR) with entity_key = "boost_polling", entity_label = "Outage Boost Poll", and _attr_icon = "mdi:lightning-bolt-circle", calling await self.coordinator.async_trigger_boost() on press.
  • Service Registration & Schema (custom_components/generac/__init__.py, custom_components/generac/services.yaml):
    • Idempotently registers generac.boost_polling in async_setup_entry with BOOST_POLLING_SCHEMA (duration_minutes 1–120 default 30, optional entry_id), targeting the matching or all loaded GeneracDataUpdateCoordinator instances (ignoring non-coordinator domain data).
    • Unregisters generac.boost_polling in async_unload_entry when unloaded is True and no GeneracDataUpdateCoordinator remains in hass.data[DOMAIN].
    • Added custom_components/generac/services.yaml documenting boost_polling fields and selectors.
  • Config Flow, Translations & Docs (custom_components/generac/config_flow.py, translations/{en,fr,nb,pt}.json, README.md):
    • Exposed CONF_ACTIVE_SCAN_INTERVAL in async_step_reconfigure (including across MFA flows) and GeneracOptionsFlowHandler (via CONF_OPTIONS).
    • Updated translations/{en,fr,nb,pt}.json with active_scan_interval and button labels, and added the services.boost_polling section in translations/en.json.
    • Documented the button platform, adaptive polling intervals/cooldown, Outage Boost Poll button, and generac.boost_polling service in README.md.
  • Tests (tests/):
    • Added tests/test_button.py (button attributes, generator-only platform setup, HA button.press integration).
    • Expanded tests/test_coordinator.py (interval clamping, min(idle, active), mock options fallback, _is_fleet_active variants, idle -> active -> cooldown -> idle transitions, and async_trigger_boost lifecycle).
    • Expanded tests/test_init.py (idempotent service registration, multi-entry & entry_id targeting, out-of-range schema validation, non-coordinator domain key safety, unload cleanup, and services.yaml + async_get_all_descriptions validation).
    • Updated tests/test_entity_registry.py (NEW_SUFFIXES for boost_polling -> button.generator_outage_boost_poll, len(classes) == 35) and tests/test_config_flow.py (test_options_flow, active_scan_interval reconfigure + MFA preservation).

User Configuration / Migration Notes

  • No breaking changes to existing entity unique_ids or entity_keys.
  • Existing entries keep their configured scan_interval (default 900 s) as the idle interval and gain active_scan_interval (default 120 s) plus the Outage Boost Poll button entity per generator on reload/upgrade.
  • Users can customize Active polling interval (seconds) and Buttons enabled under Settings → Devices & services → Generac MobileLink → Configure (or Reconfigure), and invoke generac.boost_polling from automations.

Test Plan

  • Ran /Users/binarydev/Projects/ha-generac/.venv/bin/pytest --maxfail=3 --disable-warnings: 146 passed across all 14 test modules (test_api.py, test_auth.py, test_binary_sensor.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_sensor.py, test_weather.py).
  • Ran /opt/homebrew/bin/pre-commit run --all-files --show-diff-on-failure: all 8 hooks passed (check-added-large-files, check-yaml, end-of-file-fixer, trailing-whitespace, flake8, reorder-python-imports, black, prettier).
  • Verified JSON validity across manifest.json and translations/{en,fr,nb,pt}.json, plus services.yaml validation against Home Assistant's _SERVICES_SCHEMA and async_get_all_descriptions.

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