Custom Device Types

This page describes the principle and functionality of Custom Device Types

Introduction

Akenza supports two types of Device Types which extract, transform and normalize the data sent from and to the device, there are Library and Custom Device Types.

This webinar explains how to create Custom Device Types (CDT).

Webinar about how to create a custom device type

The purpose of Custom Device Types is to provide users with the possibility to write their own encoders and decoders for a specific device payload. This kind of device type is available on the organization level. Custom Device Types are managed on the Organization level and are available in all Workspaces within this Organization.

Custom device type

In this form besides generic (name, description...) fields, the user is able to provide an Uplink Decoder script that decodes the code sent from a device and a Downlink Encoder script that encodes data sent to the device. These scripts have to be written in JavaScript language and demand that the user is somewhat knowledgeable in the technical field. Besides generic fields and the scripts, the user is able to provide some additional advanced fields like the type of Connectivity, Author, Manufacturer, Sensor Urls, Available Sensors, etc. and thus setting a more specific definition of a CDT.

To make the data available to the platform, Topics and Data Keys are used. A Topic is used to group Data Keys together. A Data Key is like a variable, but contains additional metadata and functionality. A Data Key can have units, for example cm and a type, for example number. They also have a field for a description, can be required and so on. Data Keys and Topics are defined in the schema definition of a Device Type. The name of the Data Keys and Topics used in the script has to match the names in the uplink or downlink schema definition. Adding these definitions is done in the Akenza platform, after creating a Device Type.

Scripting

Data Decoding

A Custom Device Type is used to decode data sent by devices and turn it into an actionable and human readable format (uplink decoder) or encode data that is used to send commands to devices (downlink encoder).

Uplink decoders are detailed here:

Uplink

Downlink encoders are detailed here:

Downlink

The data format of a device is defined by its device type (uplink decoder and downlink encoder). Once a device sends a data point the uplink decoder script of the device type will decode the raw data into a structured JSON format. Device types can either be created by akenza users (custom device type) or an akenza predefined device type can be used (akenza device type library). Alternatively, it is possible to synchronize a custom device type library, which will be available to all users of the akenza deployment (only available for enterprise customers).

Topics

In order to store multiple different message formats on a device, each data point is assigned to a topic (e.g. lifecycle information, configuration and measurements), which can then be used at query-time to retrieve data for a specific schema/purpose. It is advised to use one topic per payload type (i.e. always output data with the same structure to the same topic and try to prevent mixing data structures within the same topic). Generally, it is advised to use different topics for data that is not sent in the same message.

Data Schema

Each device type defines a data schema per topic. The data schema definition is defined in JSON schema. The schema definition is used throughout the akenza appliction to display and control data. Data types, the value range and units are managed by the data schema and do not have to be stored for every data point. A set of default measurement types is defined in data-models, that can be used and extended throughout JSON schemas.

A set of device types can be found here:

https://github.com/akenza-io/device-type-library