cloud.smarthq.service.integer¶
Description¶
Service to model a signed 32-bit integer value with associated units.
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.zonelinemakeupairfanspeedsv1 | Supported fan speeds are 0, 25, 30, 35, 40, 45, 50 CFM |
| cloud.smarthq.behavior.zonelinemakeupairfanspeedsv2 | Supported fan speeds are 0, 30, 35, 40, 45, 50 CFM |
| cloud.smarthq.behavior.zonelinethermostatsignals | Zoneline external thermostat wiring signal |
Example Device Response (Digital Twin API)¶
Service representing the brightness of a light.
{
"adapterId": "0000000000000000000000000000000000000000",
"alertTypes": [],
"createdDateTime": "2022-03-04T12:12:12.123Z",
"deviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"deviceType": "cloud.smarthq.device.light",
"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.integer",
"lastSyncTime": "2022-03-04T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.brightness",
"supportedCommands": [
"cloud.smarthq.command.integer.set",
"cloud.smarthq.command.integer.adjust"
],
"state": {
"value": 75.0
},
"serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"serviceDeviceType": "cloud.smarthq.device.light",
"config": {
"integerUnits": "cloud.smarthq.type.integerunits.percentage",
"defaultValue": 50.0,
"maximum": 100.0,
"label": "Light",
"minimum": 0.0
},
"lastStateTime": "2022-03-04T12:12:12.123Z"
}
],
"userId": "000000000000000"
}
Service the makeup air fan speed of a Zoneline.
{
"adapterId": "0000000000000000000000000000000000000000",
"alertTypes": [],
"createdDateTime": "2022-03-04T12:12:12.123Z",
"deviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"deviceType": "cloud.smarthq.device.ptac",
"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.integer",
"lastSyncTime": "2022-03-04T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.makeupair.speed",
"supportedCommands": [
"cloud.smarthq.command.integer.set"
],
"state": {
"value": 45.0
},
"serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"serviceDeviceType": "cloud.smarthq.device.fan",
"config": {
"allowedValues": [
0.0,
35.0,
40.0,
45.0,
50.0,
55.0
],
"integerUnits": "cloud.smarthq.type.integerunits.cfm"
},
"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 |
|---|---|---|
| allowedValues | INTEGER_ARRAY | No |
| defaultValue | INTEGER | No |
| integerUnits | INTEGER_UNITS | Yes |
| label | STRING | No |
| maximum | INTEGER | No |
| minimum | INTEGER | 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 |
|---|---|---|
| disabled | BOOLEAN | No |
| value | INTEGER | 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.integer.set¶
Command to set a new value for the integer service.
| Field Name | Property Type | Required |
|---|---|---|
| value | INTEGER | Yes |
Example Commands¶
Command to set the light brightness.
{
"command": {
"commandType": "cloud.smarthq.command.integer.set",
"value": 50.0
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.brightness",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.light",
"serviceType": "cloud.smarthq.service.integer"
}
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.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.integer.adjust¶
Command to adjust the value for the integer service by the provided delta.
| Field Name | Property Type | Required |
|---|---|---|
| delta | INTEGER | Yes |
Example Commands¶
Example command to adjust the blower speed value of integer service by the provided delta.
{
"command": {
"commandType": "cloud.smarthq.command.integer.adjust",
"delta": 5.0
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.blower.speed",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.fan",
"serviceType": "cloud.smarthq.service.integer"
}
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.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.
INTEGER¶
Value must be an integer. Field specific restrictions such as a minimum and maximum may apply depending on the field.
STRING¶
Value must be a sequence of characters, inserted between " and " (double quotes). Field specific restrictions such as a regular expression may apply depending on the field.
INTEGER_ARRAY¶
Value must be an array of integers.
INTEGER_UNITS¶
| INTEGER_UNITS | Documentation |
|---|---|
| cloud.smarthq.type.integerunits.cfm | Cubic feet per minute |
| cloud.smarthq.type.integerunits.count | Integer count |
| cloud.smarthq.type.integerunits.dbm | Decibel milliwatts |
| cloud.smarthq.type.integerunits.gallons | Gallons |
| cloud.smarthq.type.integerunits.hours | Hours |
| cloud.smarthq.type.integerunits.kwh | Kilo watt hour |
| cloud.smarthq.type.integerunits.level | level |
| cloud.smarthq.type.integerunits.minutes | Minutes |
| cloud.smarthq.type.integerunits.ounces | Ounces |
| cloud.smarthq.type.integerunits.ounces.fluid | Fluid ounces |
| cloud.smarthq.type.integerunits.percentage | Percentage |
| cloud.smarthq.type.integerunits.rpm | Revolutions per Minute |
| cloud.smarthq.type.integerunits.seconds | Seconds |
| cloud.smarthq.type.integerunits.thermostatsignalv1 | Thermostat Signal v1 |
| cloud.smarthq.type.integerunits.unitless | unitless |
| cloud.smarthq.type.integerunits.watts | Watts |