David
c492ef74d1
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>
79 lines
4 KiB
TypeScript
79 lines
4 KiB
TypeScript
import type { IClientOptions } from "mqtt";
|
|
import Device from "./device/Device.js";
|
|
import type { EndpointDefinition } from "./device/Device.js";
|
|
import { EventEmitter } from "events";
|
|
import { DisplayCategory } from "./compat/enums.js";
|
|
/** Optional settings for the bridge (1.5.1). Everything has the 1.4.0 behaviour as its default. */
|
|
export interface Alex2MQTTOptions {
|
|
/** The broker URL. Default: the public Alex2MQTT broker, mqtt://Alex2MQTT.stormysdream.club:1883. */
|
|
host?: string;
|
|
/** Extra mqtt.js client options (reconnectPeriod, connectTimeout, clientId, ...). Merged over the defaults. */
|
|
mqtt?: IClientOptions;
|
|
/** Where log lines go. Default: console (only when debugLogging is on). */
|
|
log?: (message: string, detail?: unknown) => void;
|
|
/**
|
|
* false: discovery does not list the Alexa interface on the endpoints. Default: every endpoint ends with
|
|
* { type: "AlexaInterface", interface: "Alexa", version: "3" }, which Amazon requires and 1.x left out.
|
|
*/
|
|
alexaInterface?: boolean;
|
|
}
|
|
export declare const DEFAULT_HOST = "mqtt://Alex2MQTT.stormysdream.club:1883";
|
|
/**
|
|
* The Alexa-to-MQTT bridge: one broker connection for a user's root topic, a set of registered devices, discovery and
|
|
* directive dispatch.
|
|
*
|
|
* Events (all optional to listen to - since 1.5.1 a broker outage never throws out of the library):
|
|
* "connect" connected (or reconnected) and subscribed to <root>/#
|
|
* "offline" the connection dropped; mqtt.js reconnects on its own (reconnectPeriod, default 1 s)
|
|
* "reconnect" a reconnect attempt starts
|
|
* "close" the connection closed
|
|
* "error" (err) a connection or publish error. Emitted ONLY when a listener is attached (1.4.0 emitted it
|
|
* unconditionally, and Node kills a process that has an unhandled "error" event)
|
|
* "discover" (n) a discovery request was answered with n devices
|
|
* "directive" (info) a directive was dispatched to a device: { endpointId, namespace, name }
|
|
*/
|
|
declare class Alex2MQTT extends EventEmitter {
|
|
private username;
|
|
private password;
|
|
private rootTopic;
|
|
private debugLogging;
|
|
private client;
|
|
private devices;
|
|
private MqttHost;
|
|
private options;
|
|
private logged;
|
|
/** true while the broker connection is up. */
|
|
connected: boolean;
|
|
/** ISO time of the last discovery request answered, null before the first. */
|
|
lastDiscoveryAt: string | null;
|
|
constructor(username: string, password: string, rootTopic: string, debugLogging?: boolean, options?: Alex2MQTTOptions);
|
|
private log;
|
|
/** Emit "error" only when somebody listens: an unhandled "error" event would crash the host process. */
|
|
private fail;
|
|
connect(): void;
|
|
private describeDevices;
|
|
/** Close the broker connection (resolves once closed). The devices stay registered; connect() again reuses them. */
|
|
disconnect(): Promise<void>;
|
|
/**
|
|
* Declare a device:
|
|
*
|
|
* const blinds = bridge.addDevice({ endpointId: "bedroom-blinds", name: "Bedroom Blinds",
|
|
* categories: ["INTERIOR_BLIND"], manufacturerName: "Acme", description: "Roller blind by Acme" });
|
|
*
|
|
* Throws a DeclarationError when Alexa would reject the endpoint (an endpointId with a slash, a name with
|
|
* punctuation) or when the endpointId is registered already. Discovery lists Alexa.EndpointHealth for the device
|
|
* unless endpointHealth is false.
|
|
*/
|
|
addDevice(definition: EndpointDefinition): Device;
|
|
registerDevice(name: string, endpointId: string, displayCategory?: DisplayCategory | DisplayCategory[] | null): Device;
|
|
private register;
|
|
/** Forget a device (its listeners with it). Returns false when there was none. */
|
|
unregisterDevice(endpointId: string): boolean;
|
|
/** Forget every device. */
|
|
clearDevices(): void;
|
|
getDevices(): Device[];
|
|
getDevice(endpointId: string): Device | undefined;
|
|
getRootTopic(): string;
|
|
getHost(): string;
|
|
}
|
|
export default Alex2MQTT;
|