Tutorial

This tutorial guides you through the SmartHQ data model and Digital Twin API, showing how to control and monitor devices, interpret API responses, and connect them to the data model documentation.

Goal of This Tutorial

By the end, you will feel confident using the Digital Twin API, understanding its responses, and leveraging the data model to start building your application.

Prerequisites¶

Before following this tutorial, ensure you have completed our Get Started steps.

1. List All Devices¶

Summary

First, call GET /v2/device from the Digital Twin API to see all the end-user's devices.

Now that you have created an account and set up an app in the SmartHQ ecosystem, the first recommended API call is GET /v2/device from the Digital Twin API. If the end-user has no devices, they have not commissioned any to their account. See Device Commissioning for more information.

Refer to the Responses section of the OpenAPI spec for an example response.

You can identify each device by the deviceType value, such as cloud.smarthq.device.dryer. When looking at the data model, the deviceType is shown under the Description section towards the top of each device page, as demonstrated in this dryer example.

The deviceId is a key piece of information—a string that uniquely identifies a device within the SmartHQ ecosystem. You will frequently use this deviceId in other API calls to retrieve device information and send commands.

Implementation Tip

Call the GET /v2/device in your application (passing the bearer token for that end-user in the authorization header) to see if they have the devices you intend for them to control. If your application is designed for washing machines, you can quickly determine if the end-user has a washing machine in their account to control and monitor.

2. See What Services a Device Supports¶

Summary

Second, call GET /v2/device/{deviceId} from the Digital Twin API to see all the services a device supports.

Tip: Please see the Conceptual Overview of the Data Model to understand the concept of services in the SmartHQ Data Model.

Now that you’ve obtained a deviceId in the previous step, you can use that to learn more about the particular device. Calling GET /v2/device/{deviceId} from the Digital Twin API will return detailed information about the device.

The information returned here largely mirrors what is shown in the data model documentation. For example, consider the Dryer Device, specified in the Data Model. This device, like every other device, is made up of alerts and services.

Looking at the response from GET /v2/device/{deviceId}, the response is composed of services and alerts with additional data about the device.

Warning

The data model documentation lists devices with all the services a device might support, but the device is not guaranteed to support every listed service and alert. For example, there’s a list of services a coffee brewer might support. To avoid errors in your application, use GET /v2/device/{deviceId} to confirm a specific device supports the services your app needs—similarly to how you’d use GET /v2/device to check if an end-user has a device.

Understanding the Response & Connection to Data Model Documentation¶

This section seeks to explain the response from GET /v2/device/{deviceId}, starting with a high-level overview and moving into the specifics.

The response from GET /v2/device/{deviceId} can be broken down into three main conceptual sections: (click on the "Alerts", "Services", and "Device Metadata" tabs below this line to see each section).

AlertsServicesDevice Metadata

Tip: Learn more about alerts here and how they work in SmartHQ

All information about a device's alerts falls under the alertTypes key. The alertTypes array lists the alerts this device can send to the SmartHQ ecosystem.

As an example, for a dryer, the alertTypes response could be:

"alertTypes": [
    "cloud.smarthq.alert.endofcycle",
    "cloud.smarthq.alert.endofcycle.minutesafter.30",
    "cloud.smarthq.alert.endofcycle.minutesleft.10",
    "cloud.smarthq.alert.endofcycle.minutesleft.15",
    "cloud.smarthq.alert.endofcycle.minutesleft.5",
    "cloud.smarthq.alert.inventory.sheetsleft.10",
    "cloud.smarthq.alert.inventory.sheetsleft.15",
    "cloud.smarthq.alert.inventory.sheetsleft.5",
    "cloud.smarthq.alert.startofcycle"
    ...
],

All these alerts are listed under the alerts section of the dryer.

Tip: Learn more about services here and how they work in SmartHQ

The response from GET /v2/device/{deviceId} lists all the services the device supports under the services key.

This is an example service for a dryer (deviceType: cloud.smarthq.device.dryer):

.. &qu

response. Please refer to the Digital Twin OpenAPI specification for accurate details.

Each service entry can be conceptually understood by following this process:

Start with the serviceType.
```
"deviceType": "cloud.smarthq.device.dryer",
...
"services": [
    {
        "serviceType": "cloud.smarthq.service.cycletimer",
        ...
    },
    ...
]
```
Navigate to the device page for your device. In this case, since the deviceType is cloud.smarthq.device.dryer, you would navigate to the Dryer page. On that page, search for the serviceType—in this case, cloud.smarthq.service.cycletimer.

Here, both the Dryer Cycle Timer V2 Service and Washer Cycle Timer V2 Service correspond to the generic service cloud.smarthq.service.cycletimer.

To see which context this entry applies to, use the domainType. Here, the domainType is cloud.smarthq.domain.state, which corresponds to Dryer Cycle Timer Service. In essence, this is the generic cycle timer service applied to the dryer’s remaining-time state. (This is stated in the "Tuple" description under Dryer Cycle Timer Service.)
Look at the state.
```
"deviceType": "cloud.smarthq.device.dryer",
...
"services": [
    {
        ...
        "state": {
            "secondsRemaining": 3468
        },
        ...
    },
    ...
]
```
The secondsRemaining state for cloud.smarthq.service.cycletimer can be found in the "State" section of that service. It tells you the active information about the service. In this case, this says the dryer cycle time remaining is 3468 seconds.
Look at the config.
```
"deviceType": "cloud.smarthq.device.dryer",
...
"services": [
    {
        ...
        "config": {
            "granularity": "cloud.smarthq.type.timergranularity.seconds"
        },
        ...
    },
    ...
]
```
The config tells you about the data type used for the state. Here, the granularity value is cloud.smarthq.type.timergranularity.seconds. You can verify this in the Configuration table of the cloud.smarthq.service.cycletimer service, which lists valid time granularities under Data Types.

In our example, the state value 3,468 has a granularity of seconds.

Tip

Although secondsRemaining suggests seconds, the config could specify minutes, hours, or days. Always check the config to confirm data types.

Look at the supportedCommands.

"deviceType": "cloud.smarthq.device.dryer",
...
"services": [
    {
        ...
        "supportedCommands": [],
        ...
    },
    ...
]

In our example, there are no supported commands. You can verify this on the service page in the data model documentation for cloud.smarthq.service.cycletimer, which has no “Commands” section.

Here’s an example of a service with supported commands:

"deviceType": "cloud.smarthq.device.dryer",
...
"services": [
    {
        "serviceType": "cloud.smarthq.service.trigger",
        "lastSyncTime": "2025-03-22T10:22:10.487Z",
        "domainType": "cloud.smarthq.domain.start",
        "supportedCommands": [
            "cloud.smarthq.command.trigger.do"
        ],
        "state": {
            "disabled": true
        },
        "serviceId": "7cfd0b2586c72cb2c4d3c84c5cb34352d8d627f974b92d772...",
        "serviceDeviceType": "cloud.smarthq.device.dryer",
        "config": {},
        "lastStateTime": "2025-03-22T10:22:11.345Z"
    },
    ...
]

Warning: The above is a hypothetical example and may differ slightly from the current API response. Please refer to the Digital Twin OpenAPI specification for accurate details.

Following the same process—starting with serviceType, then using domainType and serviceDeviceType to identify the tuple—this corresponds to the Dryer Start Cycle Trigger Service, which allows you to start a dryer cycle. The command context is best understood by examining the tuple.

Tip

To actually use this command, see the section below.

Remaining Fields in a Service.

The remaining data provides additional information about the service. For example, the serviceId can be used in other API calls to refer to that specific service.

The response from GET /v2/device/{deviceId} includes the device metadata outside of the "services" and "alerts" sections.

3. Send a Command¶

Summary

Third, call POST /v2/command from the Digital Twin API to send a command to a single device to control its behavior (e.g., change a temperature, start a cycle).

Now that we have seen how to:

get a list of all devices an end-user has using GET /v2/device to obtain a deviceId,
see information about a specific device, such as the commands it supports, using GET /v2/device/{deviceId},

we can send a command to the device to control it.

Sending a command can be done through two API endpoints:

POST /v2/command to send a command to a single device
POST /v2/commands to send commands to multiple devices.

Examples

To set the mode on the appliance, issue the cloud.smarthq.command.dishwasher.mode.v1.set command. Example for setting heavy mode, no delay, max dry, and both wash zones:

{
    "kind": "service#command",
    "deviceId": "173e3b45f3dbcb3f9559d91844ce4912e1c4a38a1b812afeb859ed2cc213a4cb",
    "serviceType": "cloud.smarthq.service.dishwasher.mode.v1",
    "domainType": "cloud.smarthq.domain.dishwasher.heavy",
    "serviceDeviceType": "cloud.smarthq.device.dishwasher",
    "command": {
        "commandType": "cloud.smarthq.command.dishwasher.mode.v1.set",
        "delayStartValue": 1,
        "heatedDry": "cloud.smarthq.type.dishwasher.heateddry.maxdry",
        "washZone": "cloud.smarthq.type.dishwasher.washzone.both"
    }
}

To start the cycle on a dishwasher, you need to issue the start command:

{
    "kind": "service#command",
    "deviceId": "173e3b45f3dbcb3f9559d91844ce4912e1c4a38a1b812afeb859ed2cc213a4cb",
    "serviceType": "cloud.smarthq.service.dishwasher.state.v1",
    "domainType": "cloud.smarthq.domain.dishwasher",
    "serviceDeviceType": "cloud.smarthq.device.dishwasher",
    "command": {
        "commandType": "cloud.smarthq.command.dishwasher.state.v1.start"
    }
}

To stop the cycle on a dishwasher, you need to issue the stop command:

{
    "kind": "service#command",
    "deviceId": "173e3b45f3dbcb3f9559d91844ce4912e1c4a38a1b812afeb859ed2cc213a4cb",
    "serviceType": "cloud.smarthq.service.dishwasher.state.v1",
    "domainType": "cloud.smarthq.domain.dishwasher",
    "serviceDeviceType": "cloud.smarthq.device.dishwasher",
    "command": {
        "commandType": "cloud.smarthq.command.dishwasher.state.v1.stop"
    }
}

4. Receive Device Alerts¶

To receive alerts from a device in your application or integration, see the Real-Time Device Updates page.