Skip to main content

Tutorial: Configure Multiple Devices

This tutorial will show you how to configure multiple Devices at once. You will:

  • Annotate Devices with Tags
  • Set Desired Properties of Devices based on their Tags using Device Fleet Configuration.
tip

This tutorial doesn't delve into how Devices obtain their Desired Properties from the Platform and how they report their Reported Properties back to it. To learn more about this mechanism, check out the previous tutorial.

Scenario​

These arms are highly configurable; their most important configuration parameters are their speed and precision. Properly balancing these parameters allows the robotic arms to perform various tasks:

  • Moving inventory in warehouses: Speed must be as high as possible while maintaining reasonable precision. This configuration is the default, so a robotic arm doesn't have to be explicitly configured for this purpose.
  • Welding: Precision must be much higher than in the previous case, while speed can be lower.

Because your company produces these robotic arms in large quantities, you don't want to configure each individually. Furthermore, the usage of a single robotic arm can change over time, so you want to be able to reconfigure them easily.

First, you'll register two robotic arms, robo-arm-a and robo-arm-b, and annotate each of them with two Tags:

  • The deviceType of both arms will be roboticArm to distinguish them from other machines your company produces.
  • The usage of robo-arm-a will be inventoryMoving, while robo-arm-b will have the value welding.

Then, you'll create a Device Fleet Configuration to automatically set the Desired Properties of all welding robotic arms. The Configuration will set the speed to 5 and the precision to 0.9 (assume that the robotic arm knows how to interpret these values).

You'll observe how robo-arm-b receives the Desired Properties from the Platform. Finally, you'll change the usage Tag of robo-arm-a to welding and see how the Platform reconfigures it.

Scenario schema

Requirements​

1. Start Devices​

First, you'll start two Device programs that will connect to the Platform as robo-arm-a and robo-arm-b:

If you haven't installed the Device SDK yet, run the following command:

pip install --upgrade spotflow-device

Paste the following code into a new file called configure_devices.py, or download it. Replace the placeholder <Your Provisioning Token> with your Provisioning Token.

tip

If you don't have a Provisioning Token, see Create Provisioning Token for instructions on creating it.

configure_devices.py
import json
import sys
import time
from spotflow_device import DeviceClient

if len(sys.argv) < 2:
    print("Usage: python configure_devices.py <Device ID>")
    sys.exit(1)

device_id = sys.argv[1]

# Connect to the Platform

client = DeviceClient.start(device_id=device_id, provisioning_token="<Your Provisioning Token>", db=f"spotf_{device_id}.db")

# Show all changes in configuration

desired_properties_version = None

while True:
    desired_properties = client.get_desired_properties_if_newer(desired_properties_version)
    if desired_properties is not None:
        print(f"[{client.device_id}] Received Desired Properties of version {desired_properties.version}:")
        print(json.dumps(desired_properties.values))

        desired_properties_version = desired_properties.version

        print(f"[{client.device_id}] Updating Reported Properties")
        client.update_reported_properties(desired_properties.values)
    
    time.sleep(1)

The program will display all changes to the Desired Properties and update the Reported Properties with the same values. See Tutorial: Configure Device for more details on how this mechanism works.

Navigate to the directory where you saved the file and run the following commands in two separate terminals. When run for the first time, each command will create a new Provisioning Operation and display its details:

robo-arm-a
> python configure_devices.py robo-arm-a
Provisioning operation initialized, waiting for approval.
Operation ID: 2b09af82-d620-4ea3-8422-4e36a95dc664
Verification Code: hek12e7a
robo-arm-b
> python configure_devices.py robo-arm-b
Provisioning operation initialized, waiting for approval.
Operation ID: 4163c36f-1a92-41d3-9e4c-e2873d99a97b
Verification Code: jq8hvuc1

2. Approve Devices with Tags​

You'll now approve both Devices into the Platform and annotate them with Tags:

Login to the Spotflow IoT Platform Portal and follow the instructions:

1
2
3
4
5
6

  1. Expand the section Devices in the left sidebar and open the link Approvals.

  2. The list of Provisioning Operations opens. You should see two rows with the Device ID robo-arm-b and robo-arm-a. Click Approve of robo-arm-a in the column Actions.

  3. The approval dialog window opens. Expand Device tags and enter the following Tags in the table: deviceType - roboticArm, usage - inventoryMoving. Click Approve.

  4. An approval confirmation shows up. Click Approve of robo-arm-b in the column Actions.

  5. In the approval dialog for robo-arm-b, expand Device tags and enter the following Tags in the table: deviceType - roboticArm, usage - welding. Click Approve.

  6. A box with the title Approved confirms that you've successfully approved robo-arm-b.

After each approval, the Device program of the corresponding robotic arm will enter the main loop. It will receive the Desired Properties from the Platform and display them. Initially, the Desired Properties will be empty:

robo-arm-a
[robo-arm-a] Received Desired Properties of version 1:
{}
[robo-arm-a] Updating Reported Properties
robo-arm-b
[robo-arm-b] Received Desired Properties of version 1:
{}
[robo-arm-b] Updating Reported Properties

3. Create Device Fleet Configuration​

While the programs for both Devices are still running, you'll create a Device Fleet Configuration to automatically set the Desired Properties of welding robotic arms based on their Tags.

Create the Configuration robo-arm-welding:

1
2
3
4
5
6

  1. Open the link Configurations in the left sidebar.

  2. Click Create new.

  3. In the first page of the wizard, enter `settings` to Path and {"speed": 5, "precision": 0.9} to Content. Click Next.

  4. In the second page of the wizard, enter tags.deviceType = 'roboticArm' AND tags.usage = 'welding' to Condition. The list of Matching devices should show that the Configuration will target robo-arm-b. Click Next.

  5. In the last page of the wizard, enter robo-arm-welding as the Configuration Name. Click Create.

  6. A box with the title Created confirms that you've successfully created the Configuration.

After creating the Configurations, robo-arm-b will receive the proper Desired Properties:

robo-arm-b
[robo-arm-b] Received Desired Properties of version 2:
{"settings": {"precision": 0.9, "speed": 5}}
[robo-arm-b] Updating Reported Properties
info

It might take up to a few minutes for the Platform to apply the Configurations. While this delay might be slightly inconvenient during development and testing, there's rarely a need for immediate configuration changes in production environments.

4. Update Tags​

Finally, you'll change the usage Tag of robo-arm-a to welding and observe how the Platform automatically reconfigures it:

1
2
3
4
5

  1. Open the list of Devices using the link in the left sidebar.

  2. Click the Device ID robo-arm-a.

  3. In Device Details, click the edit icon under the section Tags.

  4. A pop-up window Device Tags opens. Modify the Value of the Tag usage to welding. Click Update.

  5. A box with the title Updated confirms that you've successfully updated the Tags of robo-arm-a. Also, the section Tags should now show usage: welding.

It might take up to a few minutes for the Platform to reconfigure robo-arm-a. Eventually, the Device program will receive the proper Desired Properties:

robo-arm-a
[robo-arm-a] Received Desired Properties of version 2:
{"settings": {"precision": 0.9, "speed": 5}}
[robo-arm-a] Updating Reported Properties

Summary​

Congratulations on finishing the tutorial! While the example has shown only two Devices, it should demonstrate that Device Fleet Configuration makes configuring a large fleet of Devices feasible.

What's Next?​

  • The parent page Configure Devices explains the concepts of Tags and Device Fleet Configuration in more detail.
  • The Device SDK references for Python, C, and Rust describes the interface you can use to handle the configuration from the Device side.
  • The API reference describes all the ways to create, update, and inspect Device Fleet Configurations programmatically.
Copyright © 2024 Spotflow, s.r.o.