RoboHub Orchestrator

The orchestrator

Version: 0.2.0

The orchestrator of the RoboHub ecosystem: a registry of its modules, and the
tools that run over all of them.

The ecosystem is a set of repositories — the interfaces every platform
implements, a platform per family of parts, the runtime and transport the nodes
speak, the devices and drivers they are made of, and the gateway that collects
them. Each is versioned apart and built apart, which is right for the code and
wrong for the questions a person asks about the whole: which modules are there,
which version of each, and does any of it still build.

Those questions are about the ecosystem rather than about a repository, and this
is where they are answered.

The registry

Every module of the ecosystem is described in registry/modules/, one file per
module:

name: robohub-avr
role: platform
path: ../robohub-avr
git: https://github.com/RoboHubPlatform/robohub-avr
summary: The 8-bit AVR platform: the interfaces on an ATmega328P, and the Arduino UNO R3.

The registry says where a module is and what it is for in the ecosystem. The
module's own manifest is the truth about what it is, and the registry does
not repeat it: a registry that repeats what a module already says is a second
copy that drifts.

The role is the ecosystem's own word for what a module is: interfaces for the
contracts, platform for a family of parts, runtime for what a node runs,
collection for a set of things, middleware for what a platform is built
against, and application for what a person runs.

The commands

robohub registry list          # every module
robohub registry show avr      # one module, in full
robohub registry check         # whether the ecosystem is whole
robohub validate               # whether the ecosystem's files match the schemas
robohub lint                   # static analysis, over every module
robohub lint robohub-avr       # over one
robohub test                   # the tests, over every module
robohub test robohub-avr       # over one
robohub test robohub-avr --unit    # only the unit tests
robohub test robohub-avr --smoke   # only the smoke tests
robohub test list robohub-avr     # what tests the module has
robohub test run robohub-avr NAME # one of them, by its name
robohub test enable robohub-avr NAME   # a test is run
robohub test disable robohub-avr NAME  # a test is not run
robohub docs                   # documentation

A module that declares no tests is not a module whose tests failed: it is
reported as having none, because a run over an ecosystem that says some of it
has not been written yet is not a run that is broken.

Every command is a report about the ecosystem and nothing else. Nothing here
changes a module, and nothing here writes to a module's tree: a tool that
changes what it measures is not a tool that measures.

registry check is the one that fails. A registry that names a module that is
not there sends a reader looking for something that does not exist, and a
module that is not named is a module nobody is told about — so the check says
what is missing and does not succeed.

The registry of tests

Every module keeps a registry of its tests: what they are called, which kind
they are, whether they are run, and the command that runs them. The tests
themselves are in folders — the unit tests in one, the smoke tests in another,
and as many more of either as the project finds useful — and each folder keeps a
registry of its own, so that no registry grows past what it can be read as. The
module's own registry says which registries there are.

# tests/registry.yml
name: robohub-avr
registries:
  unit: unit/registry.yml
  smoke: smoke/registry.yml

# tests/unit/registry.yml
tests:
  the platform's own tests:
    state: enabled
    program: "sh"
    arguments: "tests/unit/run.sh"

A test that is not enabled is still a test: it is there, and it is not run. A
run of "all" is the tests that are enabled, and a run of one kind is the tests
of that kind that are enabled.

robohub test add registers a test that has been written — and runs it first.
A registry that holds a test which does not work is a registry that will fail a
run for a reason nobody can see, so a test is added only after it has passed.

The schemas

The shapes the ecosystem's files are written in are in schemas/, one file per
shape and one version per file: board.v1.json, target-spec.v1.json,
registry.v1.json and suite.v1.json. They are JSON Schema, so anything else
can check against them too.

The rules themselves are written in Rho, in src/validate.rho, so that a
program can keep them. The two are the same contract: what a rule says in one is
what a schema says in the other.

The manifests are the toolchain's own business — rho module validate is the
authority on what a manifest may say, and it is what the toolchain reads. What
the orchestrator checks is the ecosystem's own files.

The tools

The tools are the toolchain's own components — rho lint, rho test and
rho doc — run over each module in turn. The orchestrator decides what to
run them over and collects what they said; the components decide how to run and
what their findings mean. A second linter here would be a linter that reports
something else, and a run that says "no findings" from a tool that never ran is
worse than a run that failed.

Each run writes what the tool said to build/reports/<tool>-<module>.txt, so a
report survives the run that produced it.

Running it

The orchestrator is a Rho program, generated as a Go target by the toolchain:

rho build .            # build/generated/go, and build/robohub
./build/robohub registry list

Its tests are run by the toolchain's own runner:

rho test .

What is shared

The material every repository in the ecosystem needs and none of them should
own lives here, in shared/:

A repository takes what it needs from here and says where it came from, rather
than carrying a copy that drifts. The host-test runner is the clearest case:
robohub-devices and robohub-drivers each carried a copy of the same build —
the same compiler, the same warnings, the same include paths, the same generated
namespace — and had already begun to differ. The runner is here now, and what
is left in each repository is the part that is its own: the headers it
publishes and the suites it runs, in tests/host-tests.plan.

The keeper and Mesh

The keeper is the local dashboard for the ecosystem. Its Mesh section plans
and runs gateway deployments: projects, a gateway and its nodes, the
connections between them, and the firmware on their boards. A project is a
folder under ~/.rho/mesh/projects (or ROBOHUB_MESH_PROJECTS); the dashboard
at /mesh lists them with their gateway status, and opening one shows the plan
wizard. The full guide is
the keeper's Mesh guide.

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.