David
dd071548bc
The interface registry, generated and checked discovery, typed dispatch with automatic error answers, message builders, proactive events and typed helpers for every error type; the 1.x API is kept and the examples of 1.5.2 run unchanged. docs/wire-changes.md lists what a 1.x caller can observe. On 2026-09-28 a real Alexa account drove 33 test devices on this API through the public Alex2MQTT service: Alexa accepted the discovery of all of them, 50 of 58 cases passed, 4 had no action in the control call and 4 failed on what the check could see, none on an answer of the library. The readme table names the interfaces that run covered. Voice commands were not tested yet. 307 tests. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| legacy | ||
| testing | ||
| blind.js | ||
| color-lamp.js | ||
| doorbell.js | ||
| errors.js | ||
| lamp.js | ||
| lock.js | ||
| plug.mjs | ||
| README.md | ||
| scene.js | ||
| sensor.js | ||
| thermostat.js | ||
Examples
One file per recipe, on the 2.0 API. Each file is complete: it declares one device, answers its directives and connects. The state of the device is an object in the file, which you replace with what drives your device.
| File | Device | Interfaces | Shows |
|---|---|---|---|
| lamp.js | lamp | PowerController, BrightnessController | handlers, device.state(), ctx.respond() |
| color-lamp.js | colour lamp | + ColorController, ColorTemperatureController | a state that depends on the mode of the device |
| thermostat.js | thermostat | ThermostatController, TemperatureSensor | one setpoint, three modes, temperature scales |
| blind.js | roller blind | RangeController | an instance, friendly names, semantics for open and close |
| lock.js | lock | LockController | ctx.defer() for an answer that takes longer than 7 seconds |
| sensor.js | contact sensor | ContactSensor | device.changeReport() |
| scene.js | scene | SceneController | ActivationStarted and DeactivationStarted |
| doorbell.js | doorbell | DoorbellEventSource | device.raise() |
| errors.js | fan | PowerController, RangeController | AlexaErrors, ctx.error() |
| plug.mjs | plug | PowerController | the library as an ES module |
Run one
The examples read the MQTT user name, the password and the root topic of your Alex2MQTT account from the environment, and say which variable is missing:
ALEX2MQTT_USERNAME=... ALEX2MQTT_PASSWORD=... ALEX2MQTT_ROOT_TOPIC=... node examples/lamp.js
In a checkout of this repository npm install comes first: it builds dist/, which require("alex2node") resolves
to. Then discover the devices in the Alexa app.
sensor.js and doorbell.js wait for the Enter key: it opens and closes the door, and rings the bell.
lock.js takes BOLT_SECONDS, the time its bolt needs, 8 by default.
Test a device without a broker
testing/lamp.test.js tests a lamp with a MemoryPublisher and bridge.receive(). It needs
no credentials and connects nowhere:
node examples/testing/lamp.test.js
What was tested
test/examples.test.js starts every file with node, against a broker on 127.0.0.1, discovers the device, sends
it directives and checks the answers. These files were not run against an Alexa account; test devices that make the
same calls were, on 2026-09-28, the doorbell's raise() among them (the readme has the list).
1.x
legacy/ has the nine examples of 1.5.2, on the 1.x API.