RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

The gateway interface: an application asks for a mesh's projects, sources, readings and live stream, and the provider it binds answers.

robohub-gateway

The gateway interface. An application asks for a mesh's projects, sources,
readings and live stream, and switches its outputs; the provider it binds
answers. A gateway is one place, so the first enabled provider bound is the one
asked. The provider today is robohub-provider-mesh, and the simulator module
answers the same calls when an application runs without devices.

deps:
  robohub:
    robohub-gateway: ">=1.2.0"
    robohub-provider-mesh: ">=0.5.0"
    simulator: ">=0.1.0"
bind:
  robohub.gateway:
    providers: [robohub-provider-mesh, simulator]
    config:
      robohub-provider-mesh:
        project: "default"
        transport: auto
      simulator:
        enabled: "false"

This is a different module from the gateway firmware and server
(robohub-gateway/index): the interface is what an application calls, and
the Mesh provider reaches the gateway through Mesh, never directly.

Choosing the provider

The provider that answers is the first bound one whose enabled setting is not
"false". choose(name) makes one bound provider the one that answers by
writing enabled for every bound provider into the application's bind.conf
(<provider>.<key>=value lines in its workspace, which win over the bind:
values), so the choice survives a restart and needs no rebuild. The gateway tab
of appshell's settings page is that choice, with the Mesh provider's project
and transport beside it (see appshell/index).

An application rarely calls the gateway for a device by name: the inventory binds
an item's capabilities to the gateway's sources, and the rules, the dashboard
and the pages name the item (heater.switch).

What an application calls

FunctionWhat it does
provider(), providers()the provider that answers; every bound one, one per line
choose(name)makes one bound provider the one that answers
config(key), configure(key, value)the gateway's settings — its url, its project
provider_config(name, key), configure_provider(name, key, value)one provider's settings, answering or not
token()the answering provider's token setting, if one is configured. The Mesh provider stores none: each of its requests carries a short-lived service token scoped to the project
sources()the project's inputs and outputs, by stable id
source_latest(source), source_state(source)the newest reading of a source; the state behind it
source_history(source, from_ms, to_ms, step_ms)readings over a range, Unix milliseconds as text; an empty step is raw readings
action(source, state)switches an output on or off; answers whether the gateway did it
nodes()the project's tree — the gateway, every board, module and device — as a JSON array
device_states()id:state lines, for switch synchronisation
follow(path), transport()follows the live stream into a file; how it does: bus, http or none
projects(), gateway(), register_client(...), client_heartbeat(id), publish(project, topic, payload), telemetry_status()the rest of what a provider answers, for the keeper and Mesh's own pages

What a provider implements

Every function in interface: functions: of module.yml, with those
signatures. The calls are generated from the application's binding.

Release history

All notable changes to the gateway contract are recorded here, one section per release.

[0.2.0] - 2026-11-12

The sim provider is retired. No application could reach it: energy's simulation reaches widgets through Mesh, which serves every reading, and the simulated endpoints the provider called were never served. The contract now compiles in the mesh provider only.

[0.2.1] - 2026-11-12

The contract declares rho-log, which the mesh provider it includes imports, and calls the language's string functions.

[1.0.0] - 2026-11-12

The gateway contract is the gateway interface, robohub-gateway (import robohub.gateway), and its manager is gone. An application declares the interface and the provider it uses, binds the provider in its module.yml with Mesh's address and the project, and calls gateway.sources(), gateway.source_latest(...) and the rest; the first enabled provider bound answers. gateway.config and gateway.configure read and change the provider's settings on a running installation. The plugins: block and the gateway.conf file are no longer read, and the mesh-gateway plugin is removed.

[1.1.0] - 2026-11-13

action(source, state) switches an output source through the provider, so an application never stores or calls an action URL. transport() says how the provider delivers the live stream follow writes: bus when the installation has a broker and the provider is set to use it, http for the provider's own stream, none when it is not configured. register_client and client_heartbeat stay for this release, but an application no longer needs them: the keeper registers its clients, and the stream reaches it either way.

providers(), choose(name), provider_config(name, key) and configure_provider(name, key, value) let a settings page list the bound providers, make one of them the one that answers (Mesh or the simulator), and change a provider's settings whether or not it is the one answering.

[1.2.0] - 2026-11-13

nodes() is the project's tree — the gateway and every board, module and device under it, with their parents, what each is and its state — so an application can draw the mesh. The Mesh provider reads Mesh's /nodes; the simulator answers from its presets.