Skip to main content
Status: Draft spec. This page records the agreed architecture for the Fieldline LoRaWAN integration. It is not yet implemented — the ingestion endpoint described below does not exist and will return an error. Do not build against it until this page’s status changes to Full setup.
This page replaces the earlier ChirpStack integration draft, which was never built.

​
What Fieldline is

Fieldline is an aggregation layer that sits in front of a LoRaWAN network server and collects readings from LoRaWAN sensors deployed across an organization’s buildings. Rather than each sensor being registered in Data Hub by hand, Fieldline registers once per organization and every sensor behind it then appears in Data Hub on its own as a distinct device. Fieldline is its own integration type in Data Hub — not a variant of the generic CSV source. Devices arriving this way are identifiable as LoRaWAN sensors rather than being grouped with generic file uploads.

​
Why it isn’t the CSV source

The generic CSV endpoint assumes one token per data source, issued by the Data Hub team on request. That model doesn’t hold up for a LoRaWAN fleet: every new sensor would mean requesting another token, storing it, and maintaining a sensor-to-token mapping. Workable for a handful of test devices, unworkable across many buildings and hundreds of sensors.

​
The two-token model

The org-token is what lets Data Hub associate incoming devices with the correct organization automatically. Assigning an organization by hand was the only reason earlier device-based sources required you to send a serial number to the Data Hub team before data would flow — the org-token retires that step.
Treat the org-token as a credential. It scopes device creation for your whole organization, so anyone holding it can register devices against you. Do not commit it to source control or send it in plain text. Contact the Data Hub team to rotate it if you suspect exposure.

​
Automatic device registration

Data Hub creates a device the first time it sees data for it. The flow is:
1

A sensor is provisioned in Fieldline

Fieldline generates a device-token for the sensor and stores it permanently against the sensor’s DevEUI.
2

Fieldline pushes the sensor's first reading

The push carries the organization’s org-token and the sensor’s new device-token.
3

Data Hub creates the device

A device-token not seen before, under a valid org-token, causes Data Hub to create a new device in that organization and begin recording against it.
4

The device appears in the interface

It shows up under Data Hub → Data Sources with no manual setup on either side.
Each sensor remains a separate device with its own identity, history, and configuration. Two sensors of the same model in different locations stay distinct — they are never merged into a single combined dataset.

​
Device-token format

Device-tokens are generated by Fieldline and must follow this scheme:
Device-tokens must be stable. Persist each token against the sensor’s DevEUI and never regenerate it. If a token changes — on restart, redeploy, or reprovisioning — Data Hub treats it as a new sensor, creates a second device, and the sensor’s history splits across the two.

​
Upload endpoint

Not yet implemented. This endpoint is the agreed target shape but has not been built. It will be added once the design is finalised with the Fieldline team, at which point this note will be removed.
Send measurements by POST, with both tokens as headers:
One request carries readings for a single sensor. Malformed device-tokens are rejected at ingest rather than silently creating a device.
The authentication model for this endpoint is still being finalised and may change before implementation. The header names and payload shape above should be treated as provisional.

​
Sensor metadata

Measurements are pushed from Fieldline to Data Hub. Sensor metadata is pulled by Data Hub from an endpoint on the Fieldline side, queried per device-token. This is necessary because what a sensor measures and in what units cannot be inferred from readings alone. The metadata Data Hub expects for each sensor:
The exact schema for this endpoint has not been agreed yet. It will be documented here once Fieldline proposes it and Data Hub has reviewed it.

​
Configuring variables in Data Hub

Once a device has registered itself, its variables are configured the same way as any other data source:
1

Locate the device

Go to Data Hub → Data Sources and find the Fieldline device for the sensor.
2

Open it

Click through to see every variable the sensor reports.
3

Configure each variable

Click Configure, then Edit to set the display name, resource type, and units. Click Finish Editing to save.
4

Choose what to collect

Toggle Add To Data Hub on each variable you want recorded and visible on the Variables page. Variables left off are not collected.
Per-variable collection is controlled entirely on the Data Hub side. Fieldline exposes everything a sensor reports; Data Hub decides what to keep.

​
Limits

This cap is a guard against runaway device creation from a fault on either side, not a licensing limit. Contact the Data Hub team if your deployment needs more headroom.

​
Open items

These are unresolved and will be settled before implementation:
The field list above describes what Data Hub needs. The concrete request and response shape is still to be proposed by Fieldline.
The current design uses the org-token to scope incoming devices to an organization. Whether the endpoint additionally authenticates, and how, is still being decided.
If a device is deleted in Data Hub and Fieldline pushes to the same device-token again, it is not yet decided whether the device is recreated or the push is rejected.
How historical readings accumulated before the integration goes live are re-uploaded, and over what window, has not been specified.