This page was generated from the source of RoboHub. Edit the source, not this page.
RoboHub
RoboHub is home, aquarium and energy automation that runs on your own machine.
Sensors and switches report through a gateway you run; the applications that
read them, keep their history and act on them run on your computer, under your
account, with no cloud service in between. It is written in
Rho, and every part of it is a Rho module.
The parts
| Part | What it does |
|---|---|
| The keeper | The front door and the supervisor. It listens on 127.0.0.1:19090, signs people in (admin, operator and viewer roles), installs the applications, runs each as a systemd user unit from a release, and serves them under its own origin at /app/<name>/. |
| Applications | What a person uses. Mesh manages gateways and the boards and devices behind them; Aquarium looks after tanks, water, dosing, livestock and equipment; Energy works out a site's balance of solar, storage and grid, and applies a policy with load shedding. |
| Shared modules | What every application needs and none should write again: the shell and settings pages, inventory and equipment, the scheduler, rules and modes, the journal, dashboard widgets, forms, languages, logging. An application includes them, and they register their routes on its router. |
| Interfaces and providers | An application reaches the outside world only through an interface — robohub.gateway for readings and switches, robohub.bus for MQTT, robohub.alert for alerts — and binds providers to it in its module.yml: Mesh or the simulator for the gateway, the keeper's Mosquitto broker for the bus, e-mail, Telegram, a webhook or a log file for alerts. |
| Mesh, gateways and devices | A gateway collects authenticated frames from boards over serial, USB or Wi-Fi and polls network devices; Mesh plans the tree, builds and flashes the boards, and keeps every reading in one telemetry store. A gateway can report through another one (relay and uplink), so one Mesh runs several linked meshes. |
| Firmware | The device side: the board platforms (Pico, ESP32, STM32, AVR, Linux), FreeRTOS, the runtime, transport and telemetry a node runs, and the drivers and device integrations. |
architecture/index shows how the parts connect, and
architecture/reading follows one reading from a sensor to a widget.
Where to start
- Running it: start/install, then start/first-run,
start/applications and start/gateway. - Using an application: keeper/index, mesh/index,
aquarium/index, energy/index. - Writing an application: build/host-application, then the shared
modules under Build an application. - Connecting hardware: robohub-gateway/index and the parts under
Devices & firmware.
Where the code is
Each part has its own repository, versioned and released apart. This one,
robohub, holds what they share: the shared modules (modules/), the
interfaces (contracts/) and their providers (providers/), the integrations
the keeper runs (plugins/), the wire protocol (protocol/), the registry of
the ecosystem's repositories (registry/modules/), the schemas, and the
robohub command, which runs the toolchain's lint, tests and documentation over
all of them:
rho build . # builds ./build/robohub
./build/robohub registry list # every repository of the ecosystem
./build/robohub registry check # whether the registry and the checkouts agree
./build/robohub test # every module's tests
./build/robohub keeper # runs a built keeper on 127.0.0.1:19090
This site is built from all of them by applications/docsite.
Release history
All notable changes to this module are recorded here, one section per release. A module's description says what it is and does not change between releases; this says what changed, which is what tells two versions of one module apart. The section for the version being published travels with it, so a registry shows it against that version.
[0.1.0] - 2026-10-21
The orchestrator of the RoboHub ecosystem: a registry of its modules, and the tools that run over all of them.
The registry names every module of the ecosystem, where it is and what it is for, and each module's own manifest remains the truth about what it is. The orchestrator reads the manifests it needs and repeats nothing.
The tools are the toolchain's own components — the linter, the test runner and the documentation generator — run over each module in turn, and what each said is written to build/reports/. The orchestrator decides what to run them over and collects what they said; the components decide how to run and what their findings mean.
The material every repository in the ecosystem needs and none of them should own is here as well: the ignore rules, the configuration a CI build resolves, and the workflow itself, as a workflow the repositories call rather than a copy each of them carries.
[0.2.0] - 2026-11-01
The keeper gains Mesh: projects saved in a workspace, a dashboard that lists them with their gateway status, a plan of the gateway and its nodes, and network, build/program and verify steps. A project is a folder under ~/.rho/mesh/projects (or ROBOHUB_MESH_PROJECTS); it can be created, opened, renamed, described and deleted. Boards and drivers come from the registry's capabilities and deployment blocks, and transports from robohub-transport, so a new board or driver is offered without rebuilding the keeper.
The gateway page, frame history and CSV export, the wall-clock receive time beside a node's uptime, and the documentation each module now carries with its release history are part of the ecosystem this release describes.
[0.3.0] - 2026-11-02
The keeper is an applications registry. A module whose manifest declares an application block is listed at /applications, where it can be opened, started, stopped, added to the keeper's left menu as a sub-item of Applications, or removed. An application is installed from a git URL or registered from a folder that already exists; its state lives in ~/.rho/keeper/.
Mesh moved out of the keeper and into applications/mesh as a keeper-hosted application. It has its own left menu, active-project selection, attached sensor modules read dynamically from robohub-drivers/boards, per-node bus plans with I2C address and SPI chip-select allocation, and its own documentation page.
[0.3.1] - 2026-11-02
Mesh models a sensor module as a node of its own (kind: module) attached to a node, instead of a field on the node. Module nodes appear in the plan tree under the node they extend, are added with + Add module or + module, and are never built or programmed separately: the node's image carries them. A native gateway cannot take modules; the controls appear only when the gateway is a real board.
The module picker is read from robohub-drivers/boards on every load and grows a section for any new board category. The robohub-drivers root manifest now states the board module contract, so a board added to that checkout is discoverable without a list elsewhere changing.
[0.3.2] - 2026-11-02
A plugin system for the applications. An application names its plugins and settings in its own module.yml; plugins/registry.yml is the installed set and the manager confirms each path on disk before using it. The keeper has a /plugins registry to install, remove, enable and test plugins.
The alert dispatcher is the unified alert entry point: it fans out to the channels named in its targets, each with its own threshold. The transports are generic Rho providers for a log, e-mail (SMTP or a local outbox with templates), Telegram and webhooks, and an application can call a provider directly. The alert rule engine adds hysteresis, pending and cooldown windows and a rolling rate limit around a reading. Mesh raises an alert when a step fails, through the same dispatcher.
[0.3.3] - 2026-11-02
Reusable modules under modules/, with modules/registry.yml as the installed set and a keeper /modules page to install, remove and open them. A module has no port of its own: the host application includes it and the module registers its routes on the host's router.
The aquarium application is the first host: one service on one port, with the inventory module registering its routes on the aquarium router under /expenses, a scheduler module under /scheduler with a chores API, and a widgets module whose configurable number, chart, button and switch cards make the aquarium's home page a dashboard. Modules share the host's main SQL database. The aquarium has a stylized background asset and top/bottom menus. The inventory module tracks stock on hand, reorder levels, purchases with categories, quantities, unit prices, stores, dates and comments, a running total, and SQLite storage through rho-sql. A module keeps its records and settings in the workspace of the application that consumes it, so two applications using one module do not share a database; the settings are the config: map on the host's micro_apps entry, not anything beside the module.
[0.3.4] - 2026-11-02
The aquarium framework: equipment and devices, automation rules with an evaluation and audit trail, water chemistry, operational modes and the event log. The home page is a dashboard built from configurable widgets, including buttons and switches whose hooks are called when pressed. Module versions are independent of the application, and the keeper lists modules without a single host link. Module forms use the same semi-opaque panels as the aquarium.
[0.3.5] - 2026-11-04
Keeper authentication and SSO across applications. Keeper is the authorization server: it holds an ES256 signing key, mints short-lived single-use tickets, and protects its own admin UI. Aquarium and Mesh verify sessions locally with the public key, support direct WAN and reverse-proxy origins, and Mesh accepts signed service JWTs for server-to-server API calls. A robohub-auth plugin and provider registry make the auth provider selectable.
[0.4.0] - 2026-11-09
The energy application: one location's generation, storage, grid and loads in one keeper-hosted service on port 8482. It normalizes solar PV, microinverter and wind readings, tracks a LiFePO4 bank (SoC, cell window, temperature and the L51 CAN profile), controls off-grid, on-grid and hybrid modes with load shedding, generator thresholds, zero export, peak shaving and tariff windows, evaluates thermal and electrical interlocks, and writes power faults into the telemetry SQLite/WAL store. Its dashboard is the shared widgets module rather than a second implementation, and it carries the inventory, scheduler and widget modules inside the energy shell, with their pages rendered as content in the host's own menu and layout. The driver seam runs a deterministic stateful simulator by default and can switch to real-time Mesh telemetry through the same mesh-gateway provider the aquarium uses, without a restart. Simulation mode publishes simulated gateway sources so widgets preselect them; real-time mode clears those selections. Applications now register as Mesh clients with their project, callback and topic subscriptions; Mesh routes published energy faults and mode changes only to subscribed applications, authenticated by the service token and a per-client callback secret. Scripted fault injection keeps the smoke suite runnable without a bench. Every application now has a Logging settings form and a rotating per-app log, the keeper's Applications page links each app to its log file, and energy is installed as the same kind of user service as mesh and aquarium.
Also in this release:
A reactive UI, internationalisation, telemetry and provisioning release.
- Added HTMX and SSE to Aquarium, Keeper and Mesh: widget cards, Mesh tree and faults update in place, and pages answer fragments for
HX-Request. - Added English and Romanian catalogs, a shared i18n module, flag-based language switching, translated application/module navigation, forms and notification toasts, and per-locale live widget events. - Centralized runtime settings in the parent application, with vertical tabs, module tab layout, forms-engine settings, plugin alert overrides, and a shared settings store. - Keeper deploys signed staged artifacts with an atomic swap, health check and rollback, and manages application services through systemd. - Mesh telemetry gained WAL maintenance, batched retention, vacuum and storage settings, actionable faults with a live HTMX page and API, and gateway polling backoff with health reporting. - Keeper gained one-time node enrollment, a node registry, credential verification, rotation and revocation. - Cross-entity includes use portable bare names, and RoboHub dependencies are declared once underdeps.robohub.