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 selects 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 section 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.

Services

A service is simply a JSON object that represents a specific feature or function of a SmartHQ-enabled device, such as temperature, cycle status, or time remaining. Each service corresponds to a particular aspect of the device 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 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. Oftentimes this can be a sub-device, like an 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.

See Example Service Explanation below for a detailed explanation of the Meter service.

This breaks down these topics with a thorough and practical example.

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.

Config

The config defines the operational characteristics and constraints of a service, determining how it functions and what values it can accept. It contains properties that specify the service's behavior.

See the Example Service Explanation below to see how config is used in the meter service. The config is used in similar ways across many services.

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 the freezer 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, e.g., refrigerators, air conditioners, etc.
  • A serviceDeviceType can be the main device or a sub-device. For example, this could be 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 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.

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 about 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 pertains to a particular device. Completely different devices may support the same type of alert, but the types 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 as regular alerts, except service alerts typically pertain 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 alert 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. In washing machines, the service alert cloud.smarthq.alert.coinbox.capacity.50 is used to indicate the coinbox capacity has reached 50 percent, which does not pertain to any error state or issue.

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.

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.

Example Service Explanation

What This Section Explains:

The following example applies to the Meter Service.

This documentation further explains everything in the meter service documentation page. The general principles can be applied to all services.

General Info

The meter service represents the state of a meter within an appliance. This service can be used to represent multiple meters within the same appliance.

serviceType:

This will always be cloud.smarthq.service.meter

lastSyncTime:

This is the last time that the appliance received a sync command.

domainType:

This property declares the context that the meter service will be used in. In the first service example (see below), the domain is voltage, so we can determine that the units that are being measured would be volts.

In the second example, the domain is cold water, so the units would be a volumetric unit like liters or cubic feet.

supportedCommands:

Some services support commands that can change what the appliance is doing. At this time, there are no commands associated with the meter service.

state:

This is the current status of the service. meterValue is the only required property.

  • meterValue - double

    This is the actual value of the meter. For example, this could be the cumulative energy consumed by an appliance in kWh. The config object determines if this value is instantaneous or cumulative, measured or estimated, and the units of measure.

  • meterValueDelta - double

    This is the difference between the current meterValue and the previous meterValue. If the previous meterValue is unknown, this value is set to null.

  • disabled - boolean

    This indicates whether this service is disabled.

  • updateFrequencySeconds - integer

    This is the number of seconds that determines how often the state is updated. If you want to measure the instantaneous flow of water from a water heater (Service Example 2), it could be used to trigger an alert when you’re using a lot more water than expected (unit is leaking).

serviceId:

This value is a unique identifier of the instance of the service that is randomly generated, so the values of other properties will have no influence on this value.

serviceDeviceType

The serviceDeviceType is used as a unique tuple with serviceType and domainType to identify a specific component or sub-device.

The serviceDeviceType describes the service on the appliance.

For example, a refrigerator (deviceType) could have a service for a light (serviceDeviceType) that would toggle (serviceType) power (domainType) on or off.

Another example could be a refrigerator with a service where the serviceDeviceType is cloud.smarthq.device.meter because that service is used to measure the cumulative cold water usage of the appliance.

In this example, the appliance’s deviceType (found in the Device Information Response) is refrigerator, the serviceDeviceType is meter, the domainType is water and the serviceType is meter.

config:

These are the properties that will determine how the service is used. All properties are required.

  • reading
    Prefix: cloud.smarthq.type.reading. Accepted values: measured, estimated

reading can be either measured in the event that this service is used to actually read something from a component on the appliance or estimated if this service is not reading from a component and could be based on other information from the appliance (e.g. a meter service used to estimate the voltage draw over the next 12 hours).

  • measurement
    Prefix: cloud.smarthq.type.measurement. Accepted values: instantaneous, cumulative

measurement determines whether this is a value that’s determined by a single point in time or aggregates multiple previous data points. If you wanted to represent the current voltage draw, use instantaneous. If you want to represent the voltage drawn over the past week of usage, use cumulative.

  • meterUnits
    Prefix: cloud.smarthq.type.meterunits. Accepted values: kwh, volts, amps, liters, mililiters, cubicfeet

meterUnits is where the units are defined for the value that is represented in the state object. This is also dependent on the service’s domainType. If the domain is voltage, you wouldn’t be using liters as a unit of measure.

lastStateTime:

This is the last time that the service’s state was updated.

Example Service 1: Instantaneous Measured Voltage of a Meter
{
"serviceType": "cloud.smarthq.service.meter",
"lastSyncTime": "2024-03-19T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.voltage",
"supportedCommands": [],
"state": {
"meterValue": 14.5,
"meterValueDelta": 1.0,
"disabled": false,
"updateFrequencySeconds": 15
},
"serviceId": "instantaneousMeasuredVoltageMeterService",
"serviceDeviceType": "cloud.smarthq.device.meter",
"config": {
"reading": "cloud.smarthq.type.reading.measured",
"meterUnits": "cloud.smarthq.type.meterunits.volts",
"measurement": "cloud.smarthq.type.measurement.instantaneous"
},
"lastStateTime": "2024-03-19T12:12:12.123Z"
}
Example Service 2: Instantaneous Measured Cold Water of a Water Heater
{
"serviceType": "cloud.smarthq.service.meter",
"lastSyncTime": "2024-03-19T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.water.cold",
"supportedCommands": [],
"state": {
"meterValue": 230.3,
"meterValueDelta": 133.0,
"disabled": false,
"updateFrequencySeconds": 5
},
"serviceId": "23a09410b19623f4afac4afa3b96bca3b951dcb998339d057bb854672e107293",
"serviceDeviceType": "cloud.smarthq.device.meter",
"config": {
"reading": "cloud.smarthq.type.reading.measured",
"meterUnits": "cloud.smarthq.type.meterunits.liters",
"measurement": "cloud.smarthq.type.measurement.instantaneous"
},
"lastStateTime": "2024-03-19T12:12:12.123Z"
}
Example Service 3: Cumulative Estimated Hot Water of a Water Heater
{
"serviceType": "cloud.smarthq.service.meter",
"lastSyncTime": "2024-03-19T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.water.hot",
"supportedCommands": [],
"state": {
"meterValue": 145.2,
"updateFrequencySeconds": 21600
},
"serviceId": "38c79410b19623f4afac4afa3b96bca3b951dcb998339d057bb854672e105130",
"serviceDeviceType": "cloud.smarthq.device.meter",
"config": {
"reading": "cloud.smarthq.type.reading.estimated",
"meterUnits": "cloud.smarthq.type.meterunits.liters",
"measurement": "cloud.smarthq.type.measurement.cumulative"
},
"lastStateTime": "2024-03-19T12:12:12.123Z"
}

Next Steps: See this tutorial for an in-depth look at practically using services and alerts through our APIs.