Skip to main content

Manage Devices

Overview

This page explains all the concepts relevant to registering Devices to the Spotflow IoT Platform and managing them. The following diagram shows the relationships between these concepts:

Device Configuration

A Device that is successfully registered to the Platform is uniquely identified by its Device ID. Such a Device can establish a secure connection to the Platform at any time using a Registration Token, a short string that the Device SDK refreshes periodically.

The most common way to register a Device is to use a process called Device Provisioning. You create a Provisioning Token in the Platform and embed it in the Device. The Device uses the Provisioning Token to initiate a Provisioning Operation. After you approve the operation, the Device receives its Device ID and Registration Token.

The Platform enables you to manage each Device's configuration and state using Desired Properties, Reported Properties, and Tags. Desired Properties propagate from the Platform to the Device, and Reported Properties go the other way. Tags are key-value pairs kept only on the Platform; the Device can't access them. You can set Desired Properties manually or use Automatic Device Configuration, which targets Devices based on their Tags and Reported Properties. See Device Configuration for more details.

tip

Get Started shows how to register a Device using Device Provisioning. Configure Devices demonstrates how to use Desired and Reported Properties to configure a Device.

Device

In the context of the Platform, a Device can be any physical object (autonomous robot, vehicle, electronic gadget, or appliance) as well as a computer program (virtual Device). The Device calls the Platform HTTP API to obtain and regularly refresh its Registration Token. The Registration Token allows the Device to establish a secure connection to the Platform and send data. All this registration and communication logic is handled by the Device SDK so that you don't have to implement it manually.

Each registered Device contains the following properties:

Device ID

Within each Workspace, every registered Device must have a unique Device ID. It's a string that is 4-90 characters long and contains only the characters 0-9, a-z, A-Z, -, _, and ..

warning

Make sure that each physical Device in the same Workspace has a unique Device ID. Two Devices with the same Device ID can't be connected to the Platform at the same time.

If you connect to the Platform with a Device that has the same Device ID as another currently connected Device, the first Device will be disconnected. As the Device SDK in the first Device tries to reconnect, it might disconnect the second Device, and so on. As a result, both connections will be unstable, and the data sent by both Devices might be mixed together.

Registration Token

To connect to the Platform, a Device needs a Registration Token. Only with the Registration Token, the Device can perform common tasks, such as send Messages to the Platform. There are two ways to obtain the token:

  • Perform Device Provisioning. This is the most common way and we recommend it for its security and ease of implementation.
  • Embed a unique X.509 certificate into the device. In this case you need to manage your own certificate authority and issue the certificates for all devices. Therefore, the implementation effort is higher than in the first case. Contact us for more information.

Each Registration Token contains:

  • Device ID of the device it's been issued for. Therefore, you can't reuse a single Registration Token by multiple devices.
  • Optional expiration time, after which the platform stops accepting it. The time between the token's creation and expiration is called the lifetime of the token. If no expiration time is specified, we call the lifetime infinite.

While the Registration Token is still valid, the Device can refresh it. It means that the Device obtains a new Registration Token and starts using it instead of the old one. The Device SDK automatically refreshes the token after it reaches half of its lifetime.

Best practice is to set the lifetime slightly longer than the time that the device spends disconnected from the platform. The device will be disconnected mostly because it's turned off or because its Internet connectivity is limited. When it's turned on and connected to the Internet, we recommend to keep it connected to the platform. The connection makes sure that the Device SDK can refresh the token before it expires.

It seems easier to use infinite Registration Token lifetimes because then you don't need to refresh the tokens and register the devices repeatedly. However, it's a bad security practice. If an old Registration Token is leaked and falls into the wrong hands, it's better if it doesn't work.

If you find out that a Registration Token was compromised, you can revoke it manually. Revoking makes it invalid even before its expiration time.

Device Provisioning

Device Provisioning is the preferred process used to register a Device into the Platform. At first, you must create a Provisioning Token in the Platform and configure it according to the needs of your scenario. Each Device that wants to register to the Platform must have an embedded Provisioning Token, multiple Devices can share the same token. The diagram below show the following steps:

After the Device is turned on, it uses the Provisioning Token to initiate a Provisioning Operation (1, 2). The Device then displays the operation details to the technician who is responsible for its registration (3). Usually, it will be a person who is physically close to the Device and can see the operation details on its screen. While the Device is periodically asking the Platform if the operation was approved (4, 5), the technician finds the operation in the Platform and approves it (6). Finally, after the Device completes the operation (7), it receives its Registration Token (8). The Device then uses the Registration Token (9) to obtain the Device ID and other credentials for the connection to the Platform (10).

note

Although the process may seem unnecessarily complicated, it follows the current best practices in IoT security. For example, an unfortunate leak of a Provisioning Token doesn't allow unwanted parties to connect to the Platform.

Provisioning Token

A Provisioning Token is another short string generated by the Platform for the authentication of Devices. As we show above, a Device can use it to initialize Device Provisioning. You can use Provisioning Tokens in two ways:

  • Create a single token and embed it into a whole set of Devices. Each Device selects its Device ID when it starts the Provisioning Operation.
  • Create and embed a specific token into each Device. The token already contains the Device ID, so the Device doesn't have to select it.

In some cases, you may want to leave the choice of the Device ID to the technician who approves the operation. The desired Registration Token lifetime may also differ between individual Devices. For example, if a Device is located in a place with limited Internet connectivity, you might want to increase the lifetime. To handle such cases, you can adjust these parameters when you create a new Provisioning Token:

  • Optional maximum Registration Token lifetime sets the lifetime of the Registration Token the device receives as the result of Device Provisioning.
  • Registration Token lifetime override mode determines whether the lifetime of the Registration Token can be overriden during the approval of the Provisioning Operation. Possible values:
    • Disabled: It can't be overriden. Maximum Registration Token lifetime is always used.
    • Allowed: It can be overriden. Maximum Registration Token lifetime is used if the technician approving the operation doesn't specify the lifetime.
    • Enforced: The technician approving the operation must specify the lifetime.
  • Optional allow infinite token lifetime specifies if the lifetime of the produced Registration Token can be infinite.
  • Optional Device ID sets the default Device ID which the newly registered device receives.
  • Device ID override mode specifies when the default Device ID can be overriden. Possible values:
    • Disabled: It's not possible to override the default Device ID.
    • Allowed during the provisioning initialization: The device can override the Device ID when it initializes Device Provisioning.
    • Enforced during the provisioning initialization: The device must specify the Device ID when it initializes Device Provisioning.
    • Allowed during the provisioning approval: The technician can override the Device ID during the operation approval.
    • Enforced during the provisioning approval: The technician must specify the Device ID during the operation approval.
    • Allowed both during the initialization and the approval: Both the device during the operation initialization and the technician during its approval can override the Device ID.

Not all combinations of these parameters are valid. For example, you can't leave out the Device ID if you set the Device ID override mode to Disabled.

Provisioning Operation

When a Device starts its provisioning, this attempt is recorded as a new Provisioning Operation. The Device provides the following parameters:

  • Optional Device ID the Device wants to receive.
  • List of optional parameters that the technician will see when approving the operation.

Apart from these parameters, a newly created operation contains many different properties. The most important ones are:

  • Operation ID is a GUID which uniquely identifies the operation.
  • Verification code is a short string displayed by the device to convince the technician that it's the author of the operation.
  • Expiration time is the time after which the operation expires and can't be approved anymore.

A Provisioning Operation can be in four states:

  • It's pending right after a device creates it.
  • When a technician approves a pending operation, it becomes approved.
  • When the device completes an approved operation, it becomes completed and the Device receives its Registration Token.
  • An operation can become cancelled in these cases:
    • It's pending or approved and a technician manually cancels it.
    • It expires.
    • Another operation with the same Device ID becomes approved.

Device Configuration

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

Configure Devices 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'
  • 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.
    • Cannot be changed after creation.
    • For example: updateSettings.interval
  • Desired Property content
    • The content that will replace the value in the Desired Property path.
    • Cannot be changed after creation.
    • For example:
      {
      "exampleSettings" : {
      "exampleProperty" : 11
      }
      }
    • Another example:
      "value"
tip

If you need to modify the Desired Property content of a Configuration after its creation, it's best to create a new Configuration with the updated content and delete the old one:

  1. Create a new Configuration with the updated Desired Property content. Use the same priority as the old Configuration because newer templates take precedence over older ones with the same priority.
  2. Wait until the Platform applies the new Configuration to the same number of Devices as the original one. You can see this information, for example, in the Configuration Details page in the Portal.
  3. Delete the original Configuration.