Octopus Energy France smart home integration, free and open source
Linky and Gazpar usage, cost, balance and off-peak hours of your Octopus Energy France contract.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.2.0
- ★ 0
Follow your Octopus Energy France contract (electricity and gas, formerly Plüm Énergie) in Gladys: the consumption your Linky or Gazpar meter reports, its cost, your account balance, the next payment, and above all the off-peak hours (heures creuses) of your contract, to the minute, to start the water heater or the car charge at the right time.
Electricity also feeds the Gladys 5.2 energy tracking, day by day, on the date it was really consumed, even though Enedis sends the readings a day or two late.
Not affiliated with Octopus Energy. Developed without the hardware: feedback welcome — developed without an Octopus Energy account: your feedback is welcome (GitHub issues or the Gladys forum). The exchanges with Octopus follow the open-source Home Assistant integration ha-octopus-french, but could not be tried with a real account.
Overview
- One Gladys device per supply point: an electricity meter (the PRM number of your Linky) and a gas meter (the PCE number of your Gazpar), when your contract has both.
- Electricity: the dated consumption goes to the Gladys energy tracking; plus the consumption and cost of the last day read and of the month, the account balance, the next payment, the name of the offer, and the current tariff period (peak or off-peak hours) with its price.
- Gas: the same summaries in kWh and euros, the balance and the next payment.
- A dashboard widget, three scene triggers and a scene action.
- The account is read every 3 hours. The off-peak hours are followed to the minute, without connecting to Octopus.
Requirements
- Gladys 5.2.0 or later (import of a consumption dated in the past).
- An electricity or gas contract with Octopus Energy France and access to your customer area (e-mail address and password). Octopus customers in the United Kingdom or another country are not concerned: their platform is a different one.
- A smart meter (Linky, Gazpar) for the daily consumption. Without one, only the balance, the payment and the contract are shown.
- Internet access for your Gladys: the integration talks to the Octopus
Energy France API (
api.oefr-kraken.energy).
Configuration
Install the integration from Integrations → Install from GitHub (or from the store), then fill in:
| Field | What to enter |
|---|---|
| E-mail address | The sign-in address of your Octopus Energy customer area |
| Password | The password of that customer area |
| History to import | Electricity days sent to the energy tracking on the first reading (7 days to 1 year) |
| Language of device names | Language of the feature names (French by default), set when you add a meter |
Save: the integration signs in, reads the account and offers your meters in the Discovery tab. Add them; their values arrive at once.
The Sign in and refresh now button reads the account again without waiting for the 3-hour cycle (once every quarter of an hour at most).
When Octopus refuses the address or the password, the integration stops and does not try again until you fix the configuration: too many failures could lock your account.
Devices
Each meter is a device named after its energy and the last four digits of its number, for example "Octopus Electricity …0123".
Electricity meter
| Feature | Unit | What it is |
|---|---|---|
| Daily consumption | kWh | The consumption of each day, dated, for the Gladys energy tracking |
| Last day consumption | kWh | The last complete day read by Enedis (often the day before yesterday) |
| Last day cost | € | Its cost incl. taxes as computed by Octopus, standing charge excluded |
| Month consumption | kWh | The month of the last reading, up to that day |
| Month cost | € | Its cost incl. taxes without standing charge, only when every day of it has a cost |
| Account balance | € | The balance of your electricity account at Octopus: positive in your favour, negative when you owe |
| Next payment | € | The amount of the next planned direct debit |
| Next payment date | text | Its date |
| Offer | text | The name of your offer |
| Off-peak hours now | yes/no | 1 during the off-peak hours of your contract, 0 otherwise |
| Tariff period | text | "Off-peak hours", "Peak hours" or "Base rate" |
| Current price per kWh | € | The price per kWh incl. taxes of the current period |
| Off-peak hours of the contract | text | The off-peak ranges, for example "22:00–06:00" |
Gas meter
The same summaries, without the daily consumption nor the off-peak hours: Last day consumption, Last day cost, Month consumption, Month cost (in kWh, as on your bills), Account balance, Next payment, Next payment date and Offer. Octopus gives no cost with the gas readings, so it is computed at the price per kWh incl. taxes of your contract, standing charge excluded. A Gazpar that only sends a monthly reading shows the month only.
Energy tracking
Enedis sends the Linky readings to Octopus a day or two late. Gladys 5.2 can import a consumption dated in the past: the integration sends each day on its real date, through the dedicated core endpoint, and sends the last three days again at every reading (Enedis sometimes corrects its recent readings; Gladys writes only what changed). The Gladys energy charts and the cost computed from your contract are therefore right despite the delay.
No cumulative index is published, on purpose: Gladys would turn an index received a day late into a single half hour of consumption.
For Gladys to compute the costs, choose the Daily consumption feature of your electricity meter as the main meter in the energy settings and create your contract there. The Last day cost and Month cost features come from Octopus and do not depend on that contract.
Gas is not sent to the energy tracking: Gladys 5.2 prices electricity only, and a gas consumption would be added to the electricity one.
Off-peak hours and tariff period
The integration reads the off-peak hours of your contract, from the most precise source to the least precise:
- the time slots of the off-peak rate of your Octopus contract;
- the supplier calendar of your meter;
- the off-peak hours the Linky announces ("HC (22H00-6H00)").
Every minute, without connecting to Octopus, it works out the current period, in French legal time (clock changes included), publishes Off-peak hours now, Tariff period and Current price per kWh, and fires the scenes when the period changes.
- Base offer: a single period, all day.
- Peak / off-peak offer: the period and its price.
- Two-season offer (summer and winter peak and off-peak hours): the ranges and the price of the current season.
- Tempo-like offer: the period is given, but not the price, which depends on the colour of the day that Octopus does not announce in the account.
Dashboard widget
Octopus Energy shows, for one meter (the first electricity meter when you choose none): the date of the last reading, the consumption of that day and of the month, their cost, the last 14 days as bars, the current tariff period and until when, the price per kWh, the account balance and the next payment. It updates at every reading and at every change of period. When the configuration is missing or the password is refused, the widget says so.
Scene triggers and action
- Off-peak hours start (trigger): fires on the minute the off-peak hours
of your contract start. Optionally choose the meter. Variables: the end of
the off-peak hours (
until, HH:MM) and the off-peak price (price, €/kWh). - Off-peak hours end (trigger): fires on the minute they end and the peak
hours begin. Variables: the time of the next off-peak hours (
until) and the peak price (price). - New day of readings (trigger): Octopus received a new complete day from
the Linky or the Gazpar, often a day or two late. Optionally filter on the
meter or the energy. Variables: the day (
date, YYYY-MM-DD), its consumption (consumption, kWh) and its cost (cost), the consumption and cost of the month (month_consumption,month_cost), the energy (energy:electricityorgas). Fired once per new day; the first reading after the installation only sets the starting point. - Read an Octopus meter summary (action): gives the last day read, its
consumption and cost, the consumption and cost of the month, the balance,
the next payment and its date, the tariff period (
base,peakoroff_peak) and the current price, for the next actions of the scene. An unknown figure stays empty.
Why triggers on top of Off-peak hours now? The state is published again regularly (every 6 hours) so that Gladys does not consider it stale: a scene "when the state is 1" could start again. The triggers fire only once, when the period changes, and never at a restart. Use the state as a condition ("only during off-peak hours") and the triggers to start a scene.
Scene examples
- Water heater on off-peak hours: trigger Off-peak hours start → turn the water heater plug on; trigger Off-peak hours end → turn it off.
- Car charge: trigger Off-peak hours start → turn the charging point on, send "Charge started until {{triggerEvent.data.until}}".
- Delayed washing machine: when the "start later" button is pressed, condition Off-peak hours now = 1 → start at once, otherwise wait for the trigger.
- Daily report: trigger New day of readings (energy: electricity) → message "{{triggerEvent.data.date}}: {{triggerEvent.data.consumption}} kWh, {{triggerEvent.data.cost}} €. Month: {{triggerEvent.data.month_cost}} €."
- Weekly report: a scene scheduled on Sundays → Read an Octopus meter summary → message with the month cost and the balance.
Refresh and quotas
- One reading of the account every 3 hours; a new try after an hour when Octopus does not answer or asks to slow down (API request limit, error KT-CT-1199).
- A reading costs about ten requests: the sign-in (the access token lasts an hour, the refresh token a week, without sending the password again), the list of accounts, the account, and the readings of each meter. The first reading imports the chosen history: four more requests for a year. The Home Assistant integration reads every hour: this is three times less.
- The off-peak hours are computed in Gladys, without a request.
- The integration polls itself: it does not depend on the Gladys polling.
- The terms of use of Octopus Energy apply to your account: this integration only reads your own data, read-only.
Troubleshooting
- "Octopus Energy refused the e-mail address or the password": check them by signing in to your Octopus customer area, then fix the configuration (the integration then tries again at once).
- "Octopus Energy cannot be reached": the API did not answer; a new try within the hour. If it lasts, Octopus may have changed its API: open a GitHub issue with the logs.
- No meter offered: the account has no active supply point yet (a terminated meter is not offered).
- The last day is the day before yesterday: normal, Enedis and GRDF send the readings late.
- No daily consumption: your meter may not be a smart one, or you did not allow the collection of your consumption data in your customer area.
- No tariff period: Octopus gave neither the off-peak ranges of the contract nor those of the meter. Report it with the name of your offer.
- Logs: set
LOG_LEVEL=debugto see every reading. The logs never show the e-mail address, the password nor the tokens.
Limitations
- Developed without the hardware: feedback welcome — developed without an Octopus account. The requests follow those of the Home Assistant integration ha-octopus-french, not a real try: the first real uses may reveal differences.
- The readings are a day or two late: no instant power, no "today". For real time, use a teleinformation module on your Linky.
- The energy tracking receives days, not half hours: a peak / off-peak contract created in Gladys cannot split a day between its two prices. The Octopus cost features do.
- Gas is outside the energy tracking.
- Tempo offers: no current price, nor colour of the day. Managed offers (Octopus Intelligent, vehicle charging) are not supported.
- The gas cost is estimated at the price per kWh of your contract; the costs never include the standing charge.
- One sign-in per integration; every account and meter of that sign-in is offered.
- No command: the integration controls nothing at Octopus.
Privacy and data
The e-mail address and the password stay in the Gladys configuration. The
/data/octopus-state.json file keeps the Octopus refresh token (so the
password is not sent at every reading) and, for each meter, how far the
energy tracking was fed. Only the integration can read it. Nothing is sent
anywhere but to the Octopus Energy France API and to your Gladys.
Credits
The GraphQL requests and the reading of the Octopus Energy France answers are adapted from ha-octopus-french by domodom30 (MIT licence), the Home Assistant integration for Octopus Energy France; its tests provided the answer shapes used in the tests here. Octopus Energy, Linky, Gazpar, Enedis and GRDF are trademarks of their respective owners.
Configuration settings
These are the settings Octopus Energy France asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Octopus Energy customer area | section | No | Sign in with the e-mail address and password of your Octopus Energy France customer area. Linky and Gazpar readings arrive a day or two late and are read every 3 hours. Not affiliated with Octopus Energy. |
| E-mail address | string | Yes | |
| Password | secret | Yes | |
| History to import | select | No | Electricity days sent to the Gladys energy tracking on the first reading. |
| Language of device names | select | No | Names are set when you add a meter to Gladys. |
How to install Octopus Energy France in Gladys
- In Gladys, open Integrations: Octopus Energy France appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-octopus-fr:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-octopus-fr.
Octopus Energy France requires Gladys >=5.2.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Octopus Energy France is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation