Metadata-Version: 2.5
Name: statsbadge-octopus
Version: 1.0.0
Summary: Octopus Energy half-hourly prices and meter readings as statsbadge readings
Project-URL: Homepage, https://github.com/pimoroni/statsbadge-octopus
Project-URL: Repository, https://github.com/pimoroni/statsbadge-octopus
Project-URL: Issues, https://github.com/pimoroni/statsbadge-octopus/issues
Author-email: Philip Howard <phil@pimoroni.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: statsbadge>=1.3.0
Description-Content-Type: text/markdown

# statsbadge-octopus

Your Octopus Energy prices and meter readings as readings, for [statsbadge](https://github.com/pimoroni/statsbadge).

On an Agile tariff the useful half of the price curve has not happened yet, so the next six hours travel as **bars with the times down the side**: put the washing on at the short one.

On any tariff, each meter reports what it used, what that day cost, and a half-hourly graph of it. A flat tariff has no curve to draw, so the bars and the cheapest-slot readings are not offered for one - the **Tariff** reading is there to say which you are on.

## Install

```bash
statsbadge ext add octopus
```

Then, in the config UI under **Extensions**, paste an API key and your account number. The meters appear as checkboxes on the next reload, and each one becomes a source in the field pickers.

## The key

Both are on [octopus.energy/dashboard/new/accounts/personal-details/api-access](https://octopus.energy/dashboard/new/accounts/personal-details/api-access): the key starts `sk_live_`, the account number with an `A`.

The key is stored in the host's config file in plain text. It is read-only and gives access to your account's meter readings, so treat it like a password.

## Settings

| Setting | What it does |
| ------- | ------------ |
| API key | The key above |
| Account number | Used once an hour, to find your meters and the tariff each is on |
| What the gas meter reports | `m3` or `kWh` - see below |
| One per meter | Whether to watch it |

Nothing else needs setting. The tariff, the region, the product code and the meter serials all come off the account, so switching tariff needs no edit here.

## What each meter reports

| Reading | What it is |
| ------- | ---------- |
| Price now | Pence a kWh including VAT, for the half hour in progress |
| Standing charge | Pence a day |
| Tariff | The product the readings are priced against, so a page with no curve says why |
| Newest half hour | The most recent half hour the meter has sent Octopus, which is not the half hour just gone - see below |
| Newest full day | A whole local day, so a part-reported day is skipped rather than read as a quiet one |
| Cost of that day | That day's half-hours, each priced at the rate that applied to it |
| Meter behind by | How far behind the newest reading is. A day or two is normal |

On a tariff with a half-hourly curve, also:

| Reading | What it is |
| ------- | ---------- |
| Next slots | A lane per half hour for the next six, for a **bars** page |
| Price next slot | The half hour after this one |
| Cheapest published / Dearest published | Across everything published ahead |
| Cheapest slot in | Hours until it, so a **grid** page can say "cheapest in 1.5h" |
| Prices published for | How far ahead the tariff has been published, which is how you tell tomorrow has landed |

## Pages worth building

| Page | Kind | Field |
| ---- | ---- | ----- |
| The next six hours | bars | `Next slots` |
| Today's shape | graph | `Price now` |
| At a glance | grid | `Price now`, `Cheapest slot in`, `Newest full day`, `Cost of that day` |
| Where it is going | trend | `Price now` |

## None of the meter readings are live

A smart meter sends its half-hours to Octopus in its own time, usually a day or two later, and the API has what it has been sent. So **Newest half hour** is the most recent half hour on record, not the one just gone, and a graph of it ends where the readings do rather than at now.

**Meter behind by** is how stale that is. Worth putting beside the others on a grid page: 19 kWh means something different at 2 hours behind than at 40.

The prices are live. It is only the meter that lags.

## Gas

Octopus hands gas consumption over in kWh from a SMETS1 meter and in cubic metres from a SMETS2, and the API does not say which you have. The setting defaults to `m3`, which is the common case now.

If gas readings look about eleven times too small or too large, that setting is the wrong way round.

## Agile goes negative

When the grid is oversupplied the price drops below zero and you are paid to use electricity. Nothing here clamps that, so:

- a **grid**, **text** or **trend** page shows a negative fine
- a **dial** cannot draw one, and reads as empty
- a **bars** page draws a negative lane as nothing

So a dial is the wrong page for a price. Use it for `Last full day` if you want one.

## What it asks for, and how often

Every clock is set by how fast the thing behind it moves. Octopus documents no rate limit, which is a reason to be careful with it and not a licence.

| Request | How often | Why that often |
| ------- | --------- | -------------- |
| `/products/.../standard-unit-rates/` | Hourly, per tariff | A tariff publishes tomorrow's in one go each afternoon |
| `/{fuel}-meter-points/.../consumption/` | Hourly, per meter | A meter sends its half-hours a day or more later |
| `/accounts/{number}` | Every 6 hours | A switch takes days, and meter serials never change |
| `/products/.../standing-charges/` | Twice a day | Pence a day, moving at a tariff change or a price cap |

That is about **5 requests an hour** for a house with one electricity meter and one gas meter, and it scales with meter points rather than with anything else.

The price on the badge turns over on the half hour whatever the fetch interval is: two days of the curve are held, and the slot covering now is read out of it on every sample. So an hour late in noticing tomorrow's prices costs nothing on screen.

A failure waits two minutes and then doubles, up to an hour. A rejected key otherwise means thirty requests an hour for as long as nobody notices.

Export meter points are skipped. What a panel sold and what the house bought would draw the same page and mean the opposite.

## Licence

MIT
