Alexa.ThermostatController.Schedule Interface

Implement the Alexa.ThermostatController.Schedule interface in your Alexa skill so that users can define schedules for their thermostat device. A user can set up the temperature schedule on the device or in the Alexa app.

Typically, you use the Alexa.ThermostatController.Schedule interface in conjunction with the Alexa.ThermostatController and Alexa.TemperatureSensor interfaces.

For the list of locales that the Alexa.ThermostatController.Schedule interface supports, see List of Alexa Interfaces and Supported Languages.

Utterances

The Alexa.ThermostatController.Schedule interface is different than other Alexa Schedule. Your skill doesn't support voice user interactions with Alexa directly. Instead, Alexa communicates with your skill to set and get thermostat schedules. This interface doesn't have any user utterances.

Properties and objects

The Alexa.ThermostatController.Schedule interface includes the following properties and objects.

Reportable properties

The following table shows the properties that the Alexa.ThermostatController.Schedule interface defines. You identify the properties that you support in your discovery response . All the properties are optional. Include only the properties that match the features of your thermostat device.

Property Description Type

adaptiveRecoveryEnabled

Used to enable or disable pre-heating and pre-cooling within the schedule. For example, before the next schedule begins, the HVAC system turns on the heat to try to meet the target temperature at the start of the next schedule.

Boolean

scheduleEnabled

Used to enable or disable the thermostat schedule.

Boolean

WeeklySchedule object

The WeeklySchedule object defines the schedule that your thermostat device follows.

Property Description Type Required

temperatureScale

The preferred temperature scale configured on the thermostat. This value is usually the same as the temperatureScale property in the Alexa.ThermostatController.Configuration interface.

String

Yes

Monday

Indicates the schedule for Monday.

Array of ScheduleEntry objects

Yes

Tuesday

Indicates the schedule for Tuesday.

Array of ScheduleEntry objects

Yes

Wednesday

Indicates the schedule for Wednesday.

Array of ScheduleEntry objects

Yes

Thursday

Indicates the schedule for Thursday.

Array of ScheduleEntry objects

Yes

Friday

Indicates the schedule for Friday.

Array of ScheduleEntry objects

Yes

Saturday

Indicates the schedule for Saturday.

Array of ScheduleEntry objects

Yes

Sunday

Indicates the schedule for Sunday.

Array of ScheduleEntry objects

Yes

ScheduleEntry objects

The ScheduleEntry object defines the details of the thermostat temperature setting at a particular time of the day. The schedule entry doesn't include an end time. The time ends when the next schedule entry begins.

Property Description Type Required

periodStartTimeInMinutes

Indicates the start time for the temperature change, expressed in number of minutes from the start of day. For example, 300 minutes is 5:00 AM.

Integer

Yes

setpoints

Defines the target temperature for the living space to reach and maintain until the next schedule entry.

SetPoints object

Yes

fanSetting

Indicates the operational setting of the fan.

FanSetting object

No

SetPoints object

The SetPoints object defines the target temperature for the living space.

Property Description Type

upperSetpoint

The thermostat should maintain the temperature below this setpoint.

Temperature

lowerSetpoint

The thermostat should maintain the temperature above this setpoint.

Temperature

FanSetting object

The FanSetting object defines the fan operating mode.

Property Description Type

mode

Indicates the operational setting on the fan. For example, CIRCULATE indicates that the fan runs at random intervals.
If the mode isn't specified, the HVAC system defaults to the manufacturer default setting.
Valid values: ON, AUTO, CIRCULATE

String

Discovery

You describe endpoints that support Alexa.ThermostatController.Schedule using the standard discovery mechanism described in Alexa.Discovery.

Set retrievable to true for the properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report.

Use THERMOSTAT for the display category. For the full list of display categories, see display categories.

In addition to the usual discovery response fields, for Alexa.ThermostatController.Schedule, include a configuration object that contains the following fields.

Property Description Type Required

supportedFanModes

Indicates the supported operating modes of the fan.
Valid values: ON, AUTO, CIRCULATE

Array of strings

Yes

supportsAdaptiveRecovery

Indicates supports for pre-heating or pre-cooling.

Boolean

Yes

maxEntryPerDay

Maximum number of schedule entries for each day. If the restriction is complex, you can validate the schedule in your skill or device.

Integer

No

Discover response example

The following example shows a Discover.Response message for an Alexa skill that accepts thermostat configuration and supports the Alexa.ThermostatController, and Alexa.EndpointHealth interfaces. In this example, the thermostat device supports adaptive recovery.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "message id"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "Description that appears in the Alexa app",
                "friendlyName": "Your device name, displayed in the Alexa app",
                "displayCategories": ["THERMOSTAT"],
                "additionalAttributes": {
                    "manufacturer": "Sample Manufacturer",
                    "model": "Sample Model",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Your custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3",
                        "properties": {
                            "supported": [
                                {
                                    "name": "thermostatMode"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedModes": [
                                "HEAT",
                                "COOL",
                                "AUTO",
                                "OFF"
                            ],
                            "supportsScheduling": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController.Schedule",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                    "name": "adaptiveRecoveryEnabled"
                                },
                                {
                                    "name": "scheduleEnabled"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedFanModes": [
                                "ON",
                                "AUTO"
                            ],
                            "supportsAdaptiveRecovery": true,
                            "maxEntryPerDay": 4
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Directives

SetWeeklySchedule directive

Support the SetWeeklySchedule directive so that you can get the schedule that the customer configured during the thermostat setup or later in the Alexa app.

SetWeeklySchedule directive example

The following example shows a SetWeeklySchedule directive that Alexa sends to your skill.

{
    "directive": {
        "header": {
            "namespace": "Alexa.ThermostatController.Schedule",
            "name": "SetWeeklySchedule",
            "messageId": "message id",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "3.2"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint-id",
            "cookie": {}
        },
        "payload": {
            "weeklySchedule": {
                "temperatureScale": "FAHRENHEIT",
                "Monday": [{
                    "startTimeInMinutes": 480,
                    "setpoints": {
                        "lowerSetpoint": 66.5,
                        "upperSetpoint": 70.5
                    }
                }],
                "Tuesday": [{
                    "startTimeInMinutes": 1005,
                    "setpoints": {
                        "lowerSetpoint": 66.5,
                        "upperSetpoint": 70.5
                    }
                }],
                "Wednesday": [{
                        "startTimeInMinutes": 600,
                        "setpoints": {
                            "lowerSetpoint": 66.5,
                            "upperSetpoint": 70.5
                        }
                    },
                    {
                        "startTimeInMinutes": 1080,
                        "setpoints": {
                            "lowerSetpoint": 66.5,
                            "upperSetpoint": 70.5
                        }
                    }
                ],
                "Thursday": [],
                "Friday": [{
                    "startTimeInMinutes": 720,
                    "setpoints": {
                        "lowerSetpoint": 66.5,
                        "upperSetpoint": 70.5
                    }
                }],
                "Saturday": [{
                        "startTimeInMinutes": 0,
                        "setpoints": {
                            "lowerSetpoint": 60.5,
                            "upperSetpoint": 65.5
                        },
                        "fanSettings": {
                            "mode": "AUTO"
                        }
                    },
                    {
                        "startTimeInMinutes": 1005,
                        "setpoints": {
                            "lowerSetpoint": 66.5,
                            "upperSetpoint": 70.5
                        },
                        "fanSettings": {
                            "mode": "ON"
                        }
                    }
                ],
                "Sunday": [{
                        "startTimeInMinutes": 0,
                        "setpoints": {
                            "lowerSetpoint": 60.5,
                            "upperSetpoint": 65.5
                        },
                        "fanSettings": {
                            "mode": "AUTO"
                        }
                    },
                    {
                        "startTimeInMinutes": 1320,
                        "setpoints": {
                            "lowerSetpoint": 66.5,
                            "upperSetpoint": 70.5
                        }
                    }
                ]
            }
        }
    }
}

SetWeeklySchedule directive payload

The following table shows the payload details for the SetWeeklySchedule directive that Alexa sends to your skill.

Property Description Type Required

weeklySchedule

Indicates the schedule that the thermostat device follows for each day of the week.

WeeklySchedule object

No

SetWeeklySchedule response event

If you handle a SetWeeklySchedule directive successfully, respond with an Alexa.Response event.

SetWeeklySchedule directive error handling

If you can't handle a SetWeeklySchedule directive successfully, don't change the schedule on the device and respond with an Alexa.ThermostatController.Schedule.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to thermostats.

GetWeeklySchedule directive

Support the GetWeeklySchedule directive so that Alexa can get the schedule set on the thermostat device.

This directive doesn't have a payload.

GetWeeklySchedule directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController.Schedule",
      "name": "GetWeeklySchedule",
      "messageId": "message id",
      "correlationToken": "an opaque correlation token",
      "payloadVersion": "3.2"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {}
  }
}

GetWeeklySchedule response event

If you handle a GetWeeklySchedule directive successfully, respond with an Alexa.Response event.

GetWeeklySchedule response example

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.ThermostatController.Schedule",
            "name": "GetWeeklySchedule.Response",
            "messageId": "message id",
            "correlationToken": "opaque correlation token",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "endpointId": "endpoint id"
        },
        "payload": {
            "weeklySchedule": {
                "temperatureScale": "FAHRENHEIT",
                "Monday": [{
                    "startTimeInMinutes": 480,
                    "setpoints": {
                        "lowerSetpoint": 66.5,
                        "upperSetpoint": 70.5
                    }
                }],
                "Tuesday": [{
                    "startTimeInMinutes": 1005,
                    "setpoints": {
                        "lowerSetpoint": 66.5,
                        "upperSetpoint": 70.5
                    }
                }],
                "Wednesday": [{
                        "startTimeInMinutes": 600,
                        "setpoints": {
                            "lowerSetpoint": 66.5,
                            "upperSetpoint": 70.5
                        }
                    },
                    {
                        "startTimeInMinutes": 1080,
                        "setpoints": {
                            "lowerSetpoint": 66.5,
                            "upperSetpoint": 70.5
                        }
                    }
                ],
                "Thursday": [],
                "Friday": [{
                    "startTimeInMinutes": 720,
                    "setpoints": {
                        "lowerSetpoint": 66.5,
                        "upperSetpoint": 70.5
                    }
                }],
                "Saturday": [{
                        "startTimeInMinutes": 0,
                        "setpoints": {
                            "lowerSetpoint": 60.5,
                            "upperSetpoint": 65.5
                        },
                        "fanSettings": {
                            "mode": "AUTO"
                        }
                    },
                    {
                        "startTimeInMinutes": 1005,
                        "setpoints": {
                            "lowerSetpoint": 66.5,
                            "upperSetpoint": 70.5
                        },
                        "fanSettings": {
                            "mode": "ON"
                        }
                    }
                ],
                "Sunday": [{
                        "startTimeInMinutes": 0,
                        "setpoints": {
                            "lowerSetpoint": 60.5,
                            "upperSetpoint": 65.5
                        },
                        "fanSettings": {
                            "mode": "AUTO"
                        }
                    },
                    {
                        "startTimeInMinutes": 1320,
                        "setpoints": {
                            "lowerSetpoint": 66.5,
                            "upperSetpoint": 70.5
                        }
                    }
                ]
            }
        }
    }
}

GetWeeklySchedule response payload

On success, return the schedule stored on the thermostat device.

Property Description Type Required

weeklySchedule

Indicates the schedule that the thermostat device follows for each day of the week.

WeeklySchedule object

No

GetWeeklySchedule directive error handling

If you can't handle a GetWeeklySchedule directive successfully, respond with an Alexa.ThermostatController.Schedule.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to thermostats.

SetScheduleState directive

Support the SetScheduleState directive so that users can enable and disable the thermostat schedule. You must save the previously set schedule so that the customer can enable the schedule again.

SetScheduleState directive example

The following example shows a SetScheduleState directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController.Schedule",
      "name": "SetScheduleState",
      "messageId": "message id",
      "correlationToken": "an opaque correlation token",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {
      "scheduleEnabled": true
    }
  }
}

SetScheduleState directive payload

The following table shows the payload details for the SetScheduleState directive.

Property Description Type Required

scheduleEnabled

Indicates whether to enable (true) or disable (false) the thermostat schedule.

Boolean

Yes

SetScheduleState response event

If you handle a SetScheduleState directive successfully, respond with an Alexa.Response event.

SetScheduleState directive error handling

If you can't handle a SetScheduleState directive successfully, respond with an Alexa.ThermostatController.Schedule.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to thermostats.

SetAdaptiveRecovery directive

If your device supports adaptive recovery, Alexa sends the SetAdaptiveRecovery directive so that users can enable or disable pre-heating and pre-cooling.

SetAdaptiveRecovery directive example

The following example shows a SetAdaptiveRecovery directive that Alexa sends to your skill.

{
    "directive": {
        "header": {
            "namespace": "Alexa.ThermostatController.Schedule",
            "name": "SetAdaptiveRecovery",
            "messageId": "message id",
            "correlationToken": "an opaque correlation token",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint-id",
            "cookie": {}
        },
        "payload": {
            "adaptiveRecoveryEnabled": true
        }
    }
}

SetAdaptiveRecovery directive payload

The following table shows the payload details for the SetAdaptiveRecovery directive.

Property Description Type Required

adaptiveRecoveryEnabled

Indicates whether to enable (true) or disable (false) adaptive recovery.

Boolean

Yes

SetAdaptiveRecovery response event

If you handle a SetAdaptiveRecovery directive successfully, respond with an Alexa.Response event.

SetAdaptiveRecovery directive error handling

If you can't handle a SetAdaptiveRecovery directive successfully, respond with an Alexa.ThermostatController.Schedule.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to thermostats.

State reporting

Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. The response contains the current state of all retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.

StateReport response event example

In this example, the thermostat device supports both setupState and temperatureScale.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "message id",
            "correlationToken": "correlation token received in the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController.Schedule",
                "name": "adaptiveRecoveryEnabled",
                "value": true,
                "timeOfSample": "2020-02-26T16:20:50Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.ThermostatController.Schedule",
                "name": "scheduleEnabled",
                "value": true,
                "timeOfSample": "2020-02-26T16:20:50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2020-02-26T16: 20: 50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

Change reporting

You send a ChangeReport event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

The payload contains the values of properties that have changed, the context contains the values of other relevant properties.

The following example shows a ChangeReport after the user disables the schedule.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "message id",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.ThermostatController.Schedule",
                    "name": "scheduleEnabled",
                    "value": false,
                    "timeOfSample": "2017-02-03T16: 20: 50.52Z",
                    "uncertaintyInMilliseconds": 500
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController.Schedule",
                "name": "adaptiveRecoveryEnabled",
                "value": true,
                "timeOfSample": "2020-02-26T16:20:50Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2020-02-26T16: 20: 50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}