Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ repos:
hooks:
- id: check-added-large-files
- id: check-yaml
args: [--unsafe]
- id: end-of-file-fixer
- id: trailing-whitespace
- repo: local
Expand Down
33 changes: 29 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,11 @@

**Custom Generac integration component with support for generators and propane tank monitors. It will set up the following platforms.**

| Platform | Entities created for each generator |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary_sensor` | `is_connected`, `is_connecting`, `has_maintenance_alert`, `has_warning` |
| `sensor` | `status`, `run_time`, `protection_time`, `activation_date`, `last_seen`, `connection_time`, `battery_voltage`, `device_type`, `dealer_email`, `dealer_name`, `dealer_phone`, `address`, `status_text`, `status_label`, `serial_number`, `model_number`, `device_ssid`, `panel_id` |
| Platform | Entities created for each generator |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary_sensor` | `is_connected`, `is_connecting`, `has_maintenance_alert`, `has_warning`, `missed_exercise` |
| `sensor` | `status`, `run_time`, `protection_time`, `activation_date`, `last_seen`, `connection_time`, `battery_voltage`, `device_type`, `dealer_email`, `dealer_name`, `dealer_phone`, `address`, `status_text`, `status_label`, `serial_number`, `model_number`, `device_ssid`, `panel_id`, `hours_until_service` |
| `button` | `reset_service_timer` |

| Platform | Entities created for each propane tank monitor |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
Expand Down Expand Up @@ -65,6 +66,30 @@ Click this button to skip steps 1 and 2 below: [![Open your Home Assistant insta

## Configuration is done in the UI

### Readiness Tracking, Maintenance Timer & Repairs Alerts

Each generator automatically tracks exercise activity and maintenance runtime baselines using Home Assistant storage (persisting cleanly across restarts without reloading the integration):

- **Maintenance Service Timer**:
- `sensor.<generator>_hours_until_service` shows estimated runtime hours remaining until the configured service interval (default `100` hours, configurable via **Options** -> `service_interval_hours`; set to `0` to disable).
- On first setup, the baseline initializes to the generator's current `run_time` to avoid false day-1 alarms.
- After completing maintenance (oil change, filter, etc.), press **Reset Maintenance Timer** (`button.<generator>_reset_maintenance_timer`) on the device page to reset the baseline to the current run hours and clear any timer-based Repairs issue immediately.
- **Exercise Readiness Tracking**:
- `binary_sensor.<generator>_missed_exercise` turns `on` if no `Running`/`Exercising` status or run-hour increase is observed within `exercise_interval_days` (default `16` days to cover weekly and biweekly schedules; set to `0` to disable).
- **Proactive Home Assistant Repairs Alerts**:
- `low_battery_voltage`: raised when generator starting battery voltage drops below `low_battery_threshold` (default `12.2` V).
- `missed_exercise`: raised when the generator exceeds `exercise_interval_days` without observed activity.
- `maintenance_due`: raised when runtime since the last service reset reaches `service_interval_hours` or Mobile Link reports a maintenance alert.
- `subscription_dunning`: raised when Mobile Link reports a past-due/dunning subscription status.

### Bundled Automation Blueprints

When the integration sets up, three ready-to-use automation blueprints are automatically installed to `<config>/blueprints/automation/generac/`:

1. **Generac Outage Load Shedding** (`generac_outage_load_shedding.yaml`) — Sheds high-draw entities when status transitions to `Running` (ignoring `Exercising` cycles), waits for `Ready` stabilization, and optionally restores loads with a stagger delay.
2. **Generac Fault & Dealer Contact Alert** (`generac_fault_dealer_alert.yaml`) — Sends a notification populated with generator status, diagnostic `status_text`, and your preferred dealer's name and phone number on `Warning`, `Stopped`, `Communication Issue`, warning, or maintenance alerts.
3. **Generac Pre-Storm Readiness Digest** (`generac_storm_readiness_digest.yaml`) — Sends a readiness digest with status, connectivity, battery voltage, hours until service, and optional propane fuel level when a weather alert or trigger entity turns `on`.

## Username + Password Authentication

This integration previously used a cookie-fishing authentication workflow. As of PR #267, it has now been replaced by a standard OAuth workflow similar to the mobile app, using your username and password, with auto-refreshing token retrieval. You no longer need to enter your cookie's string!
Expand Down
20 changes: 16 additions & 4 deletions custom_components/generac/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
from .api import InvalidCredentialsException
from .auth import GeneracAuth
from .auth import InvalidGrantError
from .blueprints import install_bundled_blueprints
from .const import CONF_DPOP_PEM
from .const import CONF_PASSWORD
from .const import CONF_REFRESH_TOKEN
Expand All @@ -25,8 +26,10 @@
from .const import PLATFORMS
from .const import STARTUP_MESSAGE
from .coordinator import GeneracDataUpdateCoordinator
from .issues import async_delete_token_expiry_issue
from .issues import async_delete_all_entry_issues
from .readiness import async_remove_readiness_store
from .utils import async_client_session
from .utils import entry_options

_LOGGER: logging.Logger = logging.getLogger(__package__)

Expand All @@ -37,7 +40,7 @@
def _reload_signature(entry: ConfigEntry) -> tuple[dict, dict]:
"""Snapshot of entry options and non-token data that require a reload on change."""
return (
dict(entry.options),
dict(entry_options(entry)),
{k: v for k, v in entry.data.items() if k not in _TOKEN_KEYS},
)

Expand Down Expand Up @@ -114,6 +117,14 @@ async def _persist_relogin(fresh: GeneracAuth) -> None:
if not coordinator.last_update_success:
raise ConfigEntryNotReady

try:
await hass.async_add_executor_job(
install_bundled_blueprints,
hass.config.path("blueprints", "automation", DOMAIN),
)
except OSError as ex:
_LOGGER.warning("Could not install bundled Generac blueprints: %s", ex)

hass.data[DOMAIN][entry.entry_id] = coordinator

await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
Expand Down Expand Up @@ -153,5 +164,6 @@ async def async_reload_entry(hass: HomeAssistant, entry: ConfigEntry) -> None:


async def async_remove_entry(hass: HomeAssistant, entry: ConfigEntry) -> None:
"""Clean up the expiry Repairs issue when the entry is deleted."""
async_delete_token_expiry_issue(hass, entry)
"""Clean up Repairs issues and readiness storage when the entry is deleted."""
async_delete_all_entry_issues(hass, entry)
await async_remove_readiness_store(hass, entry)
28 changes: 25 additions & 3 deletions custom_components/generac/binary_sensor.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""Binary sensor platform for generac."""
from __future__ import annotations

from typing import Type

from homeassistant.components.binary_sensor import BinarySensorDeviceClass
Expand All @@ -7,9 +9,11 @@
from homeassistant.core import HomeAssistant
from homeassistant.helpers.entity_platform import AddEntitiesCallback

from .const import DEVICE_TYPE_GENERATOR
from .const import DOMAIN
from .coordinator import GeneracDataUpdateCoordinator
from .entity import GeneracEntity
from .models import Item


async def async_setup_entry(
Expand All @@ -22,17 +26,21 @@ async def async_setup_entry(
async_add_entities(
sensor(coordinator, entry, device_id, item)
for device_id, item in data.items()
for sensor in sensors()
for sensor in sensors(item)
)


def sensors() -> Type[GeneracEntity]:
return [
def sensors(item: Item | None = None) -> list[Type[GeneracEntity]]:
"""Return binary sensor entity classes applicable to an item."""
lst: list[Type[GeneracEntity]] = [
GeneracConnectedSensor,
GeneracConnectingSensor,
GeneracMaintenanceAlertSensor,
GeneracWarningSensor,
]
if item is not None and item.apparatus.type == DEVICE_TYPE_GENERATOR:
lst.append(GeneracMissedExerciseSensor)
return lst


class GeneracConnectedSensor(GeneracEntity, BinarySensorEntity):
Expand Down Expand Up @@ -101,3 +109,17 @@ def device_class(self):
def is_on(self):
"""Return true if the binary_sensor is on."""
return self.aparatus_detail.showWarning


class GeneracMissedExerciseSensor(GeneracEntity, BinarySensorEntity):
"""Binary sensor indicating whether scheduled exercise appears overdue."""

entity_key = "missed_exercise"
entity_label = "Missed Exercise"

_attr_device_class = BinarySensorDeviceClass.PROBLEM

@property
def is_on(self) -> bool:
"""Return True if the generator has missed its exercise window."""
return bool(self.coordinator.is_missed_exercise(self.device_id))
33 changes: 33 additions & 0 deletions custom_components/generac/blueprints.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
"""Installer for bundled Generac Home Assistant automation blueprints."""
from __future__ import annotations

from pathlib import Path

BUNDLED_BLUEPRINTS_DIR = Path(__file__).resolve().parent / "blueprints" / "automation"


def list_bundled_blueprints() -> list[Path]:
"""Return sorted paths to bundled automation blueprint YAML files."""
if not BUNDLED_BLUEPRINTS_DIR.is_dir():
return []
return sorted(BUNDLED_BLUEPRINTS_DIR.glob("*.yaml"))


def install_bundled_blueprints(target_dir: str | Path) -> list[Path]:
"""Copy bundled automation blueprints into ``target_dir`` if missing or changed.

Idempotent and safe to run inside ``hass.async_add_executor_job``.
Returns the list of destination paths written.
"""
dest_dir = Path(target_dir)
dest_dir.mkdir(parents=True, exist_ok=True)

written: list[Path] = []
for src in list_bundled_blueprints():
content = src.read_bytes()
dest = dest_dir / src.name
if dest.exists() and dest.read_bytes() == content:
continue
dest.write_bytes(content)
written.append(dest)
return written
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
blueprint:
name: Generac Fault & Dealer Contact Alert
description: >-
Send a detailed notification including generator status, diagnostic text,
and your preferred dealer's name and phone number when a fault, stop,
communication issue, warning, or maintenance alert occurs.
domain: automation
author: ha-generac
input:
status_sensor:
name: Generator Status Sensor
selector:
entity:
filter:
- integration: generac
domain: sensor
status_text_sensor:
name: Generator Status Text Sensor
selector:
entity:
filter:
- integration: generac
domain: sensor
warning_sensor:
name: Generator Warning Binary Sensor
selector:
entity:
filter:
- integration: generac
domain: binary_sensor
maintenance_sensor:
name: Generator Maintenance Alert Binary Sensor
selector:
entity:
filter:
- integration: generac
domain: binary_sensor
dealer_name_sensor:
name: Dealer Name Sensor
selector:
entity:
filter:
- integration: generac
domain: sensor
dealer_phone_sensor:
name: Dealer Phone Sensor
selector:
entity:
filter:
- integration: generac
domain: sensor
notify_service:
name: Notification Service
description: >-
Home Assistant notify service to call (for example, notify.notify or
notify.mobile_app_your_phone).
default: notify.notify
selector:
text: {}

mode: queued
max: 10

triggers:
- trigger: state
entity_id: !input status_sensor
to:
- "Warning"
- "Stopped"
- "Communication Issue"
- trigger: state
entity_id: !input warning_sensor
to: "on"
- trigger: state
entity_id: !input maintenance_sensor
to: "on"

variables:
status_entity: !input status_sensor
status_text_entity: !input status_text_sensor
maintenance_entity: !input maintenance_sensor
dealer_name_entity: !input dealer_name_sensor
dealer_phone_entity: !input dealer_phone_sensor

actions:
- alias: Send fault and dealer contact notification
action: !input notify_service
data:
title: >-
{% if trigger.entity_id == maintenance_entity %}
Generac Maintenance Alert ({{ states(status_entity) }})
{% else %}
Generac Alert: {{ states(status_entity) }}
{% endif %}
message: >-
{% set status = states(status_entity) %}
{% set details = states(status_text_entity) %}
{% set dealer = states(dealer_name_entity) %}
{% set phone = states(dealer_phone_entity) %}
Status: {{ status }}
{% if details not in ['unknown', 'unavailable', ''] %}
Details: {{ details }}
{% endif %}
Dealer: {{ dealer if dealer not in ['unknown', 'unavailable', ''] else 'Not configured' }}
Phone: {{ phone if phone not in ['unknown', 'unavailable', ''] else 'Not configured' }}
Loading
Loading