Meet KaaIoT at MWC25 Barcelona
March 3-6, 2025 Fira Gran Via, Barcelona
Kaa Documentation

Device Configuration Repository

What is Device Configuration Repository

The Device Configuration Repository is a storage solution that allows storing and managing various settings or parameters for devices. This feature helps control the behavior of your connected devices by delivering configuration data. In the Kaa IoT platform, this data is represented as a free-form JSON document.

Examples of device configuration usage:

  • Smart Home Automation System: Remotely adjust the temperature settings of your thermostat or the brightness of your smart lights.

  • Fleet Management System: Set the reporting interval of your vehicle’s GPS tracker to optimize battery efficiency.

In both cases, this is achieved by sending configuration data to the devices, allowing them to adjust their behavior accordingly.

JSON example of a device configuration:

{
  "temperature": 25,
  "brightness": 80
}

Receiving the above configuration, your smart device will adjust the indoor temperature to 25°C and brightness to 80%.

Device Configuration Types

In Kaa, there are two main types of device configuration:

  • Default Configuration: A configuration that is applied to all devices within a specific application version. It’s starting point configuration. Let’s say you have 100 devices. Defining a configuration for each device individually would be time-consuming. Instead, you can define a configuration for all devices with a specific application version, and Kaa will distribute this configuration to all existing and future devices automatically.
  • Endpoint-Specific Configuration: A configuration that is applied to a specific endpoint. Endpoint-specific configurations can be managed in batches—either via an Endpoint Filter or by selecting multiple endpoints simultaneously. Refer to the below section to learn how to manage endpoint-specific configurations in batches.

Batch management of endpoint-specific configurations is particularly useful when you have a fleet of devices with the same application version but want to group them based on certain criteria, such as device location.

For example:

  • Endpoints in Location A can have Configuration X.
  • Endpoints in Location B can have Configuration Y.

Imagine you have three thermostats in your house, each in a different room: living room, bedroom, and kitchen. All thermostats are registered under the same application version, e.g., bs7hbk6an6qhlo5moeo0-v1.

  • You can set a default configuration for all thermostats to maintain a comfortable temperature of 25°C.
  • Additionally, you can set an endpoint-specific configuration for the thermostat in the bedroom to maintain a temperature of 22°C for better sleep quality.

In this scenario, the default configuration will be as follows:

{
  "temperature": 25
}

And the endpoint-specific configuration for the bedroom thermostat will be next:

{
  "temperature": 22
}

So whenever the thermostat in the bedroom connects to the platform, it will receive temperature: 22, while the other thermostats will receive temperature: 25 over MQTT or HTTP device API.

What You Can Do With Device Configuration in Kaa

Manage Device Configuration from Kaa UI

You can manage device configuration from the Kaa UI with the help of three widgets:

  • Single Number Configuration
  • Configuration Form
  • JSON Configuration

Configuration Widgets

To add them, go to the “Solutions” -> choose or create a solution -> choose or create a dashboard -> enter Edit Mode -> click “Add Widget” -> choose the desired widget from the “Configuration management” section.

Let’s configure the “JSON Configuration” widget as an example. Add it to your dashboard. Then click on the edit icon in the top right corner of the widget to configure it. Choose the application version, and enable “Display default device configuration”.

Edit Configuration Widget

Click “Save” to apply the changes. This way, the widget will manage the default type of device configuration.

Paste the desired JSON configuration into the widget and click “Save”. Now whenever you device connects to the platform, it will receive this configuration.

Manage Device Configuration in Widget

Manage Device Configuration in Batch

If you want to set endpoint-specific configurations for multiple devices simultaneously, you can use a batch approach. When configuring the Device Configuration widget, you can select the “Batch update” option to apply the configuration to multiple devices at once. You can specify endpoints using either “Filter” or “Selection”:

  • Filter: You can choose any of the previously created endpoint filters. The configuration will be distributed to all endpoints that match the selected filter.
  • Selection: Manually select a list of endpoints to which you want the configuration to be distributed.

Manage Device Configuration Repository Using REST API

Refer to the REST API documentation to manage device configuration using REST API.

Difference Between Device Commands and Device Configuration Repository

In the Kaa IoT Platform, both Device Configuration Repository and Device Commands serve to send JSON data to devices, but they differ in purpose, behavior, and use cases. Here’s the logical distinction:

  1. Device Configuration Repository:
    • Purpose: Manages and synchronizes the configuration settings of devices.
    • Use Case: Used when the goal is to define and enforce a structured configuration that the device must adhere to.
    • Behavior:
      • The configuration is stored in the Kaa platform and serves as the “desired state” for the device.
      • Devices can periodically sync to retrieve the latest configuration or receive it in real-time if the configuration changes.
      • Ensures consistency by maintaining a record of the current and past configurations.
    • Example:
      • Setting up a device’s operational parameters like sampling frequency, thresholds, or network settings.
      • The platform ensures the device always operates with the correct configuration even after a reboot or loss of connection.
  2. Device Commands:
    • Purpose: Sends on-demand, one-time commands or instructions to devices.
    • Use Case: Used for ad-hoc or immediate actions that do not represent a persistent state or configuration.
    • Behavior:
      • Commands are transient and are not stored as the device’s desired state.
      • They are often executed immediately by the device without being retained for future reference.
      • Suitable for triggering specific actions rather than setting parameters.
      • May include optional execution result payload.
    • Example:
      • Triggering a device to perform a firmware update.
      • Sending a command to capture an immediate sensor reading or restart the device.

Key Differences:

Aspect Device Configuration Repository Device Commands
Purpose Define and enforce persistent device settings. Trigger immediate, one-time actions.
State Management Represents the desired state, stored in the platform. Transient, not stored long-term.
Synchronization Devices synchronize with the repository periodically or on updates. Executed as soon as sent.
Use Case Examples Setting operational parameters. Triggering an action like a reboot.
Persistence Persistent and synchronized. Non-persistent and action-specific.

In summary:

  • Use the Device Configuration Repository when the data represents long-term settings or parameters that define the desired behavior of the device.
  • Use Device Commands when you need to perform immediate, temporary actions without modifying the device’s persistent state.

What’s Next

Refer to the Tutorial on Device Configuration Repository, where we provide a step-by-step walkthrough on how to apply device configurations on your device.