registry: ThermostatController 3.2 and ThermostatController.Schedule

The thermostat is described from its page: one, two or three setpoints with holdUntil, AdjustTargetTemperature,
SetThermostatMode with the six modes (EM_HEAT is new), ResumeSchedule, adaptiveRecoveryStatus, and its seven error
types under Alexa.ThermostatController. A declaration gives supportedModes, supportsScheduling and the properties
the device has; without them discovery is what 1.5.2 sent: HEAT, COOL, AUTO, OFF and the three setpoints with
thermostatMode. supportedModes without HEAT or COOL is refused where it is declared.

ThermostatController.Schedule replaces its stub. Wire change for a 1.x declaration of it: version 3.2 (was 1) and
scheduleEnabled listed (was nothing). SetAdaptiveRecovery is taken only with supportsAdaptiveRecovery.

24 examples of three pages are saved as fixtures; the page folds the SetWeeklySchedule example away, its payload
is tested from the tables. 207 tests pass, 191 before.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
David 2026-09-28 20:34:49 +00:00
parent af1489696d
commit f555a5df70
67 changed files with 2445 additions and 58 deletions

View file

@ -3,7 +3,10 @@
// the page prints it, and a payload that does not fit is answered with INVALID_VALUE without the handler.
const { test } = require("node:test");
const assert = require("node:assert/strict");
const { Alex2MQTT, LockController, MemoryPublisher, PowerLevelController, registry } = require("alex2node");
const {
Alex2MQTT, AlexaErrors, LockController, MemoryPublisher, PowerLevelController, ThermostatController,
ThermostatControllerSchedule, registry,
} = require("alex2node");
const interfaces = require("../fixtures/interfaces.js");
const { doc, examples } = require("../helpers/fixtures.js");
const { directive } = require("../helpers/harness.js");
@ -80,3 +83,37 @@ test("Alexa.LockController: a slow lock defers without a warning, and answers as
"warning: Amazon documents no DeferredResponse for Alexa.PowerLevelController, Alexa may not wait for the answer",
]);
});
test("Alexa.ThermostatController: an error of the thermostat goes under its namespace, a temperature out of range under Alexa", async () => {
const { device, receive, answers } = bridgeWithout();
const celsius = (value) => ({ value, scale: "CELSIUS" });
const thrown = [
AlexaErrors.setpointsTooClose("The setpoints are too close.", celsius(2)),
AlexaErrors.of("THERMOSTAT_IS_OFF", "The thermostat is currently off."),
AlexaErrors.temperatureOutOfRange("The requested temperature of -15 is out of range.", { minimumValue: celsius(15), maximumValue: celsius(30) }),
];
let count = 0;
device.add(ThermostatController).on("SetTargetTemperature", () => { throw thrown[count++]; });
device.add(ThermostatControllerSchedule, { supportedFanModes: ["AUTO"], supportsAdaptiveRecovery: false })
.on("SetWeeklySchedule", (ctx) => ctx.error("INSUFFICIENT_SPACE", "the thermostat keeps four entries a day"));
const set = doc("alexa-thermostatcontroller", "SetTargetTemperature-single.directive").directive;
for (let i = 0; i < thrown.length; i += 1) await receive(set);
const printed = ["REQUESTED_SETPOINTS_TOO_CLOSE", "THERMOSTAT_IS_OFF", "TEMPERATURE_VALUE_OUT_OF_RANGE"]
.map((type) => doc("alexa-thermostatcontroller-errorresponse", `${type}.error`).event);
assert.deepEqual(answers(), printed.map(({ header, payload }) => ["alexaResponce", header.namespace, "ErrorResponse", payload]));
assert.deepEqual(printed.map(({ header }) => header.namespace), ["Alexa.ThermostatController", "Alexa.ThermostatController", "Alexa"]);
await receive(directive("Alexa.ThermostatController.Schedule", "SetWeeklySchedule", "device-1", "ct", {}));
assert.deepEqual(answers().at(-1), [
"alexaResponce", "Alexa.ThermostatController.Schedule", "ErrorResponse",
{ type: "INSUFFICIENT_SPACE", message: "the thermostat keeps four entries a day" },
]);
// Declared without adaptive recovery, the thermostat is not sent the directive that switches it
await receive(doc("alexa-thermostatcontroller-schedule", "SetAdaptiveRecovery.directive").directive);
assert.deepEqual(answers().at(-1), ["alexaResponce", "Alexa", "ErrorResponse", {
type: "INVALID_DIRECTIVE",
message: "Alexa.ThermostatController.Schedule as device-1 declares it does not take SetAdaptiveRecovery",
}]);
});

View file

@ -0,0 +1,22 @@
{
"event": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "Endpoint ID"
},
"payload": {
"type": "REQUESTED_SETPOINTS_TOO_CLOSE",
"message": "The setpoints are too close.",
"minimumTemperatureDelta": {
"value": 2,
"scale": "CELSIUS"
}
}
}
}

View file

@ -0,0 +1,28 @@
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "Endpoint ID"
},
"payload": {
"type": "TEMPERATURE_VALUE_OUT_OF_RANGE",
"message": "The requested temperature of -15 is out of range.",
"validRange": {
"minimumValue": {
"value": 15,
"scale": "CELSIUS"
},
"maximumValue": {
"value": 30,
"scale": "CELSIUS"
}
}
}
}
}

View file

@ -0,0 +1,22 @@
{
"event": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"type": "THERMOSTAT_IS_OFF",
"message": "The thermostat is currently off."
}
}
}

View file

@ -0,0 +1,60 @@
{
"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
}
]
}
}

View file

@ -0,0 +1,22 @@
{
"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
}
}
}

View file

@ -0,0 +1,22 @@
{
"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
}
}
}

View file

@ -0,0 +1,53 @@
{
"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
}
]
}
}

View file

@ -0,0 +1,101 @@
{
"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"
}
]
}
]
}
}
}

View file

@ -0,0 +1,25 @@
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "AdjustTargetTemperature",
"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": {
"targetSetpointDelta": {
"value": -2,
"scale": "CELSIUS"
}
}
}
}

View file

@ -0,0 +1,46 @@
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2024-01-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 18,
"scale": "CELSIUS"
},
"timeOfSample": "2024-01-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 20,
"scale": "CELSIUS"
},
"timeOfSample": "2024-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}

View file

@ -0,0 +1,73 @@
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "endpoint id"
},
"payload": {
"change": {
"cause": {
"type": "RULE_TRIGGER"
},
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "COOL",
"timeOfSample": "2024-07-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 18,
"scale": "CELSIUS"
},
"timeOfSample": "2024-07-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "adaptiveRecoveryStatus",
"value": "PRECOOLING",
"timeOfSample": "2024-07-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.1,
"scale": "CELSIUS"
},
"timeOfSample": "2024-07-01T08:01:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {
"properties": [
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2024-06-30T23:59:00.32Z",
"uncertaintyInMilliseconds": 0
}
]
}
}

View file

@ -0,0 +1,66 @@
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "endpoint id"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "EM_HEAT",
"timeOfSample": "2024-01-01T08:00:00.05Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 18,
"scale": "CELSIUS"
},
"timeOfSample": "2024-01-01T08:00:00.05Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.1,
"scale": "CELSIUS"
},
"timeOfSample": "2024-01-01T08:00:00.05Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
},
"context": {
"properties": [
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2024-01-01T07:50:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}

View file

@ -0,0 +1,20 @@
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "ResumeSchedule",
"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": {}
}
}

View file

@ -0,0 +1,46 @@
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2024-07-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 18,
"scale": "CELSIUS"
},
"timeOfSample": "2024-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 17.9,
"scale": "CELSIUS"
},
"timeOfSample": "2024-07-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}

View file

@ -0,0 +1,32 @@
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "SetTargetTemperature",
"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": {
"lowerSetpoint": {
"value": 68,
"scale": "FAHRENHEIT"
},
"upperSetpoint": {
"value": 72,
"scale": "FAHRENHEIT"
},
"holdUntil": {
"duration": "PT30M"
}
}
}
}

View file

@ -0,0 +1,56 @@
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "AUTO",
"timeOfSample": "2024-01-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "lowerSetpoint",
"value": {
"value": 68,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2024-01-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "upperSetpoint",
"value": {
"value": 72,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2024-01-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 66.5,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2024-01-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}

View file

@ -0,0 +1,29 @@
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "SetTargetTemperature",
"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": {
"targetSetpoint": {
"value": 20,
"scale": "CELSIUS"
},
"holdUntil": {
"start": "2017-10-04T14:00Z",
"end": "2017-10-04T14:15Z"
}
}
}
}

View file

@ -0,0 +1,46 @@
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2024-01-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 20,
"scale": "CELSIUS"
},
"timeOfSample": "2024-01-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.3,
"scale": "CELSIUS"
},
"timeOfSample": "2024-01-21T08:00:00.12Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}

View file

@ -0,0 +1,24 @@
{
"directive": {
"header": {
"namespace": "Alexa.ThermostatController",
"name": "SetThermostatMode",
"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": {
"thermostatMode": {
"value": "COOL"
}
}
}
}

View file

@ -0,0 +1,46 @@
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "COOL",
"timeOfSample": "2024-07-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 17,
"scale": "CELSIUS"
},
"timeOfSample": "2024-07-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19,
"scale": "CELSIUS"
},
"timeOfSample": "2024-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}

View file

@ -0,0 +1,63 @@
{
"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",
"name": "thermostatMode",
"value": "COOL",
"timeOfSample": "2020-02-26T18:20:00.00Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 20,
"scale": "CELSIUS"
},
"timeOfSample": "2020-02-26T18:20:00.00Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "adaptiveRecoveryStatus",
"value": "INACTIVE",
"timeOfSample": "2020-02-26T18:20:00.00Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2020-02-26T18:20:00.00Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2020-02-26T18:20:00.00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}

View file

@ -0,0 +1,59 @@
{
"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",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2024-07-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 20,
"scale": "CELSIUS"
},
"timeOfSample": "2024-07-01T08:00:00.12Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.9,
"scale": "CELSIUS"
},
"timeOfSample": "2024-07-06T15:02:00.12Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2024-07-06T15:00:00.12Z",
"uncertaintyInMilliseconds": 0
}
]
}
}

View file

@ -0,0 +1,91 @@
{
"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": "Manufacturer of the endpoint",
"description": "Smart Air Conditioner",
"friendlyName": "Living room A/C",
"displayCategories": [
"THERMOSTAT",
"TEMPERATURE_SENSOR"
],
"additionalAttributes": {
"manufacturer": "Manufacturer of the endpoint",
"model": "Model of the device",
"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": "targetSetpoint"
},
{
"name": "thermostatMode"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportedModes": [
"OFF",
"COOL"
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.1",
"properties": {
"supported": [
{
"name": "connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}

View file

@ -0,0 +1,100 @@
{
"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": "Manufacturer of the endpoint",
"description": "Smart Thermostat by Thermostat Maker",
"friendlyName": "Hallway Thermostat",
"displayCategories": [
"THERMOSTAT",
"TEMPERATURE_SENSOR"
],
"additionalAttributes": {
"manufacturer": "Manufacturer of the endpoint",
"model": "Model of the device",
"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": "lowerSetpoint"
},
{
"name": "upperSetpoint"
},
{
"name": "thermostatMode"
},
{
"name": "adaptiveRecoveryStatus"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportedModes": [
"HEAT",
"COOL",
"AUTO",
"EM_HEAT"
],
"supportsScheduling": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.TemperatureSensor",
"version": "3",
"properties": {
"supported": [
{
"name": "temperature"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [
{
"name": "connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}

View file

@ -12,6 +12,8 @@
// refused [[directive, payload, message]]: a payload the directive does not take, and the message of the
// INVALID_VALUE that answers it
// unfit [[property, value]]: a value the property does not take
// chosen true: a declaration lists the properties the device has, an example some of those of the interface
// folded the directives whose example the page folds away, so that it was not saved
//
// test/registry/descriptors.test.js, test/device/discovery.test.js and test/dispatch/interfaces.test.js run the
// entries. The first one fails for a descriptor of tier 1 or 2 that has no entry.
@ -108,6 +110,59 @@ module.exports = [
}],
},
{ namespace: "Alexa.TemperatureSensor", page: "alexa-temperaturesensor", declared: [{ options: reported, example: "discovery" }] },
{
namespace: "Alexa.ThermostatController",
page: "alexa-thermostatcontroller",
chosen: true,
declared: [
{
example: "discovery",
options: {
...reported,
supportedModes: ["HEAT", "COOL", "AUTO", "EM_HEAT"],
supportsScheduling: true,
properties: ["lowerSetpoint", "upperSetpoint", "thermostatMode", "adaptiveRecoveryStatus"],
},
},
{
page: "alexa-thermostatcontroller-schedule",
example: "discovery",
options: { ...reported, supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: true, properties: ["thermostatMode"] },
},
],
refused: [
["SetTargetTemperature", { targetSetpoint: { value: 20, scale: "RANKINE" } }, 'payload.targetSetpoint.scale: expected CELSIUS | FAHRENHEIT | KELVIN, got "RANKINE"'],
[
"SetTargetTemperature",
{ holdUntil: { duration: "PT30M" } },
'payload: expected one or more of targetSetpoint, lowerSetpoint, upperSetpoint, got {"holdUntil":{"duration":"PT30M"}}',
],
[
"SetTargetTemperature",
{ targetSetpoint: { value: 20, scale: "CELSIUS" }, holdUntil: { duration: "30 minutes" } },
'payload.holdUntil.duration: expected a duration like PT3M15S, got "30 minutes"',
],
["AdjustTargetTemperature", { targetSetpointDelta: 2 }, "payload.targetSetpointDelta: expected an object with value, scale, got 2"],
["SetThermostatMode", { thermostatMode: { value: "WARM" } }, 'payload.thermostatMode.value: expected AUTO | COOL | ECO | EM_HEAT | HEAT | OFF, got "WARM"'],
["SetThermostatMode", { thermostatMode: "HEAT" }, 'payload.thermostatMode: expected an object with value, got "HEAT"'],
],
unfit: [["thermostatMode", "EMERGENCY"], ["targetSetpoint", 20], ["upperSetpoint", { value: 20 }], ["adaptiveRecoveryStatus", "ACTIVE"]],
},
{
namespace: "Alexa.ThermostatController.Schedule",
page: "alexa-thermostatcontroller-schedule",
folded: ["SetWeeklySchedule"],
declared: [{
example: "discovery",
options: { ...reported, supportedFanModes: ["ON", "AUTO"], supportsAdaptiveRecovery: true, maxEntryPerDay: 4 },
}],
refused: [
["SetScheduleState", { scheduleEnabled: "yes" }, 'payload.scheduleEnabled: expected true or false, got "yes"'],
["SetAdaptiveRecovery", {}, "payload.adaptiveRecoveryEnabled: expected true or false, got nothing"],
["SetWeeklySchedule", { weeklySchedule: { temperatureScale: "CELSIUS" } }, "payload.weeklySchedule.Monday: expected a list, got nothing"],
],
unfit: [["scheduleEnabled", "ON"], ["adaptiveRecoveryEnabled", 1]],
},
{
namespace: "Alexa.ToggleController",
page: "alexa-togglecontroller",

View file

@ -30,7 +30,7 @@ test("a descriptor of tier 1 or 2 has an entry in test/fixtures/interfaces.js, a
assert.deepEqual(described.map((descriptor) => descriptor.namespace), interfaces.map((entry) => entry.namespace).sort());
});
for (const { namespace, page, declared, unfit = [] } of interfaces) {
for (const { namespace, page, declared, unfit = [], chosen = false, folded = [] } of interfaces) {
test(`${namespace}: version, properties, directive payloads and property values of ${page}.html`, () => {
const descriptor = registry.get(namespace);
assert.ok(descriptor.doc.endsWith(`/${page}.html`), descriptor.doc);
@ -43,14 +43,15 @@ for (const { namespace, page, declared, unfit = [] } of interfaces) {
assert.equal(capability.version, descriptor.version, `${example}: version`);
assert.equal("instance" in capability, descriptor.instanced, `${example}: instance`);
const supported = capability.properties ? capability.properties.supported.map((property) => property.name) : [];
assert.deepEqual(supported, Object.keys(descriptor.properties), `${example}: properties`);
const known = Object.keys(descriptor.properties);
assert.deepEqual(supported, chosen ? known.filter((name) => supported.includes(name)) : known, `${example}: properties`);
}
}
const directives = examples(page, ".directive").map((name) => doc(page, name).directive);
assert.deepEqual(
directives.map((directive) => directive.header.name).sort(),
Object.keys(descriptor.directives).filter((name) => name !== "ReportState").sort(),
[...new Set(directives.map((directive) => directive.header.name))].sort(),
Object.keys(descriptor.directives).filter((name) => name !== "ReportState" && !folded.includes(name)).sort(),
"the page has an example of every directive"
);
for (const { header, payload } of directives) {
@ -131,16 +132,18 @@ test("every AlexaInterfaceType is in the registry: described, or a stub with the
assert.deepEqual(stub.directives, {}, stub.namespace);
assert.equal(stub.instanced, false, stub.namespace);
}
const thermostat = registry.get("Alexa.ThermostatController");
assert.equal(thermostat.version, "3.2");
assert.deepEqual(Object.keys(thermostat.properties), ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"]);
});
test("AlexaInterface.getVersion() and getProps() read the registry", () => {
// What a thermostat lists is for its declaration to say: a 1.x declaration lists what 1.5.2 listed
const chosen = {
"Alexa.ThermostatController": ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"],
"Alexa.ThermostatController.Schedule": ["scheduleEnabled"],
};
for (const descriptor of registry.list().filter(({ namespace }) => namespace !== "Alexa")) {
const capability = new AlexaInterface(descriptor.namespace);
assert.equal(capability.getVersion(), descriptor.version, descriptor.namespace);
assert.deepEqual(capability.getProps(), Object.keys(descriptor.properties), descriptor.namespace);
assert.deepEqual(capability.getProps(), chosen[descriptor.namespace] ?? Object.keys(descriptor.properties), descriptor.namespace);
}
// 1.5.2 had no version for these two and put "UNKNOWN" in discovery
assert.equal(new AlexaInterface(AlexaInterfaceType.TIME_HOLD_CONTROLLER).getVersion(), "3");

View file

@ -0,0 +1,153 @@
"use strict";
// Alexa.ThermostatController 3.2 and Alexa.ThermostatController.Schedule: what the examples of their pages do not
// show. The examples themselves are run by descriptors.test.js, device/discovery.test.js and dispatch/interfaces.test.js.
const { test } = require("node:test");
const assert = require("node:assert/strict");
const {
AlexaInterfaceType, AlexaStatusMessage, DeclarationError, SchemaError, TemperatureSensorScale, ThermostatController,
ThermostatControllerSchedule, ThermostatMode, ThermostatModes,
} = require("alex2node");
const { endpoint } = require("../helpers/endpoint.js");
const { capabilities } = require("../helpers/fixtures.js");
const celsius = (value) => ({ value, scale: "CELSIUS" });
const thermostat = () => endpoint("thermo-1", "Thermostat", ["THERMOSTAT"]);
const OF_1X = {
type: "AlexaInterface",
interface: "Alexa.ThermostatController",
version: "3.2",
properties: {
supported: [{ name: "targetSetpoint" }, { name: "lowerSetpoint" }, { name: "upperSetpoint" }, { name: "thermostatMode" }],
proactivelyReported: false,
retrievable: true,
},
configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false },
};
test("SetTargetTemperature: one, two and three setpoints, with and without holdUntil; none is refused", () => {
const { payload } = ThermostatController.directives.SetTargetTemperature;
const single = { targetSetpoint: celsius(20) };
const dual = { lowerSetpoint: celsius(18), upperSetpoint: celsius(24) };
const hold = { holdUntil: { start: "2017-10-04T14:00Z", end: "2017-10-04T14:15Z" } };
for (const setpoints of [single, dual, { ...single, ...dual }, { ...single, ...hold }, { ...single, ...dual, ...hold }]) {
assert.deepEqual(payload.parse(setpoints, "payload"), setpoints);
}
assert.throws(() => payload.parse({}, "payload"), /^SchemaError: payload: expected one or more of targetSetpoint, lowerSetpoint, upperSetpoint, got \{\}$/);
assert.throws(() => payload.parse(hold, "payload"), SchemaError);
const all = { start: "2017-10-04T14:00Z", end: "2017-10-04T14:15Z", duration: "PT15M" };
assert.throws(() => payload.parse({ ...single, holdUntil: all }, "payload"), /^SchemaError: payload\.holdUntil: expected a time interval with one or two of/);
});
test("the modes are the six of the page, EM_HEAT among them, in a directive and in a report", () => {
assert.deepEqual(ThermostatModes, ["AUTO", "COOL", "ECO", "EM_HEAT", "HEAT", "OFF"]);
const { directives, properties } = ThermostatController;
for (const value of ThermostatModes) {
assert.deepEqual(directives.SetThermostatMode.payload.parse({ thermostatMode: { value } }), { thermostatMode: { value } });
assert.equal(properties.thermostatMode.value.parse(value), value);
}
assert.equal(ThermostatMode.EM_HEAT, "EM_HEAT");
// The mode 1.x had of its own is none Alexa knows
assert.throws(() => properties.thermostatMode.value.parse(ThermostatMode.CUSTOM, "thermostatMode"), SchemaError);
});
test("a thermostat declared without options, the 1.x way or with add(), is announced as 1.5.2 announced it", () => {
const capability = thermostat().addCapability(AlexaInterfaceType.THERMOSTAT_CONTROLLER);
assert.deepEqual(capability.getJSON(), OF_1X);
assert.deepEqual(capability.getProps(), ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"]);
const device = thermostat();
assert.deepEqual(device.add(ThermostatController).toJSON(), OF_1X);
assert.deepEqual(device.check(), []);
});
test("a thermostat declares its modes, its properties and whether it holds a temperature for a time", () => {
const heater = thermostat().add(ThermostatController, {
supportedModes: ["HEAT", "EM_HEAT", "OFF"], properties: ["targetSetpoint", "thermostatMode"], proactivelyReported: true,
});
assert.deepEqual(heater.toJSON(), {
...OF_1X,
properties: { supported: [{ name: "targetSetpoint" }, { name: "thermostatMode" }], proactivelyReported: true, retrievable: true },
configuration: { supportedModes: ["HEAT", "EM_HEAT", "OFF"], supportsScheduling: false },
});
// The air conditioner of the page leaves supportsScheduling out, which is false: "The default is false"
const [printed] = capabilities("alexa-thermostatcontroller", "Alexa.ThermostatController", "discovery-air-conditioner");
const conditioner = thermostat().add(ThermostatController, {
supportedModes: ["OFF", "COOL"], properties: ["targetSetpoint", "thermostatMode"], proactivelyReported: true,
});
assert.equal("supportsScheduling" in printed.configuration, false);
assert.deepEqual(conditioner.toJSON(), { ...printed, configuration: { ...printed.configuration, supportsScheduling: false } });
});
test("a declaration Alexa would reject is refused: no HEAT or COOL, an entry twice, a name that is none", () => {
const refused = (options) => {
try {
thermostat().add(ThermostatController, options);
} catch (err) {
assert.ok(err instanceof DeclarationError, String(err));
return err.message;
}
return "declared";
};
assert.equal(refused({ supportedModes: ["AUTO", "OFF"] }), "thermo-1: Alexa.ThermostatController: supportedModes AUTO, OFF has neither HEAT nor COOL, Alexa wants one");
assert.equal(refused({ supportedModes: ["HEAT", "OFF", "HEAT"] }), "thermo-1: Alexa.ThermostatController: HEAT is listed twice");
assert.equal(refused({ properties: ["targetSetpoint", "targetSetpoint"] }), "thermo-1: Alexa.ThermostatController: targetSetpoint is listed twice");
assert.match(refused({ supportedModes: ["HEAT", "WARM"] }), /supportedModes\[1\]: expected AUTO \| COOL \| ECO \| EM_HEAT \| HEAT \| OFF, got "WARM"$/);
assert.match(refused({ properties: ["setpoint"] }), /properties\[0\]: expected targetSetpoint \| .* \| adaptiveRecoveryStatus, got "setpoint"$/);
assert.match(refused({ modes: ["HEAT"] }), /modes: unknown key/);
});
test("what the 1.x helpers report for a thermostat is the JSON of 1.5.2, and a value the interface takes", () => {
const message = new AlexaStatusMessage("ct", "root", "thermo-1", null, true)
.addThermostatModeProp(ThermostatMode.HEAT)
.addThermostatControllerProp("targetSetpoint", TemperatureSensorScale.CELSIUS, 21.5)
.addThermostatControllerProp("lowerSetpoint", TemperatureSensorScale.FAHRENHEIT, 68)
.addThermostatControllerProp("upperSetpoint", TemperatureSensorScale.FAHRENHEIT, 77);
const reported = message.toJSON().context.properties;
assert.deepEqual(reported.map(({ namespace, name, value }) => [namespace, name, value]), [
["Alexa.ThermostatController", "thermostatMode", "HEAT"],
["Alexa.ThermostatController", "targetSetpoint", celsius(21.5)],
["Alexa.ThermostatController", "lowerSetpoint", celsius(20)],
["Alexa.ThermostatController", "upperSetpoint", celsius(25)],
]);
for (const { name, value } of reported) assert.deepEqual(ThermostatController.properties[name].value.parse(value, name), value);
});
test("Schedule: a 1.x declaration lists scheduleEnabled and no configuration, and check() names what is missing", () => {
const device = thermostat();
const capability = device.addCapability(AlexaInterfaceType.THERMOSTAT_CONTROLLER_SCHEDULE);
assert.deepEqual(capability.getJSON(), {
type: "AlexaInterface",
interface: "Alexa.ThermostatController.Schedule",
version: "3.2",
properties: { supported: [{ name: "scheduleEnabled" }], proactivelyReported: false, retrievable: true },
});
assert.deepEqual(device.check(), ["thermo-1: Alexa.ThermostatController.Schedule: supportedFanModes: expected a list, got nothing"]);
const plain = thermostat().add(ThermostatControllerSchedule, { supportedFanModes: ["ON", "AUTO", "CIRCULATE"], supportsAdaptiveRecovery: false });
assert.deepEqual(plain.toJSON().properties.supported, [{ name: "scheduleEnabled" }]);
assert.deepEqual(plain.toJSON().configuration, { supportedFanModes: ["ON", "AUTO", "CIRCULATE"], supportsAdaptiveRecovery: false });
});
test("SetWeeklySchedule: a week of entries as the tables of the page describe them", () => {
const { payload } = ThermostatControllerSchedule.directives.SetWeeklySchedule;
const workday = [
{ startTimeInMinutes: 360, setpoints: { lowerSetpoint: celsius(20), upperSetpoint: celsius(24) }, activityType: { type: "HOME" } },
{ startTimeInMinutes: 480, setpoints: { lowerSetpoint: celsius(16) }, fanSetting: { mode: "AUTO" }, activityType: { type: "AWAY" } },
{ startTimeInMinutes: 1320, setpoints: { upperSetpoint: celsius(26) }, fanSetting: { mode: "CIRCULATE" }, activityType: { type: "SLEEP" } },
];
const week = (monday) => ({
temperatureScale: "CELSIUS", Monday: monday, Tuesday: workday, Wednesday: workday, Thursday: workday, Friday: workday, Saturday: [], Sunday: [],
});
assert.deepEqual(payload.parse({ weeklySchedule: week(workday) }, "payload"), { weeklySchedule: week(workday) });
// The table marks weeklySchedule as not required
assert.deepEqual(payload.parse({}, "payload"), {});
const refused = (entry, message) => assert.throws(
() => payload.parse({ weeklySchedule: week([{ ...workday[0], ...entry }]) }, "payload"),
(err) => err instanceof SchemaError && err.message === `payload.weeklySchedule.Monday[0].${message}`
);
refused({ startTimeInMinutes: 1440 }, "startTimeInMinutes: expected an integer from 0 to 1439, got 1440");
refused({ setpoints: undefined }, "setpoints: expected an object with upperSetpoint, lowerSetpoint, got nothing");
refused({ fanSetting: { mode: "OFF" } }, 'fanSetting.mode: expected ON | AUTO | CIRCULATE, got "OFF"');
refused({ activityType: { type: "PARTY" } }, 'activityType.type: expected AWAY | HOME | SLEEP, got "PARTY"');
});