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>
51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
# 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.js) | lamp | PowerController, BrightnessController | handlers, `device.state()`, `ctx.respond()` |
|
|
| [color-lamp.js](color-lamp.js) | colour lamp | + ColorController, ColorTemperatureController | a state that depends on the mode of the device |
|
|
| [thermostat.js](thermostat.js) | thermostat | ThermostatController, TemperatureSensor | one setpoint, three modes, temperature scales |
|
|
| [blind.js](blind.js) | roller blind | RangeController | an instance, friendly names, semantics for open and close |
|
|
| [lock.js](lock.js) | lock | LockController | `ctx.defer()` for an answer that takes longer than 7 seconds |
|
|
| [sensor.js](sensor.js) | contact sensor | ContactSensor | `device.changeReport()` |
|
|
| [scene.js](scene.js) | scene | SceneController | ActivationStarted and DeactivationStarted |
|
|
| [doorbell.js](doorbell.js) | doorbell | DoorbellEventSource | `device.raise()` |
|
|
| [errors.js](errors.js) | fan | PowerController, RangeController | `AlexaErrors`, `ctx.error()` |
|
|
| [plug.mjs](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:
|
|
|
|
```sh
|
|
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](testing/lamp.test.js) tests a lamp with a `MemoryPublisher` and `bridge.receive()`. It needs
|
|
no credentials and connects nowhere:
|
|
|
|
```sh
|
|
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/](legacy) has the nine examples of 1.5.2, on the 1.x API.
|