> For the complete documentation index, see [llms.txt](https://docs.akenza.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akenza.io/device-management/your-data-flow/device-type/device-type/uplink.md).

# 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.

```javascript
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.

```javascript
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:

```typescript
{
    "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.

```typescript
{
    "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.

```typescript
{
    "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.

```typescript
{
    "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:

{% code overflow="wrap" %}

```json
{
  "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"
}
```

{% endcode %}

### MQTT Device uplink event

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

{% code overflow="wrap" %}

```json
{
 "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"
}
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akenza.io/device-management/your-data-flow/device-type/device-type/uplink.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
