David
785944b2da
The readme is rewritten for 2.0: what the library needs, install, the lamp as quick start, concepts, the table of interfaces, recipes, the bridge contract, errors, testing without Alexa, migration from 1.x and limits. scripts/capability-table.js (npm run docs) writes the table from the registry and the text of three example files into their code blocks; "Through Alexa" names only the runs of 2026-09-28, made with 1.5.2. test/readme.test.js fails on a stale table or file, runs examples/testing/lamp.test.js (MemoryPublisher, no broker) and compiles the other code blocks. package.json: description, keywords, CHANGELOG.md in files. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2.6 KiB
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. The examples were not run against an Alexa account. doorbell.js publishes
to <root>/event, and whether a press reaches Alexa depends on the Alex2MQTT service relaying that topic.
1.x
legacy/ has the nine examples of 1.5.2, on the 1.x API.