Skip to main content

Get Started

This 15-minute tutorial will show you how to start using the Spotflow IoT Platform. You'll simulate a weather station that measures the temperature and humidity in your room every few seconds. We'll show you how to:

  • Create a new Workspace
  • Register a Device
  • Visualize current Device telemetry in Grafana
  • View stored telemetry records

Scenario schema

Contact us if you encounter any problems; we'll be happy to help!

Requirements​

Let's start!

1. Create Workspace​

A Workspace is a container where you put all the Devices and other assets relevant to a certain task. Use either the Portal, CLI, or API to create a new one:

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

1
2
3

  1. On the Overview page of the Portal, click Create new workspace.

  2. Enter a short and fitting Display Name for the Workspace, such as "Test Workspace". You can change the name later. Click Create.

  3. After the Workspace is created, you'll be redirected to the Workspace Details page. The Workspace is also selected as the current one in the upper right corner of the page. Most importantly, all the links in the left menu are now enabled, and you can use all the Platform features.

tip

You can find more information about Users and Workspaces in the User Guide. See the reference of CLI and API for more details about the available commands and endpoints.

2. Configure Data Flow​

You'll now configure the Platform to forward all the data from the Device to the integrated instance of Grafana:

1
2
3
4
5
6

  1. Open the link Data Flows in the left sidebar.

  2. You'll see the list of Streams that are organized into Stream Groups. Select the Stream default in the Stream Group default.

  3. On the right side of the screen, you see the detailed configuration of the Stream. These options influence where the data are stored and how they are processed. Click the Egress tab.

  4. The section Routes shows all the Egress Sinks where the Stream forwards the data it receives. The list is empty by default. Click Create new route.

  5. Enter a machine-readable Name (allowed are only alphanumeric characters, -, _, and .) such as Grafana. In the selection box Egress Sink, select Grafana. Click Save.

  6. Nice! Now you should see the newly created Egress Route in the list.

tip

The User Guide provides more information about how to send data to the Platform and process them further.

3. Create Provisioning Token​

The process used to register a Device to the Platform is called Device Provisioning. To perform it, the Device needs a Provisioning Token. Let's create it:

1
2
3
4
5
6
7

  1. Open the link Devices in the left sidebar.

  2. The list of all connected Devices opens. The Device will appear here after you register it to the Platform. Open the link Tokens in the left sidebar.

  3. The list of Provisioning Tokens opens. Click Create new in the upper right corner.

  4. Use the Recommended Registration Token Lifetime. Click Next.

  5. Keep the default configuration of how Devices obtain their IDs. Click Next.

  6. Enter an arbitrary name (e.g., Test Token) and click Create.

  7. The newly created Provisioning Token appears at the bottom of the page. Click the copy icon on the right side to copy it to the clipboard. Note it somewhere so that you can use it in the next step.

tip

Learn more about Device Provisioning and management in the User Guide.

4. Gather Data from Device​

The Device will now use the Provisioning Token to start a Provisioning Operation. After you approve it, the Device will finish the registration and start sending data to the Platform.

4.1. Use Device SDK​

The Device SDK is available for Python and C:

Install the recent Device SDK for Python using the following command:

pip install --upgrade spotflow-device

Paste the following code into a new file, or download it. Replace the placeholder <Your Provisioning Token> with your Provisioning Token and run the program.

get_started.py
import datetime
import json
import time
from spotflow_device import DeviceClient

# Connect to the Platform (starts Device Provisioning if the Device is not already registered)
client = DeviceClient.start(device_id="my-device", provisioning_token="<Your Provisioning Token>", db="spotflow.db")

# Create a sender to the default stream
sender = client.create_stream_sender(stream_group = "default-stream-group", stream = "default-stream")

for i in range(0, 60):
    # Send and display the measured data
    payload = json.dumps({
        "timestamp": datetime.datetime.now().astimezone().isoformat(),
        "temperatureCelsius": 21 + (i * 0.05),
        "humidityPercent": 50 + (i * 0.1)
    })
    sender.send_message(payload.encode())
    print(payload)

    # Pause till next iteration
    time.sleep(5)

DeviceClient.start will display the following text:

Provisioning operation initialized, waiting for approval.
Operation ID: b170c9ab-961c-4c02-af88-d4287d9cea1f
Verification Code: jgcjtprw

After you approve the operation in the next step, the Device will start sending the data as short Messages.

4.2. Approve Device​

While the code on the Device side is still running, you'll now approve the Provisioning Operation started in the previous step:

1
2
3
4
5
6

  1. Expand the link Devices in the left sidebar if it's not already expanded. Open the link Approvals.

  2. The list of Provisioning Operations opens. You should see a row with the Device ID my-device. Click Approve in the column Actions.

  3. The approval dialog window shows the Provisioning Operation details and allows you to override Device registration details. Leave the default values and click Approve.

  4. Good job! The Device disappeared from the table because its state changed to Approved, while the current filter shows only the Devices in the state Waiting for Approval. When the Device SDK completes the registration, the Device changes its state to Completed and appears in the table of all registered Devices. Navigate to it by clicking the link Devices in the left sidebar.

  5. You should see a row in the table with the Device ID my-device. If you don't see it, the Device hasn't completed the registration yet. Ensure that the code on the Device side finished the registration and proceeded to send Messages, and click the refresh button after a few seconds. Click the Device ID my-device to see the details.

  6. The Device Details page is useful to inspect the Device state. The Connection Status shows whether the Device is currently connected to the Platform. In our case, the status will be Connected when the program is sending Messages and Disconnected otherwise. Statistics show the recent traffic from the Device. There might be a lag of several seconds before the Portal shows the current information, so refresh the page as needed.

Finally, if you look at the program output, you should see that the device is registered and started sending Messages:

Provisioning operation initialized, waiting for approval.
Operation ID: b170c9ab-961c-4c02-af88-d4287d9cea1f
Verification Code: jgcjtprw
{"timestamp": "2023-10-02T13:26:34.351761+02:00", "temperatureCelsius": 21.0, "humidityPercent": 50.0}
{"timestamp": "2023-10-02T13:26:39.358295+02:00", "temperatureCelsius": 21.05, "humidityPercent": 50.1}
{"timestamp": "2023-10-02T13:26:44.370000+02:00", "temperatureCelsius": 21.1, "humidityPercent": 50.2}
...

Continue to the next section even if the program is still running.

tip

The Device SDK documentation provides more information for both its Python and C versions.

5. View Data​

We'll now show you how to visualize each received Message in real time using Grafana and how to view multiple stored Messages.

5.1. Visualize Data in Grafana​

1
2
3
4
5
6
7
8
9
10
11
12
13

  1. Open the link Grafana in the left sidebar.

  2. The Home page of the integrated instance of Grafana will open in a new browser tab. It answers some common questions about how you can use it. Click the menu icon.

  3. Open the link Explore in the menu.

  4. In the query editor, open the data-source picker.

  5. Select the data source that starts with device_metric. The other one contains the usage data of your Workspace.

  6. Click Select table.

  7. The Platform creates a new table from each metric it receives in any Message. It also changes the name of the metric into the snake case. Select humidity_percent.

  8. Because we want to know when the Device took the measurement, select the "time" Column.

  9. Click the + button to add another column.

  10. Choose the second column. Select value.

  11. Grafana shows only the last 50 records by default. To change this, click Order and erase the Limit.

  12. Expand the options of the big Run query button in the top-right corner. Select 5s to automatically refresh the query every 5 seconds.

  13. Scroll down to the query results. If the Device is still sending Messages, you'll see them appearing as rows in the Table and points in the Graph in real time.

note

If the program finished sending Messages, you can rerun it to see the data appearing in Grafana. You don't need to approve the Device this time because it's already registered.

tip

Feel free to explore the received data and create custom dashboards, as described in the official Grafana documentation. To learn more about the integrated instance of Grafana and the format it accepts, see the User Guide. To develop custom streaming applications, look at Egress Sinks.

5.2. Inspect Stored Data​

By default, all the Streams in a Workspace store the received Messages as blobs into the same Azure storage account. We'll show you how to get its shared access signature (SAS) URL that you'll later use to access the data:

1
2
3
4
5

  1. Open the link Workspaces in the left sidebar.

  2. Click the Name of the Workspace you are currently using.

  3. In the Workspace Details page, click Connect to storage.

  4. Keep the default values and click Generate.

  5. Click the copy icon to copy the generated SAS URL to the clipboard.

We'll show you how to access the Messages in Azure Blob Storage using Azure Storage Explorer and Azure CLI. Select the one that suits you best:

Go to the Azure Storage Explorer website and download the version for your operating system. Install and launch the program, then continue with the following steps:

1
2
3
4
5
6
7
8
9
10
11

  1. In the left sidebar, click the connection icon.

  2. From the available resource types in the pop-up wizard, select Blob container or directory.

  3. Choose Shared access signature URL (SAS) as the connection method. Click Next.

  4. Enter your SAS URL into Blob container or directory SAS URL, Display name will be then filled automatically. Click Next.

  5. Click Connect.

  6. After the wizard closes, the blob container appears in the hierarchy of the panel Explorer. The table with the container's contents also opens in the main area. By default, it shows the blobs in a hierarchical structure. For better orientation, we will show their full names instead. Click the filter icon on the top right of the panel.

  7. In List Mode, select Flat.

  8. You should now see a list of blobs (files). Close the view options by clicking the filter icon again.

  9. Double-click one of the blobs to download it.

  10. If a security warning about an untrusted extension appears, you can safely click Yes. Open the downloaded file in a text editor.

  11. The file contains the content of the selected Message.

tip

Learn more about how the Platform stores the received data in the User Guide.

You can find more information about Azure Blob Storage in the official documentation. Apart from Azure Storage Explorer and Azure CLI, you can also use Azure SDKs available in multiple programming languages, or call the REST API directly.

Summary​

Congratulations on getting this far! If you followed the previous steps, your Device can now send telemetry to the Spotflow IoT Platform, the Platform stores all the received data in Azure Blob Storage, and you can see the measurements arriving in real time using Grafana. Let's review how you and your Device interacted with the Platform:

  1. You created a Workspace, which serves as a container for all the assets in the Platform.
  2. You configured the Stream default-stream (located in the Stream Group default-stream-group) to immediately forward the received Messages to the integrated instance of Grafana.
  3. You created a Provisioning Token and stored it in your Device.
  4. The Device used the Provisioning Token to create an instance of Provisioning Operation.
  5. While the Device was waiting, you approved the operation.
  6. The Device finished the operation and obtained credentials for connecting to the Platform.
  7. The Device started sending Messages to the Stream default-stream
  8. The Platform forwarded all the received Messages to the integrated instance of Grafana so you could see them in real time.
  9. Simultaneously, the Platform saved each Message as a separate blob in Azure Blob Storage.
  10. You created a custom query in Grafana to display the received data.
  11. You connected to Azure Blob Storage, inspected the Messages, and downloaded one of them.

Any other Device can now use the Provisioning Token and send its Messages to the Stream default-stream. Hundreds or thousands of Devices write to the same Stream in real-life scenarios.

What's Next​

  • We provide the reference of the Device SDK both for Python and C.
  • To control the Platform without using the Portal, see the references of CLI and API.
  • If you have any questions or requests, contact us.
Copyright © 2024 Spotflow, s.r.o.