This page was generated from the source of RoboHub. Edit the source, not this page.
Energy
The energy application looks after one site's power: its solar strings,
microinverters, wind turbines and generator, its batteries, its grid connection and
its loads. It works what they report out into one balance every five seconds, runs
the site by a policy the rules read, sheds loads by priority when the battery runs
low and puts them back afterwards, and counts the day — energy made, used, bought and
sold, and what it cost. It reaches devices only through the gateway interface — Mesh
for real devices, or the simulator when there is no mesh.



Reaching it
| Through the keeper | http://127.0.0.1:19090/app/energy/ |
| Its own loopback port | http://127.0.0.1:8482/ |
| Unit | energy (systemd user unit the keeper writes) |
Energy is a keeper-hosted application: the keeper installs it, signs people in and
runs it (keeper/index). A person needs an energy: grant in the keeper's
Users & access. To run it from a terminal instead:
rho build .
ROBOHUB_APP_WORKSPACE=/tmp/energy RHO_HTTP_ADDR=127.0.0.1:8482 ./build/energy
Pages
The rail groups the pages as the work is: the site, its care, what runs by itself,
and the system. The top bar has a Shed loads button that starts the load-shedding mode
by hand.
| Page | Address | What it does |
|---|---|---|
| Overview | / | The energy mesh — the Mesh project's tree as energy sees it, each device coloured by the group of what is bound to it, with the power flowing on its edges — then the totals, the day, the policy and the journal |
| Generation | /generation | The solar strings, microinverters, turbines and generator, what each makes now, and the day's total |
| Storage | /storage | The battery banks: state of charge, power, temperature, and each bank's capacity (set here) |
| Grid | /grid | What is bought and sold now and today, the voltage, the price now and the day's cost |
| Loads | /loads | Each load's state and switch, its priority and whether it may be shed |
| Devices | /devices | The equipment by group, each capability bound to a gateway source; new equipment |
| Schedule | /scheduler | Cleaning the panels, checking the bank, servicing the generator by its runtime |
| Inventory | /expenses | The equipment, fuel and spares, with their stock and purchases |
| Policy & tariff | /policy | The thresholds and limits the rules read, and the tariff |
| Rules | /rules | The rules and modes, their state, editing a rule and putting a preset back |
| Journal | /journal | Everything that happened; open warnings are resolved here |
| Dashboard | /widgets | Widgets over what energy publishes |
| Settings | /settings | See below |
| Documentation | /docs | This guide, embedded in the program |
The pages of 0.2 — /sources, /modes, /safety, /events, /faults — lead to
where their work is now.
The balance
Every five seconds energy reads the power of each piece of equipment bound on the
Devices page and adds it up by group; presets/site.yml says which categories are
which group:
| Group | Categories |
|---|---|
| Generation | Solar strings, Microinverters, Wind turbines, Generator |
| Storage | Batteries |
| Grid | Grid connection |
| Loads | Loads |
Battery power is positive while charging and grid power while importing, as a meter
says them. The load is what is left whenever generation, the battery or the grid is
read: generation, less what goes into the battery, plus what comes from the grid. The
state of charge is the banks' own, weighed by their capacity.
Reverse the sign
A meter that counts the other way — a battery whose power is positive while it
discharges, or a grid meter that counts export as positive — is marked with
Reverse the sign beside its readings on the Generation, Storage or Grid page. Its
power is turned before the balance counts it and wherever a page shows it.
What is published
The balance is kept for the rules and offered every minute, with its history, through
/api/v1/values:
| Value | What it is |
|---|---|
site.generation_w, site.load_w, site.battery_w, site.grid_w | the power now, in watts |
site.import_w, site.export_w | bought from and sold to the grid now |
site.soc | the state of charge, in percent |
site.battery_temp, site.grid_voltage, site.grid_frequency | the hottest bank, the grid |
site.self_sufficiency | the share of the load not bought, in percent |
site.generation_today, site.load_today, site.import_today, site.export_today, site.cost_today | the day so far |
policy.<key>, tariff.price_now | the policy, and the import price in force |
The policy
The Policy page keeps what the site decides; a rule reads it by name, so a threshold
changed there is the one every rule uses. The page checks the whole policy before
keeping any of it — each number in its range, the shedding threshold below the
reserve, the generator's start below its stop, the lowest grid voltage below the
highest — and a policy that does not hold together is refused with the reasons. An
empty field is its default.
| Key | Default | What it is |
|---|---|---|
reserve_soc | 25 % | shedding ends above it |
load_shed_soc | 15 % | shedding starts below it |
generator_start_soc, generator_stop_soc | 10 %, 40 % | the generator's switch |
battery_temp_limit | 45 °C | the battery alarm |
grid_min_voltage, grid_max_voltage | 207 V, 253 V | the grid's voltage window |
import_limit, export_limit | 0 W (none) | warnings above them |
tariff_import, tariff_export | 0.85, 0.30 per kWh | prices |
tariff_peak, peak_from, peak_to | 0, 17:00–21:00 | a peak import price and its window |
The preset rules:
| Rule | When | Does |
|---|---|---|
shed-loads | site.soc < policy.load_shed_soc, until above policy.reserve_soc | starts the load-shed mode, and ends it |
generator | site.soc < policy.generator_start_soc, until above policy.generator_stop_soc | switches generator on, and off |
battery-hot | the hottest bank above policy.battery_temp_limit for a minute | an error alert |
grid-voltage | the grid outside its voltage window for 30 s | a warning alert |
import-limit, export-limit | buying or selling more than the limit for a minute | a warning alert |
The maintenance mode suspends shed-loads and generator.
Load shedding
While load-shed is in force, energy switches off one sheddable load a minute — the
highest priority number first, of two the one drawing more — as long as the battery
is discharging. A load whose switch does not answer is passed over and the next one
shed on the next tick. When the mode ends, every load energy shed is switched back
on; a load a person switched off is left alone. Priority 1 is shed last, and a load
that may not be shed never is. Each load's priority and whether it may be shed are
set on the Loads page.
Devices
The Devices page is the inventory's, the same one the aquarium has: energy says which
groups there are, which categories each lists and how a reading is shown. Each piece
of equipment is an inventory item whose capabilities — power, state of charge,
temperature, voltage, a switch — are bound to the sources the gateway lists; new
equipment is added under its group, to a category of that group. Until an item is
bound it counts for nothing in the balance.
Settings
| Tab | What it holds |
|---|---|
| Gateway | Where readings come from (Mesh or the simulator), Mesh's project, and how its changes arrive: automatically, over the broker or over HTTP. |
| Inventory | The inventory module's settings, the currency among them. |
| Scheduler | The scheduler's own settings. |
| Widgets | The dashboard's own settings. |
| Logging | Level, text or JSON, rotating file, size, retention, standard error. |
| About | The gateway in use and the application's API. |
Mesh's address and the token it is read with come from the keeper; nothing is copied
into energy. The gateway settings are the binding's, written to bind.conf in the
workspace.
How it connects to the rest
| What | How |
|---|---|
robohub.gateway | Bound to robohub-provider-mesh/index (Mesh at http://127.0.0.1:8478, project default, transport auto) and to the simulator, off by default, which runs a whole site from presets/sim.yml. The energy mesh is the gateway's nodes(). |
robohub.bus | Bound to robohub-provider-mqtt: subscribes to mesh/+/telemetry, the live feed Mesh relays. |
| Calls | deploy.calls: [mesh] — the keeper makes it a client of Mesh. |
| Shared modules | inventory/index (the equipment and the Devices page), scheduler, rules, journal, widgets, appapi, simulator, appshell, ui, forms, notifications, settings, i18n, logging, htmx. |
| Host hooks | host_app, host_app_title, host_shell, host_settings_tabs/form/save, host_devices_*. |
| Presets | presets/: site.yml, inventory.yml, rules.yml, schedule.yml, api.yml, sim.yml. |
API
Under energy's sign-in; another application asks with a service token.
| Method and path | What it answers |
|---|---|
GET /api/v1/values | every value energy publishes (above) |
GET /api/v1/values/{id} | one value |
GET /api/v1/values/{id}/history | its history |
GET /api/v1/events | what happened, as events |
GET /api/journal | the journal |
GET /api/rules | the rules and their state |
GET/POST /api/scheduler/chores, POST /api/scheduler/chores/{id}/complete, /snooze, /usage | the chores |
GET /api/widgets, POST /api/widgets/{id}/value, /press | the dashboard's widgets |
GET /api/expenses/count | how many inventory items there are |
Operating notes
| What | Where |
|---|---|
| Workspace | ~/.rho/keeper/workspaces/energy under the keeper (ROBOHUB_APP_WORKSPACE) |
| Database | data/app.db in the workspace: the day's counts, the loads' places and the shared modules' records |
| Settings, bindings | data/settings.conf, bind.conf in the workspace |
Logs. Energy logs to standard error, kept by its unit's journal (the keeper's
Log, or journalctl --user -u energy); the Logging tab adds a rotating file.
Backup. Copy the workspace with energy stopped; data/app.db is everything it
knows.
From 0.2. At its first start 0.3 moves what 0.2 kept, once: the sources, banks,
grid feeds and loads become inventory items (unbound — map them on the Devices page),
the loads keep their priorities and a critical circuit is never shed, the
configuration becomes the policy, the events become the journal's history, and the
hand-fed dashboard cards read site.*. The old tables are left as they were.
Tests. python3 tests/energy_smoke.py builds energy, starts it on the simulator
with a database 0.2 left behind, and walks the migration, every page, the bindings,
the balance, shedding and restoring a load, the policy and the settings.
Release history
[0.1.0] - 2026-11-09
The first energy application: one location's generation, storage, grid and loads in one service.
- Multi-source ingestion and normalization for PV strings, microinverters and wind turbines, with derived power/current when one figure is absent. - LiFePO4 bank tracking: SoC, SoH, cell window, temperature and the L51 CAN profile. - Grid import/export, voltage, frequency, synchronization and strict zero export. - Off-grid, on-grid and hybrid operating modes with load shedding, generator thresholds, peak shaving and tariff windows. - Typed energy and telemetry schemas, generated through the SQL port. - CSRF-protected admin forms through the forms module, with number and IPv4 validation. - Safety interlocks that write power faults into the telemetry SQLite/WAL store. - The dashboard is the shared widgets module: seeded numeric, status and chart cards bound to simulated Mesh sources, per-locale SSE, and a ten-second refresh from the application's background worker. Energy no longer renders a second dashboard of its own. - Inventory (
/expenses), scheduler (/scheduler) and widgets (/widgets) are carried as reusable modules. Their pages render content through the energy host shell, so the energy menu, header and footer are the same everywhere. Module items are separate menu entries, not an "Apps" group. - Widget card CSS comes from the widgets module (widgets_style()); energy and aquarium no longer keep private widget styles. The aquarium home now passes that style too, fixing its unstyled cards. - Widget move, resize and pin controls are in place over HTMX; moving a card replaces the grid instead of redirecting to a new page. - The dashboard shows the current mode as a big badge beside its title with a two-second heartbeat; the switch is in Settings, no restart needed. Simulation mode disables the Mesh fields; real-time mode disables the scripted-fault field. Real-time mode uses the samemesh-gatewayplugin as the aquarium. The Mesh project is a select built from the projects the entered Mesh address reports; the telemetry project is derived from that selection instead of being a separate input. Each node can name its Mesh source. - Simulation mode publishes simulated Mesh sources (energy.generation,energy.soc,energy.faults, and so on). The widget source picker lists and preselects them; switching to real-time clears the simulated selections so a real Mesh source can be chosen. - Energy-specific fault SSE on/energy/streamstill drives the Faults page, in its ownenergy-live.eventsfile, separate from the notifications feed. - A deterministic, stateful simulator selected by the persisted driver-mode setting, withROBOHUB_DRIVER_MODEas the environment default, and scripted fault injection for tests and demonstrations. - A smoke test that runs the whole loop on a workstation with no hardware.
[0.1.1] - 2026-11-12
Energy declares the robohub-auth plugin, like aquarium; it already used the keeper's sign-in.
[0.1.2] - 2026-11-12
Every list read into a fixed array asks for at most what the array holds: the fault lists asked for 128 rows into 32 places. The smoke test signs in with a keeper ticket, checks the telemetry outbox Mesh polls instead of the store energy no longer keeps, and reads the fault state from energy rather than from the dashboard card Mesh feeds.
[0.1.3] - 2026-11-12
The telemetry outbox is numbered and rewritten under one lock. The simulator and a request recorded readings at the same time and could give two readings one number, and an acknowledgement that rewrote the outbox between a read and an append lost the reading appended. project.yml writes only what differs from the built-in target, and carries the templates folder whole.
[0.1.4] - 2026-11-12
The simulator's tick and the requests that write the site — an ingested reading, a scripted fault — hold one lock. A tick that read the site before an ingest and wrote its step after overwrote the ingested battery with the value it had replaced, so a cleared low-battery fault could stay raised. The smoke test waits for the fault to clear rather than for a fixed time, and says which faults are still active when one does not.
[0.2.0] - 2026-11-12
Energy reaches Mesh through the gateway interface, binding the Mesh provider with Mesh's address and the project in module.yml. The Settings page writes those into the binding's settings for the installation; the mesh-gateway plugin entry, the contract include and gateway.conf are gone.
[0.2.1] - 2026-11-13
A generated read that finds nothing is now Ok(0) rather than an Err (rho-sql 0.2), so the places that asked "is it there?" with is_ok alone — seeding the first source, battery, grid and loads, reading one row by id or by name, the configuration and a fault's state — also check that a row came back.
[0.3.0] - 2026-11-13
Energy moves to its own repository, robohub-energy, and onto the shared RoboHub modules and the gateway contract. It no longer simulates devices or serves them to Mesh: devices are Mesh's, and energy reads them through the gateway like every other application.
- The equipment is the inventory's: solar strings, microinverters, wind turbines, batteries, the grid connection, loads, the generator, fuel and spares, each category with the capabilities energy reads. The Devices page binds them to the sources the gateway lists, by group. - One balance, worked out every five seconds from what is bound: generation, load (metered, or what is left), battery power and the state of charge weighed by capacity, the grid, self-sufficiency. It is kept for the rules as
site.*, offered with its history as values, and counted into the day: energy generated, used, bought and sold, and what it cost. - The Policy page: the reserve, the shedding threshold, the generator's start and stop, the battery temperature limit, the grid's voltage window and limits, and the tariff with a peak window. The rules read it aspolicy.*. - Load shedding by priority: the shed-loads rule starts theload-shedmode below the threshold, and energy switches off one sheddable load a minute, the highest priority number first, while the battery discharges; every load it shed comes back when the mode ends. The Loads page sets each load's place. - The overview is the energy mesh: the Mesh project's tree, gateway, boards and devices, coloured by the group of what is bound on each, with the power flowing on its edges; then the day, the policy and the journal. - Rules, modes, the schedule, the journal, the dashboard and the API are the shared modules', seeded frompresets/; the simulator runs a whole site frompresets/sim.yml. - 0.2's sources, banks, grid feeds and loads become inventory items, its loads keep their priorities (a critical circuit is never shed), its configuration becomes the policy, its events the journal's history, and its hand-fed dashboard cards read what energy publishes. The old tables are left as they were. - Removed: the Mesh outbox and its routes, the driver ingestion, the telemetry tables of energy's own and the pages of 0.2, which redirect to where their work is now.
[0.3.1] - 2026-11-13
same_origin refuses a form posted from another origin. Built on widgets 0.3.1, inventory 0.2.1, i18n 0.4.1, rules 0.1.1 and notifications 0.1.4.
[0.3.2] - 2026-11-13
The clock is read from the process (rho_now_s, rho 0.6.0) instead of from date written to a file and read back, which a request and the background loop could truncate under each other: entries dated 1970 and modes that expired at once. The day and time of day the balance and the tariff use likewise. Built on provider-mesh 0.5.1, which no longer hands one source's reading to another — a load's switch could read another source's value.
[0.3.3] - 2026-11-13
Correctness fixes from the 2026-11 review.
- The Policy page checks the whole policy before keeping any of it: each number in its range, the shedding threshold below the reserve, the generator's start below its stop, the grid's lowest voltage below its highest. A policy that does not hold together — which made a rule fire and clear on alternate ticks and a relay chatter — is refused with the reasons and what was typed. An empty field is its default again. - Shedding passes over a load whose switch does not answer and sheds the next one on the next tick, instead of trying the same plug once a minute for ever; a load that cannot be switched back on is said once and tried every tick. - The load is the balance whenever generation, the battery or the grid is read, not the sum of the loads that happen to be metered: one smart plug made it the plug. - The import and export limits are alert rules (
import-limit,export-limit) onsite.import_wandsite.export_w, published with the balance. - The groups are read from the presets once per tick, not up to four times per item. - The migration from 0.2 can be interrupted and run again: equipment already moved is found by its handle, and the events are copied once. - The overview's status no longer starts with a separator; the mesh's board label is translated.
[0.3.4] - 2026-11-13
Built on the shared modules' fixes: cron chores read as cron, rule durations with decimals and days, a mode ended once, the journal badge past 500, the newest history points, inventory totals in 64 bits and decimal commas, no blank notification.
[0.3.5] - 2026-11-13
Built on rules 0.1.4: a rule whose action fails says so once and tries again a minute later, even when a reading hovers at its threshold.
[0.3.6] - 2026-11-14
The settings page, the docs page and the shell's top bar are the shared appshell module's (robohub/modules/appshell 0.1.0); energy keeps its rail, its load-shedding button and its layout, and answers hostapp() and hostapp_title(). Its own copy of the settings page and the strings only it used are gone.
[0.3.7] - 2026-11-14
Its own trimming and number reading and writing are gone: the toolchain's str_trim and milli_* (rho 0.7.0) do it, the same way every RoboHub module now does. Needs rho 0.7.0.
[0.3.8] - 2026-11-14
The Devices page is the inventory's (inventory 0.3.0): energy says which groups there are, which categories each lists and how a reading is shown, and the page — the same one the aquarium has — does the rest. Equipment is only added to a category of the group it is added under.
[0.3.9] - 2026-11-14
Reading an item's capability or a published value — what every rule does every few seconds — is a lookup, not a list of every item (inventory 0.3.1, appapi 0.1.4).
[0.3.10] - 2026-11-14
A meter that counts power the other way from energy — a battery positive while it discharges, a grid meter counting export as positive — is marked with Reverse the sign on the Generation, Storage or Grid page, and its power is turned before the balance counts it and where the page shows it (energy_meter).
[0.3.11] - 2026-11-14
Rules can be edited on the Rules page, a preset rule put back as its preset (rules 0.1.8).
[0.3.12] - 2026-11-14
Uses the toolchain's i64_to_str, str_field and str_upper instead of its own copies, and the modules' single rule for where data lives (rho 0.8.0).
[0.3.13] - 2026-11-14
Kept in step with inventory 0.3.3 and scheduler 0.2.7.
[0.3.14] - 2026-11-14
Its settings page lists the inventory, scheduler and widgets tabs itself (host_settings_*), each module's own form.
[0.3.15] - 2026-11-14
The gateway's node and source lists are split with Energy's own helper rather than one the widgets module keeps for itself (widgets 0.4.0 lists what it exports).
[0.3.16] - 2026-11-14
The energy mesh on the overview counts a meter marked "Reverse the sign" the same way the balance does: the tree said "in" where the Grid tile said "out".