RoboHub

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.

The overview: the energy mesh and the balance — generation, load, battery, grid and how self-sufficient the site is

Loads: each load's state, switch and place in the shedding order

Policy & tariff: the thresholds and limits the rules read, and the prices

Reaching it

Through the keeperhttp://127.0.0.1:19090/app/energy/
Its own loopback porthttp://127.0.0.1:8482/
Unitenergy (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.

PageAddressWhat 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/generationThe solar strings, microinverters, turbines and generator, what each makes now, and the day's total
Storage/storageThe battery banks: state of charge, power, temperature, and each bank's capacity (set here)
Grid/gridWhat is bought and sold now and today, the voltage, the price now and the day's cost
Loads/loadsEach load's state and switch, its priority and whether it may be shed
Devices/devicesThe equipment by group, each capability bound to a gateway source; new equipment
Schedule/schedulerCleaning the panels, checking the bank, servicing the generator by its runtime
Inventory/expensesThe equipment, fuel and spares, with their stock and purchases
Policy & tariff/policyThe thresholds and limits the rules read, and the tariff
Rules/rulesThe rules and modes, their state, editing a rule and putting a preset back
Journal/journalEverything that happened; open warnings are resolved here
Dashboard/widgetsWidgets over what energy publishes
Settings/settingsSee below
Documentation/docsThis 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:

GroupCategories
GenerationSolar strings, Microinverters, Wind turbines, Generator
StorageBatteries
GridGrid connection
LoadsLoads

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:

ValueWhat it is
site.generation_w, site.load_w, site.battery_w, site.grid_wthe power now, in watts
site.import_w, site.export_wbought from and sold to the grid now
site.socthe state of charge, in percent
site.battery_temp, site.grid_voltage, site.grid_frequencythe hottest bank, the grid
site.self_sufficiencythe share of the load not bought, in percent
site.generation_today, site.load_today, site.import_today, site.export_today, site.cost_todaythe day so far
policy.<key>, tariff.price_nowthe 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.

KeyDefaultWhat it is
reserve_soc25 %shedding ends above it
load_shed_soc15 %shedding starts below it
generator_start_soc, generator_stop_soc10 %, 40 %the generator's switch
battery_temp_limit45 °Cthe battery alarm
grid_min_voltage, grid_max_voltage207 V, 253 Vthe grid's voltage window
import_limit, export_limit0 W (none)warnings above them
tariff_import, tariff_export0.85, 0.30 per kWhprices
tariff_peak, peak_from, peak_to0, 17:00–21:00a peak import price and its window

The preset rules:

RuleWhenDoes
shed-loadssite.soc < policy.load_shed_soc, until above policy.reserve_socstarts the load-shed mode, and ends it
generatorsite.soc < policy.generator_start_soc, until above policy.generator_stop_socswitches generator on, and off
battery-hotthe hottest bank above policy.battery_temp_limit for a minutean error alert
grid-voltagethe grid outside its voltage window for 30 sa warning alert
import-limit, export-limitbuying or selling more than the limit for a minutea 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

TabWhat it holds
GatewayWhere readings come from (Mesh or the simulator), Mesh's project, and how its changes arrive: automatically, over the broker or over HTTP.
InventoryThe inventory module's settings, the currency among them.
SchedulerThe scheduler's own settings.
WidgetsThe dashboard's own settings.
LoggingLevel, text or JSON, rotating file, size, retention, standard error.
AboutThe 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

WhatHow
robohub.gatewayBound 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.busBound to robohub-provider-mqtt: subscribes to mesh/+/telemetry, the live feed Mesh relays.
Callsdeploy.calls: [mesh] — the keeper makes it a client of Mesh.
Shared modulesinventory/index (the equipment and the Devices page), scheduler, rules, journal, widgets, appapi, simulator, appshell, ui, forms, notifications, settings, i18n, logging, htmx.
Host hookshost_app, host_app_title, host_shell, host_settings_tabs/form/save, host_devices_*.
Presetspresets/: 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 pathWhat it answers
GET /api/v1/valuesevery value energy publishes (above)
GET /api/v1/values/{id}one value
GET /api/v1/values/{id}/historyits history
GET /api/v1/eventswhat happened, as events
GET /api/journalthe journal
GET /api/rulesthe rules and their state
GET/POST /api/scheduler/chores, POST /api/scheduler/chores/{id}/complete, /snooze, /usagethe chores
GET /api/widgets, POST /api/widgets/{id}/value, /pressthe dashboard's widgets
GET /api/expenses/counthow many inventory items there are

Operating notes

WhatWhere
Workspace~/.rho/keeper/workspaces/energy under the keeper (ROBOHUB_APP_WORKSPACE)
Databasedata/app.db in the workspace: the day's counts, the loads' places and the shared modules' records
Settings, bindingsdata/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 same mesh-gateway plugin 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/stream still drives the Faults page, in its own energy-live.events file, separate from the notifications feed. - A deterministic, stateful simulator selected by the persisted driver-mode setting, with ROBOHUB_DRIVER_MODE as 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 as policy.*. - Load shedding by priority: the shed-loads rule starts the load-shed mode 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 from presets/; the simulator runs a whole site from presets/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) on site.import_w and site.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".