This project is a user interface for controlling LEDs using MQTT (Message Queuing Telemetry Transport) protocol. It allows users to remotely control the state and color of LEDs connected to an MQTT broker.
This project is designed to work with the following ESP-32 LED controller: https://github.com/GitSoks/esp32_led_strip_mqtt_client
- MQTT LED Controller GUI
The MQTT LED Controller UI is a web-based application built with Python. It provides a user-friendly interface for controlling LEDs connected to an MQTT broker.
- Connect to an MQTT broker and subscribe to LED control topics.
- Display the current state and color of the LEDs.
- Allow users to toggle the state of the LEDs (on/off).
- Allow users to change the color of the LEDs using a color picker.
- Publish MQTT messages to control the LEDs.
- Automatic and dynamic UI updates based on MQTT messages and connected devices.
- List connected devices and allow users to select a device to control.
- Option to Dockerize the application with an included MQTT broker.
showcase_video_compressed.mp4
The following diagrams show an example of how the MQTT LED Controller UI can be used to control LEDs connected to an MQTT broker.
The MQTT LED Controller UI communicates with the ESP-32 LED controllers using MQTT messages. The ESP-32 LED controllers subscribe to the LED control topic and publish LED state updates to the MQTT broker. The MQTT LED Controller UI subscribes to the LED state topic and publishes LED control messages to the MQTT broker. The following diagram illustrates the communication flow between the MQTT LED Controller UI, the MQTT broker, and the ESP-32 LED controllers. It also shows how the MQTT LED Controller UI can be used to control multiple devices and users, and how the UI updates dynamically based on MQTT messages.
graph LR;
gui[["MQTT LED Controller GUI
(Docker Container)"]] -. mqtt: LED cmd .->
broker[["MQTT Broker
(Mosquitto Docker Container)"]];
broker -- mqtt: LED cmd---> esp1["ESP-32 LED Controller"];
subgraph Device 2
esp2 ==> led2[/WS2812B LED Strip/]
end
subgraph Device 1
esp1 ==> led1[/WS2812B LED Strip/]
end
esp1 -- mqtt: LED stat --> broker;
broker -- mqtt: LED cmd---> esp2["ESP-32 LED Controller"];
esp2 -- mqtt: LED stat --> broker;
subgraph "Server (docker compose up)"
broker -. mqtt: LED stat .-> gui;
end
user1["User 1
(Webbrowser)"] <-- http--> gui;
user2["User 2
(Webbrowser)"] <-- http--> gui;
style broker fill:#275edd ,stroke:#333,stroke-width:4px
style user1 stroke:orange,stroke-width:4px
style user2 stroke:orange,stroke-width:4px
style gui fill:#4627dd ,stroke:#333,stroke-width:4px
Take a look at the requirements.txt file for all dependencies.
The following third party Python packages are used in this project:
You may also need to install docker and docker-compose on your machine to run the docker-compose.yaml file and the included MQTT broker.
(skip this step if you want to use the GUI in a local python environment)
-
Clone the repository:
git clone https://github.com/your-username/mqtt-led-controller-ui.git
-
install docker on your machine
-
compose up the docker compose file (docker-compose.yaml):
docker compose up
-
Open the application in your web browser:
http://localhost:8080
-
Clone the repository:
git clone https://github.com/your-username/mqtt-led-controller-ui.git
-
install python (>= 3.10)
-
Install all python dependencies
pip install -r requirements.txt
-
Start the application:
python mqtt_led_controller_ui/main.py
-
Open the application in your web browser:
http://localhost:8080
The MQTT LED Controller UI can be configured by modifying the settings.py file. This file contains the following settings:
mqttBrokerUrl: The URL of the MQTT broker.mqttUsername: The username for connecting to the MQTT broker (optional).mqttPassword: The password for connecting to the MQTT broker (optional).ledStateTopic: The MQTT topic for subscribing to LED state updates.ledColorTopic: The MQTT topic for subscribing to LED color updates.ledControlTopic: The MQTT topic for publishing LED control messages.
-
Launch the application in your web browser.
-
Connect to the MQTT broker by entering the required credentials.
-
Once connected, the application will display the current state and color of the LEDs.
-
Toggle the state of the LEDs by clicking the "On" or "Off" button.
-
Change the color of the LEDs by selecting a color from the color picker.
-
The application will publish MQTT messages to control the LEDs based on user actions.
flowchart LR
A[("main.py")] == Initializes and orchestrates ==> B[("device_manager.py")] & C[("mqtt_controller.py")] & D[("ui_elements.py")]
B -- Defines --> E["DeviceManager"]
C -- Defines --> F["MQTTController"]
D -- Defines --> G["UI Elements"]
E -. Manages .-> H{{"Device"}}
F -. Handles .-> I{{"MQTT Client"}}
G -. Creates and manages .-> J{{"User Interface"}}
A:::main
B:::main
C:::main
D:::main
E:::sub
F:::sub
G:::sub
Here are some resources that I found helpful while working on this project:
- NiceGui - A Python library for building web-based GUIs.
- Mosquitto - An open source MQTT broker.
- MQTT Explorer - A useful tool for exploring MQTT brokers.
- MQTT Essentials - A great introduction to MQTT.
- Paho MQTT - A Python MQTT client library.
- docker-compose - A tool for defining and running multi-container Docker applications.
David - GitSoks on GitHub
Project Link: https://github.com/GitSoks/mqtt-led-controller-ui