# Alex2ESP Alex2ESP is a lightweight Arduino/PlatformIO library for integrating ESP8266 and ESP32 microcontrollers with Amazon Alexa smart home APIs. The library simplifies the process of creating Alexa-compatible devices using MQTT. For more details on how to configure Alex2ESP, visit [Alex2MQTT Documentation](https://alex2mqtt.stormysdream.club/). --- ## Features - Supports "All" Alexa smart home capabilities. - Provides action mapping for advanced directive customization including Open,Close,Raise,and Lower commands. - Allows custom JSON injection in both discovery and state reporting to allow for unsupported devices. - Event-driven architecture for handling Alexa directives. --- ## Alternatives one of the most popular library for controlling esp like devices using alexa is [FauxmoESP]{https://github.com/vintlabs/fauxmoESP} however FauxmoESP works by emulating a light bulb so it is limited in what commands it accepts. --- ## Quick Start ### Installation Download the library as zip or via PlatformIO and include it in your project: ```cpp #include ``` --- ## Creating a Basic Device ### Example: Light Control Here’s how to create a simple device that controls a light: First create an instance of the alexa client and initilize it with your MQTT Credentials ```cpp Alex2ESP alexClient; ``` Credentials can be found at https://alex2mqtt.stormysdream.club/ after logging in with amazon. ```cpp alexClient.begin(ALEXA_USERNAME, ALEXA_PASSWORD, ALEXA_ROOT_TOPIC); ``` Once initilized you can begin to add virtual devices, in this example we add a power controller to toggle a light ```cpp AlexaDevice* device1 = alexClient.getDevice("Test Lamp", "ESP-01"); device1->setDisplayCategory(DisplayCategory::LIGHT); device1->addCapability(AlexaInterfaceType::POWER_CONTROLLER); device1->registerEvent("ReportState", [](const JsonDocument& directive, const AlexaInterfaceType& type) { // Build and send status report device1->buildStatusMessage(directive["header"]["correlationToken"]) .AddHealthProp(EndpointHealth::OK) .AddPowerControllerProp(outputState) .send(); }); // Register event listener for "Event" directive to handle state changes device1->registerEvent("Event", [](const JsonDocument& directive, const AlexaInterfaceType& type) { if (type == AlexaInterfaceType::POWER_CONTROLLER) { if (directive["header"]["name"] == "TurnOn") { outputState = PowerController::ON; Serial.println("Turning ON"); } else if (directive["header"]["name"] == "TurnOff") { outputState = PowerController::OFF; Serial.println("Turning OFF"); } // Send the updated state after change device1->buildStatusMessage(directive["header"]["correlationToken"], true) .AddHealthProp(EndpointHealth::OK) .AddPowerControllerProp(outputState) .send(); } }); ``` --- ### Example: Toggle Controller for Blinds Alex2ESP also supports action mapping so we can map keywords such as "open" and "close" to a toggle controller For a comprehensive list of Alexa actions and mappings, visit the [Alexa Developer Documentation](https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-discovery-objects.html#action-mapping) ```cpp AlexaDevice* device = alexClient.getDevice("Bedroom Blinds", "ESP-01"); device->setDisplayCategory(DisplayCategory::LIGHT); AlexaInterface* toggleController = device->addCapability(AlexaInterfaceType::TOGGLE_CONTROLLER); toggleController->setInstance("ESP-01.Toggle"); toggleController->addFriendlyName("Bedroom Blinds", "en-US"); ActionMapping closeMapping({AlexaActions::Close}, "TurnOn"); ActionMapping openMapping({AlexaActions::Open}, "TurnOff"); toggleController->addActionMapping(closeMapping); toggleController->addActionMapping(openMapping); ``` --- ## 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) --- ## Advanced ussage For devices with limited or partial support, Alex2ESP provides functions that allow you to attach custom JSON objects to the status report. For example, to report the status of a PowerController type, you can use the `AddPowerControllerProp` function. However, if a specific "add props" function does not exist for your use case, you can utilize the `AddContextProp` function to pass a custom JSON object. For instance, to manually report the state of a PowerController, you can use the following code: ```cpp JsonDocument doc; doc["namespace"] = "Alexa.PowerController"; doc["name"] = "powerState"; doc["value"] = "ON"; doc["timeOfSample"] = "{REPLACE_WITH_DATETIME}"; // Alex2MQTT server wil do the replace doc["uncertaintyInMilliseconds"] = 0; AddContextProp(doc.as()) ``` --- ## 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.