From f555a5df70d61823a8e55e954b54677b5a8bf780 Mon Sep 17 00:00:00 2001 From: David Date: Mon, 28 Sep 2026 20:34:49 +0000 Subject: [PATCH] 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 --- dist/cjs/compat/AlexaInterface.js | 4 +- dist/cjs/compat/enums.js | 2 + dist/cjs/device/Capability.js | 2 +- dist/cjs/index.js | 7 +- dist/cjs/registry/index.js | 10 +- .../interfaces/ThermostatController.js | 97 +++++++++++ .../ThermostatControllerSchedule.js | 80 +++++++++ dist/cjs/registry/interfaces/stubs.js | 7 +- dist/esm/compat/AlexaInterface.d.ts | 2 +- dist/esm/compat/AlexaInterface.js | 4 +- dist/esm/compat/enums.d.ts | 4 +- dist/esm/compat/enums.js | 2 + dist/esm/device/Capability.js | 2 +- dist/esm/index.d.ts | 6 +- dist/esm/index.js | 4 +- dist/esm/registry/index.d.ts | 6 +- dist/esm/registry/index.js | 7 +- .../interfaces/ThermostatController.d.ts | 71 ++++++++ .../interfaces/ThermostatController.js | 94 +++++++++++ .../ThermostatControllerSchedule.d.ts | 142 ++++++++++++++++ .../ThermostatControllerSchedule.js | 77 +++++++++ dist/esm/registry/interfaces/stubs.js | 7 +- dist/esm/registry/types.d.ts | 2 + dist/types/compat/AlexaInterface.d.ts | 2 +- dist/types/compat/enums.d.ts | 4 +- dist/types/index.d.ts | 6 +- dist/types/registry/index.d.ts | 6 +- .../interfaces/ThermostatController.d.ts | 71 ++++++++ .../ThermostatControllerSchedule.d.ts | 142 ++++++++++++++++ dist/types/registry/types.d.ts | 2 + src/compat/AlexaInterface.ts | 4 +- src/compat/enums.ts | 2 + src/device/Capability.ts | 2 +- src/index.ts | 6 +- src/registry/index.ts | 8 +- .../interfaces/ThermostatController.ts | 101 ++++++++++++ .../ThermostatControllerSchedule.ts | 81 ++++++++++ src/registry/interfaces/stubs.ts | 7 +- src/registry/types.ts | 2 + test/dispatch/interfaces.test.js | 39 ++++- .../REQUESTED_SETPOINTS_TOO_CLOSE.error.json | 22 +++ .../TEMPERATURE_VALUE_OUT_OF_RANGE.error.json | 28 ++++ .../THERMOSTAT_IS_OFF.error.json | 22 +++ .../ChangeReport.json | 60 +++++++ .../SetAdaptiveRecovery.directive.json | 22 +++ .../SetScheduleState.directive.json | 22 +++ .../StateReport.json | 53 ++++++ .../discovery.json | 101 ++++++++++++ .../AdjustTargetTemperature.directive.json | 25 +++ .../AdjustTargetTemperature.response.json | 46 ++++++ .../ChangeReport-air-conditioner.json | 73 +++++++++ .../ChangeReport.json | 66 ++++++++ .../ResumeSchedule.directive.json | 20 +++ .../ResumeSchedule.response.json | 46 ++++++ .../SetTargetTemperature-dual.directive.json | 32 ++++ .../SetTargetTemperature-dual.response.json | 56 +++++++ ...SetTargetTemperature-single.directive.json | 29 ++++ .../SetTargetTemperature-single.response.json | 46 ++++++ .../SetThermostatMode.directive.json | 24 +++ .../SetThermostatMode.response.json | 46 ++++++ .../StateReport-air-conditioner.json | 63 ++++++++ .../StateReport.json | 59 +++++++ .../discovery-air-conditioner.json | 91 +++++++++++ .../alexa-thermostatcontroller/discovery.json | 100 ++++++++++++ test/fixtures/interfaces.js | 55 +++++++ test/registry/descriptors.test.js | 19 ++- test/registry/thermostat.test.js | 153 ++++++++++++++++++ 67 files changed, 2445 insertions(+), 58 deletions(-) create mode 100644 dist/cjs/registry/interfaces/ThermostatController.js create mode 100644 dist/cjs/registry/interfaces/ThermostatControllerSchedule.js create mode 100644 dist/esm/registry/interfaces/ThermostatController.d.ts create mode 100644 dist/esm/registry/interfaces/ThermostatController.js create mode 100644 dist/esm/registry/interfaces/ThermostatControllerSchedule.d.ts create mode 100644 dist/esm/registry/interfaces/ThermostatControllerSchedule.js create mode 100644 dist/types/registry/interfaces/ThermostatController.d.ts create mode 100644 dist/types/registry/interfaces/ThermostatControllerSchedule.d.ts create mode 100644 src/registry/interfaces/ThermostatController.ts create mode 100644 src/registry/interfaces/ThermostatControllerSchedule.ts create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/REQUESTED_SETPOINTS_TOO_CLOSE.error.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/TEMPERATURE_VALUE_OUT_OF_RANGE.error.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/THERMOSTAT_IS_OFF.error.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/ChangeReport.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/SetAdaptiveRecovery.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/SetScheduleState.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/StateReport.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/discovery.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/AdjustTargetTemperature.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/AdjustTargetTemperature.response.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/ChangeReport-air-conditioner.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/ChangeReport.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/ResumeSchedule.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/ResumeSchedule.response.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-dual.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-dual.response.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-single.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-single.response.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/SetThermostatMode.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/SetThermostatMode.response.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/StateReport-air-conditioner.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/StateReport.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/discovery-air-conditioner.json create mode 100644 test/fixtures/alexa-docs/alexa-thermostatcontroller/discovery.json create mode 100644 test/registry/thermostat.test.js diff --git a/dist/cjs/compat/AlexaInterface.js b/dist/cjs/compat/AlexaInterface.js index 6abe5c2..75b4abd 100644 --- a/dist/cjs/compat/AlexaInterface.js +++ b/dist/cjs/compat/AlexaInterface.js @@ -56,9 +56,9 @@ class AlexaInterface extends Capability_js_1.Capability { getVersion() { return this.descriptor.version; } - /** @deprecated Read the keys of descriptor.properties. */ + /** @deprecated The properties discovery lists: read properties.supported of toJSON(). */ getProps() { - return Object.keys(this.descriptor.properties); + return (super.toJSON().properties?.supported ?? []).map(({ name }) => name); } getJSON() { return super.toJSON(); diff --git a/dist/cjs/compat/enums.js b/dist/cjs/compat/enums.js index 2fed837..6a515b4 100644 --- a/dist/cjs/compat/enums.js +++ b/dist/cjs/compat/enums.js @@ -172,6 +172,8 @@ var ThermostatMode; ThermostatMode["AUTO"] = "AUTO"; ThermostatMode["ECO"] = "ECO"; ThermostatMode["CUSTOM"] = "CUSTOM"; + /** Emergency heating, since 2.0. */ + ThermostatMode["EM_HEAT"] = "EM_HEAT"; })(ThermostatMode || (exports.ThermostatMode = ThermostatMode = {})); /** The scale of a temperature given to addTemperatureSensorProp() and addThermostatControllerProp(). */ var TemperatureSensorScale; diff --git a/dist/cjs/device/Capability.js b/dist/cjs/device/Capability.js index 67b3f52..bcedbca 100644 --- a/dist/cjs/device/Capability.js +++ b/dist/cjs/device/Capability.js @@ -63,7 +63,7 @@ class Capability { }; if (extras.properties !== false) { json.properties = { - supported: Object.keys(descriptor.properties).map((name) => ({ name })), + supported: (extras.supported ?? Object.keys(descriptor.properties)).map((name) => ({ name })), proactivelyReported: this.proactivelyReported, retrievable: this.retrievable, }; diff --git a/dist/cjs/index.js b/dist/cjs/index.js index 28d305d..512bd81 100644 --- a/dist/cjs/index.js +++ b/dist/cjs/index.js @@ -36,8 +36,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) { return (mod && mod.__esModule) ? mod : { "default": mod }; }; Object.defineProperty(exports, "__esModule", { value: true }); -exports.AlexaStatusMessage = exports.ThermostatMode = exports.TemperatureSensorScale = exports.PowerState = exports.DisplayCategory = exports.AlexaInterfaceType = exports.AlexaErrorType = exports.AlexaActions = exports.ActionMapping = exports.AlexaInterface = exports.MemoryPublisher = exports.topics = exports.property = exports.StateBuilder = exports.MessageError = exports.AlexaErrors = exports.AlexaError = exports.messages = exports.DisplayCategories = exports.States = exports.Actions = exports.Units = exports.Assets = exports.SemanticsBuilder = exports.semantics = exports.text = exports.asset = exports.EndpointHealth = exports.PowerController = exports.ToggleController = exports.TemperatureSensor = exports.RangeController = exports.PowerLevelController = exports.PercentageController = exports.MotionSensor = exports.ModeController = exports.LockController = exports.HumiditySensor = exports.ContactSensor = exports.ColorTemperatureController = exports.ColorController = exports.BrightnessController = exports.Alexa = exports.SchemaError = exports.DeclarationError = exports.registry = exports.Capability = exports.Device = exports.DEFAULT_HOST = exports.Alex2MQTT = void 0; -exports.AlexaErrorResponse = void 0; +exports.PowerState = exports.DisplayCategory = exports.AlexaInterfaceType = exports.AlexaErrorType = exports.AlexaActions = exports.ActionMapping = exports.AlexaInterface = exports.MemoryPublisher = exports.topics = exports.property = exports.StateBuilder = exports.MessageError = exports.AlexaErrors = exports.AlexaError = exports.messages = exports.ThermostatModes = exports.DisplayCategories = exports.States = exports.Actions = exports.Units = exports.Assets = exports.SemanticsBuilder = exports.semantics = exports.text = exports.asset = exports.EndpointHealth = exports.PowerController = exports.ToggleController = exports.ThermostatControllerSchedule = exports.ThermostatController = exports.TemperatureSensor = exports.RangeController = exports.PowerLevelController = exports.PercentageController = exports.MotionSensor = exports.ModeController = exports.LockController = exports.HumiditySensor = exports.ContactSensor = exports.ColorTemperatureController = exports.ColorController = exports.BrightnessController = exports.Alexa = exports.SchemaError = exports.DeclarationError = exports.registry = exports.Capability = exports.Device = exports.DEFAULT_HOST = exports.Alex2MQTT = void 0; +exports.AlexaErrorResponse = exports.AlexaStatusMessage = exports.ThermostatMode = exports.TemperatureSensorScale = void 0; // Relative specifiers carry ".js": Node's ES module loader resolves no extension, and TypeScript maps it back to the .ts. var Alex2Node_js_1 = require("./Alex2Node.js"); Object.defineProperty(exports, "Alex2MQTT", { enumerable: true, get: function () { return __importDefault(Alex2Node_js_1).default; } }); @@ -65,6 +65,8 @@ Object.defineProperty(exports, "PercentageController", { enumerable: true, get: Object.defineProperty(exports, "PowerLevelController", { enumerable: true, get: function () { return index_js_2.PowerLevelController; } }); Object.defineProperty(exports, "RangeController", { enumerable: true, get: function () { return index_js_2.RangeController; } }); Object.defineProperty(exports, "TemperatureSensor", { enumerable: true, get: function () { return index_js_2.TemperatureSensor; } }); +Object.defineProperty(exports, "ThermostatController", { enumerable: true, get: function () { return index_js_2.ThermostatController; } }); +Object.defineProperty(exports, "ThermostatControllerSchedule", { enumerable: true, get: function () { return index_js_2.ThermostatControllerSchedule; } }); Object.defineProperty(exports, "ToggleController", { enumerable: true, get: function () { return index_js_2.ToggleController; } }); var enums_js_1 = require("./compat/enums.js"); Object.defineProperty(exports, "PowerController", { enumerable: true, get: function () { return enums_js_1.PowerController; } }); @@ -81,6 +83,7 @@ Object.defineProperty(exports, "Units", { enumerable: true, get: function () { r Object.defineProperty(exports, "Actions", { enumerable: true, get: function () { return index_js_4.ACTIONS; } }); Object.defineProperty(exports, "States", { enumerable: true, get: function () { return index_js_4.STATES; } }); Object.defineProperty(exports, "DisplayCategories", { enumerable: true, get: function () { return index_js_4.DISPLAY_CATEGORIES; } }); +Object.defineProperty(exports, "ThermostatModes", { enumerable: true, get: function () { return index_js_4.THERMOSTAT_MODES; } }); // The messages: what the bridge publishes, built from plain values exports.messages = __importStar(require("./messages/index.js")); var index_js_5 = require("./messages/index.js"); diff --git a/dist/cjs/registry/index.js b/dist/cjs/registry/index.js index 00b3f29..0ea83c5 100644 --- a/dist/cjs/registry/index.js +++ b/dist/cjs/registry/index.js @@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) { for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p); }; Object.defineProperty(exports, "__esModule", { value: true }); -exports.SchemaError = exports.s = exports.defineInterface = exports.DeclarationError = exports.SemanticsBuilder = exports.semantics = exports.text = exports.asset = exports.ToggleController = exports.TemperatureSensor = exports.RangeController = exports.PowerLevelController = exports.PowerController = exports.PercentageController = exports.MotionSensor = exports.ModeController = exports.LockController = exports.HumiditySensor = exports.EndpointHealth = exports.ContactSensor = exports.ColorTemperatureController = exports.ColorController = exports.BrightnessController = exports.Alexa = exports.registry = void 0; +exports.SchemaError = exports.s = exports.defineInterface = exports.DeclarationError = exports.SemanticsBuilder = exports.semantics = exports.text = exports.asset = exports.THERMOSTAT_MODES = exports.ToggleController = exports.ThermostatControllerSchedule = exports.ThermostatController = exports.TemperatureSensor = exports.RangeController = exports.PowerLevelController = exports.PowerController = exports.PercentageController = exports.MotionSensor = exports.ModeController = exports.LockController = exports.HumiditySensor = exports.EndpointHealth = exports.ContactSensor = exports.ColorTemperatureController = exports.ColorController = exports.BrightnessController = exports.Alexa = exports.registry = void 0; // The interfaces the library knows, by namespace. const Alexa_js_1 = require("./interfaces/Alexa.js"); Object.defineProperty(exports, "Alexa", { enumerable: true, get: function () { return Alexa_js_1.Alexa; } }); @@ -46,6 +46,10 @@ const RangeController_js_1 = require("./interfaces/RangeController.js"); Object.defineProperty(exports, "RangeController", { enumerable: true, get: function () { return RangeController_js_1.RangeController; } }); const TemperatureSensor_js_1 = require("./interfaces/TemperatureSensor.js"); Object.defineProperty(exports, "TemperatureSensor", { enumerable: true, get: function () { return TemperatureSensor_js_1.TemperatureSensor; } }); +const ThermostatController_js_1 = require("./interfaces/ThermostatController.js"); +Object.defineProperty(exports, "ThermostatController", { enumerable: true, get: function () { return ThermostatController_js_1.ThermostatController; } }); +const ThermostatControllerSchedule_js_1 = require("./interfaces/ThermostatControllerSchedule.js"); +Object.defineProperty(exports, "ThermostatControllerSchedule", { enumerable: true, get: function () { return ThermostatControllerSchedule_js_1.ThermostatControllerSchedule; } }); const ToggleController_js_1 = require("./interfaces/ToggleController.js"); Object.defineProperty(exports, "ToggleController", { enumerable: true, get: function () { return ToggleController_js_1.ToggleController; } }); const stubs_js_1 = require("./interfaces/stubs.js"); @@ -66,6 +70,8 @@ const described = [ PowerLevelController_js_1.PowerLevelController, RangeController_js_1.RangeController, TemperatureSensor_js_1.TemperatureSensor, + ThermostatController_js_1.ThermostatController, + ThermostatControllerSchedule_js_1.ThermostatControllerSchedule, ToggleController_js_1.ToggleController, ]; const descriptors = new Map(); @@ -92,6 +98,8 @@ exports.registry = { return [...descriptors.values()].sort((a, b) => (a.namespace < b.namespace ? -1 : 1)); }, }; +var ThermostatController_js_2 = require("./interfaces/ThermostatController.js"); +Object.defineProperty(exports, "THERMOSTAT_MODES", { enumerable: true, get: function () { return ThermostatController_js_2.THERMOSTAT_MODES; } }); var resources_js_1 = require("./resources.js"); Object.defineProperty(exports, "asset", { enumerable: true, get: function () { return resources_js_1.asset; } }); Object.defineProperty(exports, "text", { enumerable: true, get: function () { return resources_js_1.text; } }); diff --git a/dist/cjs/registry/interfaces/ThermostatController.js b/dist/cjs/registry/interfaces/ThermostatController.js new file mode 100644 index 0000000..f214a6f --- /dev/null +++ b/dist/cjs/registry/interfaces/ThermostatController.js @@ -0,0 +1,97 @@ +"use strict"; +Object.defineProperty(exports, "__esModule", { value: true }); +exports.ThermostatController = exports.THERMOSTAT_MODES = void 0; +const schema_js_1 = require("../schema.js"); +const types_js_1 = require("../types.js"); +/** alexa-property-schemas.html, "ThermostatMode values". EM_HEAT, emergency heating, came with version 3.2. */ +exports.THERMOSTAT_MODES = ["AUTO", "COOL", "ECO", "EM_HEAT", "HEAT", "OFF"]; +const PROPERTIES = ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode", "adaptiveRecoveryStatus"]; +// What 1.x announced for every thermostat. A declaration that leaves an option out announces the same. +const MODES_OF_1X = ["HEAT", "COOL", "AUTO", "OFF"]; +const PROPERTIES_OF_1X = ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"]; +const setpoints = schema_js_1.s.object({ + targetSetpoint: schema_js_1.s.optional(schema_js_1.s.temperature()), + lowerSetpoint: schema_js_1.s.optional(schema_js_1.s.temperature()), + upperSetpoint: schema_js_1.s.optional(schema_js_1.s.temperature()), + holdUntil: schema_js_1.s.optional(schema_js_1.s.timeInterval()), +}); +// One setpoint for a thermostat that holds a temperature, the lower and the upper for one that holds a range, all +// three for one that aims at a temperature within a range. The page marks each as not required; a payload without +// any sets nothing. +const setTargetTemperature = { + expects: "one or more of targetSetpoint, lowerSetpoint, upperSetpoint", + parse(input, path = "") { + const payload = setpoints.parse(input, path); + if (!payload.targetSetpoint && !payload.lowerSetpoint && !payload.upperSetpoint) + throw (0, schema_js_1.mismatch)(path, this.expects, input); + return payload; + }, +}; +/** + * Version 3.2. A thermostat declares the properties it has: targetSetpoint for a single setpoint, lowerSetpoint and + * upperSetpoint for two, all three for a target within a range. Temperatures are reported "in the same temperature + * scale (Celsius or Fahrenheit) that the thermostat is set to display". An error of errorTypes goes under the + * namespace of the interface, TEMPERATURE_VALUE_OUT_OF_RANGE under Alexa + * (alexa-thermostatcontroller-errorresponse.html). + */ +exports.ThermostatController = (0, types_js_1.defineInterface)({ + namespace: "Alexa.ThermostatController", + version: "3.2", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-thermostatcontroller.html", + kind: "controller", + tier: 1, + instanced: false, + properties: { + targetSetpoint: { name: "targetSetpoint", value: schema_js_1.s.temperature() }, + lowerSetpoint: { name: "lowerSetpoint", value: schema_js_1.s.temperature() }, + upperSetpoint: { name: "upperSetpoint", value: schema_js_1.s.temperature() }, + thermostatMode: { name: "thermostatMode", value: schema_js_1.s.enum(...exports.THERMOSTAT_MODES) }, + adaptiveRecoveryStatus: { + name: "adaptiveRecoveryStatus", + value: schema_js_1.s.enum("PREHEATING", "PRECOOLING", "INACTIVE"), + note: "heating or cooling ahead of an entry of the schedule, of Alexa.ThermostatController.Schedule", + }, + }, + directives: { + SetTargetTemperature: { + name: "SetTargetTemperature", + payload: setTargetTemperature, + note: "holdUntil comes only to a thermostat declared with supportsScheduling", + }, + AdjustTargetTemperature: { name: "AdjustTargetTemperature", payload: schema_js_1.s.object({ targetSetpointDelta: schema_js_1.s.temperature() }) }, + SetThermostatMode: { + name: "SetThermostatMode", + payload: schema_js_1.s.object({ thermostatMode: schema_js_1.s.object({ value: schema_js_1.s.enum(...exports.THERMOSTAT_MODES) }) }), + }, + ResumeSchedule: { name: "ResumeSchedule", payload: schema_js_1.s.object({}), note: "en-US only" }, + }, + options: schema_js_1.s.object({ + /** Default: HEAT, COOL, AUTO, OFF. */ + supportedModes: schema_js_1.s.optional(schema_js_1.s.array(schema_js_1.s.enum(...exports.THERMOSTAT_MODES), { min: 1 })), + /** The user can set a temperature for a time: SetTargetTemperature comes with holdUntil. Default: false. */ + supportsScheduling: schema_js_1.s.optional(schema_js_1.s.boolean()), + /** The properties the thermostat has. Default: the three setpoints and thermostatMode. */ + properties: schema_js_1.s.optional(schema_js_1.s.array(schema_js_1.s.enum(...PROPERTIES), { min: 1 })), + }, { unknownKeys: "reject" }), + discovery({ options: { supportedModes = MODES_OF_1X, supportsScheduling = false, properties = PROPERTIES_OF_1X } }) { + return { supported: properties, configuration: { supportedModes, supportsScheduling } }; + }, + validate(capability) { + const { supportedModes = MODES_OF_1X, properties = PROPERTIES_OF_1X } = capability.options; + // alexa-thermostatcontroller.html, "Configuration object": "You must include at least one of HEAT or COOL" + if (!supportedModes.includes("HEAT") && !supportedModes.includes("COOL")) { + throw new types_js_1.DeclarationError(capability, `supportedModes ${supportedModes.join(", ")} has neither HEAT nor COOL, Alexa wants one`); + } + const lists = [supportedModes, properties]; + for (const list of lists) { + const twice = list.find((entry, i) => list.indexOf(entry) !== i); + if (twice) + throw new types_js_1.DeclarationError(capability, `${twice} is listed twice`); + } + }, + errorNamespace: "Alexa.ThermostatController", + errorTypes: [ + "DUAL_SETPOINTS_UNSUPPORTED", "REQUESTED_SETPOINTS_TOO_CLOSE", "THERMOSTAT_IS_OFF", "TRIPLE_SETPOINTS_UNSUPPORTED", + "UNSUPPORTED_THERMOSTAT_MODE", "UNWILLING_TO_SET_SCHEDULE", "UNWILLING_TO_SET_VALUE", + ], +}); diff --git a/dist/cjs/registry/interfaces/ThermostatControllerSchedule.js b/dist/cjs/registry/interfaces/ThermostatControllerSchedule.js new file mode 100644 index 0000000..ae60bc8 --- /dev/null +++ b/dist/cjs/registry/interfaces/ThermostatControllerSchedule.js @@ -0,0 +1,80 @@ +"use strict"; +Object.defineProperty(exports, "__esModule", { value: true }); +exports.ThermostatControllerSchedule = void 0; +const schema_js_1 = require("../schema.js"); +const types_js_1 = require("../types.js"); +const FAN_MODES = ["ON", "AUTO", "CIRCULATE"]; +// alexa-thermostatcontroller-schedule.html, "ScheduleEntry object": an entry ends where the next one starts +const entry = schema_js_1.s.object({ + startTimeInMinutes: schema_js_1.s.number({ min: 0, max: 1439, integer: true }), + setpoints: schema_js_1.s.object({ upperSetpoint: schema_js_1.s.optional(schema_js_1.s.temperature()), lowerSetpoint: schema_js_1.s.optional(schema_js_1.s.temperature()) }), + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: schema_js_1.s.optional(schema_js_1.s.object({ mode: schema_js_1.s.optional(schema_js_1.s.enum(...FAN_MODES)) })), + activityType: schema_js_1.s.optional(schema_js_1.s.object({ type: schema_js_1.s.enum("AWAY", "HOME", "SLEEP") })), +}); +const day = schema_js_1.s.array(entry); +// Same page, "WeeklySchedule object" +const weeklySchedule = schema_js_1.s.object({ + temperatureScale: schema_js_1.s.enum("CELSIUS", "FAHRENHEIT", "KELVIN"), + Monday: day, + Tuesday: day, + Wednesday: day, + Thursday: day, + Friday: day, + Saturday: day, + Sunday: day, +}); +/** + * Version 3.2. The schedule a user writes in the Alexa app: the interface has no utterances. Discovery lists + * adaptiveRecoveryEnabled for a thermostat declared with supportsAdaptiveRecovery, and Alexa sends + * SetAdaptiveRecovery to such a thermostat only. + */ +exports.ThermostatControllerSchedule = (0, types_js_1.defineInterface)({ + namespace: "Alexa.ThermostatController.Schedule", + version: "3.2", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-thermostatcontroller-schedule.html", + kind: "controller", + tier: 2, + instanced: false, + properties: { + adaptiveRecoveryEnabled: { name: "adaptiveRecoveryEnabled", value: schema_js_1.s.boolean() }, + scheduleEnabled: { name: "scheduleEnabled", value: schema_js_1.s.boolean() }, + }, + directives: { + SetWeeklySchedule: { + name: "SetWeeklySchedule", + payload: schema_js_1.s.object({ weeklySchedule: schema_js_1.s.optional(weeklySchedule) }), + note: "a schedule the thermostat cannot keep leaves the one it has and is answered with an error", + }, + SetScheduleState: { + name: "SetScheduleState", + payload: schema_js_1.s.object({ scheduleEnabled: schema_js_1.s.boolean() }), + note: "a disabled schedule is kept: the user can enable it again", + }, + SetAdaptiveRecovery: { + name: "SetAdaptiveRecovery", + payload: schema_js_1.s.object({ adaptiveRecoveryEnabled: schema_js_1.s.boolean() }), + when: ({ options }) => options.supportsAdaptiveRecovery === true, + }, + }, + options: schema_js_1.s.object({ + supportedFanModes: schema_js_1.s.array(schema_js_1.s.enum(...FAN_MODES)), + /** The thermostat heats or cools ahead of an entry, to be at its temperature when it starts. */ + supportsAdaptiveRecovery: schema_js_1.s.boolean(), + maxEntryPerDay: schema_js_1.s.optional(schema_js_1.s.number({ min: 1, integer: true })), + }, { unknownKeys: "reject" }), + // A capability declared the 1.x way has none of the options; check() says so, discovery lists what there is + discovery({ options: { supportedFanModes, supportsAdaptiveRecovery, maxEntryPerDay } }) { + const configuration = { + ...(supportedFanModes && { supportedFanModes }), + ...(supportsAdaptiveRecovery !== undefined && { supportsAdaptiveRecovery }), + ...(maxEntryPerDay !== undefined && { maxEntryPerDay }), + }; + return { + supported: supportsAdaptiveRecovery ? ["adaptiveRecoveryEnabled", "scheduleEnabled"] : ["scheduleEnabled"], + ...(Object.keys(configuration).length > 0 && { configuration }), + }; + }, + errorNamespace: "Alexa.ThermostatController.Schedule", + errorTypes: ["INSUFFICIENT_SPACE"], +}); diff --git a/dist/cjs/registry/interfaces/stubs.js b/dist/cjs/registry/interfaces/stubs.js index 7717736..53f3b6d 100644 --- a/dist/cjs/registry/interfaces/stubs.js +++ b/dist/cjs/registry/interfaces/stubs.js @@ -59,10 +59,8 @@ const TABLE = [ ["Alexa.SmartVision.SnapshotProvider", "1", [], "alexa-smartvision-snapshotprovider.html"], ["Alexa.Speaker", "1", [], "alexa-speaker.html"], ["Alexa.StepSpeaker", "1", [], "alexa-stepspeaker.html"], - ["Alexa.ThermostatController", "3.2", ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"], "alexa-thermostatcontroller.html"], ["Alexa.ThermostatController.Configuration", "1", [], "alexa-thermostatcontroller-configuration.html"], ["Alexa.ThermostatController.HVAC.Components", "1", [], "alexa-thermostatcontroller-hvac-components.html"], - ["Alexa.ThermostatController.Schedule", "1", [], "alexa-thermostatcontroller-schedule.html"], // "UNKNOWN" in 1.5.2 as well; the page is titled "Interface 3" ["Alexa.TimeHoldController", "3", [], "alexa-timeholdcontroller.html"], ["Alexa.UIController", "1", [], "alexa-uicontroller.html"], @@ -70,16 +68,13 @@ const TABLE = [ ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"], ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"], ]; -// What 1.5.2 added to the capability object of two of them +// What 1.5.2 added to the capability object of one of them const EXTRAS = { // No properties object; supportsDeactivation and proactivelyReported on the capability itself "Alexa.SceneController": ({ proactivelyReported }) => ({ properties: false, topLevel: { supportsDeactivation: true, proactivelyReported }, }), - "Alexa.ThermostatController": () => ({ - configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false }, - }), }; function kindOf(namespace) { if (namespace.endsWith("Sensor")) diff --git a/dist/esm/compat/AlexaInterface.d.ts b/dist/esm/compat/AlexaInterface.d.ts index 8e6eb0b..13c2482 100644 --- a/dist/esm/compat/AlexaInterface.d.ts +++ b/dist/esm/compat/AlexaInterface.d.ts @@ -51,7 +51,7 @@ export declare class AlexaInterface extends Capability { getTypeString(): string; /** @deprecated Read descriptor.version. */ getVersion(): string; - /** @deprecated Read the keys of descriptor.properties. */ + /** @deprecated The properties discovery lists: read properties.supported of toJSON(). */ getProps(): string[]; getJSON(): CapabilityJson; toJSON(): CapabilityJson; diff --git a/dist/esm/compat/AlexaInterface.js b/dist/esm/compat/AlexaInterface.js index 4e104de..21f3f1a 100644 --- a/dist/esm/compat/AlexaInterface.js +++ b/dist/esm/compat/AlexaInterface.js @@ -53,9 +53,9 @@ export class AlexaInterface extends Capability { getVersion() { return this.descriptor.version; } - /** @deprecated Read the keys of descriptor.properties. */ + /** @deprecated The properties discovery lists: read properties.supported of toJSON(). */ getProps() { - return Object.keys(this.descriptor.properties); + return (super.toJSON().properties?.supported ?? []).map(({ name }) => name); } getJSON() { return super.toJSON(); diff --git a/dist/esm/compat/enums.d.ts b/dist/esm/compat/enums.d.ts index 66b7107..62b8701 100644 --- a/dist/esm/compat/enums.d.ts +++ b/dist/esm/compat/enums.d.ts @@ -199,7 +199,9 @@ export declare enum ThermostatMode { COOL = "COOL", AUTO = "AUTO", ECO = "ECO", - CUSTOM = "CUSTOM" + CUSTOM = "CUSTOM", + /** Emergency heating, since 2.0. */ + EM_HEAT = "EM_HEAT" } /** The scale of a temperature given to addTemperatureSensorProp() and addThermostatControllerProp(). */ export declare enum TemperatureSensorScale { diff --git a/dist/esm/compat/enums.js b/dist/esm/compat/enums.js index f285a61..9c4dd5d 100644 --- a/dist/esm/compat/enums.js +++ b/dist/esm/compat/enums.js @@ -169,6 +169,8 @@ export var ThermostatMode; ThermostatMode["AUTO"] = "AUTO"; ThermostatMode["ECO"] = "ECO"; ThermostatMode["CUSTOM"] = "CUSTOM"; + /** Emergency heating, since 2.0. */ + ThermostatMode["EM_HEAT"] = "EM_HEAT"; })(ThermostatMode || (ThermostatMode = {})); /** The scale of a temperature given to addTemperatureSensorProp() and addThermostatControllerProp(). */ export var TemperatureSensorScale; diff --git a/dist/esm/device/Capability.js b/dist/esm/device/Capability.js index ea8f453..8eb316b 100644 --- a/dist/esm/device/Capability.js +++ b/dist/esm/device/Capability.js @@ -60,7 +60,7 @@ export class Capability { }; if (extras.properties !== false) { json.properties = { - supported: Object.keys(descriptor.properties).map((name) => ({ name })), + supported: (extras.supported ?? Object.keys(descriptor.properties)).map((name) => ({ name })), proactivelyReported: this.proactivelyReported, retrievable: this.retrievable, }; diff --git a/dist/esm/index.d.ts b/dist/esm/index.d.ts index a1d0f1b..1d9a078 100644 --- a/dist/esm/index.d.ts +++ b/dist/esm/index.d.ts @@ -5,11 +5,11 @@ export type { EndpointDefinition, EndpointJson } from "./device/Device.js"; export { Capability } from "./device/Capability.js"; export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capability.js"; export { registry, DeclarationError, SchemaError } from "./registry/index.js"; -export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerLevelController, RangeController, TemperatureSensor, ToggleController, } from "./registry/index.js"; +export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerLevelController, RangeController, TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController, } from "./registry/index.js"; export { PowerController, EndpointHealth } from "./compat/enums.js"; export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js"; -export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js"; -export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, ActionName, StateName, Mode, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; +export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, THERMOSTAT_MODES as ThermostatModes, } from "./registry/index.js"; +export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, ActionName, StateName, Mode, ThermostatModeName, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; export * as messages from "./messages/index.js"; export { AlexaError, AlexaErrors, MessageError, StateBuilder, property } from "./messages/index.js"; export type { ChangeCause, ChangeReportMessage, DeferredResponseMessage, ErrorResponseMessage, Header, ProactiveEventMessage, Property, PropertyOptions, ResponseMessage, SceneEventMessage, } from "./messages/index.js"; diff --git a/dist/esm/index.js b/dist/esm/index.js index 29aa773..33a0a99 100644 --- a/dist/esm/index.js +++ b/dist/esm/index.js @@ -4,11 +4,11 @@ export { default as Device } from "./device/Device.js"; export { Capability } from "./device/Capability.js"; // The interfaces, for device.add(), and the registry that holds them by name export { registry, DeclarationError, SchemaError } from "./registry/index.js"; -export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerLevelController, RangeController, TemperatureSensor, ToggleController, } from "./registry/index.js"; +export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerLevelController, RangeController, TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController, } from "./registry/index.js"; export { PowerController, EndpointHealth } from "./compat/enums.js"; export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js"; // The vocabularies of the Smart Home API -export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js"; +export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, THERMOSTAT_MODES as ThermostatModes, } from "./registry/index.js"; // The messages: what the bridge publishes, built from plain values export * as messages from "./messages/index.js"; export { AlexaError, AlexaErrors, MessageError, StateBuilder, property } from "./messages/index.js"; diff --git a/dist/esm/registry/index.d.ts b/dist/esm/registry/index.d.ts index 7b7dccd..1b75de5 100644 --- a/dist/esm/registry/index.d.ts +++ b/dist/esm/registry/index.d.ts @@ -13,6 +13,8 @@ import { PowerController } from "./interfaces/PowerController.js"; import { PowerLevelController } from "./interfaces/PowerLevelController.js"; import { RangeController } from "./interfaces/RangeController.js"; import { TemperatureSensor } from "./interfaces/TemperatureSensor.js"; +import { ThermostatController } from "./interfaces/ThermostatController.js"; +import { ThermostatControllerSchedule } from "./interfaces/ThermostatControllerSchedule.js"; import { ToggleController } from "./interfaces/ToggleController.js"; import type { AnyDescriptor } from "./types.js"; export declare const registry: { @@ -23,8 +25,10 @@ export declare const registry: { /** Every descriptor, ordered by namespace. */ list(): AnyDescriptor[]; }; -export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, EndpointHealth, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerController, PowerLevelController, RangeController, TemperatureSensor, ToggleController, }; +export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, EndpointHealth, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerController, PowerLevelController, RangeController, TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController, }; export type { Mode } from "./interfaces/ModeController.js"; +export { THERMOSTAT_MODES } from "./interfaces/ThermostatController.js"; +export type { ThermostatModeName } from "./interfaces/ThermostatController.js"; export { asset, text } from "./resources.js"; export { semantics, SemanticsBuilder } from "./semantics.js"; export type { ActionName, StateName } from "./semantics.js"; diff --git a/dist/esm/registry/index.js b/dist/esm/registry/index.js index 8fbe67e..6e9fcc3 100644 --- a/dist/esm/registry/index.js +++ b/dist/esm/registry/index.js @@ -14,6 +14,8 @@ import { PowerController } from "./interfaces/PowerController.js"; import { PowerLevelController } from "./interfaces/PowerLevelController.js"; import { RangeController } from "./interfaces/RangeController.js"; import { TemperatureSensor } from "./interfaces/TemperatureSensor.js"; +import { ThermostatController } from "./interfaces/ThermostatController.js"; +import { ThermostatControllerSchedule } from "./interfaces/ThermostatControllerSchedule.js"; import { ToggleController } from "./interfaces/ToggleController.js"; import { STUBS } from "./interfaces/stubs.js"; import { DeclarationError } from "./types.js"; @@ -33,6 +35,8 @@ const described = [ PowerLevelController, RangeController, TemperatureSensor, + ThermostatController, + ThermostatControllerSchedule, ToggleController, ]; const descriptors = new Map(); @@ -59,7 +63,8 @@ export const registry = { return [...descriptors.values()].sort((a, b) => (a.namespace < b.namespace ? -1 : 1)); }, }; -export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, EndpointHealth, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerController, PowerLevelController, RangeController, TemperatureSensor, ToggleController, }; +export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, EndpointHealth, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerController, PowerLevelController, RangeController, TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController, }; +export { THERMOSTAT_MODES } from "./interfaces/ThermostatController.js"; export { asset, text } from "./resources.js"; export { semantics, SemanticsBuilder } from "./semantics.js"; export { DeclarationError, defineInterface } from "./types.js"; diff --git a/dist/esm/registry/interfaces/ThermostatController.d.ts b/dist/esm/registry/interfaces/ThermostatController.d.ts new file mode 100644 index 0000000..556bee3 --- /dev/null +++ b/dist/esm/registry/interfaces/ThermostatController.d.ts @@ -0,0 +1,71 @@ +import type { Schema } from "../schema.js"; +/** alexa-property-schemas.html, "ThermostatMode values". EM_HEAT, emergency heating, came with version 3.2. */ +export declare const THERMOSTAT_MODES: readonly ["AUTO", "COOL", "ECO", "EM_HEAT", "HEAT", "OFF"]; +export type ThermostatModeName = (typeof THERMOSTAT_MODES)[number]; +/** + * Version 3.2. A thermostat declares the properties it has: targetSetpoint for a single setpoint, lowerSetpoint and + * upperSetpoint for two, all three for a target within a range. Temperatures are reported "in the same temperature + * scale (Celsius or Fahrenheit) that the thermostat is set to display". An error of errorTypes goes under the + * namespace of the interface, TEMPERATURE_VALUE_OUT_OF_RANGE under Alexa + * (alexa-thermostatcontroller-errorresponse.html). + */ +export declare const ThermostatController: import("../types.js").InterfaceDescriptor<{ + targetSetpoint: { + name: string; + value: Schema; + }; + lowerSetpoint: { + name: string; + value: Schema; + }; + upperSetpoint: { + name: string; + value: Schema; + }; + thermostatMode: { + name: string; + value: import("../schema.js").EnumSchema<"ECO" | "OFF" | "AUTO" | "COOL" | "EM_HEAT" | "HEAT">; + }; + adaptiveRecoveryStatus: { + name: string; + value: import("../schema.js").EnumSchema<"PREHEATING" | "PRECOOLING" | "INACTIVE">; + note: string; + }; +}, { + SetTargetTemperature: { + name: string; + payload: Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + upperSetpoint: import("../schema.js").OptionalSchema; + holdUntil: import("../schema.js").OptionalSchema; + }>>; + note: string; + }; + AdjustTargetTemperature: { + name: string; + payload: Schema; + }>>; + }; + SetThermostatMode: { + name: string; + payload: Schema; + }>>; + }>>; + }; + ResumeSchedule: { + name: string; + payload: Schema>; + note: string; + }; +}, import("../schema.js").InferShape<{ + /** Default: HEAT, COOL, AUTO, OFF. */ + supportedModes: import("../schema.js").OptionalSchema<("ECO" | "OFF" | "AUTO" | "COOL" | "EM_HEAT" | "HEAT")[]>; + /** The user can set a temperature for a time: SetTargetTemperature comes with holdUntil. Default: false. */ + supportsScheduling: import("../schema.js").OptionalSchema; + /** The properties the thermostat has. Default: the three setpoints and thermostatMode. */ + properties: import("../schema.js").OptionalSchema<("targetSetpoint" | "lowerSetpoint" | "upperSetpoint" | "thermostatMode" | "adaptiveRecoveryStatus")[]>; +}>, false>; diff --git a/dist/esm/registry/interfaces/ThermostatController.js b/dist/esm/registry/interfaces/ThermostatController.js new file mode 100644 index 0000000..ec854dc --- /dev/null +++ b/dist/esm/registry/interfaces/ThermostatController.js @@ -0,0 +1,94 @@ +import { mismatch, s } from "../schema.js"; +import { DeclarationError, defineInterface } from "../types.js"; +/** alexa-property-schemas.html, "ThermostatMode values". EM_HEAT, emergency heating, came with version 3.2. */ +export const THERMOSTAT_MODES = ["AUTO", "COOL", "ECO", "EM_HEAT", "HEAT", "OFF"]; +const PROPERTIES = ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode", "adaptiveRecoveryStatus"]; +// What 1.x announced for every thermostat. A declaration that leaves an option out announces the same. +const MODES_OF_1X = ["HEAT", "COOL", "AUTO", "OFF"]; +const PROPERTIES_OF_1X = ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"]; +const setpoints = s.object({ + targetSetpoint: s.optional(s.temperature()), + lowerSetpoint: s.optional(s.temperature()), + upperSetpoint: s.optional(s.temperature()), + holdUntil: s.optional(s.timeInterval()), +}); +// One setpoint for a thermostat that holds a temperature, the lower and the upper for one that holds a range, all +// three for one that aims at a temperature within a range. The page marks each as not required; a payload without +// any sets nothing. +const setTargetTemperature = { + expects: "one or more of targetSetpoint, lowerSetpoint, upperSetpoint", + parse(input, path = "") { + const payload = setpoints.parse(input, path); + if (!payload.targetSetpoint && !payload.lowerSetpoint && !payload.upperSetpoint) + throw mismatch(path, this.expects, input); + return payload; + }, +}; +/** + * Version 3.2. A thermostat declares the properties it has: targetSetpoint for a single setpoint, lowerSetpoint and + * upperSetpoint for two, all three for a target within a range. Temperatures are reported "in the same temperature + * scale (Celsius or Fahrenheit) that the thermostat is set to display". An error of errorTypes goes under the + * namespace of the interface, TEMPERATURE_VALUE_OUT_OF_RANGE under Alexa + * (alexa-thermostatcontroller-errorresponse.html). + */ +export const ThermostatController = defineInterface({ + namespace: "Alexa.ThermostatController", + version: "3.2", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-thermostatcontroller.html", + kind: "controller", + tier: 1, + instanced: false, + properties: { + targetSetpoint: { name: "targetSetpoint", value: s.temperature() }, + lowerSetpoint: { name: "lowerSetpoint", value: s.temperature() }, + upperSetpoint: { name: "upperSetpoint", value: s.temperature() }, + thermostatMode: { name: "thermostatMode", value: s.enum(...THERMOSTAT_MODES) }, + adaptiveRecoveryStatus: { + name: "adaptiveRecoveryStatus", + value: s.enum("PREHEATING", "PRECOOLING", "INACTIVE"), + note: "heating or cooling ahead of an entry of the schedule, of Alexa.ThermostatController.Schedule", + }, + }, + directives: { + SetTargetTemperature: { + name: "SetTargetTemperature", + payload: setTargetTemperature, + note: "holdUntil comes only to a thermostat declared with supportsScheduling", + }, + AdjustTargetTemperature: { name: "AdjustTargetTemperature", payload: s.object({ targetSetpointDelta: s.temperature() }) }, + SetThermostatMode: { + name: "SetThermostatMode", + payload: s.object({ thermostatMode: s.object({ value: s.enum(...THERMOSTAT_MODES) }) }), + }, + ResumeSchedule: { name: "ResumeSchedule", payload: s.object({}), note: "en-US only" }, + }, + options: s.object({ + /** Default: HEAT, COOL, AUTO, OFF. */ + supportedModes: s.optional(s.array(s.enum(...THERMOSTAT_MODES), { min: 1 })), + /** The user can set a temperature for a time: SetTargetTemperature comes with holdUntil. Default: false. */ + supportsScheduling: s.optional(s.boolean()), + /** The properties the thermostat has. Default: the three setpoints and thermostatMode. */ + properties: s.optional(s.array(s.enum(...PROPERTIES), { min: 1 })), + }, { unknownKeys: "reject" }), + discovery({ options: { supportedModes = MODES_OF_1X, supportsScheduling = false, properties = PROPERTIES_OF_1X } }) { + return { supported: properties, configuration: { supportedModes, supportsScheduling } }; + }, + validate(capability) { + const { supportedModes = MODES_OF_1X, properties = PROPERTIES_OF_1X } = capability.options; + // alexa-thermostatcontroller.html, "Configuration object": "You must include at least one of HEAT or COOL" + if (!supportedModes.includes("HEAT") && !supportedModes.includes("COOL")) { + throw new DeclarationError(capability, `supportedModes ${supportedModes.join(", ")} has neither HEAT nor COOL, Alexa wants one`); + } + const lists = [supportedModes, properties]; + for (const list of lists) { + const twice = list.find((entry, i) => list.indexOf(entry) !== i); + if (twice) + throw new DeclarationError(capability, `${twice} is listed twice`); + } + }, + errorNamespace: "Alexa.ThermostatController", + errorTypes: [ + "DUAL_SETPOINTS_UNSUPPORTED", "REQUESTED_SETPOINTS_TOO_CLOSE", "THERMOSTAT_IS_OFF", "TRIPLE_SETPOINTS_UNSUPPORTED", + "UNSUPPORTED_THERMOSTAT_MODE", "UNWILLING_TO_SET_SCHEDULE", "UNWILLING_TO_SET_VALUE", + ], +}); diff --git a/dist/esm/registry/interfaces/ThermostatControllerSchedule.d.ts b/dist/esm/registry/interfaces/ThermostatControllerSchedule.d.ts new file mode 100644 index 0000000..7159eb9 --- /dev/null +++ b/dist/esm/registry/interfaces/ThermostatControllerSchedule.d.ts @@ -0,0 +1,142 @@ +/** + * Version 3.2. The schedule a user writes in the Alexa app: the interface has no utterances. Discovery lists + * adaptiveRecoveryEnabled for a thermostat declared with supportsAdaptiveRecovery, and Alexa sends + * SetAdaptiveRecovery to such a thermostat only. + */ +export declare const ThermostatControllerSchedule: import("../types.js").InterfaceDescriptor<{ + adaptiveRecoveryEnabled: { + name: string; + value: import("../schema.js").Schema; + }; + scheduleEnabled: { + name: string; + value: import("../schema.js").Schema; + }; +}, { + SetWeeklySchedule: { + name: string; + payload: import("../schema.js").Schema; + Monday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Tuesday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Wednesday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Thursday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Friday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Saturday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Sunday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + }>>; + }>>; + note: string; + }; + SetScheduleState: { + name: string; + payload: import("../schema.js").Schema; + }>>; + note: string; + }; + SetAdaptiveRecovery: { + name: string; + payload: import("../schema.js").Schema; + }>>; + when: ({ options }: import("../types.js").Declared) => boolean; + }; +}, import("../schema.js").InferShape<{ + supportedFanModes: import("../schema.js").Schema<("ON" | "AUTO" | "CIRCULATE")[]>; + /** The thermostat heats or cools ahead of an entry, to be at its temperature when it starts. */ + supportsAdaptiveRecovery: import("../schema.js").Schema; + maxEntryPerDay: import("../schema.js").OptionalSchema; +}>, false>; diff --git a/dist/esm/registry/interfaces/ThermostatControllerSchedule.js b/dist/esm/registry/interfaces/ThermostatControllerSchedule.js new file mode 100644 index 0000000..ae4233a --- /dev/null +++ b/dist/esm/registry/interfaces/ThermostatControllerSchedule.js @@ -0,0 +1,77 @@ +import { s } from "../schema.js"; +import { defineInterface } from "../types.js"; +const FAN_MODES = ["ON", "AUTO", "CIRCULATE"]; +// alexa-thermostatcontroller-schedule.html, "ScheduleEntry object": an entry ends where the next one starts +const entry = s.object({ + startTimeInMinutes: s.number({ min: 0, max: 1439, integer: true }), + setpoints: s.object({ upperSetpoint: s.optional(s.temperature()), lowerSetpoint: s.optional(s.temperature()) }), + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: s.optional(s.object({ mode: s.optional(s.enum(...FAN_MODES)) })), + activityType: s.optional(s.object({ type: s.enum("AWAY", "HOME", "SLEEP") })), +}); +const day = s.array(entry); +// Same page, "WeeklySchedule object" +const weeklySchedule = s.object({ + temperatureScale: s.enum("CELSIUS", "FAHRENHEIT", "KELVIN"), + Monday: day, + Tuesday: day, + Wednesday: day, + Thursday: day, + Friday: day, + Saturday: day, + Sunday: day, +}); +/** + * Version 3.2. The schedule a user writes in the Alexa app: the interface has no utterances. Discovery lists + * adaptiveRecoveryEnabled for a thermostat declared with supportsAdaptiveRecovery, and Alexa sends + * SetAdaptiveRecovery to such a thermostat only. + */ +export const ThermostatControllerSchedule = defineInterface({ + namespace: "Alexa.ThermostatController.Schedule", + version: "3.2", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-thermostatcontroller-schedule.html", + kind: "controller", + tier: 2, + instanced: false, + properties: { + adaptiveRecoveryEnabled: { name: "adaptiveRecoveryEnabled", value: s.boolean() }, + scheduleEnabled: { name: "scheduleEnabled", value: s.boolean() }, + }, + directives: { + SetWeeklySchedule: { + name: "SetWeeklySchedule", + payload: s.object({ weeklySchedule: s.optional(weeklySchedule) }), + note: "a schedule the thermostat cannot keep leaves the one it has and is answered with an error", + }, + SetScheduleState: { + name: "SetScheduleState", + payload: s.object({ scheduleEnabled: s.boolean() }), + note: "a disabled schedule is kept: the user can enable it again", + }, + SetAdaptiveRecovery: { + name: "SetAdaptiveRecovery", + payload: s.object({ adaptiveRecoveryEnabled: s.boolean() }), + when: ({ options }) => options.supportsAdaptiveRecovery === true, + }, + }, + options: s.object({ + supportedFanModes: s.array(s.enum(...FAN_MODES)), + /** The thermostat heats or cools ahead of an entry, to be at its temperature when it starts. */ + supportsAdaptiveRecovery: s.boolean(), + maxEntryPerDay: s.optional(s.number({ min: 1, integer: true })), + }, { unknownKeys: "reject" }), + // A capability declared the 1.x way has none of the options; check() says so, discovery lists what there is + discovery({ options: { supportedFanModes, supportsAdaptiveRecovery, maxEntryPerDay } }) { + const configuration = { + ...(supportedFanModes && { supportedFanModes }), + ...(supportsAdaptiveRecovery !== undefined && { supportsAdaptiveRecovery }), + ...(maxEntryPerDay !== undefined && { maxEntryPerDay }), + }; + return { + supported: supportsAdaptiveRecovery ? ["adaptiveRecoveryEnabled", "scheduleEnabled"] : ["scheduleEnabled"], + ...(Object.keys(configuration).length > 0 && { configuration }), + }; + }, + errorNamespace: "Alexa.ThermostatController.Schedule", + errorTypes: ["INSUFFICIENT_SPACE"], +}); diff --git a/dist/esm/registry/interfaces/stubs.js b/dist/esm/registry/interfaces/stubs.js index ae3f2f7..eb022ba 100644 --- a/dist/esm/registry/interfaces/stubs.js +++ b/dist/esm/registry/interfaces/stubs.js @@ -56,10 +56,8 @@ const TABLE = [ ["Alexa.SmartVision.SnapshotProvider", "1", [], "alexa-smartvision-snapshotprovider.html"], ["Alexa.Speaker", "1", [], "alexa-speaker.html"], ["Alexa.StepSpeaker", "1", [], "alexa-stepspeaker.html"], - ["Alexa.ThermostatController", "3.2", ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"], "alexa-thermostatcontroller.html"], ["Alexa.ThermostatController.Configuration", "1", [], "alexa-thermostatcontroller-configuration.html"], ["Alexa.ThermostatController.HVAC.Components", "1", [], "alexa-thermostatcontroller-hvac-components.html"], - ["Alexa.ThermostatController.Schedule", "1", [], "alexa-thermostatcontroller-schedule.html"], // "UNKNOWN" in 1.5.2 as well; the page is titled "Interface 3" ["Alexa.TimeHoldController", "3", [], "alexa-timeholdcontroller.html"], ["Alexa.UIController", "1", [], "alexa-uicontroller.html"], @@ -67,16 +65,13 @@ const TABLE = [ ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"], ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"], ]; -// What 1.5.2 added to the capability object of two of them +// What 1.5.2 added to the capability object of one of them const EXTRAS = { // No properties object; supportsDeactivation and proactivelyReported on the capability itself "Alexa.SceneController": ({ proactivelyReported }) => ({ properties: false, topLevel: { supportsDeactivation: true, proactivelyReported }, }), - "Alexa.ThermostatController": () => ({ - configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false }, - }), }; function kindOf(namespace) { if (namespace.endsWith("Sensor")) diff --git a/dist/esm/registry/types.d.ts b/dist/esm/registry/types.d.ts index d6e882e..cbac58c 100644 --- a/dist/esm/registry/types.d.ts +++ b/dist/esm/registry/types.d.ts @@ -76,6 +76,8 @@ export interface CapabilityExtras { topLevel?: Record; /** false: the capability has no properties object (the Alexa interface, a scene). */ properties?: false; + /** The properties the capability lists, where a declaration has some of those of the interface. Default: all. */ + supported?: readonly string[]; } /** A capability as declared on an endpoint: what discovery() and validate() of its descriptor are given. */ export interface Declared { diff --git a/dist/types/compat/AlexaInterface.d.ts b/dist/types/compat/AlexaInterface.d.ts index 8e6eb0b..13c2482 100644 --- a/dist/types/compat/AlexaInterface.d.ts +++ b/dist/types/compat/AlexaInterface.d.ts @@ -51,7 +51,7 @@ export declare class AlexaInterface extends Capability { getTypeString(): string; /** @deprecated Read descriptor.version. */ getVersion(): string; - /** @deprecated Read the keys of descriptor.properties. */ + /** @deprecated The properties discovery lists: read properties.supported of toJSON(). */ getProps(): string[]; getJSON(): CapabilityJson; toJSON(): CapabilityJson; diff --git a/dist/types/compat/enums.d.ts b/dist/types/compat/enums.d.ts index 66b7107..62b8701 100644 --- a/dist/types/compat/enums.d.ts +++ b/dist/types/compat/enums.d.ts @@ -199,7 +199,9 @@ export declare enum ThermostatMode { COOL = "COOL", AUTO = "AUTO", ECO = "ECO", - CUSTOM = "CUSTOM" + CUSTOM = "CUSTOM", + /** Emergency heating, since 2.0. */ + EM_HEAT = "EM_HEAT" } /** The scale of a temperature given to addTemperatureSensorProp() and addThermostatControllerProp(). */ export declare enum TemperatureSensorScale { diff --git a/dist/types/index.d.ts b/dist/types/index.d.ts index a1d0f1b..1d9a078 100644 --- a/dist/types/index.d.ts +++ b/dist/types/index.d.ts @@ -5,11 +5,11 @@ export type { EndpointDefinition, EndpointJson } from "./device/Device.js"; export { Capability } from "./device/Capability.js"; export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capability.js"; export { registry, DeclarationError, SchemaError } from "./registry/index.js"; -export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerLevelController, RangeController, TemperatureSensor, ToggleController, } from "./registry/index.js"; +export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerLevelController, RangeController, TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController, } from "./registry/index.js"; export { PowerController, EndpointHealth } from "./compat/enums.js"; export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js"; -export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js"; -export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, ActionName, StateName, Mode, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; +export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, THERMOSTAT_MODES as ThermostatModes, } from "./registry/index.js"; +export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, ActionName, StateName, Mode, ThermostatModeName, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; export * as messages from "./messages/index.js"; export { AlexaError, AlexaErrors, MessageError, StateBuilder, property } from "./messages/index.js"; export type { ChangeCause, ChangeReportMessage, DeferredResponseMessage, ErrorResponseMessage, Header, ProactiveEventMessage, Property, PropertyOptions, ResponseMessage, SceneEventMessage, } from "./messages/index.js"; diff --git a/dist/types/registry/index.d.ts b/dist/types/registry/index.d.ts index 7b7dccd..1b75de5 100644 --- a/dist/types/registry/index.d.ts +++ b/dist/types/registry/index.d.ts @@ -13,6 +13,8 @@ import { PowerController } from "./interfaces/PowerController.js"; import { PowerLevelController } from "./interfaces/PowerLevelController.js"; import { RangeController } from "./interfaces/RangeController.js"; import { TemperatureSensor } from "./interfaces/TemperatureSensor.js"; +import { ThermostatController } from "./interfaces/ThermostatController.js"; +import { ThermostatControllerSchedule } from "./interfaces/ThermostatControllerSchedule.js"; import { ToggleController } from "./interfaces/ToggleController.js"; import type { AnyDescriptor } from "./types.js"; export declare const registry: { @@ -23,8 +25,10 @@ export declare const registry: { /** Every descriptor, ordered by namespace. */ list(): AnyDescriptor[]; }; -export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, EndpointHealth, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerController, PowerLevelController, RangeController, TemperatureSensor, ToggleController, }; +export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, EndpointHealth, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerController, PowerLevelController, RangeController, TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController, }; export type { Mode } from "./interfaces/ModeController.js"; +export { THERMOSTAT_MODES } from "./interfaces/ThermostatController.js"; +export type { ThermostatModeName } from "./interfaces/ThermostatController.js"; export { asset, text } from "./resources.js"; export { semantics, SemanticsBuilder } from "./semantics.js"; export type { ActionName, StateName } from "./semantics.js"; diff --git a/dist/types/registry/interfaces/ThermostatController.d.ts b/dist/types/registry/interfaces/ThermostatController.d.ts new file mode 100644 index 0000000..556bee3 --- /dev/null +++ b/dist/types/registry/interfaces/ThermostatController.d.ts @@ -0,0 +1,71 @@ +import type { Schema } from "../schema.js"; +/** alexa-property-schemas.html, "ThermostatMode values". EM_HEAT, emergency heating, came with version 3.2. */ +export declare const THERMOSTAT_MODES: readonly ["AUTO", "COOL", "ECO", "EM_HEAT", "HEAT", "OFF"]; +export type ThermostatModeName = (typeof THERMOSTAT_MODES)[number]; +/** + * Version 3.2. A thermostat declares the properties it has: targetSetpoint for a single setpoint, lowerSetpoint and + * upperSetpoint for two, all three for a target within a range. Temperatures are reported "in the same temperature + * scale (Celsius or Fahrenheit) that the thermostat is set to display". An error of errorTypes goes under the + * namespace of the interface, TEMPERATURE_VALUE_OUT_OF_RANGE under Alexa + * (alexa-thermostatcontroller-errorresponse.html). + */ +export declare const ThermostatController: import("../types.js").InterfaceDescriptor<{ + targetSetpoint: { + name: string; + value: Schema; + }; + lowerSetpoint: { + name: string; + value: Schema; + }; + upperSetpoint: { + name: string; + value: Schema; + }; + thermostatMode: { + name: string; + value: import("../schema.js").EnumSchema<"ECO" | "OFF" | "AUTO" | "COOL" | "EM_HEAT" | "HEAT">; + }; + adaptiveRecoveryStatus: { + name: string; + value: import("../schema.js").EnumSchema<"PREHEATING" | "PRECOOLING" | "INACTIVE">; + note: string; + }; +}, { + SetTargetTemperature: { + name: string; + payload: Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + upperSetpoint: import("../schema.js").OptionalSchema; + holdUntil: import("../schema.js").OptionalSchema; + }>>; + note: string; + }; + AdjustTargetTemperature: { + name: string; + payload: Schema; + }>>; + }; + SetThermostatMode: { + name: string; + payload: Schema; + }>>; + }>>; + }; + ResumeSchedule: { + name: string; + payload: Schema>; + note: string; + }; +}, import("../schema.js").InferShape<{ + /** Default: HEAT, COOL, AUTO, OFF. */ + supportedModes: import("../schema.js").OptionalSchema<("ECO" | "OFF" | "AUTO" | "COOL" | "EM_HEAT" | "HEAT")[]>; + /** The user can set a temperature for a time: SetTargetTemperature comes with holdUntil. Default: false. */ + supportsScheduling: import("../schema.js").OptionalSchema; + /** The properties the thermostat has. Default: the three setpoints and thermostatMode. */ + properties: import("../schema.js").OptionalSchema<("targetSetpoint" | "lowerSetpoint" | "upperSetpoint" | "thermostatMode" | "adaptiveRecoveryStatus")[]>; +}>, false>; diff --git a/dist/types/registry/interfaces/ThermostatControllerSchedule.d.ts b/dist/types/registry/interfaces/ThermostatControllerSchedule.d.ts new file mode 100644 index 0000000..7159eb9 --- /dev/null +++ b/dist/types/registry/interfaces/ThermostatControllerSchedule.d.ts @@ -0,0 +1,142 @@ +/** + * Version 3.2. The schedule a user writes in the Alexa app: the interface has no utterances. Discovery lists + * adaptiveRecoveryEnabled for a thermostat declared with supportsAdaptiveRecovery, and Alexa sends + * SetAdaptiveRecovery to such a thermostat only. + */ +export declare const ThermostatControllerSchedule: import("../types.js").InterfaceDescriptor<{ + adaptiveRecoveryEnabled: { + name: string; + value: import("../schema.js").Schema; + }; + scheduleEnabled: { + name: string; + value: import("../schema.js").Schema; + }; +}, { + SetWeeklySchedule: { + name: string; + payload: import("../schema.js").Schema; + Monday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Tuesday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Wednesday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Thursday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Friday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Saturday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + Sunday: import("../schema.js").Schema; + setpoints: import("../schema.js").Schema; + lowerSetpoint: import("../schema.js").OptionalSchema; + }>>; + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: import("../schema.js").OptionalSchema; + }>>; + activityType: import("../schema.js").OptionalSchema; + }>>; + }>[]>; + }>>; + }>>; + note: string; + }; + SetScheduleState: { + name: string; + payload: import("../schema.js").Schema; + }>>; + note: string; + }; + SetAdaptiveRecovery: { + name: string; + payload: import("../schema.js").Schema; + }>>; + when: ({ options }: import("../types.js").Declared) => boolean; + }; +}, import("../schema.js").InferShape<{ + supportedFanModes: import("../schema.js").Schema<("ON" | "AUTO" | "CIRCULATE")[]>; + /** The thermostat heats or cools ahead of an entry, to be at its temperature when it starts. */ + supportsAdaptiveRecovery: import("../schema.js").Schema; + maxEntryPerDay: import("../schema.js").OptionalSchema; +}>, false>; diff --git a/dist/types/registry/types.d.ts b/dist/types/registry/types.d.ts index d6e882e..cbac58c 100644 --- a/dist/types/registry/types.d.ts +++ b/dist/types/registry/types.d.ts @@ -76,6 +76,8 @@ export interface CapabilityExtras { topLevel?: Record; /** false: the capability has no properties object (the Alexa interface, a scene). */ properties?: false; + /** The properties the capability lists, where a declaration has some of those of the interface. Default: all. */ + supported?: readonly string[]; } /** A capability as declared on an endpoint: what discovery() and validate() of its descriptor are given. */ export interface Declared { diff --git a/src/compat/AlexaInterface.ts b/src/compat/AlexaInterface.ts index 031b09c..7455eaf 100644 --- a/src/compat/AlexaInterface.ts +++ b/src/compat/AlexaInterface.ts @@ -76,9 +76,9 @@ export class AlexaInterface extends Capability { return this.descriptor.version; } - /** @deprecated Read the keys of descriptor.properties. */ + /** @deprecated The properties discovery lists: read properties.supported of toJSON(). */ getProps(): string[] { - return Object.keys(this.descriptor.properties); + return (super.toJSON().properties?.supported ?? []).map(({ name }) => name); } getJSON(): CapabilityJson { diff --git a/src/compat/enums.ts b/src/compat/enums.ts index 083ad3f..bb221f0 100644 --- a/src/compat/enums.ts +++ b/src/compat/enums.ts @@ -177,6 +177,8 @@ export enum ThermostatMode { AUTO = "AUTO", ECO = "ECO", CUSTOM = "CUSTOM", + /** Emergency heating, since 2.0. */ + EM_HEAT = "EM_HEAT", } /** The scale of a temperature given to addTemperatureSensorProp() and addThermostatControllerProp(). */ diff --git a/src/device/Capability.ts b/src/device/Capability.ts index 9d2b00a..ceca181 100644 --- a/src/device/Capability.ts +++ b/src/device/Capability.ts @@ -130,7 +130,7 @@ export class Capability

({ name })), + supported: (extras.supported ?? Object.keys(descriptor.properties)).map((name) => ({ name })), proactivelyReported: this.proactivelyReported, retrievable: this.retrievable, }; diff --git a/src/index.ts b/src/index.ts index bd7d938..6501cd2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -11,7 +11,7 @@ export { registry, DeclarationError, SchemaError } from "./registry/index.js"; export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerLevelController, RangeController, TemperatureSensor, - ToggleController, + ThermostatController, ThermostatControllerSchedule, ToggleController, } from "./registry/index.js"; export { PowerController, EndpointHealth } from "./compat/enums.js"; export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js"; @@ -19,13 +19,13 @@ export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js"; // The vocabularies of the Smart Home API export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, - DISPLAY_CATEGORIES as DisplayCategories, + DISPLAY_CATEGORIES as DisplayCategories, THERMOSTAT_MODES as ThermostatModes, } from "./registry/index.js"; export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, - ActionName, StateName, Mode, Infer, Schema, Temperature, TimeInterval, + ActionName, StateName, Mode, ThermostatModeName, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; // The messages: what the bridge publishes, built from plain values diff --git a/src/registry/index.ts b/src/registry/index.ts index 1ac46c7..3ce9d98 100644 --- a/src/registry/index.ts +++ b/src/registry/index.ts @@ -14,6 +14,8 @@ import { PowerController } from "./interfaces/PowerController.js"; import { PowerLevelController } from "./interfaces/PowerLevelController.js"; import { RangeController } from "./interfaces/RangeController.js"; import { TemperatureSensor } from "./interfaces/TemperatureSensor.js"; +import { ThermostatController } from "./interfaces/ThermostatController.js"; +import { ThermostatControllerSchedule } from "./interfaces/ThermostatControllerSchedule.js"; import { ToggleController } from "./interfaces/ToggleController.js"; import { STUBS } from "./interfaces/stubs.js"; import { DeclarationError } from "./types.js"; @@ -35,6 +37,8 @@ const described: readonly AnyDescriptor[] = [ PowerLevelController, RangeController, TemperatureSensor, + ThermostatController, + ThermostatControllerSchedule, ToggleController, ]; @@ -67,9 +71,11 @@ export const registry = { export { Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, EndpointHealth, HumiditySensor, LockController, ModeController, MotionSensor, PercentageController, PowerController, PowerLevelController, RangeController, - TemperatureSensor, ToggleController, + TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController, }; export type { Mode } from "./interfaces/ModeController.js"; +export { THERMOSTAT_MODES } from "./interfaces/ThermostatController.js"; +export type { ThermostatModeName } from "./interfaces/ThermostatController.js"; export { asset, text } from "./resources.js"; export { semantics, SemanticsBuilder } from "./semantics.js"; export type { ActionName, StateName } from "./semantics.js"; diff --git a/src/registry/interfaces/ThermostatController.ts b/src/registry/interfaces/ThermostatController.ts new file mode 100644 index 0000000..2f879e1 --- /dev/null +++ b/src/registry/interfaces/ThermostatController.ts @@ -0,0 +1,101 @@ +import { mismatch, s } from "../schema.js"; +import type { Infer, Schema } from "../schema.js"; +import { DeclarationError, defineInterface } from "../types.js"; + +/** alexa-property-schemas.html, "ThermostatMode values". EM_HEAT, emergency heating, came with version 3.2. */ +export const THERMOSTAT_MODES = ["AUTO", "COOL", "ECO", "EM_HEAT", "HEAT", "OFF"] as const; +export type ThermostatModeName = (typeof THERMOSTAT_MODES)[number]; + +const PROPERTIES = ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode", "adaptiveRecoveryStatus"] as const; +type PropertyName = (typeof PROPERTIES)[number]; + +// What 1.x announced for every thermostat. A declaration that leaves an option out announces the same. +const MODES_OF_1X: readonly ThermostatModeName[] = ["HEAT", "COOL", "AUTO", "OFF"]; +const PROPERTIES_OF_1X: readonly PropertyName[] = ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"]; + +const setpoints = s.object({ + targetSetpoint: s.optional(s.temperature()), + lowerSetpoint: s.optional(s.temperature()), + upperSetpoint: s.optional(s.temperature()), + holdUntil: s.optional(s.timeInterval()), +}); + +// One setpoint for a thermostat that holds a temperature, the lower and the upper for one that holds a range, all +// three for one that aims at a temperature within a range. The page marks each as not required; a payload without +// any sets nothing. +const setTargetTemperature: Schema> = { + expects: "one or more of targetSetpoint, lowerSetpoint, upperSetpoint", + parse(input, path = "") { + const payload = setpoints.parse(input, path); + if (!payload.targetSetpoint && !payload.lowerSetpoint && !payload.upperSetpoint) throw mismatch(path, this.expects, input); + return payload; + }, +}; + +/** + * Version 3.2. A thermostat declares the properties it has: targetSetpoint for a single setpoint, lowerSetpoint and + * upperSetpoint for two, all three for a target within a range. Temperatures are reported "in the same temperature + * scale (Celsius or Fahrenheit) that the thermostat is set to display". An error of errorTypes goes under the + * namespace of the interface, TEMPERATURE_VALUE_OUT_OF_RANGE under Alexa + * (alexa-thermostatcontroller-errorresponse.html). + */ +export const ThermostatController = defineInterface({ + namespace: "Alexa.ThermostatController", + version: "3.2", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-thermostatcontroller.html", + kind: "controller", + tier: 1, + instanced: false, + properties: { + targetSetpoint: { name: "targetSetpoint", value: s.temperature() }, + lowerSetpoint: { name: "lowerSetpoint", value: s.temperature() }, + upperSetpoint: { name: "upperSetpoint", value: s.temperature() }, + thermostatMode: { name: "thermostatMode", value: s.enum(...THERMOSTAT_MODES) }, + adaptiveRecoveryStatus: { + name: "adaptiveRecoveryStatus", + value: s.enum("PREHEATING", "PRECOOLING", "INACTIVE"), + note: "heating or cooling ahead of an entry of the schedule, of Alexa.ThermostatController.Schedule", + }, + }, + directives: { + SetTargetTemperature: { + name: "SetTargetTemperature", + payload: setTargetTemperature, + note: "holdUntil comes only to a thermostat declared with supportsScheduling", + }, + AdjustTargetTemperature: { name: "AdjustTargetTemperature", payload: s.object({ targetSetpointDelta: s.temperature() }) }, + SetThermostatMode: { + name: "SetThermostatMode", + payload: s.object({ thermostatMode: s.object({ value: s.enum(...THERMOSTAT_MODES) }) }), + }, + ResumeSchedule: { name: "ResumeSchedule", payload: s.object({}), note: "en-US only" }, + }, + options: s.object({ + /** Default: HEAT, COOL, AUTO, OFF. */ + supportedModes: s.optional(s.array(s.enum(...THERMOSTAT_MODES), { min: 1 })), + /** The user can set a temperature for a time: SetTargetTemperature comes with holdUntil. Default: false. */ + supportsScheduling: s.optional(s.boolean()), + /** The properties the thermostat has. Default: the three setpoints and thermostatMode. */ + properties: s.optional(s.array(s.enum(...PROPERTIES), { min: 1 })), + }, { unknownKeys: "reject" }), + discovery({ options: { supportedModes = MODES_OF_1X, supportsScheduling = false, properties = PROPERTIES_OF_1X } }) { + return { supported: properties, configuration: { supportedModes, supportsScheduling } }; + }, + validate(capability) { + const { supportedModes = MODES_OF_1X, properties = PROPERTIES_OF_1X } = capability.options; + // alexa-thermostatcontroller.html, "Configuration object": "You must include at least one of HEAT or COOL" + if (!supportedModes.includes("HEAT") && !supportedModes.includes("COOL")) { + throw new DeclarationError(capability, `supportedModes ${supportedModes.join(", ")} has neither HEAT nor COOL, Alexa wants one`); + } + const lists: ReadonlyArray = [supportedModes, properties]; + for (const list of lists) { + const twice = list.find((entry, i) => list.indexOf(entry) !== i); + if (twice) throw new DeclarationError(capability, `${twice} is listed twice`); + } + }, + errorNamespace: "Alexa.ThermostatController", + errorTypes: [ + "DUAL_SETPOINTS_UNSUPPORTED", "REQUESTED_SETPOINTS_TOO_CLOSE", "THERMOSTAT_IS_OFF", "TRIPLE_SETPOINTS_UNSUPPORTED", + "UNSUPPORTED_THERMOSTAT_MODE", "UNWILLING_TO_SET_SCHEDULE", "UNWILLING_TO_SET_VALUE", + ], +}); diff --git a/src/registry/interfaces/ThermostatControllerSchedule.ts b/src/registry/interfaces/ThermostatControllerSchedule.ts new file mode 100644 index 0000000..da95099 --- /dev/null +++ b/src/registry/interfaces/ThermostatControllerSchedule.ts @@ -0,0 +1,81 @@ +import { s } from "../schema.js"; +import { defineInterface } from "../types.js"; + +const FAN_MODES = ["ON", "AUTO", "CIRCULATE"] as const; + +// alexa-thermostatcontroller-schedule.html, "ScheduleEntry object": an entry ends where the next one starts +const entry = s.object({ + startTimeInMinutes: s.number({ min: 0, max: 1439, integer: true }), + setpoints: s.object({ upperSetpoint: s.optional(s.temperature()), lowerSetpoint: s.optional(s.temperature()) }), + /** Without a mode the fan runs as the manufacturer set it. */ + fanSetting: s.optional(s.object({ mode: s.optional(s.enum(...FAN_MODES)) })), + activityType: s.optional(s.object({ type: s.enum("AWAY", "HOME", "SLEEP") })), +}); +const day = s.array(entry); + +// Same page, "WeeklySchedule object" +const weeklySchedule = s.object({ + temperatureScale: s.enum("CELSIUS", "FAHRENHEIT", "KELVIN"), + Monday: day, + Tuesday: day, + Wednesday: day, + Thursday: day, + Friday: day, + Saturday: day, + Sunday: day, +}); + +/** + * Version 3.2. The schedule a user writes in the Alexa app: the interface has no utterances. Discovery lists + * adaptiveRecoveryEnabled for a thermostat declared with supportsAdaptiveRecovery, and Alexa sends + * SetAdaptiveRecovery to such a thermostat only. + */ +export const ThermostatControllerSchedule = defineInterface({ + namespace: "Alexa.ThermostatController.Schedule", + version: "3.2", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-thermostatcontroller-schedule.html", + kind: "controller", + tier: 2, + instanced: false, + properties: { + adaptiveRecoveryEnabled: { name: "adaptiveRecoveryEnabled", value: s.boolean() }, + scheduleEnabled: { name: "scheduleEnabled", value: s.boolean() }, + }, + directives: { + SetWeeklySchedule: { + name: "SetWeeklySchedule", + payload: s.object({ weeklySchedule: s.optional(weeklySchedule) }), + note: "a schedule the thermostat cannot keep leaves the one it has and is answered with an error", + }, + SetScheduleState: { + name: "SetScheduleState", + payload: s.object({ scheduleEnabled: s.boolean() }), + note: "a disabled schedule is kept: the user can enable it again", + }, + SetAdaptiveRecovery: { + name: "SetAdaptiveRecovery", + payload: s.object({ adaptiveRecoveryEnabled: s.boolean() }), + when: ({ options }) => options.supportsAdaptiveRecovery === true, + }, + }, + options: s.object({ + supportedFanModes: s.array(s.enum(...FAN_MODES)), + /** The thermostat heats or cools ahead of an entry, to be at its temperature when it starts. */ + supportsAdaptiveRecovery: s.boolean(), + maxEntryPerDay: s.optional(s.number({ min: 1, integer: true })), + }, { unknownKeys: "reject" }), + // A capability declared the 1.x way has none of the options; check() says so, discovery lists what there is + discovery({ options: { supportedFanModes, supportsAdaptiveRecovery, maxEntryPerDay } }) { + const configuration = { + ...(supportedFanModes && { supportedFanModes }), + ...(supportsAdaptiveRecovery !== undefined && { supportsAdaptiveRecovery }), + ...(maxEntryPerDay !== undefined && { maxEntryPerDay }), + }; + return { + supported: supportsAdaptiveRecovery ? ["adaptiveRecoveryEnabled", "scheduleEnabled"] : ["scheduleEnabled"], + ...(Object.keys(configuration).length > 0 && { configuration }), + }; + }, + errorNamespace: "Alexa.ThermostatController.Schedule", + errorTypes: ["INSUFFICIENT_SPACE"], +}); diff --git a/src/registry/interfaces/stubs.ts b/src/registry/interfaces/stubs.ts index 3b26020..bd71f04 100644 --- a/src/registry/interfaces/stubs.ts +++ b/src/registry/interfaces/stubs.ts @@ -62,10 +62,8 @@ const TABLE: readonly Row[] = [ ["Alexa.SmartVision.SnapshotProvider", "1", [], "alexa-smartvision-snapshotprovider.html"], ["Alexa.Speaker", "1", [], "alexa-speaker.html"], ["Alexa.StepSpeaker", "1", [], "alexa-stepspeaker.html"], - ["Alexa.ThermostatController", "3.2", ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"], "alexa-thermostatcontroller.html"], ["Alexa.ThermostatController.Configuration", "1", [], "alexa-thermostatcontroller-configuration.html"], ["Alexa.ThermostatController.HVAC.Components", "1", [], "alexa-thermostatcontroller-hvac-components.html"], - ["Alexa.ThermostatController.Schedule", "1", [], "alexa-thermostatcontroller-schedule.html"], // "UNKNOWN" in 1.5.2 as well; the page is titled "Interface 3" ["Alexa.TimeHoldController", "3", [], "alexa-timeholdcontroller.html"], ["Alexa.UIController", "1", [], "alexa-uicontroller.html"], @@ -74,16 +72,13 @@ const TABLE: readonly Row[] = [ ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"], ]; -// What 1.5.2 added to the capability object of two of them +// What 1.5.2 added to the capability object of one of them const EXTRAS: Record = { // No properties object; supportsDeactivation and proactivelyReported on the capability itself "Alexa.SceneController": ({ proactivelyReported }) => ({ properties: false, topLevel: { supportsDeactivation: true, proactivelyReported }, }), - "Alexa.ThermostatController": () => ({ - configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false }, - }), }; function kindOf(namespace: string): AnyDescriptor["kind"] { diff --git a/src/registry/types.ts b/src/registry/types.ts index 8b01136..a839d70 100644 --- a/src/registry/types.ts +++ b/src/registry/types.ts @@ -72,6 +72,8 @@ export interface CapabilityExtras { topLevel?: Record; /** false: the capability has no properties object (the Alexa interface, a scene). */ properties?: false; + /** The properties the capability lists, where a declaration has some of those of the interface. Default: all. */ + supported?: readonly string[]; } /** A capability as declared on an endpoint: what discovery() and validate() of its descriptor are given. */ diff --git a/test/dispatch/interfaces.test.js b/test/dispatch/interfaces.test.js index c6560e3..b830231 100644 --- a/test/dispatch/interfaces.test.js +++ b/test/dispatch/interfaces.test.js @@ -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", + }]); +}); diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/REQUESTED_SETPOINTS_TOO_CLOSE.error.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/REQUESTED_SETPOINTS_TOO_CLOSE.error.json new file mode 100644 index 0000000..c77bb8a --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/REQUESTED_SETPOINTS_TOO_CLOSE.error.json @@ -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" + } + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/TEMPERATURE_VALUE_OUT_OF_RANGE.error.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/TEMPERATURE_VALUE_OUT_OF_RANGE.error.json new file mode 100644 index 0000000..fa65a39 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/TEMPERATURE_VALUE_OUT_OF_RANGE.error.json @@ -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" + } + } + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/THERMOSTAT_IS_OFF.error.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/THERMOSTAT_IS_OFF.error.json new file mode 100644 index 0000000..5e0d243 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller-errorresponse/THERMOSTAT_IS_OFF.error.json @@ -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." + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/ChangeReport.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/ChangeReport.json new file mode 100644 index 0000000..5f0980e --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/ChangeReport.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/SetAdaptiveRecovery.directive.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/SetAdaptiveRecovery.directive.json new file mode 100644 index 0000000..5c806fe --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/SetAdaptiveRecovery.directive.json @@ -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 + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/SetScheduleState.directive.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/SetScheduleState.directive.json new file mode 100644 index 0000000..28ce237 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/SetScheduleState.directive.json @@ -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 + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/StateReport.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/StateReport.json new file mode 100644 index 0000000..c1180b2 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/StateReport.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/discovery.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/discovery.json new file mode 100644 index 0000000..fb828ad --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller-schedule/discovery.json @@ -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" + } + ] + } + ] + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/AdjustTargetTemperature.directive.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/AdjustTargetTemperature.directive.json new file mode 100644 index 0000000..a15c41f --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/AdjustTargetTemperature.directive.json @@ -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" + } + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/AdjustTargetTemperature.response.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/AdjustTargetTemperature.response.json new file mode 100644 index 0000000..305a57c --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/AdjustTargetTemperature.response.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/ChangeReport-air-conditioner.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/ChangeReport-air-conditioner.json new file mode 100644 index 0000000..9e3dfc2 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/ChangeReport-air-conditioner.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/ChangeReport.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/ChangeReport.json new file mode 100644 index 0000000..cbfff03 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/ChangeReport.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/ResumeSchedule.directive.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/ResumeSchedule.directive.json new file mode 100644 index 0000000..363b990 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/ResumeSchedule.directive.json @@ -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": {} + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/ResumeSchedule.response.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/ResumeSchedule.response.json new file mode 100644 index 0000000..ddd4a8d --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/ResumeSchedule.response.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-dual.directive.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-dual.directive.json new file mode 100644 index 0000000..1d97c26 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-dual.directive.json @@ -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" + } + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-dual.response.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-dual.response.json new file mode 100644 index 0000000..540c364 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-dual.response.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-single.directive.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-single.directive.json new file mode 100644 index 0000000..155aef7 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-single.directive.json @@ -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" + } + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-single.response.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-single.response.json new file mode 100644 index 0000000..21f8c53 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetTargetTemperature-single.response.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetThermostatMode.directive.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetThermostatMode.directive.json new file mode 100644 index 0000000..6816af9 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetThermostatMode.directive.json @@ -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" + } + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetThermostatMode.response.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetThermostatMode.response.json new file mode 100644 index 0000000..5043cef --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/SetThermostatMode.response.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/StateReport-air-conditioner.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/StateReport-air-conditioner.json new file mode 100644 index 0000000..6f8a2fb --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/StateReport-air-conditioner.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/StateReport.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/StateReport.json new file mode 100644 index 0000000..70378f6 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/StateReport.json @@ -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 + } + ] + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/discovery-air-conditioner.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/discovery-air-conditioner.json new file mode 100644 index 0000000..a8392b1 --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/discovery-air-conditioner.json @@ -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" + } + ] + } + ] + } + } +} diff --git a/test/fixtures/alexa-docs/alexa-thermostatcontroller/discovery.json b/test/fixtures/alexa-docs/alexa-thermostatcontroller/discovery.json new file mode 100644 index 0000000..80182fd --- /dev/null +++ b/test/fixtures/alexa-docs/alexa-thermostatcontroller/discovery.json @@ -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" + } + ] + } + ] + } + } +} diff --git a/test/fixtures/interfaces.js b/test/fixtures/interfaces.js index 6f061dc..692e33e 100644 --- a/test/fixtures/interfaces.js +++ b/test/fixtures/interfaces.js @@ -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", diff --git a/test/registry/descriptors.test.js b/test/registry/descriptors.test.js index 6b12615..75e5f33 100644 --- a/test/registry/descriptors.test.js +++ b/test/registry/descriptors.test.js @@ -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"); diff --git a/test/registry/thermostat.test.js b/test/registry/thermostat.test.js new file mode 100644 index 0000000..c0f8a2b --- /dev/null +++ b/test/registry/thermostat.test.js @@ -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"'); +});