Uplink

Uplink decoders are used to decode or "translate" a device-specific payload into a human-readable JSON object (e.g. HEX -> JSON object).

Script Structure

An uplink decoder script has to implement the function consume(object) which takes an event object as argument. An error will be returned if the script doesn't implement a consume(event) function.

function consume(event) {
    emit('sample', { data: {}, topic: 'default' });
}

The consume(event) function is the entry point for the script and will be invoked upon execution. Each execution loads the script again, resetting any variable values which were set in previous runs.

Decoding the Payload

Here you can see a example to decode the payload from hex to a unsigned integer in this case a counter variable. This variable is added to the data payload and emitted to the default topic.

function consume(event) {
    let payload = event.data.payloadHex;
    let bits = Bits.hexToBits(payload);
    data.counter = Bits.bitsToUnsigned(bits.substr(6, 10)) / 4;
    // emit
    emit('sample', { data: {}, topic: 'default' });
}

Uplink Event Object

The uplink event object differs slightly based on connectivity but share the same base structure. Every event contains the following structure:

{
    "data": {
        // the data sent in the uplink request
    },
    "device": {
        // device properties
    },
    "uplinkMetrics": {
        // info about the uplink
    },
    "topic": "default", //topic sent along with the event or "default" if not specified
    "timestamp": "iso-8601-date-string"
}

Example HTTP or MQTT event

The data object contains everything which was sent in the request body of the uplink request.

{
    "data": {
        "temperature": 12.4,
        "humidty": 85,
	...
    },
    "device": {
	"id": "string", // the akenza id
	"deviceId": "string", // the device id
	"name": "string",
        "description": "string"
    },
    "uplinkMetrics": { // meta information about the uplink forwarded by the carrier
        "deviceId": "string", // the device id
        "uplinkSize": 223, // recieved uplink size in bytes
        "timestamp": "iso-8601-date-string" // Either user defined or defaults to time when the uplink was received at akenza
    },
    "topic": "events",
    "timestamp": "iso-8601-date-string" // Either user defined or defaults to time when the uplink was received at akenza
}

Example LoRaWAN event

The contents of the uplinkMetrics object differs depending on the network provider.

{
    "data": {
        "port": 2, // the port specified in the LoRaWAN uplink
        "payloadHex": "aabbcc112233" // the hex string sent by the device 
    },
    "device": {
        "id": "string", // the akenza id
        "deviceId": "string", // the device id
        "name": "string",
        "description": "string"
    },
    "uplinkMetrics": { // meta information about the uplink forwarded by the network provider
        "deviceId": "string", // the device id
        "uplinkSize": 223, // recieved uplink size in bytes
        "timestamp": "iso-8601-date-string", // time when the uplink was registered on the gateway
        "latitude": 46.928403,
        "longitude": 7.628662,
        "port": 2,
        "frameCountUp": 14,
        "frameCountDown": 1,
        "rssi": -88.0,
        "snr": 7.75,
        "sf": 7,
        "txPower": 8.0,
        "numberOfGateways": 2,
        "esp": -88.67,
        "sqi": 3
    },
    "timestamp": "iso-8601-date-string" // time when the uplink was registered on the gateway
}

Example Array Uplink event

When processing an array uplink, the structure is slighly different to other events. The data object contains a single property values which contains the original array sent in the uplink.

{
    "data": {
	"values": [{
            "temperature": 12.4,
	    "humidty": 85,
            ...
	},
	...
	]
    },
    "device": {
	...
    },
    "uplinkMetrics": { // meta information about the uplink forwarded by the carrier
    ...
    }
}

Event examples

LoRaWAN Device uplink event

A raw LoRaWAN uplink that invokes an uplink decoder script (Custom Device Type), looks as follows:

{
  "data": {
    "port": 2,
    "customAttributes": null,
    "payloadHex": "810dac6c000000b010"
  },
  "uplinkMetrics": {
    "id": "8888888888888888",
    "uplinkId": "88888888-8888-8888-8888-888888888888",
    "deviceId": "0000000000000fff",
    "uplinkSize": 364,
    "timestamp": "2025-10-23T12:43:46.083Z",
    "port": 2,
    "frameCountUp": 4325,
    "frameCountDown": 115,
    "rssi": -114,
    "snr": -6,
    "sf": 7,
    "txPower": 16,
    "numberOfGateways": 1,
    "esp": -120.97,
    "sqi": 3
  },
  "topic": "default",
  "device": {
    "customFields": {
      "FloorNumber": 1,
      "SiteId": "AK_OFFICE",
      "SpaceId": "1OGR20"
    },
    "name": "Vicky",
    "description": "Balcony door",
    "id": "0000000000000fff",
    "deviceId": "1122334455667788"
  },
  "timestamp": "2025-10-23T12:43:46.083Z"
}

MQTT Device uplink event

A raw MQTT uplink that invokes an uplink decoder script (Custom Device Type), looks as follows:

{
 "data": {
  "value": 12.332
 },
 "uplinkMetrics": {
    "id": "8888888888888888",
    "uplinkId": "88888888-8888-8888-8888-888888888888",
    "deviceId": "0000000000000fff",
    "uplinkSize": 15,
    "timestamp": "2025-10-23T12:43:46.083Z"
 },
 "topic": "default",
 "state": {},
 "device": {
    "customFields": {
     "SiteId": "AK_OFFICE",
    },
    "name": "Meter",
    "description": "",
    "id": "0200000000000000",
    "deviceId": "42:D4:FF:0B:81:2E"
 },
 "timestamp": "2025-10-23T12:43:46.083Z"
}