Skip to content
GitHub

HotLoop Edge Relay overview

The Edge Relay is the headless one. It sits on a Pi or a small industrial PC next to the machines, polls them with the same drivers the Gateway uses, and forwards every reading over Sparkplug B to a Gateway somewhere with a real database. When the uplink dies it queues to disk and replays when the link comes back, so the historian upstream ends up with the outage backfilled, not a hole in it, as long as the outage fits the queue, which is capped at 64 MiB by default. No database, no web UI, no users, no write path, and every one of those missing pieces is something that can’t break at 3 AM.

The current release is 4.23.2: ghcr.io/hotloop-io/hotloop-edge-relay:4.23.2 built for amd64, arm64 and arm/v7 (a Pi 3 or a 32-bit Pi OS install is exactly the box a relay ends up on), about 15 MB, pulled with no login, and the hotloop-edge-relay chart from https://hotloop.io/hotloop. 4.16.0 was the first release that published it, and arm/v7 came with 4.18.10. It shares a version number with the Gateway, and a release refuses to go out unless both charts carry the tag’s version and the Quadlet unit follows :stable. So the relay gets a new version every release whether its code changed or not. One version number to ask about, and a relay chart can never point at an image nobody pushed. Install it.

Upgrading a relay? Upgrading from 4.17.0 and upgrading from 4.16.0 have the relay’s part.

Not a smaller Gateway with the options turned off. It’s a different binary. It never links the database, the web UI and its auth, the automation engine, the entity registry, or MCP, and a test asks go list -deps what the binary actually links and fails if any of them sneaks in through a shared package. There’s no relay mode hiding in the Gateway, because a mode is a switch, and a switch can get flipped by one bad environment variable on a box nobody’s watching. A package that was never linked can’t be flipped on.

Not able to take a write, serve a screen, or answer an agent. All three need a signed-in person to pin the action on, and this thing has no users at all. It reads and it forwards, and that’s the whole job.

Not open to configuration from the network. Devices and tags come from one JSON file on the box. The one other way in is a device file pushed from the Gateway over the broker connection the relay already dials out on, and that one applies live. The relay never listens for a new config.

  • Polls with the Gateway’s own engine: the same workers, the same reconnect and back-off, and the same drivers for OPC UA, Modbus, MQTT and Sparkplug B, EtherNet/IP, S7comm, MTConnect, and HTTP. Since 4.18.10 it can also listen to MQTT brokers you name in the device file and read what announces itself there (ESPHome, Zigbee2MQTT, Tasmota, Shelly), and nothing it discovers can be armed, because a relay has no write path at all. Since 4.17.0 it can poll a UniFi console too, read-only: the tags its device file declares, and of the client work only the per-network client counts, with no OT watch. A driver bug fixed in the Gateway is fixed here.
  • Forwards as a Sparkplug B edge node: births, sequence numbers, and deaths the way the spec says. A reconnect announces the node once, not twice.
  • Survives the link dying. Readings queue to a single file on disk. When the broker comes back the queue drains before any live reading goes out, oldest first, each one flagged is_historical so the host upstream doesn’t mistake a replay for the tag’s current value. Delivery is at least once, so whatever consumes it has to tolerate a duplicate after a crash mid-replay. The queue is capped at 64 MiB by default, and past the cap the oldest readings are dropped and counted. That is about 248,000 readings, about two minutes at 2,000 readings a second, so size it from your own rate, about 240 bytes a reading with short tag names (measured on the same queue in Edge 4.21.1). Set it to 0 and it is unbounded, and a long enough outage fills the volume. Install says how to set it.
  • Answers two read-only endpoints on port 8081: /healthz (the process is up) and /status (device counts by connection state, tag count, queue depth, compiled-in protocols, whether the broker is connected, its version, image digest, and update mode, and which device file is running and which was refused). No tag values, no addresses, no config. Both are unauthenticated on purpose: there’s no user database to hang a login on, and one shared token would add no real protection. Keep them behind the same perimeter as the box.
  • Takes orders from a Gateway. Register a relay with the Gateway’s fleet management (API only, there’s no Fleet screen) and the Gateway tracks it from its births and deaths, and can send it a rebirth, a restart, a new device file, or the approval for an update it is holding. A pushed device file applies live, with no restart. A restart is its own command, because it drops the relay’s broker session and every device session it holds, and a box that sits there for months shouldn’t do that to take a config change.

Nothing on the relay decides who may restart it or push it a device file. The Gateway checks at its API: fleet.rebirth for a rebirth, and fleet.restart, fleet.update, and fleet.config for a restart, an update approval, and a push, all admin only. But the commands travel over the broker, so anything that can publish to the relay’s Sparkplug NCMD topic or to hotloop/edge-relay-config/# can do exactly what the Gateway does.

So lock the broker down. Its ACL should let only the Gateway’s own credentials publish NCMD and the config topic. And put TLS on the broker before you push a device file with passwords in it: a push is published retained, and anyone who can subscribe to that topic can read every credential in the file.

Edge Relay has been run end to end against a real Mosquitto broker, with a reading going through the whole binary and arriving at a plain MQTT subscriber as a correctly valued Sparkplug B NDATA. Fleet commands and config push, including a push retained before the relay even started, have been run against a real broker, and the live apply has been run against real Modbus TCP and OPC UA devices: one push adds a device, removes one, changes another, and leaves a fourth alone, with no NDEATH and no dropped session on the one that did not change. A change applied while the broker is cut off and readings are piling up drains the whole queue afterwards.

Updates have been run too: the Quadlet unit’s rollback, and the opt-in hold, with a real update held while the relay ran untouched, then taken on approval. On Podman 4.9 the unit has to say --sdnotify=healthy itself, or a dead update is reported as a success, and it does.

This binary has been run on bare metal (2026-11-17). Its OPC UA, Modbus, EtherNet/IP, and S7comm drivers are the same code the Gateway runs.

Running it at a plant? Using HotLoop in a business covers licensing and how to reach us.

The Edge Relay is under the HotLoop Source License Agreement 1.0, like every HotLoop product. It is free to use and source-available, not OSI open source, and each version converts to AGPL-3.0 or later four years after its release. Home and lab use is free, and so is use by schools, nonprofits and government bodies for their own operations. The License page has the text.