Gateway & Relay Architectures
How to attribute telemetry to the originating device in gateway and relay architectures where messages are forwarded on behalf of other devices.
In a direct-connection setup, the device that transmits a message to Spotflow is also the device that generated the message. In gateway and relay architectures, however, one device connects to the platform on behalf of others, forwarding their telemetry without those devices having a direct internet connection.
The Source Device ID and Transport Route fields allow you to preserve the identity of the originating device throughout the forwarding chain, so that logs, metrics, and crash reports are correctly attributed in Spotflow regardless of how they were delivered.
Source Device ID
The sourceDeviceId field identifies the original device that generated a message. It is included in the message payload by the forwarding device.
| Value | Meaning |
|---|---|
| Not specified | The connected device is the source, no forwarding is taking place. |
| A string | A single source device whose message is being forwarded by the connected device. |
| An array of strings | A multi-hop chain, each element is a device in the forwarding path, ordered from source to the device just before the connected one. |
Constraints:
- Maximum of 4 components in the route (including the connected device).
- Each device ID must be alphanumeric and may contain hyphens and underscores, up to 128 characters.
- Empty strings and whitespace-only values are rejected.
Transport Route
The transport route is the complete path a message took from its origin to the platform. Spotflow computes it automatically by appending the connected device's ID to the sourceDeviceId array.
sourceDeviceId in message | Connected device | Resolved transport route | Attributed device ID |
|---|---|---|---|
| (absent) | gateway-01 | ["gateway-01"] | gateway-01 |
"sensor-01" | gateway-01 | ["sensor-01", "gateway-01"] | sensor-01 |
["sensor-01", "relay-01"] | gateway-01 | ["sensor-01", "relay-01", "gateway-01"] | sensor-01 |
The attributed device ID, used for querying and display in Spotflow, is always the first element of the transport route: the original source device.
All devices appearing in the transport route are automatically registered in your Spotflow workspace. You do not need to provision gateway or relay devices separately.
Use Cases
Gateway Architecture
The most common pattern: resource-constrained devices (sensors, actuators) communicate over a short-range protocol such as BLE or Zigbee and rely on a gateway to forward their telemetry to Spotflow over the internet.
The gateway connects to Spotflow and publishes messages on behalf of each sensor, setting sourceDeviceId to the originating sensor's ID. Spotflow attributes the data to the sensor, not the gateway.
Multi-Hop Relay
For topologies with intermediate relay nodes between the source device and the internet-connected gateway:
The gateway publishes the message with sourceDeviceId: ["sensor-01", "relay-01"]. Spotflow appends the gateway's ID to produce the full transport route ["sensor-01", "relay-01", "gateway-01"] and attributes the data to sensor-01.
Protocol
The sourceDeviceId field is supported in log, metric, and crash report messages. Pass a string for a single forwarding hop, or an array of strings for a multi-hop route:
{
"body": "Temperature reading: 23.5C",
"sourceDeviceId": "sensor-01"
}{
"body": "Temperature reading: 23.5C",
"sourceDeviceId": ["sensor-01", "relay-01"]
}For the full protocol reference for each signal type, including both JSON and CBOR formats, see:
Learn more
Fundamentals: Device Authorization
Fundamentals: Logging
Fundamentals: Metrics
Fundamentals: Crash reports & core dumps
How is this guide?