cloud.smarthq.service.color¶
Description¶
Service to model a color selection.
Example Device Response (Digital Twin API)¶
Service for controlling RGB color.
{
"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.color",
"lastSyncTime": "2022-03-04T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.color",
"supportedCommands": [
"cloud.smarthq.command.color.set"
],
"state": {
"rgb": "#00FF00",
"hsbCalculated": {
"saturation": 1.0,
"brightness": 1.0,
"hue": 120.0
},
"whitenessTemperatureKelvinCalculated": 2700.0
},
"serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"serviceDeviceType": "cloud.smarthq.device.light",
"config": {
"colorSpaces": [
"cloud.smarthq.type.colorspace.rgb"
]
},
"lastStateTime": "2022-03-04T12:12:12.123Z"
}
],
"userId": "000000000000000"
}
Service for controlling HSB color.
{
"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.color",
"lastSyncTime": "2022-03-04T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.color",
"supportedCommands": [
"cloud.smarthq.command.color.set"
],
"state": {
"hsb": {
"saturation": 0.5,
"brightness": 0.5,
"hue": 0.0
},
"whitenessTemperatureKelvinCalculated": 2700.0,
"rgbCalculated": "#804040"
},
"serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"serviceDeviceType": "cloud.smarthq.device.light",
"config": {
"colorSpaces": [
"cloud.smarthq.type.colorspace.hsb"
]
},
"lastStateTime": "2022-03-04T12:12:12.123Z"
}
],
"userId": "000000000000000"
}
Service for controlling color temperature.
{
"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.color",
"lastSyncTime": "2022-03-04T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.color",
"supportedCommands": [
"cloud.smarthq.command.color.set"
],
"state": {
"hsbCalculated": {
"saturation": 0.0,
"brightness": 1.0,
"hue": 0.0
},
"whitenessTemperatureKelvin": 3100.0,
"rgbCalculated": "#FFFFFF"
},
"serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"serviceDeviceType": "cloud.smarthq.device.light",
"config": {
"colorSpaces": [
"cloud.smarthq.type.colorspace.whiteness"
]
},
"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 |
|---|---|---|
| colorSpaces | SET<COLOR_SPACE> | 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 | Regex Name | Minimum | Maximum | Calculated |
|---|---|---|---|---|---|---|
| disabled | BOOLEAN | No | ||||
| hsb | COLOR_HSB | No | ||||
| hsbCalculated | COLOR_HSB | No | Yes | |||
| rgb | STRING | No | COLOR_RGB | |||
| rgbCalculated | STRING | No | Yes | |||
| whitenessTemperatureKelvin | INTEGER | No | 0 | 10000 | ||
| whitenessTemperatureKelvinCalculated | INTEGER | 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.color.set¶
Command used to set a new color on the color service.
| Field Name | Property Type | Required | Regex Name | Minimum | Maximum | Calculated |
|---|---|---|---|---|---|---|
| hsb | COLOR_HSB | No | ||||
| hsbCalculated | COLOR_HSB | No | Yes | |||
| rgb | STRING | No | COLOR_RGB | |||
| rgbCalculated | STRING | No | Yes | |||
| whitenessTemperatureKelvin | INTEGER | No | 0 | 10000 | ||
| whitenessTemperatureKelvinCalculated | INTEGER | No | Yes |
Example Commands¶
Example for setting RGB color.
{
"command": {
"commandType": "cloud.smarthq.command.color.set",
"rgb": "#FF0000"
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.color",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.light",
"serviceType": "cloud.smarthq.service.color"
}
Example for setting HSB color.
{
"command": {
"commandType": "cloud.smarthq.command.color.set",
"hsb": {
"saturation": 0.92,
"brightness": 0.92,
"hue": 0.0
}
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.color",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.light",
"serviceType": "cloud.smarthq.service.color"
}
Example for setting color whiteness.
{
"command": {
"commandType": "cloud.smarthq.command.color.set",
"whitenessTemperatureKelvin": 3100.0
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.color",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.light",
"serviceType": "cloud.smarthq.service.color"
}
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.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.
COLOR_HSB¶
Value must be a JSON object with three attributes. - hue: integer between 0 and 360 - saturation: double between 0 and 1 - brightness: double between 0 and 1
SET<COLOR_SPACE>¶
| SET<COLOR_SPACE> | Documentation |
|---|---|
| cloud.smarthq.type.colorspace.hsb | Hue/Saturation/Brightness color space |
| cloud.smarthq.type.colorspace.rgb | Red/Blue/Green color space |
| cloud.smarthq.type.colorspace.whiteness | Whiteness color space in Kelvin |