RoboHub

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

Deploying the gateway

The gateway is deployed as the registry is — a container image, a systemd unit,
nginx in front — with two differences: it may need a device, and it has a
second port that is not HTTP.

The shared mechanics (Ubuntu, Docker, systemd, nginx, ISPConfig, TLS, firewall)
are in the registry's applications/registry/docs/deployment.md; this page is
what is particular to a gateway.

What is being deployed

A robohub-gateway is one program in four modes (GATEWAY_MODE): node,
edge, relay, master. What changes between them is which links are open, not
which binary is built:

  • A master terminates a tree. It needs no serial device: it listens for the
    gateways below on UPLINK_PORT and serves the API.
  • A gateway with a board wired to it (a node or edge) also needs the
    serial device, passed into the container.
  • PlotJuggler reads the UDP stream (PLOTJUGGLER_ADDR), which is optional
    and off to a collector elsewhere in practice.

Container

The gateway and the Rho toolchain are separate checkouts, so the image is built
from two contexts — this repository, and rho as a second one, found in the
workspace ($RHO_WORKSPACE, or the directory that holds this repository). Nothing
is fetched from a network. The image is built by rho deploy, from the
container target in targets/container.json:

rho deploy -target container -docker -build-only
RH_DEPLOY_DOCKER_IMAGE=<dockerhub-user>/robohub-gateway \
    rho deploy -target container -docker -build-only -push   # and publish it

-n prints the steps and runs nothing.

systemd

sudo install -m 0644 deploy/gateway-docker.service /etc/systemd/system/gateway-docker.service
sudo sed -i 's#^Environment=IMAGE=.*#Environment=IMAGE=<dockerhub-user>/robohub-gateway:latest#' \
  /etc/systemd/system/gateway-docker.service
sudo systemctl daemon-reload
sudo systemctl enable --now gateway-docker
curl -fsS http://127.0.0.1:8080/healthz

The unit reads GATEWAY_MODE, GATEWAY_AREA, REST_PORT, UPLINK_PORT and
PLOTJUGGLER_ADDR from its own environment, so a host changes them by editing
the unit, not the image.

A gateway with a board

Add the device to the run line:

ExecStart=/usr/bin/docker run --rm --name gateway \
    --device /dev/ttyACM0:/dev/ttyACM0 --group-add dialout \
    -e SERIAL_PORT=/dev/ttyACM0 -e SERIAL_BAUD=115200 \
    ...

dialout is the group that owns a serial device on Debian and Ubuntu; without it
the container's user cannot open the port, and the gateway logs "no serial link,
ingest disabled" and serves anyway — a failure that is reported, not fatal.

The two ports

  • REST_PORT (8080) — the HTTP API. Bind it to loopback and put nginx in
    front, as the registry does.
  • UPLINK_PORT (5001) — where the gateways below dial in. It is a raw TCP
    stream carrying RoboHub frames, not HTTP, so nginx's http block does not
    apply: publish the port and open it in the firewall, or front it with an nginx
    stream proxy (the commented block in deploy/nginx.conf).

A relay dials the master, so the master is the side that listens and only its
uplink port must be reachable — and a relay behind NAT still connects up. The
tree is acyclic by construction: each gateway names its parent.

sudo ufw allow 22,80,443/tcp
sudo ufw allow 5001/tcp     # only if the uplink is published directly

Configuration

VariableDefaultMeaning
GATEWAY_MODEmasternode, edge, relay or master
GATEWAY_AREA1the area this gateway speaks for
REST_PORT8080the HTTP API
UPLINK_PORT5001where gateways below dial in; 0 listens on none
PLOTJUGGLER_ADDR127.0.0.1:9870the UDP collector, if any
SERIAL_PORT(unset)the board's device, when there is one
SERIAL_BAUD115200the line speed

There is no secret and no data directory: a gateway holds only what it has heard
since it started, and a reader re-reads it. State is aggregated; nothing is
backed up but the configuration.

Verifying a deployment

curl -fsS https://gw.example.com/healthz
curl -fsS https://gw.example.com/api/v1/diagnostics   # mode, area, children, frames
curl -fsS https://gw.example.com/api/v1/nodes         # the devices heard

children above zero is a gateway below having dialled in and announced. To
check the whole path — a reading up and a command down — the repository's
tools/relay-smoke.py does it on one machine, and against a deployed master it
is the same test pointed at the host: run a relay-host with
RHO_PARENT_HOST/RHO_PARENT_PORT at the master.