Skip to content

Add long-term statistics, fuel autonomy, fault/VPP telemetry, and dia… - #329

Open
binarydev wants to merge 1 commit into
mainfrom
feat/telemetry-and-fuel-autonomy
Open

binarydev wants to merge 1 commit into
mainfrom
feat/telemetry-and-fuel-autonomy

Conversation

@binarydev

Copy link
Copy Markdown
Owner

Summary

Adds Home Assistant Long-Term Statistics (state_class) support to operational sensors, introduces propane tank Remaining Fuel and configurable Estimated Runtime Remaining sensors, exposes generator Error Code, Virtual Power Plant (VPP), and subscription billing dunning telemetry, and categorizes static/metadata entities under EntityCategory.DIAGNOSTIC.

Motivation

  • Numeric telemetry (run_time, protection_time, battery_voltage, exercise_minutes, outdoor_temperature, capacity, fuel_level, device_battery_level) lacked state_class, preventing Home Assistant from recording Long-Term Statistics (LTS) for historical trends and outage analysis.
  • Propane tank monitor users had percentage and capacity values without calculated gallons remaining or estimated outage runtime autonomy based on generator burn rate.
  • MobileLink payloads already include generator eCodeLabel, enrolledInVpp, hasActiveVppEvent, and subscription.isDunning, which were not surfaced as Home Assistant entities.
  • Static metadata sensors cluttered primary device dashboards because they did not use EntityCategory.DIAGNOSTIC.

Key Changes

  • Configuration & Translations (custom_components/generac/const.py, config_flow.py, translations/{en,fr,nb,pt}.json):
    • Added CONF_FUEL_BURN_RATE = "fuel_burn_rate" and DEFAULT_FUEL_BURN_RATE = 2.2 (gal/h) to const.py and CONF_OPTIONS.
    • Updated GeneracOptionsFlowHandler with _option_schema (vol.All(vol.Coerce(float), vol.Range(min=0.0, min_included=False)) for fuel_burn_rate), _option_default sanitization for invalid stored defaults, and defensive Mapping checks on config_entry.options.
    • Added fuel_burn_rate option labels to en.json, fr.json, nb.json, and pt.json.
  • Sensor Platform (custom_components/generac/sensor.py):
    • Added SensorStateClass.TOTAL_INCREASING on RunTimeSensor and ProtectionTimeSensor.
    • Added SensorStateClass.MEASUREMENT on BatteryVoltageSensor, ExerciseMinutesSensor, OutdoorTemperatureSensor, FuelLevelSensor, and DeviceBatteryLevelSensor.
    • Updated CapacitySensor with SensorDeviceClass.VOLUME_STORAGE, UnitOfVolume.GALLONS, SensorStateClass.MEASUREMENT, and _safe_float parsing.
    • Added propane monitor sensors RemainingFuelSensor (remaining_fuel, gal, VOLUME_STORAGE, MEASUREMENT) and EstimatedRuntimeSensor (estimated_runtime, h, DURATION, MEASUREMENT) powered by _remaining_gallons and _get_fuel_burn_rate (falling back safely to 2.2 when missing, non-mapping, or <= 0).
    • Added generator ErrorCodeSensor (error_code) reading stripped non-empty eCodeLabel.
    • Set _attr_entity_category = EntityCategory.DIAGNOSTIC on 15 static/metadata sensors (DeviceTypeSensor, ActivationDateSensor, LastSeenSensor, ConnectionTimeSensor, SerialNumberSensor, ModelNumberSensor, DeviceSsidSensor, AddressSensor, DealerNameSensor, DealerEmailSensor, DealerPhoneSensor, PanelIDSensor, FuelTypeSensor, OrientationSensor, SignalStrengthSensor) while keeping operational sensors primary.
  • Binary Sensor Platform (custom_components/generac/binary_sensor.py):
    • Updated sensors(item: Item | None = None) (preserving no-arg backwards compatibility) and async_setup_entry.
    • Conditionally added GeneracVppEnrolledSensor (enrolled_in_vpp, EntityCategory.DIAGNOSTIC) and GeneracActiveVppEventSensor (active_vpp_event) for generators when enrolledInVpp or hasActiveVppEvent is non-None.
    • Conditionally added GeneracSubscriptionDunningSensor (subscription_dunning, BinarySensorDeviceClass.PROBLEM, EntityCategory.DIAGNOSTIC) when subscription is non-None.
  • Documentation & Tests (README.md, tests/):
    • Updated entity tables and added configuration/telemetry documentation in README.md.
    • Expanded tests/test_sensor.py, tests/test_binary_sensor.py, tests/test_config_flow.py, and tests/test_entity_registry.py (including len(classes) == 40, LTS attributes, EntityCategory checks, fuel_burn_rate overrides/fallbacks, VPP/subscription selection, and malformed payload edge cases).

User Configuration / Migration Notes

  • No breaking changes to existing entity unique_ids or entity_keys.
  • Existing installations automatically pick up state_class for LTS and Diagnostic grouping on metadata sensors on upgrade.
  • Users with propane monitors can tune Estimated fuel burn rate (gal/h) (fuel_burn_rate, default 2.2) via Settings → Devices & services → Generac MobileLink → Configure.
  • CapacitySensor and RemainingFuelSensor use SensorDeviceClass.VOLUME_STORAGE with UnitOfVolume.GALLONS, so Home Assistant displays values in the user's configured volume unit system (gal or L).

Test Plan

  • Ran /Users/binarydev/Projects/ha-generac/.venv/bin/pytest --maxfail=3 --disable-warnings: 143 passed across all 13 test modules (test_api.py, test_auth.py, test_binary_sensor.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).
  • Validated JSON parsing across manifest.json and translations/{en,fr,nb,pt}.json.

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