cloud.smarthq.service.cooking.mode.v1¶
Description¶
Service to model the cooking mode is used in conjunction with the cooking state service. This service represents an available cooking mode providing the configuration for what parameters are required to start it, a command for actually starting the cooking mode, as well as the state of the cooking mode if it is running.
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.cooktimeprobetemperatureexclusive | Cook time and probe temperature are mutually exclusive; exactly one must be specified. |
| cloud.smarthq.behavior.microwavenonzeropowerlevel | The Microwave does not support a power level of 0. |
Example Device Response (Digital Twin API)¶
Service representing automatic bake biscuits mode on microwave.
{
"adapterId": "0000000000000000000000000000000000000000",
"alertTypes": [],
"createdDateTime": "2022-03-04T12:12:12.123Z",
"deviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"deviceType": "cloud.smarthq.device.microwave",
"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.cooking.mode.v1",
"lastSyncTime": "2022-03-04T12:12:12.123Z",
"domainType": "cloud.smarthq.domain.cooking.bake.auto.biscuits",
"supportedCommands": [
"cloud.smarthq.command.cooking.mode.v1.start"
],
"state": {
"numericOptionValue": 0.0
},
"serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
"serviceDeviceType": "cloud.smarthq.device.microwave",
"config": {
"numericOptionUnits": "cloud.smarthq.type.numericoption.ounces",
"numericOptionMaximum": 7.0,
"numericOptionMinimum": 7.0,
"numericOptionGranularity": "cloud.smarthq.type.numericoptiongranularity.integer",
"numericOptionSupported": "cloud.smarthq.type.parameter.required"
},
"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 |
|---|---|---|---|
| cavityTemperatureCelsiusMaximum | DOUBLE | No | |
| cavityTemperatureCelsiusMaximumConverted | DOUBLE | No | Yes |
| cavityTemperatureCelsiusMinimum | DOUBLE | No | |
| cavityTemperatureCelsiusMinimumConverted | DOUBLE | No | Yes |
| cavityTemperatureFahrenheitMaximum | DOUBLE | No | |
| cavityTemperatureFahrenheitMaximumConverted | DOUBLE | No | Yes |
| cavityTemperatureFahrenheitMinimum | DOUBLE | No | |
| cavityTemperatureFahrenheitMinimumConverted | DOUBLE | No | Yes |
| cavityTemperatureSupported | SUPPORTED_PARAMETER | No | |
| cookTimeGranularity | TIME_GRANULARITY | No | |
| cookTimeMaximum | INTEGER | No | |
| cookTimeMinimum | INTEGER | No | |
| cookTimeSupported | SUPPORTED_PARAMETER | No | |
| donenessLevelSupported | SUPPORTED_PARAMETER | No | |
| donenessLevelsAvailable | SET<DONENESS_LEVEL> | No | |
| numericOptionGranularity | NUMERIC_OPTION_GRANULARITY | No | |
| numericOptionMaximum | DOUBLE | No | |
| numericOptionMinimum | DOUBLE | No | |
| numericOptionSupported | SUPPORTED_PARAMETER | No | |
| numericOptionUnits | NUMERIC_OPTION | No | |
| optionsAvailable | STRING_ARRAY | No | |
| optionsSupported | SUPPORTED_PARAMETER | No | |
| powerLevelConvectionSupported | SUPPORTED_PARAMETER | No | |
| powerLevelLowerSupported | SUPPORTED_PARAMETER | No | |
| powerLevelMicrowaveSupported | SUPPORTED_PARAMETER | No | |
| powerLevelUpperSupported | SUPPORTED_PARAMETER | No | |
| probeTemperatureCelsiusMaximum | DOUBLE | No | |
| probeTemperatureCelsiusMaximumConverted | DOUBLE | No | Yes |
| probeTemperatureCelsiusMinimum | DOUBLE | No | |
| probeTemperatureCelsiusMinimumConverted | DOUBLE | No | Yes |
| probeTemperatureFahrenheitMaximum | DOUBLE | No | |
| probeTemperatureFahrenheitMaximumConverted | DOUBLE | No | Yes |
| probeTemperatureFahrenheitMinimum | DOUBLE | No | |
| probeTemperatureFahrenheitMinimumConverted | DOUBLE | No | Yes |
| probeTemperatureSupported | SUPPORTED_PARAMETER | 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 | Minimum | Maximum | Calculated |
|---|---|---|---|---|---|
| cavityTemperatureCelsius | DOUBLE | No | |||
| cavityTemperatureCelsiusConverted | DOUBLE | No | Yes | ||
| cavityTemperatureCelsiusDefault | DOUBLE | No | |||
| cavityTemperatureCelsiusDefaultConverted | DOUBLE | No | Yes | ||
| cavityTemperatureFahrenheit | DOUBLE | No | |||
| cavityTemperatureFahrenheitConverted | DOUBLE | No | Yes | ||
| cavityTemperatureFahrenheitDefault | DOUBLE | No | |||
| cookTimeInitial | INTEGER | No | |||
| cookTimeInitialDefault | INTEGER | No | |||
| disabled | BOOLEAN | No | |||
| donenessLevel | DONENESS_LEVEL | No | |||
| numericOptionValue | DOUBLE | No | |||
| numericOptionValueDefault | DOUBLE | No | |||
| option | STRING | No | |||
| powerLevelConvection | INTEGER | No | 0 | 10 | |
| powerLevelLower | INTEGER | No | 0 | 10 | |
| powerLevelMicrowave | INTEGER | No | 0 | 10 | |
| powerLevelUpper | INTEGER | No | 0 | 10 | |
| probeTemperatureCelsius | DOUBLE | No | |||
| probeTemperatureCelsiusConverted | DOUBLE | No | Yes | ||
| probeTemperatureCelsiusDefault | DOUBLE | No | |||
| probeTemperatureCelsiusDefaultConverted | DOUBLE | No | Yes | ||
| probeTemperatureFahrenheit | DOUBLE | No | |||
| probeTemperatureFahrenheitConverted | DOUBLE | No | Yes | ||
| probeTemperatureFahrenheitDefault | DOUBLE | 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.cooking.mode.v1.start¶
Command used to start a mode on a cooking device. The specific config for the mode service determines which properties can be used and which ones are required.
| Field Name | Property Type | Required | Minimum | Maximum | Calculated |
|---|---|---|---|---|---|
| cavityCelsius | DOUBLE | No | |||
| cavityCelsiusConverted | DOUBLE | No | Yes | ||
| cavityFahrenheit | DOUBLE | No | |||
| cavityFahrenheitConverted | DOUBLE | No | Yes | ||
| cookTimeSeconds | INTEGER | No | |||
| donenessLevel | DONENESS_LEVEL | No | |||
| numericOptionValue | DOUBLE | No | |||
| option | STRING | No | |||
| powerLevelConvection | INTEGER | No | 0 | 10 | |
| powerLevelLower | INTEGER | No | 0 | 10 | |
| powerLevelMicrowave | INTEGER | No | 0 | 10 | |
| powerLevelUpper | INTEGER | No | 0 | 10 | |
| probeCelsius | DOUBLE | No | |||
| probeCelsiusConverted | DOUBLE | No | Yes | ||
| probeFahrenheit | DOUBLE | No | |||
| probeFahrenheitConverted | DOUBLE | No | Yes |
Example Commands¶
Command to start the auto bake biscuits mode on a microwave.
{
"command": {
"commandType": "cloud.smarthq.command.cooking.mode.v1.start",
"numericOptionValue": 6.0
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.cooking.bake.auto.biscuits",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.microwave",
"serviceType": "cloud.smarthq.service.cooking.mode.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.cooking.mode.v1.set¶
Command used to set a mode on a cooking device. The specific config for the mode service determines which properties can be used and which ones are required.
| Field Name | Property Type | Required | Minimum | Maximum | Calculated |
|---|---|---|---|---|---|
| cavityCelsius | DOUBLE | No | |||
| cavityCelsiusConverted | DOUBLE | No | Yes | ||
| cavityFahrenheit | DOUBLE | No | |||
| cavityFahrenheitConverted | DOUBLE | No | Yes | ||
| cookTimeSeconds | INTEGER | No | |||
| donenessLevel | DONENESS_LEVEL | No | |||
| numericOptionValue | DOUBLE | No | |||
| option | STRING | No | |||
| powerLevelConvection | INTEGER | No | 0 | 10 | |
| powerLevelLower | INTEGER | No | 0 | 10 | |
| powerLevelMicrowave | INTEGER | No | 0 | 10 | |
| powerLevelUpper | INTEGER | No | 0 | 10 | |
| probeCelsius | DOUBLE | No | |||
| probeCelsiusConverted | DOUBLE | No | Yes | ||
| probeFahrenheit | DOUBLE | No | |||
| probeFahrenheitConverted | DOUBLE | No | Yes |
Example Commands¶
Command to set the smoker mode to salmon.
{
"command": {
"commandType": "cloud.smarthq.command.cooking.mode.v1.set"
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.cooking.food.salmon",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.smoker",
"serviceType": "cloud.smarthq.service.cooking.mode.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.cooking.mode.v1.adjust.timer¶
Command used to adjust a running cook timer.
| Field Name | Property Type | Required |
|---|---|---|
| cookTimeSecondsDelta | INTEGER | Yes |
Example Commands¶
Example command to adjust cook timer.
{
"command": {
"commandType": "cloud.smarthq.command.cooking.mode.v1.adjust.timer",
"cookTimeSecondsDelta": 60.0
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.cooking.food.salmon",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.smoker",
"serviceType": "cloud.smarthq.service.cooking.mode.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.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.cooking.mode.v1.default.restore¶
Command used to restore back default mode values on a cooking device
Example Commands¶
Example command to restore mode default values.
{
"command": {
"commandType": "cloud.smarthq.command.cooking.mode.v1.default.restore"
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.cooking.food.salmon",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.smoker",
"serviceType": "cloud.smarthq.service.cooking.mode.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.cooking.mode.v1.default.set¶
Command used to set a default mode value on a cooking device
| Field Name | Property Type | Required | Minimum | Maximum | Calculated |
|---|---|---|---|---|---|
| cavityCelsius | DOUBLE | No | |||
| cavityCelsiusConverted | DOUBLE | No | Yes | ||
| cavityFahrenheit | DOUBLE | No | |||
| cavityFahrenheitConverted | DOUBLE | No | Yes | ||
| cookTimeSeconds | INTEGER | No | |||
| donenessLevel | DONENESS_LEVEL | No | |||
| numericOptionValue | DOUBLE | No | |||
| option | STRING | No | |||
| powerLevelConvection | INTEGER | No | 0 | 10 | |
| powerLevelLower | INTEGER | No | 0 | 10 | |
| powerLevelMicrowave | INTEGER | No | 0 | 10 | |
| powerLevelUpper | INTEGER | No | 0 | 10 | |
| probeCelsius | DOUBLE | No | |||
| probeCelsiusConverted | DOUBLE | No | Yes | ||
| probeFahrenheit | DOUBLE | No | |||
| probeFahrenheitConverted | DOUBLE | No | Yes |
Example Commands¶
Example Command to set the default values for smoker salmon mode.
{
"command": {
"commandType": "cloud.smarthq.command.cooking.mode.v1.default.set",
"cookTimeSeconds": 5700.0
},
"deviceId": "00000000000000000000000000000000000000000000000000000000000000",
"domainType": "cloud.smarthq.domain.cooking.food.salmon",
"kind": "service#command",
"serviceDeviceType": "cloud.smarthq.device.smoker",
"serviceType": "cloud.smarthq.service.cooking.mode.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.
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.
STRING_ARRAY¶
Value must be an array of strings.
DONENESS_LEVEL¶
| DONENESS_LEVEL | Documentation |
|---|---|
| cloud.smarthq.type.doneness.crispy | Crispy |
| cloud.smarthq.type.doneness.crunchy | Crunchy |
| cloud.smarthq.type.doneness.extracrispy | Extra Crispy |
| cloud.smarthq.type.doneness.gooey | Gooey |
| cloud.smarthq.type.doneness.level.1 | Level 1 |
| cloud.smarthq.type.doneness.level.2 | Level 2 |
| cloud.smarthq.type.doneness.level.3 | Level 3 |
| cloud.smarthq.type.doneness.level.4 | Level 4 |
| cloud.smarthq.type.doneness.level.5 | Level 5 |
| cloud.smarthq.type.doneness.level.6 | Level 6 |
| cloud.smarthq.type.doneness.level.7 | Level 7 |
| cloud.smarthq.type.doneness.level.8 | Level 8 |
| cloud.smarthq.type.doneness.normal | Normal |
NUMERIC_OPTION¶
| NUMERIC_OPTION | Documentation |
|---|---|
| cloud.smarthq.type.numericoption.count | Count |
| cloud.smarthq.type.numericoption.cups | Cups |
| cloud.smarthq.type.numericoption.gallons | Gallons |
| cloud.smarthq.type.numericoption.level.smoke | Smoke level |
| cloud.smarthq.type.numericoption.none | None |
| cloud.smarthq.type.numericoption.ounces | Ounces |
| cloud.smarthq.type.numericoption.pounds | Pounds |
| cloud.smarthq.type.numericoption.size | Size |
NUMERIC_OPTION_GRANULARITY¶
| NUMERIC_OPTION_GRANULARITY | Documentation |
|---|---|
| cloud.smarthq.type.numericoptiongranularity.hundredth | Granularity to nearest hundredth place |
| cloud.smarthq.type.numericoptiongranularity.integer | Granularity to whole number |
| cloud.smarthq.type.numericoptiongranularity.tenth | Granularity to nearest tenth place |
SET<DONENESS_LEVEL>¶
| SET<DONENESS_LEVEL> | Documentation |
|---|---|
| cloud.smarthq.type.doneness.crispy | Crispy |
| cloud.smarthq.type.doneness.crunchy | Crunchy |
| cloud.smarthq.type.doneness.extracrispy | Extra Crispy |
| cloud.smarthq.type.doneness.gooey | Gooey |
| cloud.smarthq.type.doneness.level.1 | Level 1 |
| cloud.smarthq.type.doneness.level.2 | Level 2 |
| cloud.smarthq.type.doneness.level.3 | Level 3 |
| cloud.smarthq.type.doneness.level.4 | Level 4 |
| cloud.smarthq.type.doneness.level.5 | Level 5 |
| cloud.smarthq.type.doneness.level.6 | Level 6 |
| cloud.smarthq.type.doneness.level.7 | Level 7 |
| cloud.smarthq.type.doneness.level.8 | Level 8 |
| cloud.smarthq.type.doneness.normal | Normal |
SUPPORTED_PARAMETER¶
| SUPPORTED_PARAMETER | Documentation |
|---|---|
| cloud.smarthq.type.parameter.defaulted | Associated parameter may be provided, the value defaults if not provided |
| cloud.smarthq.type.parameter.optional | Associated parameter may be provided |
| cloud.smarthq.type.parameter.prohibited | Associated parameter cannot be used, this is the implied behavior when not provided. |
| cloud.smarthq.type.parameter.required | Associated parameter must be provided |
TIME_GRANULARITY¶
| TIME_GRANULARITY | Documentation |
|---|---|
| cloud.smarthq.type.timergranularity.days | Granularity of days |
| cloud.smarthq.type.timergranularity.hours | Granularity of hours |
| cloud.smarthq.type.timergranularity.minutes | Granularity of minutes |
| cloud.smarthq.type.timergranularity.seconds | Granularity of seconds |