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
|
|
@ -1,185 +0,0 @@
|
|||
import type { ActionMapping } from "./ActionMapping.js";
|
||||
import { registry } from "./registry/index.js";
|
||||
|
||||
export enum AlexaInterfaceType {
|
||||
APPLICATION_STATE_REPORTER = "Alexa.ApplicationStateReporter",
|
||||
AUDIO_PLAY_QUEUE = "Alexa.Audio.PlayQueue",
|
||||
AUTHORIZATION_CONTROLLER = "Alexa.AuthorizationController",
|
||||
AUTOMATION_MANAGEMENT = "Alexa.AutomationManagement",
|
||||
AUTOMOTIVE_VEHICLE_DATA = "Alexa.Automotive.VehicleData",
|
||||
BRIGHTNESS_CONTROLLER = "Alexa.BrightnessController",
|
||||
CAMERA_LIVE_VIEW_CONTROLLER = "Alexa.Camera.LiveViewController",
|
||||
CAMERA_STREAM_CONTROLLER = "Alexa.CameraStreamController",
|
||||
CHANNEL_CONTROLLER = "Alexa.ChannelController",
|
||||
COLOR_CONTROLLER = "Alexa.ColorController",
|
||||
COLOR_TEMPERATURE_CONTROLLER = "Alexa.ColorTemperatureController",
|
||||
COMMISSIONABLE = "Alexa.Commissionable",
|
||||
CONSENT_MANAGEMENT_CONSENT_REQUIRED_REPORTER = "Alexa.ConsentManagement.ConsentRequiredReporter",
|
||||
CONTACT_SENSOR = "Alexa.ContactSensor",
|
||||
COOKING = "Alexa.Cooking",
|
||||
COOKING_FOOD_TEMPERATURE_CONTROLLER = "Alexa.Cooking.FoodTemperatureController",
|
||||
COOKING_FOOD_TEMPERATURE_SENSOR = "Alexa.Cooking.FoodTemperatureSensor",
|
||||
COOKING_PRESET_CONTROLLER = "Alexa.Cooking.PresetController",
|
||||
COOKING_TEMPERATURE_CONTROLLER = "Alexa.Cooking.TemperatureController",
|
||||
COOKING_TEMPERATURE_SENSOR = "Alexa.Cooking.TemperatureSensor",
|
||||
COOKING_TIME_CONTROLLER = "Alexa.Cooking.TimeController",
|
||||
DATA_CONTROLLER = "Alexa.DataController",
|
||||
DEVICE_USAGE_ESTIMATION = "Alexa.DeviceUsage.Estimation",
|
||||
DEVICE_USAGE_METER = "Alexa.DeviceUsage.Meter",
|
||||
DOORBELL_EVENT_SOURCE = "Alexa.DoorbellEventSource",
|
||||
ENDPOINT_HEALTH = "Alexa.EndpointHealth",
|
||||
EQUALIZER_CONTROLLER = "Alexa.EqualizerController",
|
||||
INPUT_CONTROLLER = "Alexa.InputController",
|
||||
INVENTORY_LEVEL_SENSOR = "Alexa.InventoryLevelSensor",
|
||||
INVENTORY_LEVEL_USAGE_SENSOR = "Alexa.InventoryLevelUsageSensor",
|
||||
INVENTORY_USAGE_SENSOR = "Alexa.InventoryUsageSensor",
|
||||
KEYPAD_CONTROLLER = "Alexa.KeypadController",
|
||||
LAUNCHER = "Alexa.Launcher",
|
||||
LOCK_CONTROLLER = "Alexa.LockController",
|
||||
MEDIA_PLAYBACK = "Alexa.Media.Playback",
|
||||
MEDIA_PLAY_QUEUE = "Alexa.Media.PlayQueue",
|
||||
MEDIA_SEARCH = "Alexa.Media.Search",
|
||||
MODE_CONTROLLER = "Alexa.ModeController",
|
||||
MOTION_SENSOR = "Alexa.MotionSensor",
|
||||
PERCENTAGE_CONTROLLER = "Alexa.PercentageController",
|
||||
PLAYBACK_CONTROLLER = "Alexa.PlaybackController",
|
||||
PLAYBACK_STATE_REPORTER = "Alexa.PlaybackStateReporter",
|
||||
POWER_CONTROLLER = "Alexa.PowerController",
|
||||
POWER_LEVEL_CONTROLLER = "Alexa.PowerLevelController",
|
||||
PROACTIVE_NOTIFICATION_SOURCE = "Alexa.ProactiveNotificationSource",
|
||||
RANGE_CONTROLLER = "Alexa.RangeController",
|
||||
RECORD_CONTROLLER = "Alexa.RecordController",
|
||||
REMOTE_VIDEO_PLAYER = "Alexa.RemoteVideoPlayer",
|
||||
RTC_SESSION_CONTROLLER = "Alexa.RTCSessionController",
|
||||
SCENE_CONTROLLER = "Alexa.SceneController",
|
||||
SECURITY_PANEL_CONTROLLER = "Alexa.SecurityPanelController",
|
||||
SECURITY_PANEL_CONTROLLER_ALERT = "Alexa.SecurityPanelController.Alert",
|
||||
SEEK_CONTROLLER = "Alexa.SeekController",
|
||||
SIMPLE_EVENT_SOURCE = "Alexa.SimpleEventSource",
|
||||
SMART_VISION_OBJECT_DETECTION_SENSOR = "Alexa.SmartVision.ObjectDetectionSensor",
|
||||
SMART_VISION_SNAPSHOT_PROVIDER = "Alexa.SmartVision.SnapshotProvider",
|
||||
SPEAKER = "Alexa.Speaker",
|
||||
STEP_SPEAKER = "Alexa.StepSpeaker",
|
||||
TEMPERATURE_SENSOR = "Alexa.TemperatureSensor",
|
||||
THERMOSTAT_CONTROLLER = "Alexa.ThermostatController",
|
||||
THERMOSTAT_CONTROLLER_CONFIGURATION = "Alexa.ThermostatController.Configuration",
|
||||
THERMOSTAT_CONTROLLER_HVAC_COMPONENTS = "Alexa.ThermostatController.HVAC.Components",
|
||||
THERMOSTAT_CONTROLLER_SCHEDULE = "Alexa.ThermostatController.Schedule",
|
||||
TIME_HOLD_CONTROLLER = "Alexa.TimeHoldController",
|
||||
TOGGLE_CONTROLLER = "Alexa.ToggleController",
|
||||
UI_CONTROLLER = "Alexa.UIController",
|
||||
USER_PREFERENCE = "Alexa.UserPreference",
|
||||
VIDEO_RECORDER = "Alexa.VideoRecorder",
|
||||
WAKE_ON_LAN_CONTROLLER = "Alexa.WakeOnLANController",
|
||||
UNKNOWN = "UNKNOWN",
|
||||
}
|
||||
|
||||
interface FriendlyName {
|
||||
text: string;
|
||||
locale: string;
|
||||
}
|
||||
|
||||
/** One ModeController mode as discovery lists it (configuration.supportedModes): the value plus its friendly names. */
|
||||
export interface SupportedMode {
|
||||
value: string;
|
||||
modeResources?: { friendlyNames: Array<{ "@type": string; value: { text?: string; locale?: string; assetId?: string } }> };
|
||||
}
|
||||
|
||||
export class AlexaInterface {
|
||||
private friendlyNames: FriendlyName[] = [];
|
||||
private actionMappings: ActionMapping[] = [];
|
||||
private supportedModes: Array<string | SupportedMode> = [];
|
||||
|
||||
constructor(
|
||||
public type: AlexaInterfaceType,
|
||||
public retrievable: boolean = true,
|
||||
public proactivelyReported: boolean = false,
|
||||
public instance = ""
|
||||
) {}
|
||||
|
||||
addActionMapping(mapping: ActionMapping): void {
|
||||
this.actionMappings.push(mapping);
|
||||
}
|
||||
|
||||
addFriendlyName(name: string, locale: string): void {
|
||||
this.friendlyNames.push({ text: name, locale });
|
||||
}
|
||||
/** The modes of a ModeController: { value, modeResources } objects as Alexa wants them (plain strings pass through as given). */
|
||||
addSupportedModes(modes: Array<string | SupportedMode>): void {
|
||||
this.supportedModes = modes;
|
||||
}
|
||||
setInstance(name: string): void {
|
||||
this.instance = name;
|
||||
}
|
||||
|
||||
getType(): AlexaInterfaceType {
|
||||
return this.type;
|
||||
}
|
||||
|
||||
getTypeString(): string {
|
||||
return this.type;
|
||||
}
|
||||
|
||||
/** The version of the interface, from its descriptor. "UNKNOWN" for a name the registry does not have. */
|
||||
getVersion(): string {
|
||||
return registry.has(this.type) ? registry.get(this.type).version : "UNKNOWN";
|
||||
}
|
||||
|
||||
/** The names of the properties the interface reports, from its descriptor. */
|
||||
getProps(): string[] {
|
||||
return registry.has(this.type) ? Object.keys(registry.get(this.type).properties) : [];
|
||||
}
|
||||
|
||||
getJSON(): object {
|
||||
const doc: any = {
|
||||
interface: this.getTypeString(),
|
||||
version: this.getVersion(),
|
||||
type: "AlexaInterface",
|
||||
properties: {
|
||||
retrievable: this.retrievable,
|
||||
proactivelyReported: this.proactivelyReported,
|
||||
supported: this.getProps().map(name => ({ name })),
|
||||
},
|
||||
};
|
||||
if (this.type == AlexaInterfaceType.SCENE_CONTROLLER) {
|
||||
// Alexa.SceneController v3 carries no properties block: supportsDeactivation + proactivelyReported at the top level
|
||||
delete doc.properties;
|
||||
doc.supportsDeactivation = true;
|
||||
doc.proactivelyReported = this.proactivelyReported;
|
||||
} else if(this.type==AlexaInterfaceType.THERMOSTAT_CONTROLLER){
|
||||
doc.configuration={
|
||||
"supportedModes": ["HEAT", "COOL", "AUTO", "OFF"],
|
||||
"supportsScheduling": false
|
||||
}
|
||||
}else if (this.supportedModes.length > 0) {
|
||||
doc["configuration"] = {
|
||||
ordered:true,
|
||||
supportedModes: this.supportedModes,
|
||||
};
|
||||
}
|
||||
if (this.instance) {
|
||||
doc.instance = this.instance;
|
||||
}
|
||||
if (this.friendlyNames.length > 0) {
|
||||
const capabilityResources = doc["capabilityResources"] || {};
|
||||
const friendlyNamesArray = capabilityResources["friendlyNames"] || [];
|
||||
this.friendlyNames.forEach((fn) => {
|
||||
const friendlyNameObj: any = { "@type": "text" };
|
||||
friendlyNameObj["value"] = {
|
||||
text: fn.text,
|
||||
locale: fn.locale,
|
||||
};
|
||||
friendlyNamesArray.push(friendlyNameObj);
|
||||
});
|
||||
capabilityResources.friendlyNames=friendlyNamesArray
|
||||
doc["capabilityResources"] = capabilityResources;
|
||||
}
|
||||
if (this.actionMappings.length > 0) {
|
||||
doc.semantics = {
|
||||
actionMappings: this.actionMappings.map((am) => am.toJSON()),
|
||||
};
|
||||
}
|
||||
|
||||
return doc;
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue