Steps to Configure Your Account

1. Install the Alex2MQTT skill and link it to your Amazon account.
2. Visit /mqtt_credentials to retrieve your MQTT username, password, and root topic.

Connecting to MQTT

Once you have the MQTT credentials, you can connect to the server using any standard MQTT client and listen for events. Most MQTT events are sent directly from Amazon's API to ensure compatibility with the latest devices.

Additional Resources

For more information on specific device payloads, refer to Amazon's device APIs documentation.

Discovery Topic

Alex2MQTT includes a discover topic: mqtt://alex2mqtt.stormysdream.club/{root topic}/discover. When Alexa starts the discovery process, a payload is sent:

{
    "namespace": "Alexa.Discovery",
    "name": "Discover",
    "payloadVersion": "3"
}
            

When a discovery payload is received, every device has 2 seconds to respond with a discovery packet. An example response looks like the following sent to the topic discover_r:

{
    "endpointId": "sample-bulb-01",
    "manufacturerName": "Smart Device Company",
    "friendlyName": "Livingroom lamp",
    "description": "Virtual smart light bulb",
    "displayCategories": ["LIGHT"],
    "additionalAttributes": {
        "manufacturer": "Sample Manufacturer",
        "model": "Sample Model",
        "serialNumber": "U11112233456",
        "firmwareVersion": "1.24.2546",
        "softwareVersion": "1.036",
        "customIdentifier": "Sample custom ID"
    },
    "cookie": {
        "key1": "arbitrary key/value pairs for skill to reference this endpoint."
    },
    "capabilities": [
        {
            "interface": "Alexa.PowerController",
            "version": "3",
            "type": "AlexaInterface",
            "properties": {
                "supported": [
                    {
                        "name": "powerState"
                    }
                ],
                "retrievable": true
            }
        }
    ]
}
            

The discovery packet comes from the Alexa API. Anything supported by the v3 Alexa interface SHOULD be supported via this skill. For more details, check out the Alexa Discovery Documentation.

Reporting State

The following example shows an Alexa.ReportState directive sent by Alexa to your device on the topic mqtt://alex2mqtt.stormysdream.club/{root topic}/{endpoint Id}/alexaDirective:

{
    "directive": {
        "header": {
            "namespace": "Alexa",
            "name": "ReportState",
            "messageId": "unique-identifier",
            "correlationToken": "correlation-token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "cookie": {}
        },
        "payload": {}
    }
}
            

When a state report is requested, the following example response is expected on the topic mqtt://alex2mqtt.stormysdream.club/{root topic}/{endpoint Id}/alexaResponse:

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "unique-identifier",
            "correlationToken": "correlation-token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "endpointId": ""
        },
        "payload": {}
    },
    "context": {
        "properties": [
            {
                "namespace": "Alexa.PowerController",
                "name": "powerState",
                "value": "OFF",
                "timeOfSample": "2022-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2022-02-03T16:20:00.00Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}
            

For more information on what to include in the response message, check out the Alexa State Report Documentation.

Example Code

For example code demonstrating basic functionality, check out our Example Light Code.