> 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/create-new-device/devices.md).

# Device

What a device is in akenza, how it is identified, and which fields it has.

A **device** represents hardware in the field, such as a sensor, a meter, or a tracker. It sends data to akenza as **uplinks**, and depending on its connectivity it can also receive **downlinks**. Devices belong to a [workspace](/device-management/managing-a-workspace.md) and are managed in the device inventory.

## What a device carries

akenza stores the following information for each device:

<table><thead><tr><th width="220">Group</th><th>What it holds</th></tr></thead><tbody><tr><td><strong>Identity</strong></td><td>The name and description you give it, the physical device ID it sends data with, and the akenza device ID used for API calls.</td></tr><tr><td><strong>Assignment</strong></td><td>The organization and workspace it belongs to.</td></tr><tr><td><strong>Processing</strong></td><td>The <a href="/device-management/your-data-flow.md">data flow</a> assigned to it, which includes the device connector and the device type that decodes its payloads.</td></tr><tr><td><strong>Connectivity</strong></td><td>How it reaches akenza, and for networked connectivity the network parameters and the <a href="/device-management/integrations.md">integration</a> it was provisioned through.</td></tr><tr><td><strong>Your metadata</strong></td><td>The <a href="/device-management/managing-a-workspace/tags.md">tags</a> and <a href="/device-management/managing-a-workspace/custom-fields.md">custom fields</a> you assign.</td></tr><tr><td><strong>State</strong></td><td>Whether it is online, its offline timeout, whether it is registered on the network, and whether it is included in the <a href="/device-management/managing-a-workspace/general-settings/device-lifecycle-reports.md">lifecycle report</a>.</td></tr><tr><td><strong>Last uplink</strong></td><td>The uplink metrics, updated with every message.</td></tr></tbody></table>

{% hint style="info" %}
The [REST API documentation](/reference/api-documentation.md) lists every field of a device. This page explains what they mean.
{% endhint %}

## Identifiers

A device has two identifiers:

* The **device ID** is set when the device is created. It is usually the physical identifier of the device, the DevEUI for LoRaWAN devices, or any suitable identifier for HTTP, MQTT, and CoAP. akenza matches incoming data on it.
* The **akenza device ID** is assigned by akenza and never changes.

You can change the device ID during the lifetime of a device, for example when you replace a sensor. The akenza device ID stays the same, so the device keeps its history, tags, custom fields, and dashboards. All REST API operations use the akenza device ID.

## Fields depend on connectivity

The [device connector](/device-management/your-data-flow/device-connector.md) in the data flow decides which fields a device has:

* **Networked connectivity**, such as [LoRaWAN](/device-management/your-data-flow/device-connector/lorawan.md) or [NB-IoT](/device-management/your-data-flow/device-connector/nb-iot.md), requires the parameters of the network. For LoRaWAN these are the DevEUI, the application EUI and key, the activation mode (OTAA or ABP), the device class, the frequency plan, and the LoRaWAN version. Carriers can require more. An Actility-based network also has a connectivity plan, a device profile, and a motion indicator.
* **IP-based connectivity**, such as [HTTP](/device-management/your-data-flow/device-connector/http.md), [MQTT](/device-management/your-data-flow/device-connector/mqtt.md), and [CoAP](/device-management/your-data-flow/device-connector/coap.md), has no network parameters. The device connects over the internet and authenticates with the secret of its connector.

The last step of the creation wizard asks for these parameters, which is why its content changes with the connector. For a walkthrough of creating a device, see:

{% content-ref url="/pages/-MUICr3a0-fo8AuI\_EKB" %}
[Connect a Device](/how-to-create-a-working-environment/how-to-connect-a-device.md)
{% endcontent-ref %}

## Online state

A device is **online** if its last uplink is newer than its **offline timeout**, which is set when the device is created. akenza only tracks whether a device has sent data, not whether it works correctly.

Set the timeout according to how often the device sends. A sensor that sends every 15 minutes with a timeout of 24 hours can stop sending for almost a day before it shows as offline. A sensor that sends once a day with a timeout of two hours shows as offline every day.

{% hint style="info" %}
Exclude test devices and spares from the [device lifecycle report](/device-management/managing-a-workspace/general-settings/device-lifecycle-reports.md) so that they are not reported as problems.
{% endhint %}

## Data

Devices send data to akenza as uplinks, either at a fixed interval or when an event occurs. Each uplink runs the data processing pipeline defined by its [data flow](/device-management/your-data-flow.md).

Data can be split into **topics** by purpose or schema, which keeps the structure of the data. One data point is a **sample**, identified by the akenza device ID, the topic, and the timestamp.

{% hint style="warning" %}
Historical device data is only available if the data flow contains an **akenzaDB** output connector. Without it, data is processed but not stored.
{% endhint %}

## Uplink metrics

**Uplink metrics** are recorded with every uplink. They describe the transmission rather than its content: the size of the payload, when it arrived, and, if the network reports it, how well it was received.

{% hint style="info" %}
Which metrics are recorded depends on the connectivity and the provider.
{% endhint %}

For HTTP, MQTT, and CoAP, only the size and the time are recorded:

```javascript
{
    "uplinkSize": 478,
    "timestamp": "2021-09-17T07:10:16Z"
}
```

A LoRaWAN uplink also contains radio and network information:

```javascript
{
    "uplinkSize": 246,
    "timestamp": "2026-09-25T14:18:44Z",
    "port": 5,
    "frameCountUp": 46897,
    "frameCountDown": 1048,
    "rssi": -119.0,
    "snr": -5.75,
    "sf": 7,
    "txPower": 2.0,
    "numberOfGateways": 1,
    "esp": -125.77,
    "sqi": 2,
    "signalQuality": "MEDIUM",
    "batteryLevel": 100.0,
    "batteryLevelStatus": "GOOD"
}
```

### Battery level

akenza reads the battery level from the sample after the device type script has run. The sample has to contain either `batteryLevel` or `batteryPercent`.

If several samples in the same uplink contain a battery value, the lowest one is stored. For passthrough data flows, the value is read directly from the uplink payload.

### Signal quality indicator (SQI)

LoRaWAN uplinks usually contain enough information to calculate the **SQI**. It is based on `snr` and `rssi` and rates the signal quality from 1 (weak) to 3 (strong).

akenza also reads it from the sample after the script has run, from `sqi`, `signalQuality`, or `signalQualityIndicator`, in that order. Values have to be between 1 and 3. Decimals are rounded down, and values outside the range are ignored. If several samples in the same uplink contain a value, the lowest one is stored. For passthrough data flows, the value is read directly from the uplink payload.

{% hint style="info" %}
The [device lifecycle report](/device-management/managing-a-workspace/general-settings/device-lifecycle-reports.md) is based on battery level and signal quality, so make sure your device type emits them.
{% endhint %}


---

# 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/create-new-device/devices.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.