David
2558e21787
The three generic controllers are described in full and leave the stub table (62 stubs remain). A declaration
takes an instance name, friendly names from text() and asset(), and the options of the interface: range, unit and
presets for a range; supportedModes and ordered for a mode; semantics() for all three, with actions mapped to
directives and states mapped to a value or a range of values.
Refused at device.add(), each with the endpoint, interface and instance in the message: no instance name or no
friendly name; an instance declared twice; a first friendly name or a phrase used by another capability of the
endpoint; a reserved word, an asset id that is not in the catalog; range.max not above range.min; a preset off the
precision grid or outside the range; fewer than two modes or a mode listed twice; a mapping to a directive the
interface does not have, to a payload that does not fit, to a mode that is not listed, to AdjustMode on modes
that are not ordered; SetEcoOn, SetEcoOff, EcoOn and EcoOff on anything but a toggle.
For 1.x callers: Alexa.RangeController lists rangeValue (1.5.2 sent supported: []); addSupportedModes() announces
a mode given as a string as { value } and notes it, and takes { ordered: false } as a second argument, the default
stays true as 1.5.2 sent it (device.add() defaults to false). Declared the 1.x way, the zoo fan and curtain give
the same JSON as before.
Tests: the zoo blind, whose range, unit and semantics were written by hand into the JSON of 1.5.2, is declared
with device.add() and equals that JSON plus the Alexa capability; five capability objects of Amazon's examples
are reproduced the same way. 27 examples of four pages added. npm test: 108 pass (was 85) in 10.5-11.3 s, also on
Node 18.20.8 and 20.20.2.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
138 lines
7.4 KiB
TypeScript
138 lines
7.4 KiB
TypeScript
// Compiled, never run (test/typings.test.js, npm run check): a CommonJS TypeScript consumer of the declarations in
|
|
// dist/types, resolved through the package's "exports". A "@ts-expect-error" line fails the compile when the
|
|
// declaration stops rejecting what follows it.
|
|
import {
|
|
ActionMapping, AlexaActions, AlexaInterfaceType, Assets, BrightnessController, DeclarationError, DisplayCategory, EndpointHealth,
|
|
ModeController, PowerController, PowerState, RangeController, TemperatureSensor, ToggleController, asset, registry, semantics, text,
|
|
} from "alex2node";
|
|
import type {
|
|
Alex2MQTT, Alex2MQTTOptions, AlexaInterface, AlexaStatusMessage, AssetId, Capability, CapabilityJson, ChangeCause, Device,
|
|
DisplayCategoryName, EndpointJson, Infer, InterfaceDescriptor, Label, Schema, SupportedMode, Temperature, UnitOfMeasure,
|
|
} from "alex2node";
|
|
|
|
declare const bridge: Alex2MQTT;
|
|
declare const message: AlexaStatusMessage;
|
|
declare const capability: AlexaInterface;
|
|
|
|
const options: Alex2MQTTOptions = { host: "mqtt://127.0.0.1:1883", mqtt: { reconnectPeriod: 1000 }, log: (line) => line.length };
|
|
const device: Device = bridge.registerDevice("Lamp", "lamp-1", [DisplayCategory.LIGHT, DisplayCategory.SWITCH]);
|
|
const added: AlexaInterface = device.addCapability(AlexaInterfaceType.POWER_CONTROLLER, { proactivelyReported: true });
|
|
|
|
// ActionMapping: the payload is optional, and an object
|
|
const close = new ActionMapping([AlexaActions.Close], "TurnOn");
|
|
capability.addActionMapping(close);
|
|
capability.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", { rangeValue: 100 }));
|
|
// @ts-expect-error a payload is an object or, as in 1.x, a string
|
|
capability.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", 100));
|
|
|
|
// addHealthProp: the enum or its string values, chainable
|
|
const chained: AlexaStatusMessage = message.addHealthProp(EndpointHealth.OK).addHealthProp("UNREACHABLE", 50);
|
|
// @ts-expect-error not a connectivity value
|
|
message.addHealthProp("ASLEEP");
|
|
// @ts-expect-error a power state is ON or OFF
|
|
message.addPowerControllerProp("ON ");
|
|
message.addPowerControllerProp(PowerController.ON);
|
|
// PowerController is the descriptor of the interface as well; the enum alone is PowerState
|
|
const on: PowerController = PowerState.ON;
|
|
const namespace: string = PowerController.namespace;
|
|
const reachable: EndpointHealth = EndpointHealth.OK;
|
|
|
|
// addSupportedModes: Mode objects, plain strings still accepted
|
|
const mode: SupportedMode = { value: "Fan.Auto", modeResources: { friendlyNames: [{ "@type": "text", value: { text: "Auto", locale: "en-US" } }] } };
|
|
capability.addSupportedModes([mode, "Fan.On"]);
|
|
|
|
const cause: ChangeCause = "PHYSICAL_INTERACTION";
|
|
const sent: Promise<string> = device.getChangeReport(cause).addPowerControllerProp(PowerController.OFF).send();
|
|
// @ts-expect-error not a cause Alexa knows
|
|
device.getChangeReport("BUTTON");
|
|
|
|
// bridge.addDevice() and device.add(): the options of the interface and the ones every capability has
|
|
const blinds: Device = bridge.addDevice({
|
|
endpointId: "bedroom-blinds",
|
|
name: "Bedroom Blinds",
|
|
categories: ["INTERIOR_BLIND", DisplayCategory.OTHER],
|
|
cookie: { room: "bedroom" },
|
|
endpointHealth: false,
|
|
});
|
|
// @ts-expect-error an endpoint has categories
|
|
bridge.addDevice({ endpointId: "lamp-2", name: "Lamp" });
|
|
// @ts-expect-error not a display category
|
|
bridge.addDevice({ endpointId: "lamp-2", name: "Lamp", categories: ["LAMP"] });
|
|
const power: Capability = blinds.add(PowerController, { proactivelyReported: true, verificationsRequired: ["TurnOff"] });
|
|
blinds.add(BrightnessController);
|
|
blinds.add(TemperatureSensor, { retrievable: true, nonControllable: true });
|
|
// @ts-expect-error not a directive of the interface
|
|
blinds.add(PowerController, { verificationsRequired: ["Toggle"] });
|
|
// @ts-expect-error not an option of the interface
|
|
blinds.add(BrightnessController, { range: { min: 0, max: 100 } });
|
|
const announced: CapabilityJson = power.toJSON();
|
|
const endpoint: EndpointJson = blinds.getJSON();
|
|
const problems: string[] = blinds.check();
|
|
|
|
// Friendly names
|
|
const names: Label[] = [asset("Alexa.Setting.Opening"), text("Position"), text("Posición", "es-MX")];
|
|
// @ts-expect-error not in the global Alexa catalog
|
|
asset("Alexa.Setting.Openning");
|
|
|
|
// The generic controllers: an instance name, friendly names and the options of the interface
|
|
const lift = blinds.add(RangeController, {
|
|
instance: "Blind.Lift",
|
|
friendlyNames: names,
|
|
range: { min: 0, max: 100, precision: 1 },
|
|
unit: "Alexa.Unit.Percent",
|
|
presets: [{ value: 100, friendlyNames: [asset("Alexa.Value.Maximum")] }],
|
|
semantics: semantics()
|
|
.action("Close", "SetRangeValue", { rangeValue: 0 })
|
|
.action(["Open", AlexaActions.Raise], "SetRangeValue", { rangeValue: 100 })
|
|
.state("Closed", 0)
|
|
.stateRange("Open", 1, 100),
|
|
retrievable: true,
|
|
proactivelyReported: true,
|
|
});
|
|
blinds.add(ModeController, {
|
|
instance: "Blind.Position",
|
|
friendlyNames: [text("Position")],
|
|
supportedModes: [{ value: "Position.Up", friendlyNames: [asset("Alexa.Value.Open")] }, { value: "Position.Down", friendlyNames: [asset("Alexa.Value.Close")] }],
|
|
ordered: false,
|
|
});
|
|
blinds.add(ToggleController, { instance: "Blind.Tilt", friendlyNames: [text("Tilt")], nonControllable: true });
|
|
// @ts-expect-error a range controller has a range
|
|
blinds.add(RangeController, { instance: "Blind.Tilt", friendlyNames: [text("Tilt")] });
|
|
// @ts-expect-error a generic controller has an instance name and friendly names
|
|
blinds.add(ToggleController, { proactivelyReported: true });
|
|
// @ts-expect-error and so it cannot be declared without options
|
|
blinds.add(ToggleController);
|
|
// @ts-expect-error not a unit of measure
|
|
blinds.add(RangeController, { instance: "Blind.Tilt", friendlyNames: [text("Tilt")], range: { min: 0, max: 90, precision: 1 }, unit: "Alexa.Unit.Percentage" });
|
|
// @ts-expect-error not a phrase Alexa has
|
|
semantics().action("Shut", "TurnOff");
|
|
// What a directive carries and what a property holds are typed by the descriptor
|
|
const lower: Infer<typeof RangeController.directives.AdjustRangeValue.payload> = { rangeValueDelta: -10, rangeValueDeltaDefault: false };
|
|
const position: Schema<number> = lift.descriptor.properties.rangeValue.value;
|
|
// @ts-expect-error a mode is a string, or null when none is set
|
|
const current: Infer<typeof ModeController.properties.mode.value> = 3;
|
|
|
|
// The registry: a descriptor by its namespace or by the 1.x enum member
|
|
const described: InterfaceDescriptor = registry.get("Alexa.PowerController");
|
|
const version: string = registry.get(AlexaInterfaceType.ENDPOINT_HEALTH).version;
|
|
const refused: Error = new DeclarationError({ endpointId: "lamp-1", namespace: described.namespace }, "declared twice");
|
|
|
|
// The vocabularies are unions of what the pages list
|
|
const opening: AssetId = Assets[0];
|
|
const percent: UnitOfMeasure = "Alexa.Unit.Percent";
|
|
const vacuum: DisplayCategoryName = "VACUUM";
|
|
// @ts-expect-error not in the global Alexa catalog
|
|
const misspelt: AssetId = "Alexa.Setting.Openning";
|
|
// @ts-expect-error an asset, but not a unit of measure
|
|
const notAUnit: UnitOfMeasure = "Alexa.Setting.Opening";
|
|
|
|
// A schema types what it parses
|
|
declare const temperature: Schema<Temperature>;
|
|
const measured: Infer<typeof temperature> = { value: 20, scale: "CELSIUS" };
|
|
// @ts-expect-error not a temperature scale
|
|
const rankine: Infer<typeof temperature> = { value: 20, scale: "RANKINE" };
|
|
|
|
export {
|
|
options, added, chained, sent, on, namespace, reachable, announced, endpoint, problems, names, lower, position, current, version,
|
|
refused, opening, percent, vacuum, misspelt, notAUnit, measured, rankine,
|
|
};
|