Alexa.ThermostatController.Schedule Interface 3.2

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

Typically, you use the Alexa.ThermostatController.Schedule interface 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. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.ThermostatController.Schedule interface is different from other Alexa interfaces. 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 heating, ventilation, and air conditioning (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

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 object

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

startTimeInMinutes

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. Valid values: 0 – 1439.

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

activityType

Indicates the type of activity that causes the temperature change.

ActivityType object

No

SetPoints object

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

Property Description Type

upperSetpoint

Indicates that the thermostat should maintain the temperature below this setpoint.

Temperature

lowerSetpoint

Indicates that 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 uses the manufacturer default setting.
Valid values: ON, AUTO, CIRCULATE.

String

ActivityType object

The ActivityType object enables the user to set a schedule based on the type of activity.

Property Description Type

type

Indicates the type of activity.
Valid values: AWAY, HOME, SLEEP.

String

Discovery

You describe endpoints that support Alexa.ThermostatController.Schedule by 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.

Configuration object

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": "Unique identifier, preferably a version 4 UUID"
        },
        "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": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3.2",
                        "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.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Directives

Alexa sends the following Alexa.ThermostatController.Schedule interface directives to your skill.

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.

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

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.

SetScheduleState directive

Support the SetScheduleState directive so that customers 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": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.2"
    },
    "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

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 customers 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": "Unique version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "3.2"
        },
        "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

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 example

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

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches 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-26T12:00:50Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.ThermostatController.Schedule",
                "name": "scheduleEnabled",
                "value": true,
                "timeOfSample": "2020-02-26T12:20:50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2020-02-26T12:20:50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2020-02-26T12:18:00.00Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

Change reporting

You send a ChangeReport event to report changes proactively 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.

ChangeReport event example

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

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "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": "2024-01-01T09:00:00.50Z",
                    "uncertaintyInMilliseconds": 500
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController.Schedule",
                "name": "adaptiveRecoveryEnabled",
                "value": true,
                "timeOfSample": "2024-01-01T08:00:00.05Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2024-01-01T08:00:00.05Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2024-01-01T09:00:00.05Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}
Was this page helpful?

Last updated: Aug 23, 2024