WLEDwiki/MQTT.md

40 lines
2.3 KiB
Markdown
Raw Normal View History

2020-05-28 14:39:07 +02:00
**Notice:** The MQTT implementation is currently being **restructured** to provide a better experience for users of Home Assistant and other automation software. **This will be a breaking change**. For details regarding the rework, please see [#207](https://github.com/Aircoookie/WLED/issues/207)!
2019-08-31 01:06:05 +02:00
2018-10-02 10:38:54 +02:00
WLED versions from 0.8.0 up are able to connect to an MQTT broker for smart home control.
Connection to both domains and IP servers is supported on port 1883.
2018-12-18 11:46:43 +01:00
Secure connections are not currently supported. I recommend only connecting to local MQTT brokers.
2020-05-28 14:41:49 +02:00
In v0.8.4-0.8.6 only, WLED supports MQTT autodiscovery by the HomeAssistant software. This has been removed because of bootloop issues and in favor of the native HomeAssistant integration.
2018-12-18 11:46:43 +01:00
2018-10-02 10:38:54 +02:00
WLED will subscribe to up to six topics to change the state of the lights.
2018-10-03 21:06:00 +02:00
- **[mqttDeviceTopic]**\
2018-10-02 10:38:54 +02:00
-> Send brightness as ASCII number 0-255 or the strings "ON", "OFF", and "T" (for toggle)
2018-10-03 21:06:00 +02:00
- **[mqttDeviceTopic]/col**\
2018-10-02 10:44:51 +02:00
-> Send color as HEX (#WWRRGGBB or #RRGGBB) or 32bit DEC. Hex has '#','h' or 'H' as prefix.
2018-10-03 21:06:00 +02:00
- **[mqttDeviceTopic]/api**\
2019-04-10 12:23:57 +02:00
-> Send an API call (using the [HTTP API](https://github.com/Aircoookie/WLED/wiki/HTTP-request-API) syntax). You may omit the "win" and just send e.g. "FX=73"
2018-10-02 10:38:54 +02:00
2018-10-03 21:06:00 +02:00
- **[mqttGroupTopic]**
- **[mqttGroupTopic]/col**
- **[mqttGroupTopic]/api**
2018-10-02 10:38:54 +02:00
2019-04-10 12:23:57 +02:00
The topic paths [mqttDeviceTopic] and [mqttGroupTopic] are customizable in Sync settings.
2018-10-03 21:06:00 +02:00
If [mqttGroupTopic] is left empty, it will not subscribe to anything. An empty [mqttDeviceTopic] will instead be replaced with the default "wled/macaddr".
[mqttDeviceTopic] is intended to be unique to one WLED device and just control that device.
[mqttGroupTopic] is intended to control a group of or all WLED devices.
2018-10-03 12:34:00 +02:00
2019-03-25 16:08:26 +01:00
UDP notifications will be sent just as if the change was done via the UI or HTTP API.
2018-10-02 10:38:54 +02:00
2019-03-25 16:08:26 +01:00
Additionally, on light change, WLED will publish to 3 topics for MQTT clients to query the state of the light.
2018-10-02 10:38:54 +02:00
2018-10-03 21:06:00 +02:00
- **[mqttDeviceTopic]/g**\
2018-10-02 10:38:54 +02:00
-> Contains current brightness as ASCII number 0-255
2018-10-03 21:06:00 +02:00
- **[mqttDeviceTopic]/c**\
2018-10-02 10:47:41 +02:00
-> Contains current color as HEX (#RRGGBB if white is 0, else #WWRRGGBB)
2019-03-25 16:08:26 +01:00
- **[mqttDeviceTopic]/v**\
-> Contains XML API response (same as HTTP API)
2020-05-28 14:41:49 +02:00
There is support for client ID and authentication, but this is presently transmitted over an unencrypted connection, so please **do not** use the same password for other services.