Alexa.ThermostatController.Schedule Interface 3.2

Implement the Alexa.ThermostatController.Schedule interface in your Alexa add-on 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 add-on doesn’t support voice user interactions with Alexa directly. Instead, Alexa communicates with your add-on 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 add-on 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 add-on or device.	Integer	No

Discover response example

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

{
    "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 add-on.

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 add-on.

Show/hide SetWeeklySchedule directive

{
    "directive": {
        "header": {
            "namespace": "Alexa.ThermostatController.Schedule",
            "name": "SetWeeklySchedule",
            "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": {
            "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
                        },
                        "fanSettings": {
                            "mode": "AUTO"
                        },
                        "activityType": {
                            "type": "HOME"
                        }
                    },
                    {
                        "startTimeInMinutes": 1080,
                        "setpoints": {
                            "lowerSetpoint": 66.5,
                            "upperSetpoint": 70.5
                        },
                        "fanSettings": {
                            "mode": "AUTO"
                        },
                        "activityType": {
                            "type": "SLEEP"
                        }
                    }
                ],
                "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 add-on.

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. A successful response confirms that the endpoint completed the requested action.

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 add-on.

{
  "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. A successful response confirms that the endpoint completed the requested action.

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 add-on.

{
    "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. A successful response confirms that the endpoint completed the requested action.

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.

{
    "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.

{
    "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
            }
        ]
    }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.ThermostatController.Schedule Interface 3.2

Utterances

Properties and objects

Reportable properties

WeeklySchedule object

ScheduleEntry object

SetPoints object

FanSetting object

ActivityType object

Discovery

Configuration object

Discover response example

Directives

SetWeeklySchedule directive

SetWeeklySchedule directive example

SetWeeklySchedule directive payload

SetWeeklySchedule response

SetWeeklySchedule directive error handling

SetScheduleState directive

SetScheduleState directive example

SetScheduleState directive payload

SetScheduleState response

SetScheduleState directive error handling

SetAdaptiveRecovery directive

SetAdaptiveRecovery directive example

SetAdaptiveRecovery directive payload

SetAdaptiveRecovery response

SetAdaptiveRecovery directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

​Utterances

​Properties and objects

​Reportable properties

​WeeklySchedule object

​ScheduleEntry object

​SetPoints object

​FanSetting object

​ActivityType object

​Discovery

​Configuration object

​Discover response example

​Directives

​SetWeeklySchedule directive

​SetWeeklySchedule directive example

​SetWeeklySchedule directive payload

​SetWeeklySchedule response

​SetWeeklySchedule directive error handling

​SetScheduleState directive

​SetScheduleState directive example

​SetScheduleState directive payload

​SetScheduleState response

​SetScheduleState directive error handling

​SetAdaptiveRecovery directive

​SetAdaptiveRecovery directive example

​SetAdaptiveRecovery directive payload

​SetAdaptiveRecovery response

​SetAdaptiveRecovery directive error handling

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Properties and objects

Reportable properties

WeeklySchedule object

ScheduleEntry object

SetPoints object

FanSetting object

ActivityType object

Discovery

Configuration object

Discover response example

Directives

SetWeeklySchedule directive

SetWeeklySchedule directive example

SetWeeklySchedule directive payload

SetWeeklySchedule response

SetWeeklySchedule directive error handling

SetScheduleState directive

SetScheduleState directive example

SetScheduleState directive payload

SetScheduleState response

SetScheduleState directive error handling

SetAdaptiveRecovery directive

SetAdaptiveRecovery directive example

SetAdaptiveRecovery directive payload

SetAdaptiveRecovery response

SetAdaptiveRecovery directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics