cloud.smarthq.service.timeofuse.v1¶
Description¶
Service for appliance Time of use. This service is used for the representation of time of use of an appliance.
Example Device Response (Digital Twin API)¶
Service for appliance time of use
{
"adapterId": "0000000000000000000000000000000000000000",
"alertTypes": [],
"createdDateTime": "2022-03-04T12:12:12.123Z",
"deviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"deviceType": "cloud.smarthq.device.appliance",
"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.timeofuse.v1",
"lastSyncTime": "2022-03-04T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.season.1",
"supportedCommands": [
"cloud.smarthq.command.timeofuse.v1.clear"
],
"state": {
"seasonActive": true
},
"serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"serviceDeviceType": "cloud.smarthq.device.appliance",
"config": {
"maximumSegments": 5.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 |
|---|---|---|
| maximumSegments | INTEGER | 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 |
|---|---|---|
| scheduleId | STRING | No |
| seasonActive | BOOLEAN | 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.timeofuse.v1.clear¶
Command used to clear the time of use setting of an appliance
Example Commands¶
Command to clear time of use setting of an appliance.
{
"command": {
"commandType": "cloud.smarthq.command.timeofuse.v1.clear"
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.season.1",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.appliance",
"serviceType": "cloud.smarthq.service.timeofuse.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.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.timeofuse.v1.set¶
Command used to set the time of use setting of an appliance
| Field Name | Property Type | Required | Minimum Items | Maximum Items |
|---|---|---|---|---|
| fridayTiers | TIER_ARRAY | Yes | 0 | 255 |
| fridayTimes | TIME_ARRAY | Yes | ||
| mondayTiers | TIER_ARRAY | Yes | 0 | 255 |
| mondayTimes | TIME_ARRAY | Yes | ||
| saturdayTiers | TIER_ARRAY | Yes | 0 | 255 |
| saturdayTimes | TIME_ARRAY | Yes | ||
| seasonStartDay | INTEGER | Yes | ||
| seasonStartMonth | INTEGER | Yes | ||
| sundayTiers | TIER_ARRAY | Yes | 0 | 255 |
| sundayTimes | TIME_ARRAY | Yes | ||
| thursdayTiers | TIER_ARRAY | Yes | 0 | 255 |
| thursdayTimes | TIME_ARRAY | Yes | ||
| tuesdayTiers | TIER_ARRAY | Yes | 0 | 255 |
| tuesdayTimes | TIME_ARRAY | Yes | ||
| wednesdayTiers | TIER_ARRAY | Yes | 0 | 255 |
| wednesdayTimes | TIME_ARRAY | Yes |
Example Commands¶
Command to set Time of use of an appliance
{
"command": {
"tuesdayTimes": [
"00:00",
"10:00",
"13:00",
"19:00",
"21:00"
],
"commandType": "cloud.smarthq.command.timeofuse.v1.set",
"sundayTimes": [
"00:00",
"10:00",
"13:00",
"19:00",
"21:00"
],
"fridayTimes": [
"00:00",
"10:00",
"13:00",
"19:00",
"21:00"
],
"seasonStartDay": 10.0,
"thursdayTiers": [
0.0,
1.0,
2.0,
1.0,
0.0
],
"mondayTimes": [
"00:00",
"10:00",
"13:00",
"19:00",
"21:00"
],
"saturdayTiers": [
0.0,
1.0,
2.0,
1.0,
0.0
],
"fridayTiers": [
0.0,
1.0,
2.0,
1.0,
0.0
],
"sundayTiers": [
0.0,
1.0,
2.0,
1.0,
0.0
],
"wednesdayTiers": [
0.0,
1.0,
2.0,
1.0,
0.0
],
"thursdayTimes": [
"00:00",
"10:00",
"13:00",
"19:00",
"21:00"
],
"seasonStartMonth": 3.0,
"wednesdayTimes": [
"00:00",
"10:00",
"13:00",
"19:00",
"21:00"
],
"saturdayTimes": [
"00:00",
"10:00",
"13:00",
"19:00",
"21:00"
],
"mondayTiers": [
0.0,
1.0,
2.0,
1.0,
0.0
],
"tuesdayTiers": [
0.0,
1.0,
2.0,
1.0,
0.0
]
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.season.1",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.appliance",
"serviceType": "cloud.smarthq.service.timeofuse.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.
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.
TIME_ARRAY¶
TODO: Newly defined type needs documentation written.
TIER_ARRAY¶
TODO: Newly defined type needs documentation written.