Skip to main content

Architecture

The Device SDK provides a public interface that you can use to register the Device to the Platform and send data in the form of Messages. After it is initialized, the Device SDK spawns background threads that handle ongoing communication with the Platform:

  • They use the Platform API to periodically refresh the Registration Token.
  • They maintain the connection with the Platform MQTT Broker. The MQTT connection is used, among others, to send Messages to the Platform.
  • They upload the contents of large Messages to the Platform, because MQTT is unsuitable for this scenario.

The public interface does not communicate with the Platform directly so that it doesn't block the execution of your software if the Internet connection is slow or unreliable. Instead, it stores all the outgoing Messages in the local database file. The background threads extract the Messages from the file and send them to the Platform. If the Internet connection works, each Message is sent immediately. Otherwise, the pending Messages are sent when the connection is restored in the order in which they were stored in the local database file.

The following diagram summarizes how the Device SDK works:

Device Registration​

This section explains all the concepts relevant to registering Devices to the Spotflow IoT Platform. 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 Device Fleet Configuration, which targets Devices based on their Tags and Reported Properties. See Configure Devices for more details.

tip

Get Started shows how to register a Device using Device Provisioning. Tutorial: Configure Single Device 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.
Copyright © 2024 Spotflow, s.r.o.