Open Green Button — Home Assistant integration

Bridges your utility's Green Button (NAESB ESPI) energy data into the Home Assistant Energy dashboard via a stateless OAuth proxy server.

🚧 Pre-alpha. See the current utility status for which utilities are supported or in progress; the proxy server itself is hosted on Fly.io.

How it works

This integration talks to a hosted proxy server at https://api.opengreenbutton.org. The proxy exists only because utilities require a stable public HTTPS callback URL for OAuth — your data never lives on it. Refresh tokens are stored encrypted in your Home Assistant config entry; every API call carries the token through the proxy and the server discards it immediately after the round-trip.

Server source code: rocketraman/open-green-button.

Installation

HACS (custom repository, until accepted into HACS default)

1. In HACS, open Integrations.
2. Click the ⋮ menu → Custom repositories.
3. Add https://github.com/rocketraman/open-green-button-homeassistant with category Integration.
4. Install Open Green Button.
5. Restart Home Assistant.

Manual

Copy custom_components/greenbutton/ into your Home Assistant config directory at <config>/custom_components/greenbutton/ and restart.

Configuration

1. Settings → Devices & Services → Add Integration → Open Green Button.
2. Pick your utility from the dropdown.
3. Click the authorization link, complete the Green Button consent flow with your utility.
4. Paste the claim code (starts with gb_live_) back into Home Assistant.

The integration writes hourly consumption data into the HA Energy dashboard's long-term statistics.

Gas and water meters on the same account are imported too, each as its own statistic — add them under Gas consumption and Water consumption in the Energy dashboard. Gas billed in therms or BTU is stored as kWh, since Home Assistant has no therm unit; volumes keep your utility's unit (ft³, m³, gal, L). This only works where the utility includes them in its Green Button feed, and not all do — for example, utilities served by London Hydro provide electricity only, even if they bill you for water.

If there's nothing to pick in the Energy dashboard yet

Right after setup, Settings → Dashboards → Energy may say no statistics available when you try to add the account. That usually means your utility hasn't sent any data yet — plenty of them only start assembling your history once you authorize, which can take from a minute to a few hours. Until the first reading arrives there is nothing to put in the dashboard, so there is nothing to pick.

Home Assistant will tell you when this is what's happening: look for a notice under Settings → Repairs. The integration re-checks on its own, first after a few minutes and then progressively less often, and the notice clears itself as soon as data lands. You don't need to delete and re-add the integration — that only appears to help because setting the account up again happens to trigger another fetch.

If it's still empty a day later the notice changes to say so, and we'd like to hear about it — the link in the notice goes to the tracking issue.

If the Energy dashboard stops updating

If usage stops arriving in the Energy dashboard while the integration reports no errors, check Settings → Repairs. Utilities occasionally re-issue a meter's ID without anything changing at your home. The readings are still imported, but under the new ID they go into new statistics, so the ones your dashboard is set up with stand still.

The integration notices this and asks whether the new ID is the same meter. Merge moves the readings imported under the new ID onto the end of your existing statistics and continues them from then on — nothing needs changing in the dashboard. Keep separate is for a meter that really is a different one: both sets of statistics are left as they are. The notice appears on the first poll after the change, so it can take up to a day.

Polling schedule

How often each utility may be polled is decided by that utility and passed to the integration by the proxy server — you can't make it poll more often. Most utilities publish once a day.

When the cadence works out to exactly once a day, you can choose when that poll runs, under Settings → Devices & services → Open Green Button → Configure. Enable Poll daily at a specific local time and pick a time. It uses Home Assistant's timezone and follows daylight-saving changes. Utilities on a shorter or multi-day cadence ignore the setting and keep their own interval.

If Home Assistant is down when a poll was due — either the interval elapsed or the daily time went by — the poll runs when it next starts. Restarting inside a window that has already been polled doesn't re-fetch: that data is already in the recorder, so the restart just waits for the next scheduled poll.

Fixing wrong or missing statistics: reload vs. rebuild

Statistics are written once, as they're fetched. Each poll asks the utility only for what's new since the last reading it imported, and readings that are already stored are never written again. So if usage shows at the wrong scale, months are missing, or cost doesn't appear, reloading the integration won't change the rows that are already there. Rebuilding the statistics will.

What a reload does

Reload (the account's ⋮ menu under Settings → Devices & services → Open Green Button) sets the account up again and polls the utility straight away. The poll picks up from the newest reading already imported, so it only fetches recent data. History is not fetched again, and stored rows are not rewritten.

A Home Assistant restart is the same, except that it skips the poll if the account was already polled within its normal schedule. That data is already stored, so there's nothing to fetch until the next scheduled poll.

Use a reload when:

• polling hit an error (the utility or the proxy was down) and you don't want to wait for the next scheduled attempt;
• you want to fetch new data now, for example after enabling debug logging (see Debugging).

Saving the integration's options already reloads the account, so you don't need to reload after changing them. After installing an update, restart Home Assistant: a reload alone keeps running the old code.

Fixes in updates usually repair your statistics automatically

When an update fixes how usage or cost is calculated, you usually don't need to do anything. On the first poll after the update, the integration checks whether your utility's data has the shape that bug affected. If it does, the integration rebuilds that account's statistics once, by itself, and logs a warning while it runs. The same happens when the proxy server changes how it handles your utility's data. Accounts the bug never touched are left alone, so they don't have to download their whole history again.

If that automatic rebuild fails (for example, because the utility didn't respond), your existing statistics are left as they were, and it's tried again on the next poll.

What a rebuild does

The Rebuild statistics action (greenbutton.rebuild_statistics) does this:

1. Downloads the account's full history again — the same window as a fresh setup, which the proxy server sets for each utility (for example, two years).
2. Only once that download has succeeded, deletes the account's usage and cost statistics.
3. Imports everything again from scratch, using the current version's calculations.

If the download fails, nothing is deleted, and the action reports an error. Readings older than that history window are not downloaded again, so if you've been running the integration longer than the window, the dashboard loses those older readings.

Rebuild an account when:

• its statistics still look wrong — wrong scale, gaps, negative bars, cost missing — after updating and letting the automatic repair run;
• history is missing that the utility does provide;
• a maintainer asks you to, while debugging an issue.

A rebuild asks your utility for the full history again, the same amount of data as a fresh setup, so run it when you need it, not on a schedule. It can take several minutes. The account's history in the Energy dashboard is replaced with the rebuilt version. You don't need to authorize with your utility again.

Rebuilding one account

The action takes an optional Account (config_entry_id). Set it to rebuild only that account; leave it out to rebuild every Open Green Button account, one after another.

From the UI: Developer tools → Actions, choose Open Green Button: Rebuild statistics, pick the account under Account, then Perform action. The account picker supplies the ID for you.

In YAML mode, or from a script or automation:

action: greenbutton.rebuild_statistics
data:
  config_entry_id: <entry id>

To find an account's entry ID yourself, open the account under Settings → Devices & services → Open Green Button and look at the browser's address bar: it ends in config_entry=<entry id>. It's also the entry.entry_id field in the account's diagnostics download. The account must be loaded (not failed or disabled) to be rebuilt.

Supported utilities

See the current utility status on the proxy server for the up-to-date list of supported and in-progress utilities.

Want your utility added? Request a new utility.

Privacy

• Your refresh token, usage data, and account identifiers live only on your Home Assistant instance.
• The hosted proxy server holds zero per-user durable state — no accounts, no databases, no usage history.
• Open source under MIT — read the code, run your own proxy, or fork it.
• Clean removal: deleting the integration via Devices & Services purges every long-term statistic it created. Multiple config entries on the same utility (e.g. a sandbox account beside a real one, or several meters at one address) get distinct, per-entry statistic IDs so they never bleed together in the Energy dashboard.

Development

Toolchain pinned via mise. Python 3.13.

mise trust            # one-time
mise install          # installs Python 3.13, auto-creates .venv
pip install -r requirements_test.txt

ruff check .
ruff format --check .
pytest

The venv at .venv/ is auto-activated when you cd into the repo.

Roadmap

Working today

• OAuth authorization against the proxy server, with refresh-token rotation handled automatically
• Polls the proxy at the utility's permitted cadence, optionally anchored to a local time of day, and writes hourly consumption into the Energy dashboard's long-term statistics via async_add_external_statistics
• Reauth flow surfaces as an HA notification when the utility revokes our refresh token
• Imports per-billing-period cost from ESPI UsageSummary blocks into the Energy dashboard's Cost column, with Ontario time-of-use distribution

Pending

• First-utility production credentials — currently in test-lab certification with the Green Button Alliance (see utility status)
• Push-based delivery (ESPI FB_39 NotificationURI) instead of polling, once a real utility supports it
• Additional utilities — request a new utility with your provider's name

Debugging

If something looks off (cost showing zero, readings missing, parser surprised by a utility's quirk), the integration ships a diagnostics export that surfaces the relevant signals in one click.

Settings → Devices & Services → Open Green Button → ⋮ → Download Diagnostics

You'll get a JSON file containing:

• Redacted config-entry data, including recent_polls — when each poll of the last few days ran and how many readings it returned (no refresh tokens or proxy tokens leak, and the service address / account number are masked — including in the entry title and the raw_xml Atom titles)
• Coordinator state (last refresh result, scan interval)
• Parsed last-response summary — usage points, series counts, billing summaries with full cost-detail breakdown
• The raw ESPI XML from the most recent upstream fetch, if debug logging is enabled

To capture the raw XML for offline analysis:

1. Enable debug logging — the integration's ⋮ menu has an "Enable debug logging" toggle. Or add to configuration.yaml:

   logger:
     logs:
       custom_components.greenbutton: debug

2. Wait for the next refresh (or reload the integration to force one).
3. Download Diagnostics — the resulting JSON has an raw_xml field with the full upstream feed.
4. Extract it with jq:

   jq -r '.raw_xml' diagnostics-greenbutton-*.json > usage.xml
   xmllint --format usage.xml | less

XML is cached on disk (in HA's .storage directory) rather than held in memory — so even multi-MB feeds don't bloat the running integration. The cache is overwritten on every debug-enabled refresh and removed when the config entry is removed.

Contributing

Issues and PRs welcome. For substantial features, open an issue first so we can talk through the approach.

Questions or feedback? Discuss this add-on on the Home Assistant Community forum.

If this integration is useful to you and you want to help keep it maintained and the proxy server hosted:

• GitHub Sponsors
• Buy Me a Coffee

Suggested $5/month — covers proxy hosting plus time spent adding utilities and keeping up with Home Assistant changes.

Legal

Open Green Button is an open community project. It is not a legal entity, and it is not affiliated with or endorsed by any utility. This integration is free to use and is provided under the MIT license, without warranty of any kind and with no liability to the authors or copyright holders.

The hosted proxy at https://api.opengreenbutton.org is run by volunteers on a best-effort basis, with no uptime or support commitment, under those same terms. If you would rather not depend on it, the server is open source and can be deployed by anyone.

Registering as a third party with a utility is a separate matter, covered under Legal in the main project README.

"Green Button" is a trademark of the Green Button Alliance; this project uses the name in reference to the open data standard.