powerfox smart home integration, free and open source
powerfox poweropti readers on electricity, gas, water and heat meters, via the powerfox cloud.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
Overview
This integration brings the powerfox poweropti readers into Gladys. A poweropti is an optical reader
clipped on the LED or the display of a meter (electricity, gas, water or heat), widely used in Germany and
Austria. The integration reads the powerfox cloud API with your powerfox account, like the Home
Assistant powerfox integration, and creates one Gladys device per reader:
- electricity meter: the instantaneous power (signed when the meter also feeds in: positive when you draw from the grid, negative when you feed in), the consumption index and the feed-in index, in kWh, which feed the Gladys energy tracking;
- water meter: the cold and/or hot water index, in m³;
- heat meter: the heat energy (kWh) and the heating water volume (m³);
- gas meter: the gas used today and this hour (m³), and its cost today (€);
- for every reader except gas: a stale reading flag, raised when powerfox says the last reading is old.
It also offers a dashboard widget (power and energy of the day) and a scene action (the totals of the day, with a ready-made sentence for a message). The integration is read only: it never changes anything on your meters or in your powerfox account.
Developed without the hardware: this integration was written from the open-source
python-powerfoxlibrary and the real API responses published in its tests, without a poweropti or a powerfox account. Feedback welcome on the Gladys forum or in the GitHub issues.This integration is not affiliated with powerfox GmbH.
Requirements
- Gladys Assistant 5.1.0 or later (5.2 recommended for the energy tracking).
- A poweropti reader set up in the powerfox app, and the e-mail and password of that powerfox account.
- Internet access from Gladys: the readings come from the powerfox cloud (
backend.powerfox.energy).
Configuration
- In Gladys, open Integrations, find powerfox (or use Install from GitHub with
https://github.com/guim31/gladys-powerfox) and install it. - In the Configuration of the integration, enter:
- E-mail and Password: the ones you use in the powerfox app;
- Refresh interval: how often each reader is read, from 10 seconds to 5 minutes (1 minute by default, see API quotas);
- Language of the names and messages: the language of the names of the new devices and of the sentence returned by the scene action (French by default).
- Click Test the connection: the message lists the readers of your account.
- Open the Discover tab and add the readers you want in Gladys. Only the added readers are read.
The password is stored in the Gladys configuration of the integration; it never appears in the logs.
Devices
Each reader becomes one device, named as in the powerfox app (or after its meter type and the end of its identifier when it has no name).
Electricity meter
| Feature | Gladys type | Unit | Notes |
|---|---|---|---|
| Power | Grid power (import +, export −) | W | on a bidirectional meter; else "Power", always ≥ 0 |
| Consumption index | Energy sensor, index | kWh | Gladys derives the 30-minute consumption and its cost |
| Feed-in index | Energy production sensor, index | kWh | only on a bidirectional meter ("Prosumer" in powerfox) |
| Stale reading | Input (0 = up to date, 1 = stale) | the Outdated flag of powerfox |
Energy tracking (Gladys 5.2): the consumption index is a cumulative energy index. When you add the device, Gladys creates by itself its 30-minute consumption and its cost features, and attaches it to the main electric meter of the energy settings. The feed-in index feeds the production tracking (and the feed-in revenue). Nothing to configure in the integration.
When the meter only shows the high and low tariff registers, the consumption index is their sum. A total at 0, or lower than the previous one (a reading glitch), is never published: Gladys would count it as a huge consumption.
Water meter
| Feature | Gladys type | Unit |
|---|---|---|
| Cold water | Volume sensor | m³ |
| Hot water | Volume sensor | m³ |
| Stale reading | Input (0 = up to date, 1 = stale) |
A cold water meter has the cold water index only, a hot water meter the hot water index only, a combined meter both.
Heat meter
| Feature | Gladys type | Unit |
|---|---|---|
| Heat energy | Counter | kWh |
| Heating water volume | Volume sensor | m³ |
| Stale reading | Input (0 = up to date, 1 = stale) |
The heat energy is published as a counter, not as an energy index, on purpose: Gladys would attach an energy index to the main electric meter and count heat as electricity.
Gas meter
| Feature | Gladys type | Unit |
|---|---|---|
| Gas today | Volume sensor | m³ |
| Gas this hour | Volume sensor | m³ |
| Gas cost today | Currency | € |
The powerfox API gives no gas index, only the hourly report of the day: these values start again from 0 at midnight (time zone of Gladys). A gas meter is read every 5 minutes at most.
Widget
powerfox widget: in the dashboard, add a widget, pick powerfox and choose a meter in its settings.
- electricity: the live power, the energy used today and fed in today (bidirectional meter), the time of the last reading and whether it is up to date;
- gas: the gas of the day, of the hour and its cost;
- water and heat: the indexes, the time of the last reading.
The daily totals come from the powerfox report, read at most every 5 minutes; the widget refreshes every 2 minutes, the power tile follows each reading.
Scene action
powerfox: energy of the day (in the "Integrations" actions of the scene editor), for an electricity or gas meter. It reads the report of the day and gives the next steps of the scene:
| Result | Meter |
|---|---|
| Electricity used today (kWh) | electricity |
| Electricity fed in today (kWh) | electricity |
| Current power (W) | electricity |
| Gas used today (m³) | gas |
| Gas cost today (€) | gas |
| Summary sentence | both |
The summary sentence reads "Today: 12.4 kWh used, 3.1 kWh fed in." in the language of the configuration. A water or heat meter, or a report that cannot be read, fails the action (the scene goes on, the result is empty). There is no scene trigger: the power, the indexes and the stale flag are device states, the device triggers of Gladys cover them.
Scene examples
- Daily message: trigger "Every day at 21:00" → action powerfox: energy of the day on the electricity meter → "Send a message" with the summary sentence.
- Use the surplus: trigger on the electricity meter, "Power" below −1500 W (feeding in) → turn on the dishwasher plug.
- Reader silent: trigger on the meter, "Stale reading" equal to 1 → send a message "The poweropti stopped reporting, check its batteries or its Wi-Fi".
- Expensive day: every day at 22:00 → powerfox: energy of the day on the gas meter → "Continue only if" the gas cost is above 10 → send a message.
API quotas
powerfox does not publish a request quota for its API. The Home Assistant integration reads each reader every
10 seconds; users reported HTTP 429 refusals when asking very often. This integration stays well below:
- one request per added reader and per refresh interval (1 minute by default, 10 seconds at least);
- a gas meter every 5 minutes at most; the daily report of the widget and of the scene action every 5 minutes at most per reader (1 minute for a scene);
- the list of the readers at start, every 6 hours, and on demand (Discover tab, Test the connection);
- after an
HTTP 429, no request at all for the delay asked by powerfox (Retry-After), or for a pause that doubles at each refusal, up to 30 minutes; - after a refused password (
HTTP 401), no request until the configuration is saved again: retrying could lock the account.
The integration only reads the data of your own account, with your credentials, like the powerfox app.
Troubleshooting
- "powerfox refused the e-mail or the password": check them in the powerfox app, enter them again, save.
- "powerfox asks to slow down": choose a longer refresh interval; the readings start again by themselves after the pause.
- "The powerfox cloud does not answer": the integration retries at each interval; check the internet access of Gladys.
- A reader stays without values and the logs say "the data transfer is denied in the powerfox app": allow the data transfer of that reader in the privacy settings of the powerfox app.
- "Stale reading" at 1: powerfox has no recent reading from the poweropti (batteries, Wi-Fi, reader moved on the meter); the integration only reports it.
- Nothing in the Discover tab: click Test the connection; a reader of an unknown type is ignored and named in the logs of the integration (Supervision tab).
The logs of the integration only show the start, the connection, the problems and their end. Each reading
appears at the debug level (LOG_LEVEL=debug).
Limits
- Cloud only: the integration uses the powerfox cloud API, not the local interface some readers offer.
- Read only: nothing can be controlled from Gladys.
- The high and low tariff registers are not published as separate features.
- The gas meters have no index, only the totals of the day and of the hour; the heat meter deltas are not published.
- Costs are shown in euros, the currency of powerfox.
- Developed without the hardware: the values were checked against the published responses of the API only. Feedback welcome.
Configuration settings
These are the settings powerfox asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your powerfox account | section | No | The e-mail and the password of the powerfox app. The readings come from the powerfox cloud: the readers must be set up in the app first. |
string | Yes | ||
| Password | secret | Yes | |
| Refresh interval | select | No | One request per reader and per interval. Gas meters are read every 5 minutes at most. |
| Language of the names and messages | select | No | Names of the new devices and texts of the scene action. |
How to install powerfox in Gladys
- In Gladys, open Integrations: powerfox appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-powerfox: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-powerfox.
powerfox requires Gladys >=5.1.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
powerfox 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