NEW
Blog Webinars Get Support
Device Metadata

Device Metadata

What is metadata

As described on the Terms and Concepts page, device metadata (also known as endpoint metadata) are key-value attributes associated with a device (that’s why it’s called device metadata). It can be the device’s location, description, serial number, hardware version, etc.

Metadata can be set by the device itself or by a user from UI.

Device metadata is represented as a JSON in the Kaa Platform. Metadata has a key and a value. A key must be a JSON string. A value can be a JSON string, number, boolean, null, JSON object, or JSON array.

Metadata example:

{
  "connected": true,
  "name": "Smart meter 1",
  "model": "Qubino Smart Meter 3-Phase",
  "latitude": 51.5025671,
  "longitude": -0.0395317,
  "address": {
    "city": "London",
    "street": "Dock Hill Ave, Rotherhithe"
  }
}

What you can do with metadata using Kaa

Kaa provides you with the following features regarding device metadata:

  • Update metadata using Device MQTT or HTTP APIs
  • Read metadata using Device MQTT or HTTP APIs
  • Display metadata on UI
  • Create a filter that will dynamically group devices based on their common attributes
  • Process metadata with Rule Engine
  • Configure alerts on metadata values
  • Manage metadata using REST API

Update metadata using Device MQTT or HTTP APIs

Managing metadata from a device is useful when you want your devices to report some descriptive information about themselves: such as serial number, MAC address, installed software version, location, and so on. You can further use these attributes for endpoint search via REST API, filtering, display, etc.

The device can fully or partially update its metadata, as well as delete specific metadata keys.

Kaa allows specifying a list of metadata fields that devices are allowed to access. You can also forbid for device to update specific fields of its metadata, making such fields read-only.

Go to Device management -> Applications -> your application -> choose your application version on the left -> “epmx” (Kaa component that is responsible for allowing devices to retrieve and manage their metadata).

Taking the example of the device metadata snippet listed at the top, if you would like to allow devices in the bs7hbk6an6qhlo5moeo0-v1 application version to update only latitude and longitude keys, and read only model key, then your configuration will look next:

endpoint metadata keys configuration

As a result, devices will be able to read only latitude, longitude, and model, and all other fields like name, address, etc. won’t be readable by the device. In addition to reading, the device will also be able to update and delete only latitude and longitude keys.

Refer to the corresponding Device API pages to figure out how your device can manage its metadata.

For MQTT:

For HTTP:

Read metadata using Device MQTT or HTTP APIs

The device can read its metadata. It can be useful for example when а user sets metadata using UI and the device must somehow read it and react accordingly to the new value.

As stated above, you can restrict your device to reading only a predefined set of metadata fields.

Refer to the corresponding Device API pages to figure out how your device can read its metadata.

For MQTT:

For HTTP:

Display metadata on UI

The most simple way to check your device’s metadata is to go to Device management -> Devices -> your device.

endpoint metadata widget

From here you can also add, edit, or delete specific metadata fields using the relevant button.

But this is not the only place where you can view and manage device metadata. Almost every UI widget works with metadata in some way. When you see “epr” in the widget’s configuration panel, then it means that this widget is able to display metadata. EPR stands for Endpoint Register component which is Kaa internal microservice that is responsible for metadata management.

epr data source

Create a filter that will dynamically group devices based on their common attributes

You can dynamically group your devices based on their common metadata attributes. Imagine you have a set of devices located in London and another set of devices located in Liverpool. Now you want to split them into two dynamic groups based on the value in the address.city field (example taken from the metadata snippet given at the top of the article). Having two separate groups, you may want to perform software update (OTA) on one of them without having impact on the other one.

endpoint filter

Here you can see that you can instantly see the matching device list (Matching endpoints), run commands on all devices matching the filter, etc.

Refer to Endpoint Filter feature description for more information.

Process metadata with Rule Engine

You can apply various rules with the help of Rule Engine using the device metadata. Rule Engine allows you to write rules of any complexity using the most popular programming language in the world - JavaScript.

Working with metadata from Rule Engine you can perform the following things in real-time:

  • Generate alerts based on metadata values
  • Execute webhooks
  • Invoke command on device
  • Generate device telemetry data based on metadata
  • Modify or enrich incoming data before storing it
  • Combine both metadata and telemetry data together
  • Run complex calculations based on real-time metadata updates

Visit the Rules section in Kaa UI and explore Rule Engine capabilities. Rule Engine documentation section will give you more details.

rule engine

Configure alerts on metadata values

Kaa can monitor incoming metadata updates in real-time and create alerts once the preconfigured condition is met. Alerts are built on top of Rule Engine.

Visit Alerts -> Alerts settings section in Kaa UI and explore alert capabilities.

metadata alert

Manage metadata using REST API

Refer to REST API documentation on how you can manage device metadata.