1. Version history

2. What is a payload description?

A payload description in LoRaWAN is a documented specification that describes how the payload of a LoRaWAN device is structured. It specifies what information is contained in the data packets, how it is encoded, and how it can be decoded.

2.1 Contents of a payload description

Field structure:
The payload description specifies how the data fields are organized within the payload.
Each field represents a specific piece of information, such as temperature, humidity, GPS coordinates, or battery level.

Example:
Byte 0-1: Temperature (in 1/100 °C, big-endian)
Byte 2: Humidity (in %, integer)
Byte 3: Battery level (in 0.1 V)

Data encoding:
Information is often stored in binary or hexadecimal format to save space.
It is specified whether the data is big-endian or little-endian (byte order).
The units of the values are specified (e.g., °C, %, volts).

Data format:
Specifies whether the data is encoded as an integer, float, string, or another type.
Some devices use scaled values that must be adjusted by multiplication or division (e.g., battery level in 0.1 V instead of directly in volts).

Optional fields:
Some payloads contain optional fields that are only sent under certain conditions. The description specifies when and how these fields appear.

Sample data:
A payload description often includes examples of an encoded data packet as well as the corresponding decoded values.

Example of a binary payload:

Hexadecimal: 0x07D0123A
- Bytes 0–1 (0x07D0): Temperature = 2000 / 100 = 20.00 °C
- Byte 2 (0x12): Humidity = 18%
- Byte 3 (0x3A): Battery level = 58 / 10 = 5.8 V

2.2 Why is a payload description important?

Decoder creation: Developers use the description to write payload decoders that automatically interpret the raw data.
Interoperability: When multiple systems or platforms communicate with the same device, the payload description helps ensure that the data is interpreted correctly.
Troubleshooting: The description is essential for diagnosing problems when the data does not look as expected.

2.3 Typical documentation

The payload description is usually provided by the manufacturer of the LoRaWAN device. It may be included in a user manual, a technical specification, or as a separate document.

An example of documentation:
Device: LoRa Sensor XY123
Payload Structure:
  Byte 0-1: Temperature (°C * 100)
  Byte 2: Humidity (%)
  Byte 3: Battery level (V * 10)

3. Payload description Sentinum

This chapter describes the structure of the telemetry data. The number of bytes in the payload depends on the sensor configuration. The data structure depends on which sensors are present in your product.

In principle, every version has a header. This header contains information about the version and status of the sensor and also includes a master reading. This reading can simply be assumed to be the current reading.

The header is followed by an additional payload section that contains further information, such as specific parameters for the measurement principle or settings for position and opening detection. Not every sensor has an additional payload section.

3.1 Payload example

The following payload example is provided for the Helios pressure sensor:

11 11 FE 1A D5 95 06 03 00 23 BE

The module key is required for the downlink.

3.2 Structure of the module key

The module key of the SENTIFACE module can be extracted from the first 2 bytes of each uplink.

3.3 Uplink example

4. Ports

5. What is a payload decoder

A LoRaWAN payload decoder is a piece of software or code used to decode and interpret the raw data transmitted by a LoRaWAN device into a comprehensible and useful format.

Background:
LoRaWAN devices typically transmit data in compressed and binary form to save bandwidth and energy. The transmitted payloads often contain raw data that must be decoded to extract measured values (e.g., temperature, humidity, GPS coordinates).

How a payload decoder works:

Input data: A gateway receives the LoRaWAN data packets and forwards them to a network server (e.g., TTN).
Decoder logic: The decoder interprets the bytes according to the payload description (unpacking, scaling, unit conversion, etc.).
Output data: The decoder returns readable structured data, often as JSON.

Example (decoded JSON):

{
  "temperature": 22.5,
  "humidity": 60,
  "battery": 3.7
}

Example of a payload decoder (JavaScript):

function decodeUplink(input) {
  const bytes = input.bytes;
  return {
    data: {
      temperature: ((bytes[0] << 8) | bytes[1]) / 100,
      humidity: bytes[2],
      battery: bytes[3] / 10
    }
  };
}

6. Which payload decoders does Sentinum provide?

Sentinum provides payload decoders for LoRaWAN in .js for TTN and for ChirpStack.