Skip to main content

Configure Devices

The Platform provides these building blocks to configure Devices:

  • You can set a Device's Desired Properties in the Platform, and the Device receives their updates.
  • The Device can update its Reported Properties, and you can then read them from the Platform.
  • You can annotate each Device using various Tags.
  • To set the Desired Properties of multiple Devices at once, you can use Automatic Device Configuration, which targets Devices based on their Tags and Reported Properties.

Device Configuration

There are two main factors to take into account when choosing which of these features to use:

  • The phase of your project: If the project is still in the development phase, you might not initially need to use these features at all. When you start working on their integration, the most flexible way that makes testing easier is to set the Desired Properties for each Device individually. If you're already in the production phase, you might want to use the Automatic Device Configuration to reduce manual work.
  • The scale of your project: It's easy to manage a configuration of a few Devices manually, but it's much harder once your fleet of Devices grows.

The following table summarizes best practices:

Development phaseProduction phase
Few devicesSet Desired Properties individuallySet Desired Properties individually or use Automatic Device Configuration
Many devicesNot recommendedUse Automatic Device Configuration

Format​

Desired Properties, Reported Properties, and Tags are JSON documents with the following restrictions:

  • Keys can't contain dots . or dollar signs $.
  • Values can be strings, numbers, booleans, arrays, or objects.
    • String values are encoded in UTF-8 and can be up to 4 KB long.
    • Setting a value to null in an API call is a request to remove it.
  • The maximum depth of objects is 10.
info

Tags have additional restrictions. For example, you can't use nested objects in Tags.

Desired Properties​

This JSON document contains properties that you want to propagate to the Device. You can either set them manually in the Platform or use Automatic Device Configuration, which targets Devices based on their Tags and Reported Properties.

The Device can't modify its Desired Properties, but it reads them and receives their updates when it's connected to the Platform. The Device SDK persists the last received version of Desired Properties in the local database file so that the Device software can access them even when the Internet connection is unstable.

You can choose any structure for Desired Properties if you conform to the format. For example:

{
  "settings": {
    "speed": 20,
    "temperature": {
      "min": 24,
      "max": 60
    },
    "voltage": 3.3,
    "wifi": {
      "enabled": true,
      "ssid": "MyWiFi",
      "ghz": [2.4, 5]
    }
  }
}

Desired Properties are versioned. Right after the Device registers to the Platform, its Desired Properties are an empty object with version 1. The Platform increments their version number each time they are updated. The Device software can access the version number using the Device SDK.

Reported Properties​

This JSON document allows the Device to communicate its current configuration and state to the Platform.

In contrast to Desired Properties, only the Device can update its Reported Properties while you and Automatic Device Configuration can only read them. The Device software can update them even if the Device is currently disconnected from the Internet because the Device SDK persists them in the local database file and sends them to the Platform when the connection is re-established.

A common use case for Reported Properties is to confirm that the Device applied the configuration changes requested in the Desired Properties. In that case, having these configuration options in the same structure in the Reported Properties is best practice. You might also want to include other properties that describe the Device's state but cannot be configured from the Platform.

Reported Properties must conform to the same format as Desired Properties. For example:

{
  "settings": {
    "speed": 20,
  },
  "status": {
    "lastMaintenance": "2024-02-04"
  }
}

The Platform adds additional information to the Reported Properties received from the Device:

  • $metadata contains information about the last modification time of each object and property.
  • $version is the version number of the Reported Properties. The Platform increments it whenever the Device updates them.
{
  "$metadata": {
    "$lastUpdated": "2024-03-20T18:19:03.6541661Z",
    "settings": {
      "$lastUpdated": "2024-03-20T18:19:03.6541661Z",
      "speed": {
        "$lastUpdated": "2024-03-20T18:19:03.6541661Z"
      }
    },
    "status": {
      "$lastUpdated": "2024-03-20T18:12:28.5824456Z",
      "lastMaintenance": {
        "$lastUpdated": "2024-03-20T18:12:28.5824456Z"
      }
    }
  },
  "$version": 3,
  "settings": {
    "speed": 20
  },
  "status": {
    "lastMaintenance": "2024-02-04"
  }
}
tip

Tutorial: Configure Single Device shows how to use Desired and Reported Properties to configure a Device.

Tags​

Tags are key-value pairs that you can assign to each Device. You can set their initial values when you approve the Device's Provisioning Operation and edit them further after the Device registers to the Platform.

The Device can't see its Tags and can't modify them. Tags are primarily used in Automatic Device Configuration to target Devices.

While the Portal provides a user-friendly table to manage Tags, the Platform stores them in the JSON format. You might encounter this format, for example, in the Platform API. In addition to the overall format restrictions, Tags must also follow these rules:

  • Tag name:
    • Consists of 1-128 characters.
    • Contains only the characters 0-9, a-z, A-Z, -, and _.
    • Starts and ends with an alphanumeric character.
  • Tag value can be only one of these types: string, number, or boolean.
    • For example: "abc", 42, 4.2, true, false
    • As a result, nested Tags such as {"a": {"b": 42}} are not allowed.

Example of Tags:

{
  "deviceType": "roboticArm",
  "usage": "inventoryMoving",
  "deployed": true,
  "floor": 3
}

Automatic Device Configuration​

Automatic Device Configuration is a set of features that allow updating Desired Properties of multiple Devices at once. Each Configuration acts as a current “template” for a specific group of Devices. All the targeted devices will have their Desired Properties set according to the Configuration.

Each Configuration sets the content of a certain “subtree” of Desired Properties. Therefore, it's common to apply multiple Configurations to a single Device:

Automatic Device Configuration scheme

tip

Consider which Desired Properties are common for the fleet of Devices and which need to be adjusted on a Device level. Some Devices are quite simple (such as vibration sensors) and for them, there is usually one shared Configuration among the fleet. For more complex Devices (such as programmable robotic arms), the Configuration depends on the desired purpose of the Device.

For example, one robotic arm performs a welding job, where high precision is the most important factor, while another moves inventory in a warehouse, where speed is prioritized. That requires different Configurations. In fact, we can treat them as different types of Devices: a welding robot and a warehouse robot.

Configuration application​

Configurations are applied constantly and continuously, which means all targeted devices will eventually (with a delay of max. a few minutes) have their Desired Properties set according to the Configuration, including newly created devices that match the Configuration. Deleting a Configuration also removes the properties set by the Configuration from all the targeted devices.

Targeting Devices​

Devices are selected based on a target condition. It's a query that filters Devices on which the Platform will apply the Configuration. This means that not only the currently existing devices will be targeted but also future devices that match the query. The target condition can contain parentheses ( and ), function calls IS_DEFINED(...), comparison operators = and !=, logical operators AND, OR and NOT, and references to the following properties:

  • Tags
    • For example: tags.deviceType = 'robotA'
  • Device ID
    • For example: deviceId = 'abc123'
  • Reported Properties
    • For example: properties.reported.updateSettings.interval = 20
warning

!= (“not equals”) in expression matches only the Devices that have the Tag / Reported Property set to some value and which is different than the one specified in the condition. It doesn't match the Devices that don't have the value specified.

Use NOT IS_DEFINED(tags.myTag) to match the Devices that don't have the Tag myTag set.

For example:

  • tags.deviceType != 'robotA' AND tags.deviceType != 'robotB'
    • Matches all Devices with the Tag deviceType set to a value different than robotA and robotB but doesn't match devices that don't have the Tag deviceType set.
  • NOT IS_DEFINED(tags.deviceType)
    • Matches all Devices that don't have the Tag deviceType set.
  • properties.reported.updateSettings.interval = 20 AND (tags.deviceType = 'robotA' OR tags.deviceType = 'robotB')
    • Matches all Devices with the Reported Property updateSettings.interval set to 20 and the Tag deviceType set to either robotA or robotB.

Configuration Settings​

  • Template name
    • Unique identifier of the Configuration.
    • Human readable, for example: robot-a-feature-x
    • Consist of 1-64 characters.
    • Contains only the characters 0-9, a-z, and -, starts and ends with an alphanumeric character.
  • Priority
    • Positive integer.
    • Higher priority (e.g. 2) Configurations overwrite lower priority (e.g. 1) Configurations.
    • Newer templates take precedence over older ones that have the same priority.
  • Target condition
    • Query string describing to which Devices a Configuration should be applied to.
    • See Targeting Devices.
  • Desired Property path
    • Path specifying to which Desired Property object the Configuration's content should be applied to.
    • For example: updateSettings.interval
  • Desired Property content
    • The content that will replace the value in the Desired Property path.
    • For example: 
      {
        "exampleSettings" : {
          "exampleProperty" : 11
        }
      }
    • Another example: 
      "value"
Copyright © 2024 Spotflow, s.r.o.