# Device

Devices (a "thing") represent deployed hardware in the field capable of connecting to the internet via a supported **Connectivity**. Devices send data via **Uplinks** and optionally receive commands via **Downlinks**. Devices can be managed in the Asset inventory.

### Identifiers

Devices are uniquely identified by both the device id, which can be set during device creation and the akenza device ID which is generated by the system. 

Usually, the device ID maps to the physical ID of the device (for LoRaWAN devices the devEUI, for HTTP and MQTT devices any suitable identifier). The device ID can be changed during the lifetime of a device (e.g. when a sensor is replaced), whereas the akenza device ID remains the same.

Data is sent using the device ID and all REST API operations require the akenza device id. 

### Configuration

A device has different fields based on the assigned data flow (i.e. LoRaWAN connectivity parameters). 

### Data

Devices send data to the cloud using uplinks. Usually, devices send data either interval or event-based. Uplinks trigger the data processing pipeline specified by a data flow.

Data can be partitioned into **Topics** based on its purpose or schema. This helps to retain the structure of the data.

One data point is referred to as a **Sample,** it is uniquely identifiable by the akenza device id, topic and timestamp.

It is only possible to access historical device data when an akenzaDB output connector is used.

### Custom Fields

It is possible to assign custom fields to a device which can be used to store additional metadata. 

### Uplink Metrics

Uplink metrics are recorded and updated each time a device sends an uplink. They contain information about the payload size, signal strength, spreading factor and more.

{% hint style="info" %}
Different metrics are recorded depending on connectivity and provider
{% endhint %}

#### Example HTTP, MQTT, CoAP Uplink Metrics

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

#### Example LoRa Uplink Metrics

```javascript
{
    "uplinkSize": 301,
    "timestamp": "2021-09-17T07:01:17Z",
    "port": 85,
    "frameCountUp": 113,
    "frameCountDown": 115,
    "rssi": -95,
    "snr": 1.25,
    "sf": 7,
    "txPower": 2,
    "numberOfGateways": 1,
    "esp": -97.43,
    "sqi": 3,
    "batteryLevel": 80.3
}
```

#### Battery Level

The battery level is extracted from the sample once the script has been processed. The sample has to contain either the property `batteryLevel` or `batteryPercent` in order for the uplink metric to be set.

If multiple samples, containing one of the battery level properties, are emitted in the same uplink, the lowest value will be stored.

For passthrough data flows the battery level is directly extracted from the uplink payload, if it contains the above mentioned properties.

#### Signal Quality Indicator (SQI)

LoRa uplinks usually provide the necessary information to calculate the SQI. It is calculated based on `snr` (signal to noise ratio) and `rssi` (receive signal strength indicator) and indicates the signal quality on a scale of 1 (weak signal) to 3 (strong signal).

The Signal Quality Indicator is also extraced from the sample once the script has been processed. The sample has to contain one of the following properties: `sqi`, `signalQuality` or `signalQualityIndicator`. If more than one of these properties are specified, the above order will take precedence. The  values must range from 1 to 3, floating numbers will be rounded down. If the values are outside of this range, the value will be ignored.

If multiple samples, containing one of the SQI properties, are emitted in the same uplink, the lowest value will be stored.

For passthrough data flows the signal quality indicator is directly extracted from the uplink payload, if it contains the above mentioned properties.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akenza.io/akenza.io/get-started/create-new-device/devices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.