discovery: generate capability JSON from the registry
A capability is a descriptor plus what the endpoint declares (device/Capability.ts), and its discovery object is
generated from the two. The new API is bridge.addDevice({ endpointId, name, categories, ... }) and
device.add(PowerController, options): both throw a DeclarationError that names the endpoint, the interface and
the instance (device/validate.ts), and leave the bridge and the device as they were. AlexaInterface is the same
Capability with the 1.x methods on it; it, ActionMapping and the enums moved to src/compat/, Device to src/device/.
What a 1.x caller can observe:
- every endpoint ends with { type: "AlexaInterface", interface: "Alexa", version: "3" } (alexa-interface.html);
new Alex2MQTT(..., { alexaInterface: false }) leaves it out
- the fields of a capability object come in the order of Amazon's examples; their content is unchanged
- addCapability() with a name that is not an interface throws (1.5.2 announced it with the version "UNKNOWN")
- ActionMapping takes the payload as an object; a JSON string is parsed (1.5.2 sent the string), any other throws
- what Alexa would reject in a 1.x declaration is not refused: device.check() lists it and the bridge logs each
line once, as "warning: ..." through the log hook, when it answers a discovery
- a device whose JSON cannot be built is left out of the answer and reported as an error event
- PowerController and EndpointHealth are the descriptors and keep ON/OFF and OK/UNREACHABLE; PowerState is new
Tests: six zoo devices declared the 1.x way give the JSON that Alexa accepted from 1.5.2 on 2026-09-28, plus the
Alexa capability. npm test: 85 pass (was 57) in 10-12 s, also on Node 18.20.8 and 20.20.2.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
parent
aa0ffd64ea
commit
c492ef74d1
90 changed files with 5539 additions and 1760 deletions
348
src/device/Device.ts
Normal file
348
src/device/Device.ts
Normal file
|
|
@ -0,0 +1,348 @@
|
|||
import { EventEmitter } from "events";
|
||||
import { randomUUID } from "crypto";
|
||||
import type { MqttClient } from "mqtt";
|
||||
import { AlexaErrorResponse } from "../AlexaErrorResponse.js";
|
||||
import { AlexaStatusMessage } from "../AlexaStatusMessage.js";
|
||||
import type { ChangeCause } from "../AlexaStatusMessage.js";
|
||||
import { AlexaInterface } from "../compat/AlexaInterface.js";
|
||||
import { DisplayCategory } from "../compat/enums.js";
|
||||
import type { AlexaInterfaceType } from "../compat/enums.js";
|
||||
import type { DisplayCategoryName } from "../registry/catalog.js";
|
||||
import { Alexa } from "../registry/interfaces/Alexa.js";
|
||||
import { EndpointHealth } from "../registry/interfaces/EndpointHealth.js";
|
||||
import { SchemaError } from "../registry/schema.js";
|
||||
import { DeclarationError } from "../registry/types.js";
|
||||
import type { Directives, EndpointView, InterfaceDescriptor, Label, Properties } from "../registry/types.js";
|
||||
import { Capability, commonOptions } from "./Capability.js";
|
||||
import type { AnyCapability, CapabilityJson, Declaration } from "./Capability.js";
|
||||
import { checkCapability, checkCapabilityCount, checkEndpoint } from "./validate.js";
|
||||
import type { EndpointFields } from "./validate.js";
|
||||
|
||||
/** An endpoint as bridge.addDevice() takes it. */
|
||||
export interface EndpointDefinition {
|
||||
/** Up to 256 letters, digits, spaces and _ - = # ; : ? @ &. The same id at every discovery. */
|
||||
endpointId: string;
|
||||
/** What the user calls the device: letters, digits and spaces. */
|
||||
name: string;
|
||||
/** The first one is the category the Alexa app shows the device under. */
|
||||
categories: Array<DisplayCategoryName | DisplayCategory>;
|
||||
/** Shown in the Alexa app, up to 128 characters. Default: "Alexa to Node.js bridge". */
|
||||
description?: string;
|
||||
/** Up to 128 characters. Default: "Alex2Node". */
|
||||
manufacturerName?: string;
|
||||
// additionalAttributes: Alexa tells two devices apart by them when two add-ons report the same one
|
||||
manufacturer?: string;
|
||||
model?: string;
|
||||
serialNumber?: string;
|
||||
firmwareVersion?: string;
|
||||
softwareVersion?: string;
|
||||
customIdentifier?: string;
|
||||
/** Returned with every directive to the endpoint. Up to 5000 bytes; not a place for state. */
|
||||
cookie?: Record<string, string>;
|
||||
/** false: the device gets no Alexa.EndpointHealth unless it declares one. */
|
||||
endpointHealth?: boolean;
|
||||
}
|
||||
|
||||
/** An endpoint object of a discovery answer (alexa-discovery-objects.html, "Endpoint object"). */
|
||||
export interface EndpointJson extends EndpointFields {
|
||||
capabilities: CapabilityJson[];
|
||||
}
|
||||
|
||||
// device.add(PowerController) needs no options, device.add(RangeController) cannot do without
|
||||
type DeclarationArguments<O, I extends boolean> = {} extends Declaration<O, I>
|
||||
? [options?: Declaration<O, I>]
|
||||
: [options: Declaration<O, I>];
|
||||
|
||||
class Device extends EventEmitter {
|
||||
public softwareVersion = "1.0.0";
|
||||
public serialNumber = "Alex2Node";
|
||||
public firmwareVersion = "1.0.0";
|
||||
public customIdentifier = "Alex2Node";
|
||||
public cookie?: Record<string, string>;
|
||||
/**
|
||||
* Discovery lists the Alexa interface on the endpoint (alexa-interface.html: "You must explicitly identify your
|
||||
* support for the Alexa interface"). The bridge sets it from its alexaInterface option.
|
||||
*/
|
||||
public alexaInterface = true;
|
||||
/**
|
||||
* Discovery lists Alexa.EndpointHealth when the device did not declare it and is not a scene. On for a device of
|
||||
* bridge.addDevice(), off for one of registerDevice(), which is announced as 1.x announced it.
|
||||
*/
|
||||
public endpointHealth = false;
|
||||
private capabilities: AnyCapability[] = [];
|
||||
/** Where a failed publish from this device or a message it built is reported; Alex2MQTT sets it (1.5.2). */
|
||||
public onPublishError?: (err: Error) => void;
|
||||
|
||||
constructor(
|
||||
private mqttClient: MqttClient,
|
||||
private rootTopic: string,
|
||||
public name: string,
|
||||
public endpointId: string,
|
||||
public displayCategory: Array<DisplayCategory> | null,
|
||||
public description: string = "Alexa to Node.js bridge",
|
||||
public manufacturerName: string = "Alex2Node",
|
||||
public manufacturer: string = "Alex2Node",
|
||||
public model: string = "Alex2Node_v1.0.0"
|
||||
) {
|
||||
super();
|
||||
}
|
||||
|
||||
/** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
|
||||
setMqttClient(client: MqttClient): void {
|
||||
this.mqttClient = client;
|
||||
}
|
||||
|
||||
getName(): string {
|
||||
return this.name;
|
||||
}
|
||||
|
||||
setName(name: string): void {
|
||||
this.name = name;
|
||||
}
|
||||
|
||||
getEndpointId(): string {
|
||||
return this.endpointId;
|
||||
}
|
||||
|
||||
setDisplayCategory(category: DisplayCategory | DisplayCategory[]): void {
|
||||
this.displayCategory = Array.isArray(category) ? category : [category];
|
||||
}
|
||||
|
||||
getDisplayCategory(): Array<DisplayCategory> {
|
||||
return this.displayCategory || [DisplayCategory.LIGHT];
|
||||
}
|
||||
|
||||
setDescription(description: string): void {
|
||||
this.description = description;
|
||||
}
|
||||
|
||||
getDescription(): string {
|
||||
return this.description;
|
||||
}
|
||||
getErrorMessage(correlationToken: string): AlexaErrorResponse {
|
||||
const msg = new AlexaErrorResponse(
|
||||
correlationToken,
|
||||
this.rootTopic,
|
||||
this.endpointId,
|
||||
this.mqttClient
|
||||
);
|
||||
msg.onPublishError = this.onPublishError;
|
||||
return msg;
|
||||
}
|
||||
getStatusMessage(
|
||||
correlationToken: string,
|
||||
isResponse = false,
|
||||
isDeferred = false
|
||||
): AlexaStatusMessage {
|
||||
const msg = new AlexaStatusMessage(
|
||||
correlationToken,
|
||||
this.rootTopic,
|
||||
this.endpointId,
|
||||
this.mqttClient,
|
||||
isResponse,
|
||||
isDeferred
|
||||
);
|
||||
msg.onPublishError = this.onPublishError;
|
||||
return msg;
|
||||
}
|
||||
/**
|
||||
* A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
|
||||
* .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
|
||||
* event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
|
||||
*/
|
||||
getChangeReport(cause: ChangeCause = "PHYSICAL_INTERACTION"): AlexaStatusMessage {
|
||||
const msg = new AlexaStatusMessage("", this.rootTopic, this.endpointId, this.mqttClient, false, false, cause);
|
||||
msg.onPublishError = this.onPublishError;
|
||||
return msg;
|
||||
}
|
||||
/**
|
||||
* Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
|
||||
* (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
|
||||
*/
|
||||
sendSceneResponse(correlationToken: string, activated: boolean, cause: ChangeCause = "VOICE_INTERACTION", sendAsync = false): Promise<string> {
|
||||
const payload = {
|
||||
context: {},
|
||||
event: {
|
||||
header: { namespace: "Alexa.SceneController", name: activated ? "ActivationStarted" : "DeactivationStarted", messageId: randomUUID(), correlationToken, payloadVersion: "3" },
|
||||
endpoint: { endpointId: this.endpointId },
|
||||
payload: { cause: { type: cause }, timestamp: new Date().toISOString() },
|
||||
},
|
||||
};
|
||||
const topic = `${this.rootTopic}/${this.endpointId}/${sendAsync ? "deferredResponse" : "alexaResponce"}`;
|
||||
return new Promise((resolve) => {
|
||||
this.mqttClient.publish(topic, JSON.stringify(payload), (err) => {
|
||||
if (!err) return resolve(topic);
|
||||
if (this.onPublishError) this.onPublishError(err); // -> the bridge's "error" event (when somebody listens)
|
||||
resolve(""); // 1.5.1 rejected here, and an un-caught send() then killed the host on any broker hiccup
|
||||
});
|
||||
});
|
||||
}
|
||||
/** The capabilities the device declared, in the order it declared them. */
|
||||
getCapabilities(): AnyCapability[] {
|
||||
return this.capabilities.slice();
|
||||
}
|
||||
setManufacturerName(name: string): void {
|
||||
this.manufacturerName = name;
|
||||
}
|
||||
|
||||
getManufacturerName(): string {
|
||||
return this.manufacturerName;
|
||||
}
|
||||
|
||||
setManufacturer(manufacturer: string): void {
|
||||
this.manufacturer = manufacturer;
|
||||
}
|
||||
|
||||
getManufacturer(): string {
|
||||
return this.manufacturer;
|
||||
}
|
||||
|
||||
setModel(model: string): void {
|
||||
this.model = model;
|
||||
}
|
||||
|
||||
getModel(): string {
|
||||
return this.model;
|
||||
}
|
||||
|
||||
getSoftwareVersion(): string {
|
||||
return this.softwareVersion;
|
||||
}
|
||||
|
||||
/**
|
||||
* Declare an interface of the device:
|
||||
*
|
||||
* lamp.add(PowerController, { proactivelyReported: true });
|
||||
* blinds.add(RangeController, { instance: "Blind.Lift", friendlyNames: [asset("Alexa.Setting.Opening")],
|
||||
* range: { min: 0, max: 100, precision: 1 } });
|
||||
*
|
||||
* Throws a DeclarationError that names the endpoint, the interface and the instance when Alexa would reject the
|
||||
* capability; the device is then as it was before the call.
|
||||
*/
|
||||
add<P extends Properties, D extends Directives, O, I extends boolean>(
|
||||
descriptor: InterfaceDescriptor<P, D, O, I>,
|
||||
...[options]: DeclarationArguments<O, I>
|
||||
): Capability<P, D, O> {
|
||||
const where = { endpointId: this.endpointId, namespace: descriptor.namespace, instance: "" };
|
||||
if (options !== undefined && (typeof options !== "object" || options === null)) {
|
||||
throw new DeclarationError(where, "the options of a declaration are an object");
|
||||
}
|
||||
try {
|
||||
const { instance, friendlyNames, retrievable, proactivelyReported, nonControllable, ...given } = commonOptions.parse(options ?? {});
|
||||
where.instance = instance ?? "";
|
||||
const common = { instance, friendlyNames: friendlyNames as Label[] | undefined, retrievable, proactivelyReported, nonControllable };
|
||||
const capability = new Capability(descriptor, { ...common, options: interfaceOptions(descriptor, given) });
|
||||
capability.endpointId = this.endpointId;
|
||||
checkCapability(capability, descriptor, this.view(this.capabilities));
|
||||
checkCapabilityCount(this.endpointId, this.announced([...this.capabilities, capability]).length);
|
||||
this.capabilities.push(capability);
|
||||
return capability;
|
||||
} catch (err) {
|
||||
throw err instanceof SchemaError ? new DeclarationError(where, err.message) : err;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Declare an interface the 1.x way, by its name: options.retrievable / proactivelyReported / instance, then the
|
||||
* add and set methods of the capability that is returned. Throws for a name that is not an interface. Anything
|
||||
* else Alexa would reject is not refused here: check() lists it.
|
||||
*/
|
||||
addCapability(type: AlexaInterfaceType | string, options: { retrievable?: boolean; proactivelyReported?: boolean; instance?: string } = {}): AlexaInterface {
|
||||
let capability: AlexaInterface;
|
||||
try {
|
||||
capability = new AlexaInterface(type, options.retrievable ?? true, options.proactivelyReported ?? false, options.instance ?? "");
|
||||
} catch (err) {
|
||||
throw err instanceof DeclarationError ? new DeclarationError({ endpointId: this.endpointId }, err.problem) : err;
|
||||
}
|
||||
capability.endpointId = this.endpointId;
|
||||
this.capabilities.push(capability);
|
||||
return capability;
|
||||
}
|
||||
|
||||
/**
|
||||
* What Alexa would reject in the device as it is declared now, one line for each: a name with punctuation, an
|
||||
* interface declared twice. Also what a capability noted about its declaration. Empty when there is nothing.
|
||||
* The bridge logs the lines when it answers a discovery.
|
||||
*/
|
||||
check(): string[] {
|
||||
const lines: string[] = [];
|
||||
const attempt = (rule: () => void): void => {
|
||||
try {
|
||||
rule();
|
||||
} catch (err) {
|
||||
if (!(err instanceof DeclarationError)) throw err;
|
||||
lines.push(err.message);
|
||||
}
|
||||
};
|
||||
attempt(() => checkEndpoint(this.fields()));
|
||||
this.capabilities.forEach((capability, i) => {
|
||||
capability.endpointId = this.endpointId;
|
||||
attempt(() => checkCapability(capability, capability.descriptor, this.view(this.capabilities.slice(0, i))));
|
||||
const notes = [...capability.notes];
|
||||
const { tier, properties } = capability.descriptor;
|
||||
if (tier === 3 && Object.keys(properties).length === 0 && capability.toJSON().properties) {
|
||||
notes.push("no property list known, discovery lists it with no supported properties");
|
||||
}
|
||||
for (const note of notes) lines.push(new DeclarationError(capability, note).message);
|
||||
});
|
||||
attempt(() => checkCapabilityCount(this.endpointId, this.announced(this.capabilities).length));
|
||||
return lines;
|
||||
}
|
||||
|
||||
/** The endpoint object for discovery. */
|
||||
getJSON(): EndpointJson {
|
||||
return { ...this.fields(), capabilities: this.announced(this.capabilities).map((capability) => capability.toJSON()) };
|
||||
}
|
||||
|
||||
private fields(): EndpointFields {
|
||||
return {
|
||||
endpointId: this.endpointId,
|
||||
friendlyName: this.name,
|
||||
description: this.description,
|
||||
manufacturerName: this.manufacturerName,
|
||||
displayCategories: this.getDisplayCategory(),
|
||||
additionalAttributes: {
|
||||
manufacturer: this.manufacturer,
|
||||
model: this.model,
|
||||
serialNumber: this.serialNumber,
|
||||
firmwareVersion: this.firmwareVersion,
|
||||
softwareVersion: this.softwareVersion,
|
||||
customIdentifier: this.customIdentifier,
|
||||
},
|
||||
...(this.cookie ? { cookie: this.cookie } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
// The endpoint as the rules of a capability see it
|
||||
private view(declaredBefore: readonly AnyCapability[]): EndpointView {
|
||||
return {
|
||||
endpointId: this.endpointId,
|
||||
friendlyName: this.name,
|
||||
description: this.description,
|
||||
displayCategories: this.getDisplayCategory(),
|
||||
capabilities: declaredBefore,
|
||||
};
|
||||
}
|
||||
|
||||
// What discovery lists: the declared capabilities, then the ones the library adds
|
||||
private announced(declared: readonly AnyCapability[]): AnyCapability[] {
|
||||
const has = (namespace: string): boolean => declared.some((capability) => capability.namespace === namespace);
|
||||
const added: AnyCapability[] = [];
|
||||
// alexa-scenecontroller.html, "Discovery": a scene is not a physical device and has no Alexa.EndpointHealth
|
||||
if (this.endpointHealth && !has(EndpointHealth.namespace) && !has("Alexa.SceneController")) {
|
||||
added.push(new Capability(EndpointHealth, { options: {} }));
|
||||
}
|
||||
if (this.alexaInterface && !has(Alexa.namespace)) added.push(new Capability(Alexa, { options: {} }));
|
||||
return [...declared, ...added];
|
||||
}
|
||||
}
|
||||
|
||||
// The options of the interface itself, checked by the schema of its descriptor
|
||||
function interfaceOptions<O>(descriptor: InterfaceDescriptor<any, any, O, boolean>, given: Record<string, unknown>): O {
|
||||
if (descriptor.options) return descriptor.options.parse(given);
|
||||
const [unknown] = Object.keys(given);
|
||||
if (unknown !== undefined) throw new SchemaError(unknown, "not an option of the interface");
|
||||
return {} as O;
|
||||
}
|
||||
|
||||
export default Device;
|
||||
Loading…
Add table
Add a link
Reference in a new issue