cloud.smarthq.service.waterheater.v1¶

Configuration

Describes boundaries and fixed properties for the service.

Go There
State

A list of the states this service can be in.

Go There
Commands

How to change the state of the service.

Go There
Data Types

All the data types used for this service.

Go There

Description¶

Service to model the current state of a water heater.

Example Device Response (Digital Twin API)¶

Service representing capacity service of water heater.

{
  "adapterId": "0000000000000000000000000000000000000000",
  "alertTypes": [],
  "createdDateTime": "2022-03-04T12:12:12.123Z",
  "deviceId": "0000000000000000000000000000000000000000000000000000000000000000",
  "deviceType": "cloud.smarthq.device.washer",
  "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.waterheater.v1",
      "lastSyncTime": "2022-03-04T12:12:12.123Z",
      "domainType": "cloud.smarthq.domain.waterheater",
      "supportedCommands": [
        "cloud.smarthq.command.waterheater.v1.set"
      ],
      "state": {
        "mode": "cloud.smarthq.type.waterheatermode.electric",
        "setpointCelsiusConverted": 37.77777777777778,
        "setpointFahrenheit": 100.0,
        "capacity": "cloud.smarthq.type.waterheatercapacity.normal"
      },
      "serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
      "serviceDeviceType": "cloud.smarthq.device.washer",
      "config": {
        "supportedCapacities": [
          "cloud.smarthq.type.waterheatercapacity.normal",
          "cloud.smarthq.type.waterheatercapacity.high",
          "cloud.smarthq.type.waterheatercapacity.extrahigh"
        ],
        "durationVacationMaximum": 4776.0,
        "supportedModes": [
          "cloud.smarthq.type.waterheatermode.vacation",
          "cloud.smarthq.type.waterheatermode.electric"
        ],
        "setpointFahrenheitMaximum": 140.0
      },
      "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
durationElectricMaximum	INTEGER	No
durationVacationMaximum	INTEGER	No
setpointCelsiusMaximum	DOUBLE	No
setpointCelsiusMinimum	DOUBLE	No
setpointFahrenheitMaximum	DOUBLE	No
setpointFahrenheitMinimum	DOUBLE	No
supportedCapacities	SET<WATERHEATERCAPACITY>	No
supportedModes	SET<WATERHEATERMODE>	Yes

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	Minimum	Calculated
capacity	WATERHEATERCAPACITY	No
disabled	BOOLEAN	No
durationRemaining	INTEGER	No	0
mode	WATERHEATERMODE	Yes
setpointCelsius	DOUBLE	No
setpointCelsiusConverted	DOUBLE	No		Yes
setpointFahrenheit	DOUBLE	No
setpointFahrenheitConverted	DOUBLE	No		Yes

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.waterheater.v1.set¶

Command to set options on a water heater device.

Field Name	Property Type	Required	Minimum	Calculated
capacity	WATERHEATERCAPACITY	No
durationRemaining	INTEGER	No	0
mode	WATERHEATERMODE	No
setpointCelsius	DOUBLE	No
setpointCelsiusConverted	DOUBLE	No		Yes
setpointFahrenheit	DOUBLE	No
setpointFahrenheitConverted	DOUBLE	No		Yes

Example Commands¶

Command to set the capacity in waterheater.

{
  "command": {
    "commandType": "cloud.smarthq.command.waterheater.v1.set",
    "capacity": "cloud.smarthq.type.waterheatercapacity.normal"
  },
  "deviceId": "00000000000000000000000000000000000000000000000000000000000000",
  "domainType": "cloud.smarthq.domain.waterheater",
  "kind": "service#command",
  "serviceDeviceType": "cloud.smarthq.device.waterheater",
  "serviceType": "cloud.smarthq.service.waterheater.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.

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.

SET<WATERHEATERCAPACITY>¶

SET<WATERHEATERCAPACITY>	Documentation
cloud.smarthq.type.waterheatercapacity.extrahigh	Extra high (X-High) tank capacity
cloud.smarthq.type.waterheatercapacity.high	High tank capacity
cloud.smarthq.type.waterheatercapacity.normal	Normal tank capacity
cloud.smarthq.type.waterheatercapacity.unknown	Unknown

SET<WATERHEATERMODE>¶

SET<WATERHEATERMODE>	Documentation
cloud.smarthq.type.waterheatermode.eheat	E-heat mode
cloud.smarthq.type.waterheatermode.electric	Standard electric mode
cloud.smarthq.type.waterheatermode.highdemand	High demand mode
cloud.smarthq.type.waterheatermode.hybrid	Hybrid mode
cloud.smarthq.type.waterheatermode.unknown	Unknown
cloud.smarthq.type.waterheatermode.vacation	Vacation mode

WATERHEATERCAPACITY¶

WATERHEATERCAPACITY	Documentation
cloud.smarthq.type.waterheatercapacity.extrahigh	Extra high (X-High) tank capacity
cloud.smarthq.type.waterheatercapacity.high	High tank capacity
cloud.smarthq.type.waterheatercapacity.normal	Normal tank capacity
cloud.smarthq.type.waterheatercapacity.unknown	Unknown

WATERHEATERMODE¶

WATERHEATERMODE	Documentation
cloud.smarthq.type.waterheatermode.eheat	E-heat mode
cloud.smarthq.type.waterheatermode.electric	Standard electric mode
cloud.smarthq.type.waterheatermode.highdemand	High demand mode
cloud.smarthq.type.waterheatermode.hybrid	Hybrid mode
cloud.smarthq.type.waterheatermode.unknown	Unknown
cloud.smarthq.type.waterheatermode.vacation	Vacation mode