Carbon Intensity UK smart home integration, free and open source

Carbon intensity of British electricity (NESO): now, 48 h forecast, best time to use power.
How clean British electricity is, right now and for the next 24 hours, from the official Carbon Intensity API of NESO (the National Energy System Operator, formerly National Grid ESO). For Great Britain as a whole, for a region, or for your postcode. This integration is not affiliated with NESO.
Overview
For every zone you follow (Great Britain, a region, a postcode), the integration adds a device with:
- the carbon intensity of the electricity of the current half-hour, in gCO₂/kWh, and the NESO index (very low → very high);
- the electricity mix: share of wind, solar, nuclear, gas, imports, biomass, hydro, coal and other sources, plus the low-carbon and renewable shares;
- the best window of the next 24 hours: when the cleanest run of the length you chose (3 hours by default) starts, in how many minutes, and its average intensity.
On top of that: a dashboard widget with the 24-hour forecast curve, two scene triggers ("Carbon index turns low", "Best window starts") and a scene action that finds the best window of any length, to run the dishwasher or charge the car when the grid is cleanest.
Requirements
- Gladys Assistant 5.3.0 or later.
- Gladys must reach
api.carbonintensity.org.ukon the internet. No account, no key: the data is open, under the CC BY 4.0 licence. - The zones are in Great Britain (England, Scotland, Wales): Northern Ireland is not covered by the API.
Configuration
- Install the integration (Integrations → Install from GitHub, then the address of the repository).
- In its Configuration tab:
- Language of the names: language of the device and feature names (fixed when a device is added) and of the texts sent to scenes;
- Great Britain as a whole: one device for the national figures (on by default);
- Regions: any of the 14 regions of the distribution networks, plus England, Scotland and Wales;
- Postcodes: up to five UK postcodes, comma-separated. Only the first
part counts (
RG10forRG10 9AB): the API maps it to its region. Your full postcode is never sent; - Length of the best window: from 30 minutes to 6 hours.
- Save, then add the devices from the Discovery tab.
Test the connection button
Reads every zone at once and shows its current intensity, or what went wrong (no answer, postcode unknown to the API, text that is not a postcode).
Devices
Carbon intensity (one per zone)
| Feature | Value |
|---|---|
| Carbon intensity | gCO₂/kWh of the half-hour in progress |
| Carbon index (1 to 5) | 1 very low, 2 low, 3 moderate, 4 high, 5 very high |
| Carbon index | the same index, as a word |
| Low-carbon share, renewable share | % |
| Wind, solar, nuclear, gas… share | % of each source, rounded |
| Best window start | time, for example 03:00 |
| Best window starts in | minutes, rounded up to 5, 0 once it has begun |
| Best window intensity | its average gCO₂/kWh |
The intensity is NESO's forecast for the half-hour in progress: the API has no measured figure for regions, nor for the current half-hour. "Low-carbon" counts wind, solar, hydro, biomass and nuclear; imports and "other" count as neither.
Widget
Carbon intensity forecast shows, for the zone chosen in its settings (the first zone by default): the intensity now and the index, the start of the best window, the forecast curve of the next 24 hours with the best window and the current time marked, and the electricity mix of the half-hour as bars. Two settings hide the best window and the mix.
Scenes
Carbon index turns low (trigger)
Fires when the index of a zone goes from moderate (or worse) to low or very
low. Filters: the zone, the index reached. Variables: level
(very_low, low), index (1, 2), index_label, intensity, zone.
Best window starts (trigger)
Fires when the half-hour in progress opens the cleanest window of the next 24
hours, for the length set in the configuration, once per window. Filter: the
zone. Variables: duration_minutes, average_intensity, end_time, zone.
In a zone that stays at 0 g/kWh (often South Scotland), every window is
equally clean: it fires again at the end of each one. The window is looked for
again every half-hour on a horizon that moves on: a cleaner window entering
the horizon can replace the one announced on the devices before it starts.
Find the best window (action)
Choose a zone and a length: the action returns start_time, end_time,
minutes_until and average_intensity for the following actions of the
scene (pick them in the variable list of the scene editor), for example to send
yourself a message "Start the washing machine at 02:30".
Scene examples
- Every evening at 8 pm, Find the best window of 2 hours, then send "Best time for the dishwasher:" followed by its start time, picked in the variable list.
- Best window starts → switch on the plug of the electric car charger; a scheduled scene switches it off in the morning.
- Carbon index turns low → turn on the water heater, with a condition on the time of day.
Limits
- Data every half-hour: the integration reads each zone once per half-hour slot (two calls for Great Britain, one for a region or postcode), only when its device is added or its widget is displayed. The API asks for no key and states no quota; it is used with this restraint.
- If the API is unreachable, the devices keep following the last 48-hour forecast, and the Configuration screen shows the zones that cannot be read.
- Times are in the time zone of Gladys.
Troubleshooting
- "Cannot be read: RG10": the API does not know the postcode, or does not answer. Use the Test the connection button to tell which.
- No device in Discovery: no zone is followed; tick Great Britain or choose a region or a postcode.
- Logs: the integration logs its start, the zones followed and failures. For
more detail, set the
LOG_LEVEL=debugenvironment variable.
Credits
Data: NESO Carbon Intensity API, CC BY 4.0 — "Carbon Intensity data from NESO". API documentation: https://carbon-intensity.github.io/api-definitions/. This integration is not affiliated with NESO.
Configuration settings
These are the settings Carbon Intensity UK asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Open data from NESO | section | No | The Carbon Intensity API of NESO (Great Britain's electricity system operator) needs no account and no key. Follow Great Britain, regions or postcodes: one device each. Not affiliated with NESO. |
| Language of the names | select | No | Language of the device and feature names (fixed when a device is added) and of the texts sent to scenes. |
| Great Britain as a whole | boolean | No | One device for the national figures (England, Scotland and Wales). |
| Regions | multi_select | No | The regions of the distribution networks, plus England, Scotland and Wales: one device each. |
| Postcodes | string | No | Up to five UK postcodes, comma-separated. Only the first part counts (RG10 for RG10 9AB): the API maps it to its region. |
| Length of the best window | select | No | The cleanest run of this length in the next 24 hours: e.g. the time a dishwasher or a car charge takes. |
How to install Carbon Intensity UK in Gladys
- In Gladys, open Integrations: Carbon Intensity UK appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-carbon-intensity-uk:1.0.0), 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-carbon-intensity-uk.
Carbon Intensity UK requires Gladys >=5.3.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
Carbon Intensity UK 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