homebridge-generac 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to homebridge-generac are listed here. The format follows Keep a Changelog, and the project follows semantic versioning from 0.1.0-beta.1. The release notes of a version are its section here and nothing else. Dates are written US style.
+
+## Unreleased
+
+## 0.1.0-beta.1 (September 15, 2026)
+
+First beta of Generac for Homebridge, a ground-up successor to homebridge-mobilelink.
+
+### Added
+
+- One accessory per generator on the Mobile Link account with a Running contact sensor, a Fault contact sensor, a Maintenance Due contact sensor, an Exercising contact sensor and a Battery service showing the starting battery level and the low battery flag. Every sensor reports Status Active from the generator's connection and Status Fault from the fault state.
+- Fault opens on a Warning status, active alarms or warnings, an alarm code, the control switch in OFF (Treat Stopped as a fault, on by default) or a lost connection (Treat a lost connection as a fault, off by default). The reasons appear on the settings page and in the log.
+- The Exercising sensor opens while the weekly exercise runs, or when Mobile Link reports one finished since the last check, so an exercise the plugin slept through is still detected. It stays open for the exercise hold time (default 5 minutes). Around the exercise time, from 2 minutes before until 20 minutes after, every day, the plugin checks at the faster interval.
+- Optional Attention needed occupancy sensor that turns on while the plugin needs you to reconnect.
+- A settings page in the Homebridge UI: connect the Mobile Link account (email, password, then the text message, authenticator or email code), see every generator with its status, fault reasons, battery, engine hours, exercise time, last exercise and last seen, rename generators, disconnect, change every setting, and reset the plugin to a fresh install. The page works in both Homebridge UI themes and at phone width.
+- Sign-in from the settings page takes effect within a minute, with no restart.
+- The `homebridge-generac status` and `homebridge-generac login` commands for terminal use.
+- Polling every 10 minutes while idle and every 90 seconds while a generator is running, exercising or in fault, with backoff up to 30 minutes on failures. Sensors show Not responding after three failures in a row.
+- Per-generator display names, kept together with renames made in the Home app.
+- Propane tank monitors and linked ecobee thermostats on the account are listed on the settings page and skipped: tank level support is planned for 0.2.0, and ecobee thermostats are already in HomeKit.
+- With Debug logging on, every status change writes the raw Mobile Link payload to `homebridge-generac/captures/` in the Homebridge storage folder, keeping the newest 10.
+
+### Notes
+
+- The plugin is read only. It cannot start, stop or exercise a generator.
+- The Mobile Link password is never stored or logged. The plugin keeps a refresh token in `homebridge-generac/credentials.json` (mode 600) inside the Homebridge storage folder, outside config.json.
+- Accounts created before April 21, 2026 need a password reset since then: Generac moved Mobile Link sign-in to a new system on that date and did not carry older passwords across.
+- Changing the Mobile Link password signs the plugin out. The settings page then shows Reconnect needed; sign in again to resume updates.
+- Accounts set up for push, voice or security-key sign-in cannot be completed by the plugin. Switch the account to text message or an authenticator app in the Mobile Link app first.
+- The settings page shows the low battery threshold with one decimal place, and the Reset dialog opens directly below the Reset link.

package/LICENSE

@@ -0,0 +1,200 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Alex Rodriguez (arodbuilds) https://alex-rodriguez.com
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,20 @@
+homebridge-generac (Generac for Homebridge)
+Copyright 2026 Alex Rodriguez (arodbuilds) https://alex-rodriguez.com
+
+Licensed under the Apache License, Version 2.0. See LICENSE.
+
+This product includes work from the following projects, in this order:
+
+1. ha-generac (https://github.com/binarydev/ha-generac)
+   The Auth0 and DPoP login flow in src/auth.ts is ported from the auth
+   module of ha-generac: the Auth0 flow by sslivins and the MFA handling by
+   pjordanandrsn. Licensed under the Apache License, Version 2.0.
+
+2. homebridge-mobilelink by Nicholas Penree
+   (https://www.npmjs.com/package/homebridge-mobilelink)
+   The original HomeKit bridge for Generac Mobile Link, of which this plugin
+   is the successor. Licensed under the Apache License, Version 2.0. No code
+   from homebridge-mobilelink is used in this project.
+
+Generac and Mobile Link are trademarks of Generac Power Systems, Inc. This
+project is not affiliated with Generac.

package/README.md

@@ -0,0 +1,179 @@
+<img src="assets/generac-banner.png" alt="Generac for Homebridge: Your standby generator in HomeKit. Status, battery, run hours and alerts from Mobile Link." width="100%">
+
+<!--
+verified-by-homebridge: this plugin has not been through Homebridge verification yet.
+Do not claim it. Once the plugin is verified, replace this comment with the badge:
+[![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
+-->
+
+[![npm version](https://img.shields.io/npm/v/homebridge-generac/beta)](https://www.npmjs.com/package/homebridge-generac)
+[![npm downloads](https://img.shields.io/npm/dt/homebridge-generac)](https://www.npmjs.com/package/homebridge-generac)
+[![License](https://img.shields.io/github/license/arodbuilds/homebridge-generac)](LICENSE)
+[![Build and Lint](https://github.com/arodbuilds/homebridge-generac/actions/workflows/build.yml/badge.svg)](https://github.com/arodbuilds/homebridge-generac/actions/workflows/build.yml)
+
+A [Homebridge](https://homebridge.io) plugin that shows the standby generators on your Generac Mobile Link account in the Home app. Each generator appears as a Running sensor, a Fault sensor, a Maintenance Due sensor, an Exercising sensor and a starting battery reading, so you can see at a glance whether the unit is ready, get a notification when it starts or reports a problem, and build automations around it. It is read only and never stores your Mobile Link password.
+
+Not affiliated with or endorsed by Generac Power Systems, Inc. Generac and Mobile Link are its trademarks. Uses Generac's undocumented Mobile Link API, which can change without notice.
+
+> **Status:** Beta. Please report what works and what does not in the [issue tracker](https://github.com/arodbuilds/homebridge-generac/issues).
+
+## Contents
+
+- [Requirements](#requirements)
+- [Install](#install)
+- [Setup](#setup)
+  - [1. Connect your Mobile Link account](#1-connect-your-mobile-link-account)
+  - [2. Enter the code](#2-enter-the-code)
+  - [3. Your generators](#3-your-generators)
+  - [4. Settings](#4-settings)
+- [What you get in HomeKit](#what-you-get-in-homekit)
+- [How it works](#how-it-works)
+- [Privacy and what is stored where](#privacy-and-what-is-stored-where)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Credits](#credits)
+- [License](#license)
+
+## Requirements
+
+- Homebridge 1.8 or 2.x, with the Homebridge UI for the settings page.
+- Node 20 or later.
+- A Generac Mobile Link account with at least one generator on it.
+- If the account predates April 21, 2026, a password reset since then. Generac moved Mobile Link sign-in to a new system on that date and did not carry older passwords across, so an older password is rejected until it is reset in the Mobile Link app.
+
+## Install
+
+Search for "Generac" under Plugins in the Homebridge UI and install the beta, or from a shell on the Homebridge host:
+
+```shell
+npm i -g homebridge-generac@beta
+```
+
+Then open the plugin's settings from the Plugins page. Everything in the setup below happens on that page. The host's Save button writes config.json and Homebridge restarts the plugin.
+
+## Setup
+
+### 1. Connect your Mobile Link account
+
+Under Mobile Link account, click Connect and enter the email and password you use in the Mobile Link app, then click Sign in. The password is used once for that sign-in and is not stored anywhere.
+
+![The Mobile Link account card: Connected, the account email and when it was last checked](assets/screenshots/account-connected.png)
+
+Once signed in, the card reads Checking until Homebridge picks up the new sign-in, which takes up to a minute and needs no restart, then Connected with the email and when the plugin last checked the account. Disconnect signs the plugin out again.
+
+### 2. Enter the code
+
+![The code step: Mobile Link texted a code to the phone on your account](assets/screenshots/connect-code.png)
+
+Mobile Link sends a code by text message, authenticator app or email, depending on how your account is set up. Type it in and click Continue. A wrong code can be tried three times; after that, or after five minutes, cancel and sign in again. Accounts set up for push, voice or security-key sign-in cannot be completed by the plugin; switch the account to text message or an authenticator app in the Mobile Link app first.
+
+### 3. Your generators
+
+![A generator card: Ready to run, battery, engine hours, exercise time, last exercise and last seen](assets/screenshots/generator-ready.png)
+
+Every generator on the account gets a card within a minute of connecting, with its Mobile Link status, the starting battery voltage, engine hours, the weekly exercise time, the last exercise Mobile Link recorded, and when the unit last reported in. Rename changes the name shown in the Home app; Save keeps it.
+
+![A generator card in Fault: Switch in OFF](assets/screenshots/generator-fault.png)
+
+When something is wrong the card shows a Fault badge with the reasons Mobile Link gives: the control switch in OFF, active alarms or warnings, an alarm code, a warning status or a lost connection. A unit that has stopped reporting shows Not responding with the time it was last heard from.
+
+### 4. Settings
+
+![The Settings section with Advanced open](assets/screenshots/settings-advanced.png)
+
+Settings holds one Advanced disclosure:
+
+- Name: the plugin name in Homebridge logs.
+- Poll interval while idle (minutes) and Poll interval while running or in fault (seconds): how often the plugin checks Mobile Link, see [How it works](#how-it-works).
+- Low battery threshold (volts): the voltage at or below which the Battery service reports low. The default is 12.0 V; a healthy starting battery on charge reads 13.4 to 13.8 V.
+- Treat Stopped as a fault: on by default. Stopped means the control switch is in OFF and the generator will not start during an outage.
+- Treat a lost connection as a fault: off by default. Wi-Fi drops are common and the sensors already show Not responding.
+- Attention needed sensor: an occupancy sensor that turns on while the plugin needs you to reconnect, for an automation that sends you a notification.
+- Exercising sensor: on by default, see [What you get in HomeKit](#what-you-get-in-homekit).
+- Exercise time: when the weekly exercise starts, prefilled from Mobile Link. Correct it if your unit starts at a different time.
+- Exercise hold (minutes): how long the Exercising sensor stays open after an exercise is detected.
+- Debug logging: verbose logging. The password is never logged, even with this on.
+- Reset plugin to fresh install: signs out, removes every generator from the Home app on the next restart, and clears the settings.
+
+## What you get in HomeKit
+
+One accessory per generator, named after the generator, with these services:
+
+| Service | Kind | Open (or on) when |
+| --- | --- | --- |
+| Running | Contact sensor | The engine is running. |
+| Fault | Contact sensor | Mobile Link reports a Warning status, an active alarm or warning, or an alarm code; the control switch is in OFF (Treat Stopped as a fault); or the unit lost its connection (Treat a lost connection as a fault, off by default). |
+| Maintenance Due | Contact sensor | Generac flags service as due. |
+| Exercising | Contact sensor | The weekly exercise is running, or Mobile Link reports one finished since the last check. |
+| Battery | Battery service | Always present: the starting battery voltage as a level (11.8 V is 0 percent, 12.8 V is 100 percent) and the low battery flag at or below the threshold. |
+
+Optionally, one Attention needed occupancy sensor for the plugin, on while the plugin cannot sign in.
+
+**Why contact sensors and not a switch.** A switch in the Home app invites you to flip it, and this plugin cannot start, stop or exercise a generator; no command endpoint has been validated and the plugin stays read only. Contact sensors say exactly what they mean, show open and closed in the Home app, and are what HomeKit automations trigger on. In Automations, choose a sensor and pick what should happen when it opens and when it closes: turn on a light when Running opens, send a notification when Fault opens.
+
+**The Exercising sensor.** Standby generators run themselves for a few minutes every week. The sensor opens when a check sees the unit exercising, and also retroactively: Mobile Link records the finished exercise with a timestamp, so an exercise the plugin slept through is still detected on the next check and opens the sensor then. The sensor stays open for the exercise hold time after the last detection. Use it to confirm the generator exercised this week, for example with an automation that notifies you if it has not opened by Saturday evening.
+
+**Notifications.** For the Fault sensor, turn on notifications in the Home app and allow them as Critical Alerts, so a fault gets through Do Not Disturb and a Focus. That is the one notification worth having from this plugin.
+
+Every sensor also reports Status Active, which is off while the unit is not responding or the plugin cannot reach Mobile Link, and Status Fault, which follows the Fault sensor. Names you give the sensors in the Home app are kept.
+
+## How it works
+
+- **Polling.** While every generator is ready and quiet the plugin checks Mobile Link every 10 minutes (Poll interval while idle, minimum 2). While any generator is running, exercising or in fault it checks every 90 seconds (Poll interval while running or in fault, minimum 60). Mobile Link itself updates every few minutes and limits how often an account can be checked, so faster settings rarely help.
+- **The exercise watch window.** Around the exercise time, from 2 minutes before it until 20 minutes after it, every day, the plugin checks at the faster interval so a live exercise is likely to be seen rather than only detected afterwards.
+- **Backoff.** When a check fails, the plugin waits longer between tries, doubling from the fast interval up to 30 minutes with some jitter. After three failures in a row the sensors show Not responding until a check succeeds.
+- **Sign-in.** The plugin signs in once, from the settings page, and keeps only a refresh token. Access tokens are refreshed shortly before they expire; the plugin never signs in again on its own and never needs the password after the first time.
+- **After a password change.** Changing the Mobile Link password revokes the refresh token. The plugin then enters Reconnect needed: it logs once, marks the sensors as not responding, turns the Attention needed sensor on if enabled, and retries hourly in case access comes back. Click Reconnect on the settings page and sign in again; nothing else changes.
+- **Configuration.** The settings page writes the platform block in config.json; the shape and every default are in [SPEC.md](SPEC.md) section 9 and in `config.schema.json`, for anyone who edits by hand.
+
+## Privacy and what is stored where
+
+- The sign-in lives in `homebridge-generac/credentials.json` inside the Homebridge storage folder, with mode 600, readable only by the Homebridge user. It holds the account email, the refresh token and the key the token is bound to. It is never written to config.json, the log or the settings page.
+- The password is never stored. It is used once to sign in from the settings page (or the `homebridge-generac login` command) and then forgotten.
+- `homebridge-generac/state.json` holds what the settings page shows: the account state, each generator's last status, and when the plugin last checked. No tokens.
+- With Debug logging on, every status change writes the raw Mobile Link payload for the generator to `homebridge-generac/captures/`, keeping the newest 10, so a real payload can be shared as a test fixture. Captures never contain tokens.
+- The log never contains passwords, tokens, keys or one-time codes, at any log level.
+- Nothing is sent anywhere but Generac. The plugin talks to Generac's sign-in service and the Mobile Link API and to nothing else.
+- To remove everything, use Reset plugin to fresh install on the settings page, or delete the `homebridge-generac` folder in the Homebridge storage folder.
+
+## Troubleshooting
+
+- **"Mobile Link rejected that password."** If you have not reset the password since April 21, 2026, reset it in the Mobile Link app, then try again. Older passwords were not carried across Generac's security update.
+- **"Mobile Link doesn't recognize that email."** Use the email you sign in with in the Mobile Link app.
+- **"Your account uses a sign-in method this plugin can't complete."** The account is set up for push, voice or security-key sign-in. In the Mobile Link app, switch to text message or an authenticator app, then try again.
+- **"Couldn't reach Mobile Link."** The Homebridge host could not reach Generac's sign-in service. Try again in a minute.
+- **The card stays on Checking.** Homebridge picks up a new sign-in within a minute without a restart. If the card has not changed after two minutes, restart Homebridge from Power Options.
+- **Reconnect needed.** Mobile Link signed the plugin out. This happens after a password change or if Generac revokes access. Click Reconnect and sign in again; the generators and their sensors stay as they were. The Attention needed sensor, if enabled, is on until you do.
+- **Not responding.** The generator has not reported to Mobile Link recently (a Wi-Fi drop is the usual cause), or the plugin has not been able to reach Mobile Link for three checks in a row. The card shows when the unit was last heard from; the sensors report Status Active off and keep their last values. It is not a fault unless Treat a lost connection as a fault is on.
+- **No generators yet.** They appear within a minute of connecting. If the account holds only a propane tank monitor or a linked ecobee thermostat, the settings page says so under Generators: tank monitors are planned for a later release, and ecobee thermostats are already native HomeKit devices and are skipped.
+- **The generator exercised but the sensor did not open.** The sensor also opens retroactively when Mobile Link records the finished exercise, usually within the next idle poll. Check Exercise time under Advanced; the plugin checks more often around that time every day.
+
+## Development
+
+Node 20 or later. Clone the repository, then:
+
+```shell
+npm ci
+npm test
+```
+
+`npm test` lints, builds and runs the node:test suites in `test/`. Tests never touch the network: `fetch` is mocked and the Mobile Link answers come from the fixtures under `test/fixtures/`. `npm run lint` and `npm run build` run the parts on their own.
+
+To try a build on a Homebridge host, symlink the clone into the global plugin path, for example `ln -s ~/homebridge-generac "$(npm root -g)/homebridge-generac"`, then restart Homebridge. The settings page is TypeScript under `homebridge-ui/src/`, compiled to `homebridge-ui/public/js/` by the build; its server side is compiled from `src/ui/` and started by `homebridge-ui/server.js`. [SPEC.md](SPEC.md) is the source of truth for behaviour, naming, configuration and the page's copy.
+
+The `homebridge-generac status` command prints the account and generator state from a terminal, and `homebridge-generac login` signs in without the settings page.
+
+## Credits
+
+Generac's Mobile Link API is undocumented, and this plugin stands on work that mapped it before:
+
+- [ha-generac](https://github.com/binarydev/ha-generac) (Apache-2.0): the Auth0 and DPoP sign-in sequence in `src/auth.ts` is ported from its auth module, the Auth0 flow by sslivins and the code-challenge handling by pjordanandrsn, as recorded in [NOTICE](NOTICE).
+- [homebridge-mobilelink](https://www.npmjs.com/package/homebridge-mobilelink) by Nicholas Penree (Apache-2.0): the original HomeKit bridge for Mobile Link, of which this plugin is the successor.
+
+Beyond the ported sign-in sequence, no code is shared with either project.
+
+Built by Alex Rodriguez. If this plugin is useful to you, say hello at [alex-rodriguez.com](https://alex-rodriguez.com/?ref=generac#building).
+
+## License
+
+Apache-2.0. Copyright 2026 Alex Rodriguez (arodbuilds).

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security policy
+
+## Supported versions
+
+Only the newest release receives security fixes. Older versions do not.
+
+## Reporting a vulnerability
+
+Please report vulnerabilities privately through GitHub: open the Security tab of this repository and choose Report a vulnerability. Do not open a public issue for security problems.
+
+You will get an acknowledgement within a few days, a fix or mitigation as soon as one is ready, and credit in the release notes if you want it.
+
+## Scope
+
+In scope: anything that could expose the Mobile Link refresh token, the DPoP key or a password, or weaken the sign-in flow.
+
+Out of scope: Generac changing its undocumented API or login page. Those break the plugin but are not vulnerabilities; report them as ordinary issues.

package/config.schema.json

@@ -0,0 +1,133 @@
+{
+  "pluginAlias": "Generac",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Generac for Homebridge shows the standby generators on your Mobile Link account in the Home app. Each generator appears as a Running sensor, a Fault sensor, a Maintenance Due sensor and a starting battery reading. Propane models will also get a tank level later. Not affiliated with or endorsed by Generac Power Systems, Inc. Generac and Mobile Link are its trademarks. Uses Generac's undocumented Mobile Link API, which can change without notice.",
+  "schema": {
+    "type": "object",
+    "required": [
+      "name"
+    ],
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Generac"
+      },
+      "pollIdleMinutes": {
+        "title": "Poll interval while idle (minutes)",
+        "type": "integer",
+        "default": 10,
+        "minimum": 2,
+        "description": "Mobile Link updates every few minutes and limits how often you can check. Faster than this rarely helps."
+      },
+      "pollActiveSeconds": {
+        "title": "Poll interval while running or in fault (seconds)",
+        "type": "integer",
+        "default": 90,
+        "minimum": 60,
+        "description": "Used while a generator is running, exercising, or reporting a problem."
+      },
+      "batteryLowVoltage": {
+        "title": "Low battery threshold (volts)",
+        "type": "number",
+        "default": 12.0,
+        "description": "A healthy starting battery on charge reads 13.4 to 13.8 V."
+      },
+      "faultOnStopped": {
+        "title": "Treat Stopped as a fault",
+        "type": "boolean",
+        "default": true,
+        "description": "Stopped means the control switch is in OFF and the generator won't start during an outage."
+      },
+      "faultOnDisconnected": {
+        "title": "Treat a lost connection as a fault",
+        "type": "boolean",
+        "default": false,
+        "description": "Off by default. Wi-Fi drops are common and the sensors already show Not responding."
+      },
+      "attentionSensor": {
+        "title": "Attention needed sensor",
+        "type": "boolean",
+        "default": false,
+        "description": "Adds an occupancy sensor to HomeKit that turns on when the plugin needs you to reconnect."
+      },
+      "exerciseSensor": {
+        "title": "Exercising sensor",
+        "type": "boolean",
+        "default": true,
+        "description": "Adds a sensor that opens while the weekly exercise runs, or when Mobile Link reports one finished. Use it to confirm the generator exercised this week."
+      },
+      "exerciseTime": {
+        "title": "Exercise time",
+        "type": "string",
+        "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
+        "description": "When your generator's weekly exercise starts. Prefilled from Mobile Link; correct it if your unit starts at a different time. The plugin checks more often around this time every day."
+      },
+      "exerciseHoldMinutes": {
+        "title": "Exercise hold (minutes)",
+        "type": "integer",
+        "default": 5,
+        "minimum": 1,
+        "description": "How long the Exercising sensor stays open after an exercise is detected."
+      },
+      "debug": {
+        "title": "Debug logging",
+        "type": "boolean",
+        "default": false,
+        "description": "Verbose logging. Your password is never logged, even with this on."
+      },
+      "credentialsPath": {
+        "type": "string"
+      },
+      "generators": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "apparatusId": {
+              "type": "integer"
+            },
+            "name": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  },
+  "layout": [
+    "name",
+    {
+      "key": "pollIdleMinutes",
+      "validationMessages": {
+        "minimum": "Minimum is 2 minutes."
+      }
+    },
+    {
+      "key": "pollActiveSeconds",
+      "validationMessages": {
+        "minimum": "Minimum is 60 seconds."
+      }
+    },
+    "batteryLowVoltage",
+    "faultOnStopped",
+    "faultOnDisconnected",
+    "attentionSensor",
+    "exerciseSensor",
+    {
+      "key": "exerciseTime",
+      "validationMessages": {
+        "pattern": "Enter a time as HH:MM, for example 10:00."
+      }
+    },
+    {
+      "key": "exerciseHoldMinutes",
+      "validationMessages": {
+        "minimum": "Minimum is 1 minute."
+      }
+    },
+    "debug"
+  ],
+  "customUi": true
+}

package/dist/accessory.d.ts

@@ -0,0 +1,54 @@
+import type { PlatformAccessory } from 'homebridge';
+import { type GeneratorState } from './model.js';
+import type { GeneracPlatform } from './platform.js';
+/**
+ * One Generac generator as a HomeKit accessory.
+ *
+ * Deliberately not an Outlet or Switch: HomeKit would then read "off" while the
+ * unit sits healthy in Ready, and a fault would have nowhere to go but a thrown
+ * error (which the Home app renders as "No Response"). Contact sensors give
+ * three independently automatable, notifiable booleans, and StatusFault /
+ * StatusActive carry the health signals HomeKit already understands.
+ *
+ *   Running          contact OPEN while the engine is running
+ *   Fault            contact OPEN on warning / alarm / stopped (see FaultOptions)
+ *   Maintenance Due  contact OPEN when Generac flags service
+ *   Exercising       contact OPEN while an exercise is detected, live or retroactively (optional, SPEC section 7)
+ *   Battery          starting-battery voltage mapped to level + low-battery flag
+ */
+export declare class GeneratorAccessory {
+    private readonly platform;
+    readonly accessory: PlatformAccessory;
+    private readonly running;
+    private readonly fault;
+    private readonly maintenance;
+    /** Present only while `exerciseSensor` is on; the platform drives it through `setExercising`. */
+    private readonly exercising;
+    private readonly battery;
+    private state;
+    private exerciseOpen;
+    private displayName;
+    constructor(platform: GeneracPlatform, accessory: PlatformAccessory, initial: GeneratorState, displayName: string);
+    private contact;
+    /**
+     * Apply a display name (the `generators[]` override or the Mobile Link name).
+     * Service names follow. ConfiguredName follows only while it still holds the
+     * name this plugin gave it, so a rename made in the Home app sticks.
+     * Returns true when anything changed, so the platform can persist the cache.
+     */
+    setDisplayName(name: string): boolean;
+    /** Every contact sensor with its label, the optional Exercising one included. */
+    private contacts;
+    private contactState;
+    private lowBattery;
+    /** Push a fresh state into HomeKit. Always updates; never gated on identity fields. */
+    update(next: GeneratorState): void;
+    /** The last state pushed to HomeKit. */
+    get current(): GeneratorState | null;
+    /** Opens or closes the Exercising sensor (SPEC section 7, service 6). A no-op without the sensor. */
+    setExercising(open: boolean): void;
+    /** Whether the Exercising sensor is open. */
+    get isExercising(): boolean;
+    /** Mark the accessory unreachable after repeated poll failures without changing its last state. */
+    markUnreachable(): void;
+}