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.

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:

npm install alex2node

Then, import it into your JavaScript or TypeScript file:

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:

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:

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.