initial release of Alex2Node
This commit is contained in:
David
parent
0804bd7397
commit
4eb2a84d72
20 changed files with 2047 additions and 3 deletions
181
readme.md
Normal file
181
readme.md
Normal file
|
|
@ -0,0 +1,181 @@
|
|||
# Alex2Node
|
||||
|
||||
Alex2Node is a lightweight Node.js library for integrating devices with Amazon Alexa smart home APIs using MQTT. The library simplifies the process of creating Alexa-compatible devices using Alex2MQTT instead of an Alexa Skill directly.
|
||||
|
||||
For more details on how to configure Alex2MQTT, visit [Alex2MQTT Documentation](https://alex2mqtt.stormysdream.club/).
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
- Supports "All" Alexa smart home capabilities.
|
||||
- Simplifies Alexa device integration with MQTT.
|
||||
- Event-driven architecture for handling Alexa directives.
|
||||
- Easily configure devices and their capabilities via simple API.
|
||||
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Installation
|
||||
|
||||
You can install **Alex2Node** via npm:
|
||||
|
||||
```bash
|
||||
npm install alex2node
|
||||
```
|
||||
|
||||
Then, import it into your JavaScript or TypeScript file:
|
||||
|
||||
```js
|
||||
const { Alex2MQTT, AlexaInterfaceType, PowerController } = require('alex2node');
|
||||
```
|
||||
|
||||
Make sure to include your MQTT connection credentials via a `.env` file or directly in the code.
|
||||
|
||||
Credentials can be found at https://alex2mqtt.stormysdream.club/ after logging in with amazon.
|
||||
|
||||
---
|
||||
|
||||
## Creating a Basic Device
|
||||
|
||||
### Example: Power Control for a Light
|
||||
|
||||
Here’s how to create a simple device that controls a light:
|
||||
|
||||
First, create an instance of the Alexa-to-MQTT client and initialize it with your MQTT credentials:
|
||||
|
||||
```js
|
||||
require("dotenv").config(); // Load environment variables from .env file
|
||||
|
||||
const { Alex2MQTT, AlexaInterfaceType, PowerController } = require("alex2node");
|
||||
|
||||
const username = process.env.MQTT_USERNAME;
|
||||
const password = process.env.MQTT_PASSWORD;
|
||||
const rootTopic = process.env.MQTT_ROOT_TOPIC;
|
||||
|
||||
const alex2NodeClient = new Alex2MQTT(username, password, rootTopic, false);
|
||||
alex2NodeClient.connect(); // Connect to the MQTT broker
|
||||
```
|
||||
|
||||
Once initialized, you can begin to add virtual devices. In this example, we will add a PowerController for a light:
|
||||
|
||||
```js
|
||||
const deviceName = "Bedroom Light";
|
||||
const bedroomLight = alex2NodeClient.registerDevice(deviceName, "endpoint1");
|
||||
|
||||
// Add the PowerController capability
|
||||
bedroomLight.addCapability(AlexaInterfaceType.POWER_CONTROLLER);
|
||||
|
||||
// Handle Alexa's ReportState directive to report the current state
|
||||
let outputState = PowerController.OFF;
|
||||
bedroomLight.on("ReportState", (payload) => {
|
||||
const { correlationToken } = payload;
|
||||
const status = bedroomLight.getStatusMessage(correlationToken);
|
||||
status
|
||||
.addHealthProp("OK")
|
||||
.addPowerControllerProp(outputState)
|
||||
.send();
|
||||
});
|
||||
|
||||
// Handle Alexa's Event directive to process state changes
|
||||
bedroomLight.on("Event", (directive, interfaceType) => {
|
||||
if (interfaceType === AlexaInterfaceType.POWER_CONTROLLER) {
|
||||
const name = directive.header.name;
|
||||
const token = directive.header.correlationToken;
|
||||
|
||||
if (name === "TurnOn") {
|
||||
outputState = PowerController.ON;
|
||||
console.log("Turning ON the Bedroom Light");
|
||||
} else if (name === "TurnOff") {
|
||||
outputState = PowerController.OFF;
|
||||
console.log("Turning OFF the Bedroom Light");
|
||||
}
|
||||
|
||||
const status = bedroomLight.getStatusMessage(token, true);
|
||||
status
|
||||
.addHealthProp("OK")
|
||||
.addPowerControllerProp(outputState)
|
||||
.send();
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Interface Types
|
||||
| Alexa Interface Type | Status |
|
||||
|-----------------------------------------------------|-------------|
|
||||
| AlexaInterfaceType::ENDPOINT_HEALTH | Fully Supported |
|
||||
| AlexaInterfaceType::POWER_CONTROLLER | Fully Supported |
|
||||
| AlexaInterfaceType::BRIGHTNESS_CONTROLLER | Fully Supported |
|
||||
| AlexaInterfaceType::TOGGLE_CONTROLLER | Fully Supported |
|
||||
| AlexaInterfaceType::TEMPERATURE_SENSOR | Fully Supported |
|
||||
| AlexaInterfaceType::COLOR_TEMPERATURE_CONTROLLER | Fully Supported |
|
||||
| AlexaInterfaceType::AUTOMATION_MANAGEMENT | Supported* |
|
||||
| AlexaInterfaceType::CHANNEL_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::COLOR_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::CONTACT_SENSOR | Supported* |
|
||||
| AlexaInterfaceType::APPLICATION_STATE_REPORTER | Supported* |
|
||||
| AlexaInterfaceType::AUDIO_PLAY_QUEUE | Supported* |
|
||||
| AlexaInterfaceType::AUTHORIZATION_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::AUTOMOTIVE_VEHICLE_DATA | Supported* |
|
||||
| AlexaInterfaceType::CAMERA_LIVE_VIEW_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::CAMERA_STREAM_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::COMMISSIONABLE | Supported* |
|
||||
| AlexaInterfaceType::CONSENT_MANAGEMENT_CONSENT_REQUIRED_REPORTER | Supported* |
|
||||
| AlexaInterfaceType::COOKING | Supported* |
|
||||
| AlexaInterfaceType::DATA_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::DEVICE_USAGE_ESTIMATION | Supported* |
|
||||
| AlexaInterfaceType::DEVICE_USAGE_METER | Supported* |
|
||||
| AlexaInterfaceType::DOORBELL_EVENT_SOURCE | Supported* |
|
||||
| AlexaInterfaceType::EQUALIZER_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::INPUT_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::INVENTORY_LEVEL_SENSOR | Supported* |
|
||||
| AlexaInterfaceType::INVENTORY_LEVEL_USAGE_SENSOR | Supported* |
|
||||
| AlexaInterfaceType::INVENTORY_USAGE_SENSOR | Supported* |
|
||||
| AlexaInterfaceType::KEYPAD_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::LAUNCHER | Supported* |
|
||||
| AlexaInterfaceType::LOCK_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::MEDIA_PLAYBACK | Supported* |
|
||||
| AlexaInterfaceType::MEDIA_SEARCH | Supported* |
|
||||
| AlexaInterfaceType::MODE_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::MOTION_SENSOR | Supported* |
|
||||
| AlexaInterfaceType::PERCENTAGE_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::PLAYBACK_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::PLAYBACK_STATE_REPORTER | Supported* |
|
||||
| AlexaInterfaceType::PROACTIVE_NOTIFICATION_SOURCE | Supported* |
|
||||
| AlexaInterfaceType::RANGE_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::RECORD_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::REMOTE_VIDEO_PLAYER | Supported* |
|
||||
| AlexaInterfaceType::RTC_SESSION_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::SCENE_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::SECURITY_PANEL_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::SEEK_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::SIMPLE_EVENT_SOURCE | Supported* |
|
||||
| AlexaInterfaceType::SMART_VISION_OBJECT_DETECTION_SENSOR | Supported* |
|
||||
| AlexaInterfaceType::SMART_VISION_SNAPSHOT_PROVIDER | Supported* |
|
||||
| AlexaInterfaceType::SPEAKER | Supported* |
|
||||
| AlexaInterfaceType::STEP_SPEAKER | Supported* |
|
||||
| AlexaInterfaceType::THERMOSTAT_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::THERMOSTAT_CONTROLLER_CONFIGURATION | Supported* |
|
||||
| AlexaInterfaceType::THERMOSTAT_CONTROLLER_HVAC_COMPONENTS | Supported* |
|
||||
| AlexaInterfaceType::THERMOSTAT_CONTROLLER_SCHEDULE | Supported* |
|
||||
| AlexaInterfaceType::TIME_HOLD_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::UI_CONTROLLER | Supported* |
|
||||
| AlexaInterfaceType::USER_PREFERENCE | Supported* |
|
||||
| AlexaInterfaceType::VIDEO_RECORDER | Supported* |
|
||||
| AlexaInterfaceType::WAKE_ON_LAN_CONTROLLER | Supported* |
|
||||
|
||||
|
||||
(*Partial support or limited implementation advanced configuration is required)
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Feel free to submit pull requests or issues for feature requests and bug fixes.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License. See the LICENSE file for details.
|
||||
Loading…
Add table
Add a link
Reference in a new issue