Devices & profiles

A device is one physical thing

You create a device once, whatever networks it speaks on. A meter with both a Sigfox module and a LoRaWAN module is one device with two technology bindings — not two devices that happen to share a name.

That matters because everything downstream keys off the device: which profile decodes it, which readings belong together, which history is whose.

Technology bindings

Each binding holds the identity that one network knows the device by.

The identifier is how an arriving message is matched back to your device, so it must match the network's own records exactly. A typo does not error — the message simply arrives unmatched, and cannot be decoded.

Bindings also hold secrets — encryption keys, AppKeys. These are encrypted at rest and never shown again after you save them. When you edit a binding, leaving a secret field blank keeps the stored value; you only type it again to replace it.

Profiles are the model, not the unit

A device profile describes a kind of device — vendor, model, and what its data looks like. Your two thousand identical water meters share one profile.

A profile carries:

• Model fields — keys every unit of this model needs, whatever radio it uses.
• Technologies — the radios this model speaks, each with its own decoder, its own settings and its own required keys.

So a profile can say "this meter exists in a Sigfox variant and a LoRaWAN variant, and here is how to decode each", while the fields common to both are declared once.

Field schema

Each profile defines which keys a device on it must fill and which are optional — and whether a key is a plain attribute or an encrypted secret.

This is what makes device creation checkable. Save a Sigfox device without its PAC and you get an error naming the exact field, rather than a device that silently never decodes.

Every field is editable, including built-in ones. Renaming a built-in keeps its meaning: the Center remembers that a renamed field is still "the PAC", so provisioning and decoding keep working.

Decoders

A decoder turns payload bytes into named readings. It belongs to a profile's technology, so every device on that profile decodes the same way.

Three kinds:

• None — the payload is forwarded as it arrived.
• Grammar — a declarative field description. No code, and the usual choice.
• JavaScript — for payloads a grammar cannot express.

JavaScript decoders run in a sandbox with no network and no filesystem, and with memory and time limits. A decoder that loops forever fails that one message instead of stalling the pipeline.

See Decode the payload for writing one.

Telemetry and meta

A decoder returns two groups, and they stay separate all the way to your sink:

• telemetry — the readings: index, unit, battery
• meta — everything about the transmission: seqNumber, rssi

They are not merged, on purpose. If a decoder put seqNumber in both, merging would silently drop one, and nothing downstream could tell a reading from a piece of radio metadata.

Next