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"
}
}
Kaa provides you with the following features regarding device metadata:
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:
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:
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:
The most simple way to check your device’s metadata is to go to Device management -> Devices -> your device.
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.
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.
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.
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:
Visit the Rules section in Kaa UI and explore Rule Engine capabilities. Rule Engine documentation section will give you more details.
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.
Refer to REST API documentation on how you can manage device metadata.