Introduction
The article describes ST AIoT Craft IoT API, which is the cloud back-end component that provides support for the IoT capabilities in the ST AIoT Craft platform.
ST AIoT Craft IoT API provides a CRUD (Create-Read-Update-Delete) interface to the entities that comprise an IoT system, that is, devices, gateways and related telemetries, commands, and properties.
- Introduction
- 1. Definition of the entities that comprise an IoT system
- 2. From the entities to the cloud
- 3. ST AIoT Craft IoT API interface
- 3.1 Example: a smart thermostat
- 3.1.1 Connection of the smart thermostat to the cloud application
- 3.1.2 How to interact with a device’s properties
- Conclusion
1. Definition of the entities that comprise an IoT system
A device is any physical entity, which is closer to the data source being measured. Devices are equipped with sensors and actuators, have limited processing capability, and are not connected to any internet connection by themselves. In the context of ST AIoT Craft, examples of supported devices are the SensorTile.box PRO and STWIN.box boards. Internet connectivity, along with other advanced functionalities, is provided instead by a gateway.
A gateway is a component that acts as an intermediary between the connected devices and the cloud/internet. It provides a bridge that allows data to flow effectively and securely between the local environment and the cloud/internet. Many modern gateways also have a significant amount of processing power, allowing complex logic to be executed close to the source and before sending the related data to the cloud.
Telemetries are the actual data provided by devices and gateways. Telemetries can be the raw measurements of the data source, for example the outputs of an accelerometer, as well as the result of an algorithm running on a device or on a Gateway.
Commands are actions that devices and gateways can perform when requested. For example, commands allow a user to start and stop logging data from a device, which is monitoring inertial measurements of a particular system.
Finally, properties define data that describes the state of a device or a gateway. For example, a device's serial number, firmware version, desired temperature setting for a thermostat, current operating mode ("On," "Off," "Standby") or battery level.
Strictly related to properties, events signals changes in a component’s properties set. An example event in the context of the ST AIoT Craft IoT API is the change in the isConnected property triggered when devices or gateways connect or disconnect from the internet.
We can summarize the entities of an IoT system managed by the ST AIoT Craft IoT API with the following picture:
2. From the entities to the cloud
Now that you have an understanding about the entities that the ST AIoT Craft IoT API manages, let’s move to the cloud, where the IoT API and related components are hosted.
The high-level architecture of the IoT API can be summarized by the following diagram:
As the diagram shows, the API provides a REST interface to the IoT Systems entities, which is consumed by the ST AIoT Craft web portal to provide the IoT functionality. The picture depicts several components, all running in an Azure environment provided by ST to ST AIoT Craft users, except for the AWS Cognito Identity Provider.
The ST AIoT Craft IoT API runs as an Azure function, a serverless compute service that executes code eliminating the need for server management. It automatically scales and charges only for execution time. It leverages three main cloud-native services from Azure: Azure Device Provisioning Service (DPS), Azure IoT Hub, and Azure CosmosDB.
The Azure DPS automates the provisioning and configuration of IoT devices, works with Azure IoT Hub, which in turn provides robust, bidirectional communication between provisioned devices and the cloud. With reference to the previous section, where we depicted the components of an IoT system, telemetries, commands, and properties are routed from devices to the cloud as messages through Azure IoT Hub. The third Azure native component leveraged by the ST AIoT Craft API is Azure CosmosDB, which provides a SQL database to store telemetries and events coming from connected devices: as a new telemetry or event reaches Azure IoT Hub, it gets automatically routed to the Azure CosmosDB service, which then stores the incoming data in the proper table in the database.
The last component of the ST AIoT Craft IoT API is AWS Cognito, which is an AWS native component, that provides a managed service for user authentication and access control. Its main role is to interact with the IoT API to authenticate and authorize the REST calls incoming from the ST AIoT Craft web portal.
This cloud infrastructure is provided by ST to all ST AIoT Craft users. It's possible to experiment with the IoT capabilities of the platform out-of-the-box, without the fuss of setting up the needed components. For advanced use cases, users can also set up their own Azure cloud infrastructure and connect it to ST AIoT Craft leveraging the provided Terraform scripts.
3. ST AIoT Craft IoT API interface
With a clear understanding of IoT system entities and a reference architecture, we can now explore the ST AIoT Craft IoT API interface, summarized with the following picture:
3.1 Example: a smart thermostat
For this example, we consider a very simple scenario consisting of a smart thermostat connected to the cloud and utilize the ST AIoT Craft API to provision it, and to observe its events and telemetries.
The smart thermostat that we use is a simulated device, which is part of the Azure IoT SDK, available in several programming languages. We use the Python implementation, which can be found in the Azure IoT Python SDK GitHub Repo.
Let us take a closer look to the capabilities of the smart thermostat, whose formal description is again available in the Azure IoT GitHub Repo. It follows the DTDL (Digital Twin Definition Language) syntax, which is an open-standard language for modeling real-world devices. It allows them to define their capabilities through properties, telemetries, and commands concepts at the beginning of this article.
From the smart thermostat DTDL model, we see it defines:
- A telemetry named temperature, providing the temperature of the room.
- A property named targetTemperature, allowing to specify the desired target temperature of the room.
- A property named maxTempSinceLastReboot, which returns the max temperature since the last device reboot.
- A command getMaxMinReport, which returns the max, min and average temperature recorded by the device.
Following this knowledge, let’s now use the ST AIoT Craft IoT API to provision the device and interact with it.
The first step in connecting a device to the cloud environment is to register it, so let’s call the dedicated endpoint of the API:
POST https://staiotcraft-iot-api-dev-efd9cxewbwbnfvgt.westeurope-01.azurewebsites.net/v1/devices
Authorization: Bearer ACCESS_TOKEN
{
"name": "example smart thermostat",
"project": "example_project",
"deployment": "example_deployment",
"isIoTEdgeCapable": false
}
With the above request, we are creating a new device named "example smart thermostat", which belongs to a project and a deployment named respectively "example_project" and "example_deployment". Projects and deployments are organizational concepts, which help to structure the provisioning of devices: a project is composed by one or more deployments, which in turn can be composed by one or more devices. The "isIoTEdgeCapable": false flag is specifying that the smart thermostat does not have gateway capabilities, rather it’s a simple connected device.
As the above API call is executed, we get the following response:
{
"id": "c8dc6706-a327-4f99-ab21-80010f667860",
"idScope": "0ne00D47E07",
"provisioningStatus": "enabled",
"tags": {
"name": "example smart thermostat",
"project": "example_project",
"deployment": "example_deployment",
"user": "f5c5a7a8-44fb-4b16-bcef-df8dc08fae8f"
},
"isIoTEdgeCapable": false,
"connectionState": "Disconnected",
"credentials": {
"type": "symmetricKey",
"symmetricKey": {
"primaryKey": "UHuGlQXGmClq6ts02WNaoMOQOXQRTfJpHXCgwnn2Xc26yjbQ+Jvxo9Zrpfz96+juy5Je5mo68sCeAIoT2Oh9tg==",
"secondaryKey": "xUzWWl4BcQldim1W/ISk3c9iV8mQJv6eaesXrBdkJR/+1N9wZWzEdAZox8kWSeGTy63Js4HXmooJAIoT9la9QQ=="
}
},
"properties": {
"desired": {}
},
"lastActivityTime": null,
"modelId": null,
"modules": null
}
There is a lot of information in the response, so we focus only on the most important ones.
The id field provides the unique id of our device, and we’ll be using it to identify the device when interacting with the IoT API as well as when we’ll be connecting our smart thermostat to the cloud.
The idScope provides the unique id of our cloud application, we’ll be using it in the next stage while connecting the device to the cloud environment.
The tags field contains metadata about our device, like its name, and the project and deployment it belongs to.
Finally, the credentials field contains the security keys, which are used by the cloud environment to authenticate our smart thermostat.
3.1.1 Connection of the smart thermostat to the cloud application
Not that we created a new device, it’s time to connect the smart thermostat to the cloud application.
To configure the example thermostat application to connect to the cloud environment, simply export the following BASH variables when starting the example Python code:
IOTHUB_DEVICE_SECURITY_TYPE="DPS"
IOTHUB_DEVICE_DPS_ID_SCOPE="0ne00D47E07"
IOTHUB_DEVICE_DPS_DEVICE_ID="c8dc6706-a327-4f99-ab21-80010f667860"
IOTHUB_DEVICE_DPS_DEVICE_KEY="UHuGlQXGmClq6ts02WNaoMOQOXQRTfJpHXCgwnn2Xc26yjbQ+Jvxo9Zrpfz96+juy5Je5mo68sCeAIoT2Oh9tg=="
If the configuration is correct, the smart thermostat application starts, providing startup messages like the following:
Starting at: 2025-08-13T13:03:40.079720+00:00
Device was assigned
staiotcraft-iothub-dev.azure-devices.net
c8dc6706-a327-4f99-ab21-80010f667860
Listening for command requests and property updates
Press Q to quit
Sending telemetry for temperature
Sent message
As shown in the message log, after a successful connection the thermostat starts sending its telemetries to the cloud. Let’s use the ST AIoT Craft IoT API to retrieve them.
To retrieve our device telemetries we can leverage the telemetries endpoint with the following API call:
GET https://staiotcraft-iot-api-dev-efd9cxewbwbnfvgt.westeurope-01.azurewebsites.net/v1/telemetries?projectID=example_project&deploymentID=example_deployment
Authorization: Bearer ACCESS_TOKEN
The above API call retrieves all telemetries of all devices belonging to the project named example_project and to the deployment named example_deployment. Since we created only one device, we’ll only get the telemetries transmitted of our smart thermostat device, which are provided us by the API response:
[
{
"deviceID": "c8dc6706-a327-4f99-ab21-80010f667860",
"timestamp": "2025-08-13T13:12:29.6760000Z",
"body": {
"temperature": 35
}
},
{
"deviceID": "c8dc6706-a327-4f99-ab21-80010f667860",
"timestamp": "2025-08-13T13:12:19.5040000Z",
"body": {
"temperature": 13
}
},
{
"deviceID": "c8dc6706-a327-4f99-ab21-80010f667860",
"timestamp": "2025-08-13T13:12:09.3320000Z",
"body": {
"temperature": 16
}
}
]
As shown above, the API returns an array of telemetries: each entry in such array is a telemetry sent by our smart thermostat device, and provides the following information:
- The deviceID is the unique identifier of the smart thermostat device: it’s the same ID that we got from the IoT API call when creating an entry for our new device.
- The timestamp field specifies the timestamp in which the telemetry has been generated by the device.
- The body field provides the transmitted telemetry, in our case a simulated temperature value.
Getting a device’s telemetries is not the only feature provided by the ST AIoT Craft IoT API, we can do a lot more. When our device connected to the cloud environment, a connection_state_event has been generated, signaling the successful connection of the device. Let’s get it with the following IoT API call:
GET https://staiotcraft-iot-api-dev-efd9cxewbwbnfvgt.westeurope-01.azurewebsites.net/v1/events?projectID=example_project&deploymentID=example_deployment
Authorization: Bearer ACCESS_TOKEN
The events endpoint leverages the same parameters as the previous API, returning all the events of all devices belonging to the project named example_project and to the deployment named example_deployment. Again, since we just have one device, we get all the events of our smart thermostat:
[{
"eventType": "connection_state_event",
"deviceID": "c8dc6706-a327-4f99-ab21-80010f667860",
"timestamp": "2025-08-13T13:04:28.0370000Z",
"body": {
"sequenceNumber": "000000000000000001DB26E3F31EC1C400000044000000000000000000000105",
"state": "deviceConnected"
}
}]
As we expect, we get a connection_state_event related to our device’s state that tells us that the connection to the cloud completed successfully.
3.1.2 How to interact with a device’s properties
Let’s now see an example of how to interact with a device’s properties. As our smart thermostat provides a dedicated property to set the target temperature of the room named targetTemperature, we can use the devices/{{deviceID}} endpoint to set it:
PUT https://staiotcraft-iot-api-dev-efd9cxewbwbnfvgt.westeurope-01.azurewebsites.net/v1/devices/c8dc6706-a327-4f99-ab21-80010f667860
Authorization: Bearer {{accessToken}}
{
"properties": {
"targetTemperature": 22.5
}
}
As the API call is executed, the desired value gets transmitted to our smart thermostat, which in turns prints the following output upon receiving the desired value:
the data in the desired properties patch was: {'$version': 2, 'targetTemperature': 22.5}The smart thermostat also provides a read-only property named maxTemperatureSinceLastReboot specifying the max temperature since the last device reboot, let’s use the IoT API to read it’s value. For this purpose we can leverage the same events endpoint we used earlier:
GET https://staiotcraft-iot-api-dev-efd9cxewbwbnfvgt.westeurope-01.azurewebsites.net/v1/events?projectID=example_project&deploymentID=example_deployment
Authorization: Bearer ACCESS_TOKEN
Since the API response will provide all events emitted by the smart thermostat so far. You may get several items in the resulting array, but a little bit of search will get you to the following entry:
{
"eventType": "change_event",
"deviceID": "c8dc6706-a327-4f99-ab21-80010f667860",
"timestamp": "2025-08-13T13:46:49.1280000Z",
"body": {
"version": 13766,
"properties": {
"reported": {
"maxTempSinceLastReboot": 10.96,
"$metadata": {
"$lastUpdated": "2025-08-13T13:46:49.0139609Z",
"maxTempSinceLastReboot": {
"$lastUpdated": "2025-08-13T13:46:49.0139609Z"
}
},
"$version": 13765
}
}
}
}
Which provides the reported value of the maxTempSinceLastReboot property of our smart thermostat (check the value of the deviceID field), along with the timestamp in which the property change occurred in the timestamp field.
Setting and reading properties allow us to interact with our devices, but oftentimes this is not enough. Many devices provide commands that allow for more complex interactions. This applies to our smart thermostat, as it provides a getMaxMinReport command, which returns the max, min, and average temperature recorded by the device.
Let’s use the ST AIoT Craft IoT API to request the execution of such a command. For this purpose, we can leverage the devices/{{deviceID}}/method endpoint:
POST https://staiotcraft-iot-api-dev-efd9cxewbwbnfvgt.westeurope-01.azurewebsites.net/v1/devices/ c8dc6706-a327-4f99-ab21-80010f667860/method
Authorization: Bearer ACCESS_TOKEN
{
"name": "getMaxMinReport"
}
As we execute the above API call, the command execution request gets to our smart thermostat, which prints the following output upon receiving it:
Command request received with payload
Payload was empty.
Done generating
{"avgTemp": 34.6, "endTime": "2025-08-13T16:39:54.062918", "maxTemp": 49, "minTemp": 10, "startTime": "2025-08-13T16:38:34.062890"}
These lines tell us that the device successfully received and executed the command we requested. In turn, it transmits the result back, which gets to us through the API’s response payload:
{
"avgTemp": 34.6,
"endTime": "2025-08-13T16:39:54.062918",
"maxTemp": 49,
"minTemp": 10,
"startTime": "2025-08-13T16:38:34.062890"
}
Now that we explored all capabilities of our smart thermostat, we can shut it down by hitting the q key in the terminal window in which the thermostat is running:
Sent message
Sent message
q
Quitting...
As the device shuts down, the connection to the cloud environment is closed. As we expect, by calling the events endpoint again, we get the confirmation that the smart thermostat device is offline by searching a deviceDisconnected event in the events array we get from the API’s response:
{
"eventType": "connection_state_event",
"deviceID": "c8dc6706-a327-4f99-ab21-80010f667860",
"timestamp": "2025-08-13T14:57:27.4580000Z",
"body": {
"sequenceNumber":
"000000000000000001DB26E3F31EC1C40000004400000000000000000000010D",
"state": "deviceDisconnected"
}
}Conclusion
In this article we saw how to leverage the ST AIoT Craft IoT API to register and connect a new device. Additionally, interacting with it to set and read the device’s properties, get related telemetries and invoke device’s commands. Try it out!
The ST AIoT Craft IoT API's capabilities extend beyond the examples in this article; it also provides interaction with gateway devices and their software modules.
