A LoRaWAN sensor sends a few bytes, for example 01 0A 2B 64. A codec knows what those bytes mean for that sensor and turns them into named values such as temperature: 26.1 and humidity: 50. Hermetry decodes every uplink with a codec before it reaches your flows.
The four choices
| Choice | Shown as | What happens |
|---|---|---|
| Automatic | Automatic (by maker and port) | Hermetry picks the codec that claims the device’s maker and the frame’s FPort. Your own codecs are preferred over the library’s. |
| None | None (raw payload to the flows) | No decoding. The payload arrives as hex under the key raw. Decode it yourself in a flow. |
| A library codec | Its name | One of the 106 codecs that come with Hermetry. See The codec library. |
| Your own codec | Its name, marked Yours | A codec you published, id t.<name>. See Write your own codec. |
Which codec a device uses
Both the device and its profile have a codec setting. The effective codec is found in this order:
- The device’s own choice, unless it is Automatic.
- Otherwise the profile’s codec, unless it is Automatic.
- Otherwise the automatic choice.
Set the codec on the profile when all its devices are the same sensor; set it on a device only for exceptions.
How the automatic choice works
The first three bytes of a DevEUI identify the device’s maker (its OUI). Each codec lists the makers (OUI) and FPorts it handles. The automatic choice takes the first codec whose maker list holds the device’s OUI and whose FPort list includes the frame’s FPort (a codec without an FPort list takes every port). Your own codecs are tried first, then the library.
If no codec claims the device, nothing is decoded and the payload arrives as raw, as with None.
What a decoded message looks like
An uplink decoded by a codec becomes a device message like this:
{
"temperature": 26.1,
"humidity": 50,
"battery": 3012,
"lora.rssi": -97,
"lora.snr": 7.5,
"lora.gw_count": 2,
"lora.dr": 5,
"lora.freq": 868100000,
"lora.fcnt_up": 1342
}The lora.* keys are added when the profile’s Add the radio values is on. Nested values are flattened with dots (probe.temperature), at most 4 levels deep and 64 keys per message. A codec value named lora.… is renamed dev.lora.… so it never collides with the network server’s keys. Units the codec declares travel with the message’s metadata.
When decoding fails
An uplink never fails because of a codec:
| Situation | Result |
|---|---|
| No codec claims the device | The payload arrives as raw (hex). |
| The codec does not recognise this frame | The payload arrives as raw. |
| The codec decoded part of it and reported errors | The decoded values and raw both arrive. |
| The chosen codec was withdrawn or deleted | The device falls back to the automatic choice. |
raw holds up to 4,096 bytes of payload as hex.
Choose a codec
- For a profile: the profile’s LoRaWAN tab, Codec, then Save.
- For a device: the device’s LoRaWAN tab, Codec, then Save.
- When adding through the API:
codecId(auto,none, a library id, or yourt.id).
Hermetry checks the choice when you save. A codec that does not exist or was withdrawn is refused: This codec does not exist or was withdrawn. Choose another codec, or Automatic. (codec_choice_unknown).
Where decoded values go
Decoded keys enter your flows like any device telemetry. They are stored only where a flow saves them; the default root flow stores every key. Codec output keys are often named the way the device maker names them. To rename or convert them, see Cleaning up decoded values.
Find the codecs
Open Devices, then the ⋯ menu, then LoRaWAN codecs. The drawer lists library codecs and yours, and lets you test any codec with a payload. You need the permission to view LoRaWAN codecs.