> ## Documentation Index
> Fetch the complete documentation index at: https://docs.communityhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Fieldline (LoRaWAN)
> Draft spec for the Fieldline LoRaWAN integration — a single organization-level registration under which every physical sensor appears in Data Hub automatically as its own device.
**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](/guides/sources/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.
| | Generic CSV | Fieldline |
| ----------------------------- | ------------------------------- | ------------------------------- |
| Credential per sensor | Yes — one token per data source | No — one token per organization |
| Who issues sensor identifiers | Data Hub team, on request | Fieldline, at provisioning time |
| New sensor setup | Manual, on both sides | Automatic on first data push |
| Appears in Data Hub as | Generic CSV source | Fieldline (LoRaWAN) device |
## The two-token model
| | Org-token | Device-token |
| ---------- | ------------------------------------ | ----------------------------------------------- |
| Issued by | Community Hub, once per organization | Fieldline, one per physical sensor |
| Identifies | The organization the data belongs to | A single sensor |
| Lifecycle | Long-lived; rotated on request | Permanent, bound to the sensor for its lifetime |
| Sent as | Request header on every push | Request header on every push |
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:
Fieldline generates a device-token for the sensor and stores it permanently against the sensor's DevEUI.
The push carries the organization's org-token and the sensor's new device-token.
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.
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:
| Rule | Value |
| ------------- | ----------------------------------------------------------- |
| Length | 30 characters |
| Character set | `0-9`, `a-z`, `A-Z` only — no spaces, no special characters |
| Case | Case-sensitive |
| Uniqueness | Unique within the organization |
**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.
```text theme={null}
https://.communityhub.cloud/api/data-hub/upload/fieldline
```
Send measurements by `POST`, with both tokens as headers:
```text theme={null}
org-token:
device-token:
```
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:
| Field | Purpose |
| ------------------ | ----------------------------------------------------- |
| Sensor identity | Stable identifier and human-readable name |
| Location | Building or site the sensor is installed in |
| Measurements | Each variable the sensor exposes |
| Units | Unit for each measurement, as reported |
| Variable type | Totalizer, instantaneous measurement, or average rate |
| Operational status | Battery level, last-seen, and other health fields |
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:
Go to **Data Hub → Data Sources** and find the Fieldline device for the sensor.
Click through to see every variable the sensor reports.
Click **Configure**, then **Edit** to set the display name, resource type, and units. Click **Finish Editing** to save.
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
| Limit | Value |
| ------------------------ | ----- |
| Devices per organization | 500 |
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.