Skip to content

Overview

The data model defines the building blocks of device communication—services, alerts, states, and commands—which are combined with context to form meaningful API messages. It provides the structure needed to understand and interact with device behavior in SmartHQ.

Datamodel Datamodel

The image on the left is from the SmartHQ data model documentation for a dryer. On the right is an update message sent by SmartHQ over a WebSocket showing the change in cycle time when the user physically selected a different dryer cycle type.

Tip: Use the Devices and Services navigation sections in the left sidebarin the menu (click the icon above) to see everything supported.

To explore the data model, it is recommended to start with a device that interests you—found in the left sidebar under the "Devices" dropdownin the menu (click the icon above)—and review the services on the device's page to understand its capabilities and available data. You can then dive deeper into any service for more details through the "Services" dropdown or from links within a Device page. The "Common" navigation sections highlights the alerts and service that every device may support.

Conceptual Overview of Data Model

In the SmartHQ cloud, a device (e.g. Washing Machine, Coffee Brewer, etc.) consists of a collection of alerts and services. These components can be reused across many devices, increasing flexibility and reducing duplicated code. (Both a washer and dryer can send the cloud.smarthq.alert.endofcycle and both can use cloud.smarthq.service.mode)

Each device will have its own ID and other information about it, but the following text seeks to explain the concepts that make up devices.

Alerts

Alerts are messages sent from the device to SmartHQ whenever the corresponding event or action takes place within a device. These are predefined messages of important or relevant events for a SmartHQ device. An example of an alert is cloud.smarthq.alert.endofcycle.minutesleft.10, which a washing machine, dryer, or many other devices send to the SmartHQ cloud when there are 10 minutes left in a cycle.

Why use alerts? Alerts are already built for you and make being aware of the occurrence of common events simpler. You could continuously check the remaining time of a wash cycle yourself through our APIs to know when 10 minutes is left. However, this functionality is already built into SmartHQ for certain devices with cloud.smarthq.alert.endofcycle.minutesleft.10.

Commonly Asked Questions:

So is an "Alert" just a notification?

Not exactly. An alert is a message generated in the SmartHQ cloud when a specific event occurs on a user's device. By itself, an alert doesn't notify anyone—it simply exists in the system. To make use of alerts (e.g., to notify users), your app must actively access them through the Digital Twin API or subscribe to them via the Event Stream API. Alerts become notifications only when your app delivers them to users.

How do I know what alerts a device supports?

A list of alerts a device can send will be found on each device's page in the data model, such as washing machine alerts.

Where can I see a list of all the alerts offered in SmartHQ?

There is no single list of every alert offered, and this is intentional. Each alert will pertain to a particular device. Completely different devices may support the same type of alert, but the type of alerts depend on the device. That is why the data model is structured by device as this applies to domainTypes and other SmartHQ concepts as well.

What's the difference between Service Alerts and Alerts?

Service alerts are functionally the same alerts, except Service alerts typically pertains to messages indicating something went wrong with your device. An example a service alert is cloud.smarthq.alert.fault.keystuck which indicates a button on a device has been continuously pressed for a minute or longer. This alerts would inform you that the button is jammed or something is actively pressing it. These are the same service alerts that the SmartHQ Service Platform uses to diagnose issues with devices. Not all service alerts indicate problems, but that is the most common use case for service alerts. In washing machines, the service alert cloud.smarthq.alert.coinbox.capacity.50 is used to indicate the coinbox capacity reaches 50 percent, which does not pertain to any error state or issues.

How do I actually make use of alerts?

You can access alerts through...

For more information on how to practically use alerts, see the device control and monitoring tutorial on receiving device alerts.

Services

Services are virtual representations of physical features or functions on a SmartHQ-enabled device. Each service corresponds to a specific aspect of the device—such as temperature, cycle status, or time remaining—and allows SmartHQ to communicate with that feature. Services provide access to current states and allow commands to be sent to modify them. For example, a refrigerator includes a Fresh Food Setpoint Temperature Service, which reports the current temperature of the fresh food section and accepts commands to change it. Each device exposes a list of supported services, which collectively represent all of its SmartHQ-controllable capabilities.

"deviceType": "cloud.smarthq.device.refrigerator.freshfood",
"deviceId": "000000000000000000",
"services": [
    {
      "serviceType": "cloud.smarthq.service.temperature",
      "lastSyncTime": "2022-03-04T12:12:12.123Z",
      "domainType": "cloud.smarthq.domain.setpoint",
      "supportedCommands": [
        "cloud.smarthq.command.temperature.set"
      ],
      "state": {
        "celsiusConverted": 2.2222222222222223,
        "fahrenheit": 36.0
      },
      "serviceId": "000000000000000000000000000000000000000000000000",
      "serviceDeviceType": "cloud.smarthq.device.refrigerator",
      "config": {
        "fahrenheitMinimum": 34.0,
        "fahrenheitDefault": 37.0,
        "fahrenheitMaximum": 45.0,
        "celsiusDefaultConverted": 2.7777777777777777,
        "celsiusMaximumConverted": 7.222222222222222,
        "label": "Convertible drawer",
        "celsiusMinimumConverted": 1.1111111111111112
      },
      "lastStateTime": "2022-03-04T12:12:12.123Z"
    },
    ...
  ]
As an example, this is one of many services returned for a refrigerator device.

A service, identified by a tuple, has a state, and may also support commands that allow its state to be intentionally changed—if the service is designed to be controllable.

See Supported Services for understanding which services a device supports.

Tuple

A tuple is a shorthand term that refers to used to the combination of: serviceType, domainType, and serviceDeviceType. Together, these uniquely identify a controllable or observable aspect of a device.

Tuple Explanation

  • serviceDeviceType – The type of device the service applies to, e.g., cloud.smarthq.device.icemaker. Often times this can be a sub-device, like a ice-maker inside a refrigerator.
  • domainType – Used to explain where the service is located or its purpose.
  • serviceType – The specific service, e.g., cloud.smarthq.service.toggle

For example, a SmartHQ-supported air conditioner may return many services. One of them might include the following:

This tuple represents the air conditioner ambient inside temperature service

The same serviceType can be reused in different contexts. For example, cloud.smarthq.service.temperature, shown in the JSON above, is also used to describe the temperature of the fresh food section of a refrigerator.

The domain and device type provide essential context. The service itself is where the functionality resides.

State

A state is the current (last reported) value of a service. It reflects real-time information about a device’s condition or behavior.

For example, consider the refrigerator fresh food setpoint temperature service from the JSON above. In this case, the service reports that the internal temperature of the refrigerator's fresh food section is 36°F (or approximately 2.2°C). This state allows SmartHQ to reflect accurate, real-time data to the user or application.

"state": {
  "celsiusConverted": 2.2222222222222223,
  "fahrenheit": 36.0
}

Each service includes a state section on its documentation page, detailing the expected state fields along with an example response. For instance, see the Cycle Timer and Toggle services.

Commands

A command is an action sent via API to change the state of a service. Each command interacts with the service's state and configuration to perform specific actions.

For example, To start a washing machine cycle, you can send the cloud.smarthq.command.trigger.do.

Not all services support commands. Some, like the Meter service, are read-only—they report values (e.g., voltage) but cannot be controlled.

The same serviceType may support commands in one context but not another. For example:

Tip: To check if a service supports commands, view the service definition for the device. If a commands section is listed, the service is controllable.

Commonly Asked Questions:

How can I conceptualize services? What are they?

Within the SmartHQ app, you can see all the information about a device. That information is coming from these services in SmartHQ.

Why have services at all? Why can't I just call a POST /v1/refrigerator/set-temperature endpoint or something similar?

A service can be used multiple times in different contexts on the same device and across devices. For example, the temperature service is used by a refrigerator for thefreezer temperature setpoint and the refrigerator temperature setpoint.

By having the values within service changes from device to device, the API endpoints used to communicate this information can remain constant. This allows adding in new devices and services easily without needing to update the APIs directly. Instead, only the data model documentation here has to change.

What's the difference between deviceType and serviceDeviceType?
  • A deviceType is the highest level device and the main product the end-user commissioned to their account, i.e. refrigerators, air conditioners, etc.
  • A serviceDeviceType can be the main device or a sub-device. For example, this could cloud.smarthq.device.appliance which would represent the overall appliance or cloud.smarthq.device.waterfilter which is a sub-device in the SmartHQ data model.
How do I actually make use of services?

(https://developer.smarthq.com/apis/digital-twin#/Device%20Information%20and%20Control/get_v2_device) you can get all the devices, and the corresponding services, for a user's account. There are various different endpoints to access services.

Additionally, you can subscribe to changes in real-time updates in services through WebSockets or HTTPS / SNS Callbacks

For a more detailed guide, see our tutorial.

Supported Services

Not all devices support every service listed on their device documentation page. For example, different models of dishwashers may only support a subset of the services shown on the Dishwasher Services page. The listed services represent all possible services a device could support—not a guarantee that every device will support them all.

See Verifying Device Capabilities for a step-by-step tutorial to determine your specific device's services.

Property Management Accounts Only

The Property Management API extends standard SmartHQ functionality with additional features and data model components. As a result, some parts of the SmartHQ data model apply only to Property Management use cases.

These sections are clearly labeled as “Property Management Only.” If you're not intentionally using the Property Management API, you can safely ignore them.