cloud.smarthq.service.thermostat.v1¶
Description¶
Service for controlling a thermostat. This is a complex service with multiple config and state parameters to accurately model the control of an air conditioner or heater.
Behaviors¶
A service may specify a behavior the device enforces that otherwise is not specified by the config. Each behavior is unique and a client should take into account the behavior when integrating with a service. A service may have multiple behaviors declared.
| Behavior | Documentation |
|---|---|
| cloud.smarthq.behavior.fanonlynoauto | When in fan only mode the auto fanSpeed does not work |
| cloud.smarthq.behavior.zonelinemaximumtemperaturesv1 | Supported maximum temperatures are 65F, 70F, 72F, 74F, 76F, 78F, 80F, 85F |
| cloud.smarthq.behavior.zonelineminimumtemperaturesv1 | Supported minimum temperatures are 60F, 64F, 66F, 68F, 70F, 72F, 74F, 76F |
Example Device Response (Digital Twin API)¶
Service representing thermostat for airconditioner.
{
"adapterId": "0000000000000000000000000000000000000000",
"alertTypes": [],
"createdDateTime": "2022-03-04T12:12:12.123Z",
"deviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"deviceType": "cloud.smarthq.device.airconditioner",
"gatewayId": "0000000000000000000000000000000000000000000000000000000000000000",
"kind": "device#item",
"lastPresenceTime": "2022-03-04T12:12:12.123Z",
"lastSyncTime": "2022-03-04T12:12:12.123Z",
"presence": "OFFLINE",
"removable": true,
"services": [
{
"serviceType": "cloud.smarthq.service.thermostat.v1",
"lastSyncTime": "2022-03-04T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.thermostat",
"supportedCommands": [
"cloud.smarthq.command.thermostat.v1.set"
],
"state": {
"mode": "cloud.smarthq.type.thermostatmode.cool",
"coolCelsiusConverted": 21.666666666666668,
"fanSpeed": "cloud.smarthq.type.fanspeed.high",
"coolFahrenheit": 71.0,
"on": true
},
"serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"serviceDeviceType": "cloud.smarthq.device.airconditioner",
"config": {
"heatFahrenheitMaximum": 86.0,
"coolFahrenheitMinimum": 62.0,
"heatCelsiusMaximumConverted": 30.0,
"coolCelsiusMaximumConverted": 30.0,
"heatCelsiusMinimumConverted": 16.666666666666668,
"supportedFanSpeeds": [
"cloud.smarthq.type.fanspeed.auto",
"cloud.smarthq.type.fanspeed.high",
"cloud.smarthq.type.fanspeed.medium",
"cloud.smarthq.type.fanspeed.low"
],
"supportedModes": [
"cloud.smarthq.type.thermostatmode.cool",
"cloud.smarthq.type.thermostatmode.fanonly",
"cloud.smarthq.type.thermostatmode.heat",
"cloud.smarthq.type.thermostatmode.dry",
"cloud.smarthq.type.thermostatmode.cool.energysaver"
],
"coolCelsiusMinimumConverted": 16.666666666666668,
"supportsEcoMode": false,
"coolFahrenheitMaximum": 86.0,
"supportedFanBehaviors": [
"cloud.smarthq.type.fanbehavior.quiet",
"cloud.smarthq.type.fanbehavior.normal",
"cloud.smarthq.type.fanbehavior.turbo"
],
"heatFahrenheitMinimum": 62.0,
"supportsSwing": false
},
"lastStateTime": "2022-03-04T12:12:12.123Z"
}
],
"userId": "000000000000000"
}
Configuration¶
The following are properties for the gateway/device sync as part of the "config" object for each individual service.
| Field Name | Property Type | Required | Calculated |
|---|---|---|---|
| coolCelsiusMaximum | DOUBLE | No | |
| coolCelsiusMaximumAllowedMaximumConverted | DOUBLE | No | Yes |
| coolCelsiusMaximumAllowedMinimumConverted | DOUBLE | No | Yes |
| coolCelsiusMaximumConverted | DOUBLE | No | Yes |
| coolCelsiusMinimum | DOUBLE | No | |
| coolCelsiusMinimumAllowedMaximumConverted | DOUBLE | No | Yes |
| coolCelsiusMinimumAllowedMinimumConverted | DOUBLE | No | Yes |
| coolCelsiusMinimumConverted | DOUBLE | No | Yes |
| coolFahrenheitMaximum | DOUBLE | No | |
| coolFahrenheitMaximumAllowedMaximum | DOUBLE | No | |
| coolFahrenheitMaximumAllowedMinimum | DOUBLE | No | |
| coolFahrenheitMaximumConverted | DOUBLE | No | Yes |
| coolFahrenheitMinimum | DOUBLE | No | |
| coolFahrenheitMinimumAllowedMaximum | DOUBLE | No | |
| coolFahrenheitMinimumAllowedMinimum | DOUBLE | No | |
| coolFahrenheitMinimumConverted | DOUBLE | No | Yes |
| coolMaximumConfigurable | BOOLEAN | No | |
| coolMinimumConfigurable | BOOLEAN | No | |
| heatCelsiusMaximum | DOUBLE | No | |
| heatCelsiusMaximumAllowedMaximumConverted | DOUBLE | No | Yes |
| heatCelsiusMaximumAllowedMinimumConverted | DOUBLE | No | Yes |
| heatCelsiusMaximumConverted | DOUBLE | No | Yes |
| heatCelsiusMinimum | DOUBLE | No | |
| heatCelsiusMinimumAllowedMaximumConverted | DOUBLE | No | Yes |
| heatCelsiusMinimumAllowedMinimumConverted | DOUBLE | No | Yes |
| heatCelsiusMinimumConverted | DOUBLE | No | Yes |
| heatFahrenheitMaximum | DOUBLE | No | |
| heatFahrenheitMaximumAllowedMaximum | DOUBLE | No | |
| heatFahrenheitMaximumAllowedMinimum | DOUBLE | No | |
| heatFahrenheitMaximumConverted | DOUBLE | No | Yes |
| heatFahrenheitMinimum | DOUBLE | No | |
| heatFahrenheitMinimumAllowedMaximum | DOUBLE | No | |
| heatFahrenheitMinimumAllowedMinimum | DOUBLE | No | |
| heatFahrenheitMinimumConverted | DOUBLE | No | Yes |
| heatMaximumConfigurable | BOOLEAN | No | |
| heatMinimumConfigurable | BOOLEAN | No | |
| humidityMaximum | INTEGER | No | |
| humidityMinimum | INTEGER | No | |
| supportedFanBehaviors | SET<FAN_BEHAVIOR> | No | |
| supportedFanSpeeds | SET<FANSPEED> | Yes | |
| supportedModes | SET<THERMOSTATMODE> | Yes | |
| supportsEcoMode | BOOLEAN | No | |
| supportsHumidity | BOOLEAN | No | |
| supportsPump | BOOLEAN | No | |
| supportsSwing | BOOLEAN | No | |
| temperatureBufferCelsiusMinimum | DOUBLE | No | |
| temperatureBufferFahrenheitMinimum | DOUBLE | No |
State¶
The following are properties for the device state report as part of the "state" object for each individual service.
| Field Name | Property Type | Required | Calculated |
|---|---|---|---|
| coolCelsius | DOUBLE | No | |
| coolCelsiusConverted | DOUBLE | No | Yes |
| coolFahrenheit | DOUBLE | No | |
| coolFahrenheitConverted | DOUBLE | No | Yes |
| disabled | BOOLEAN | No | |
| ecoMode | BOOLEAN | No | |
| fanBehavior | FAN_BEHAVIOR | No | |
| fanSpeed | FANSPEED | Yes | |
| heatCelsius | DOUBLE | No | |
| heatCelsiusConverted | DOUBLE | No | Yes |
| heatFahrenheit | DOUBLE | No | |
| heatFahrenheitConverted | DOUBLE | No | Yes |
| humidity | INTEGER | No | |
| mode | THERMOSTATMODE | Yes | |
| on | BOOLEAN | Yes | |
| pump | BOOLEAN | No | |
| swing | BOOLEAN | No |
Commands¶
The following are properties for both the Digital Twin API to send a command to the device as well as the properties passed as part of a command to the gateway to be processed by the device itself.
cloud.smarthq.command.thermostat.v1.set¶
Command to set the state on the thermostat service. Depending on which parameters are provided different aspects of the thermostat can be modified such as turning it on or off, changing the mode, changing the fan speed, or setting swing.
| Field Name | Property Type | Required | Calculated |
|---|---|---|---|
| coolCelsius | DOUBLE | No | |
| coolCelsiusConverted | DOUBLE | No | Yes |
| coolFahrenheit | DOUBLE | No | |
| coolFahrenheitConverted | DOUBLE | No | Yes |
| ecoMode | BOOLEAN | No | |
| fanBehavior | FAN_BEHAVIOR | No | |
| fanSpeed | FANSPEED | No | |
| heatCelsius | DOUBLE | No | |
| heatCelsiusConverted | DOUBLE | No | Yes |
| heatFahrenheit | DOUBLE | No | |
| heatFahrenheitConverted | DOUBLE | No | Yes |
| humidity | INTEGER | No | |
| mode | THERMOSTATMODE | No | |
| on | BOOLEAN | No | |
| pump | BOOLEAN | No | |
| swing | BOOLEAN | No |
Example Commands¶
Command to set the thermostatmode.
{
"command": {
"mode": "cloud.smarthq.type.thermostatmode.cool",
"commandType": "cloud.smarthq.command.thermostat.v1.set"
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.thermostat",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.airconditioner",
"serviceType": "cloud.smarthq.service.thermostat.v1"
}
Supported Outcomes¶
Each service has an allow listed set of outcomes that the device may return when asked to execute a command.
| Outcome | Documentation |
|---|---|
| cloud.smarthq.outcome.badrequest | The request was invalid. |
| cloud.smarthq.outcome.developererror | Only used when there is a server side bug |
| cloud.smarthq.outcome.deviceoffline | The device is offline. |
| cloud.smarthq.outcome.forbidden | The request is forbidden due to permissions. |
| cloud.smarthq.outcome.internalerror | The server had an issue processing the request |
| cloud.smarthq.outcome.missingconfig | The service config is missing |
| cloud.smarthq.outcome.missingstate | The service state is missing |
| cloud.smarthq.outcome.notallowed | The command is not allowed. |
| cloud.smarthq.outcome.notfound | The request is forbidden due to permissions. |
| cloud.smarthq.outcome.notsupported | The command is not supported. |
| cloud.smarthq.outcome.outofbounds | General out of bounds error |
| cloud.smarthq.outcome.servicedisabled | Feature is currently disabled |
| cloud.smarthq.outcome.success | Successful request |
| cloud.smarthq.outcome.timeout | The server experienced timeout waiting for a response from the gateway |
| cloud.smarthq.outcome.unavailablemode | The mode is unavailable. |
cloud.smarthq.command.thermostat.v1.set.maximum¶
Auxilary command used to change the maximum heat temperature on the thermostat on supported units.
| Field Name | Property Type | Required | Calculated |
|---|---|---|---|
| celsius | DOUBLE | No | |
| celsiusConverted | DOUBLE | No | Yes |
| fahrenheit | DOUBLE | No | |
| fahrenheitConverted | DOUBLE | No | Yes |
| mode | THERMOSTATMODE | No |
Example Commands¶
Command to change the maximum heat temperature on the thermostat .
{
"command": {
"mode": "cloud.smarthq.type.thermostatmode.heat",
"commandType": "cloud.smarthq.command.thermostat.v1.set.maximum",
"fahrenheit": 60.0
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.thermostat",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.vtac",
"serviceType": "cloud.smarthq.service.thermostat.v1"
}
Supported Outcomes¶
Each service has an allow listed set of outcomes that the device may return when asked to execute a command.
| Outcome | Documentation |
|---|---|
| cloud.smarthq.outcome.badrequest | The request was invalid. |
| cloud.smarthq.outcome.developererror | Only used when there is a server side bug |
| cloud.smarthq.outcome.deviceoffline | The device is offline. |
| cloud.smarthq.outcome.forbidden | The request is forbidden due to permissions. |
| cloud.smarthq.outcome.internalerror | The server had an issue processing the request |
| cloud.smarthq.outcome.missingconfig | The service config is missing |
| cloud.smarthq.outcome.missingstate | The service state is missing |
| cloud.smarthq.outcome.notallowed | The command is not allowed. |
| cloud.smarthq.outcome.notfound | The request is forbidden due to permissions. |
| cloud.smarthq.outcome.notsupported | The command is not supported. |
| cloud.smarthq.outcome.outofbounds | General out of bounds error |
| cloud.smarthq.outcome.servicedisabled | Feature is currently disabled |
| cloud.smarthq.outcome.success | Successful request |
| cloud.smarthq.outcome.timeout | The server experienced timeout waiting for a response from the gateway |
cloud.smarthq.command.thermostat.v1.set.minimum¶
Auxilary command used to change the maximum cool temperature on the thermostat on supported units.
| Field Name | Property Type | Required | Calculated |
|---|---|---|---|
| celsius | DOUBLE | No | |
| celsiusConverted | DOUBLE | No | Yes |
| fahrenheit | DOUBLE | No | |
| fahrenheitConverted | DOUBLE | No | Yes |
| mode | THERMOSTATMODE | No |
Example Commands¶
Command to change the minimum heat temperature on the thermostat .
{
"command": {
"mode": "cloud.smarthq.type.thermostatmode.heat",
"commandType": "cloud.smarthq.command.thermostat.v1.set.minimum",
"fahrenheit": 59.0
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.thermostat",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.vtac",
"serviceType": "cloud.smarthq.service.thermostat.v1"
}
Supported Outcomes¶
Each service has an allow listed set of outcomes that the device may return when asked to execute a command.
| Outcome | Documentation |
|---|---|
| cloud.smarthq.outcome.badrequest | The request was invalid. |
| cloud.smarthq.outcome.developererror | Only used when there is a server side bug |
| cloud.smarthq.outcome.deviceoffline | The device is offline. |
| cloud.smarthq.outcome.forbidden | The request is forbidden due to permissions. |
| cloud.smarthq.outcome.internalerror | The server had an issue processing the request |
| cloud.smarthq.outcome.missingconfig | The service config is missing |
| cloud.smarthq.outcome.missingstate | The service state is missing |
| cloud.smarthq.outcome.notallowed | The command is not allowed. |
| cloud.smarthq.outcome.notfound | The request is forbidden due to permissions. |
| cloud.smarthq.outcome.notsupported | The command is not supported. |
| cloud.smarthq.outcome.outofbounds | General out of bounds error |
| cloud.smarthq.outcome.servicedisabled | Feature is currently disabled |
| cloud.smarthq.outcome.success | Successful request |
| cloud.smarthq.outcome.timeout | The server experienced timeout waiting for a response from the gateway |
Data Types¶
BOOLEAN¶
Value must be either true or false.
DOUBLE¶
Value must be an double. Field specific restrictions such as a minimum and maximum may apply depending on the field.
INTEGER¶
Value must be an integer. Field specific restrictions such as a minimum and maximum may apply depending on the field.
FANSPEED¶
| FANSPEED | Documentation |
|---|---|
| cloud.smarthq.type.fanspeed.auto | Fan speed of automatic |
| cloud.smarthq.type.fanspeed.circulate | Fan speed of circulate |
| cloud.smarthq.type.fanspeed.high | Fan speed of high |
| cloud.smarthq.type.fanspeed.low | Fan speed of low |
| cloud.smarthq.type.fanspeed.medium | Fan speed of medium |
| cloud.smarthq.type.fanspeed.off | Fan speed of off |
| cloud.smarthq.type.fanspeed.on | Fan speed of on |
| cloud.smarthq.type.fanspeed.unknown | Unknown |
FAN_BEHAVIOR¶
| FAN_BEHAVIOR | Documentation |
|---|---|
| cloud.smarthq.type.fanbehavior.normal | Normal |
| cloud.smarthq.type.fanbehavior.notapplicable | Not Applicable |
| cloud.smarthq.type.fanbehavior.quiet | Quiet |
| cloud.smarthq.type.fanbehavior.turbo | Turbo |
SET<FANSPEED>¶
| SET<FANSPEED> | Documentation |
|---|---|
| cloud.smarthq.type.fanspeed.auto | Fan speed of automatic |
| cloud.smarthq.type.fanspeed.circulate | Fan speed of circulate |
| cloud.smarthq.type.fanspeed.high | Fan speed of high |
| cloud.smarthq.type.fanspeed.low | Fan speed of low |
| cloud.smarthq.type.fanspeed.medium | Fan speed of medium |
| cloud.smarthq.type.fanspeed.off | Fan speed of off |
| cloud.smarthq.type.fanspeed.on | Fan speed of on |
| cloud.smarthq.type.fanspeed.unknown | Unknown |
SET<FAN_BEHAVIOR>¶
| SET<FAN_BEHAVIOR> | Documentation |
|---|---|
| cloud.smarthq.type.fanbehavior.normal | Normal |
| cloud.smarthq.type.fanbehavior.notapplicable | Not Applicable |
| cloud.smarthq.type.fanbehavior.quiet | Quiet |
| cloud.smarthq.type.fanbehavior.turbo | Turbo |
SET<THERMOSTATMODE>¶
| SET<THERMOSTATMODE> | Documentation |
|---|---|
| cloud.smarthq.type.thermostatmode.auto | Automatic |
| cloud.smarthq.type.thermostatmode.auto.twotemperature | Automatic Two Temperature |
| cloud.smarthq.type.thermostatmode.continuous | Continuous |
| cloud.smarthq.type.thermostatmode.cool | Cool |
| cloud.smarthq.type.thermostatmode.cool.energysaver | Energy Saver |
| cloud.smarthq.type.thermostatmode.cool.quiet | Cool Quiet |
| cloud.smarthq.type.thermostatmode.cool.turbo | Cool Turbo |
| cloud.smarthq.type.thermostatmode.dry | Dry |
| cloud.smarthq.type.thermostatmode.external | External Thermostat |
| cloud.smarthq.type.thermostatmode.fanonly | Fan Only |
| cloud.smarthq.type.thermostatmode.heat | Heat |
| cloud.smarthq.type.thermostatmode.off | Off |
| cloud.smarthq.type.thermostatmode.on | On |
| cloud.smarthq.type.thermostatmode.unknown | Unknown |
THERMOSTATMODE¶
| THERMOSTATMODE | Documentation |
|---|---|
| cloud.smarthq.type.thermostatmode.auto | Automatic |
| cloud.smarthq.type.thermostatmode.auto.twotemperature | Automatic Two Temperature |
| cloud.smarthq.type.thermostatmode.continuous | Continuous |
| cloud.smarthq.type.thermostatmode.cool | Cool |
| cloud.smarthq.type.thermostatmode.cool.energysaver | Energy Saver |
| cloud.smarthq.type.thermostatmode.cool.quiet | Cool Quiet |
| cloud.smarthq.type.thermostatmode.cool.turbo | Cool Turbo |
| cloud.smarthq.type.thermostatmode.dry | Dry |
| cloud.smarthq.type.thermostatmode.external | External Thermostat |
| cloud.smarthq.type.thermostatmode.fanonly | Fan Only |
| cloud.smarthq.type.thermostatmode.heat | Heat |
| cloud.smarthq.type.thermostatmode.off | Off |
| cloud.smarthq.type.thermostatmode.on | On |
| cloud.smarthq.type.thermostatmode.unknown | Unknown |