LumiESP

LumiESP is a project utilizing an ESP32 microcontroller to control an LED strip via MQTT. It is designed for easy customization and extension, enabling the creation of custom modes and settings. The included Makefile streamlines PlatformIO commands for building, uploading, and monitoring the code.

Note: This project is still in development and may contain bugs or incomplete features. Please report any issues you encounter.

What is the ESP32 and MQTT?

The ESP32 is a versatile, low-cost microcontroller with built-in Wi-Fi and Bluetooth capabilities, making it ideal for IoT (Internet of Things) projects. It allows devices to connect to the internet and communicate wirelessly. MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for small sensors and mobile devices. It enables efficient communication between devices by sending and receiving messages over a network.

Features

• Control LED strips using the ESP32 over MQTT (e.g., LED strips like WS2812, WS2812B, WS2813, etc.)
• Customizable settings for LED strips, such as brightness and color and custom modes
• Simplified build, upload, and monitoring process using PlatformIO commands
• Ability to define custom modes and settings for the LED strips

Requirements

• ESP32 microcontroller (e.g., ESP32 Dev Module)
• PlatformIO installed on your system or simply use this nix-shell
• LED strip (e.g., WS2812, WS2812B, WS2813)
• MQTT broker (e.g., Mosquitto)

Installation

1. Install PlatformIO

PlatformIO is a cross-platform code builder and the easiest way to manage your embedded software environment. To install PlatformIO, follow the official instructions found here.

Note: If you are using NixOS, you can use the provided shell.nix file to enter a shell with PlatformIO installed.

2. Clone the Repository

Clone the LumiESP project repository to your local machine:

git clone https://github.com/friedjof/lumiESP.git
cd LumiESP

3. Build, Upload, and Monitor

The project includes a Makefile that simplifies the use of PlatformIO commands. Make sure to edit the variables in the Makefile according to your setup.

Note: You have to copy the config/config.h-template to config/config.h and fill in the necessary information. You can also use the setup.py script to do this for you (run python setup.py or make setup).

Variables

• PORT: Serial port of your ESP32 (e.g., /dev/ttyUSB0).
• BOARD: The type of ESP32 board (e.g., esp32dev).
• SPEED: Baud rate for the serial monitor (e.g., 115200).

Development Environment

You can run a mosquitto MQTT broker locally on your machine for testing. To run the MQTT broker using Docker, follow these steps:

Note: Make sure you have Docker installed on your system and you are in the root directory of this project.

Setup the username and password for the MQTT broker (replace <username> with your desired username e.g., esp):

docker run -it -v ./mosquitto/config:/mosquitto/config eclipse-mosquitto mosquitto_passwd -c /mosquitto/config/password.txt <username>

Start the MQTT broker

docker compose up -d

Makefile

• Build the project: make build
• Upload the code to the ESP32: make upload
• Monitor the serial output: make monitor
• Clean the build files: make clean
• Setup the repository: make setup
• Clean, build, flash, and open the serial monitor: make flash
• print the help message: make help

MQTT Topics

LumiESP
├── LumiESP     // this defines the system topic
│   ├── sub
│   │   ├── status     // the system status
│   │   ├── datetime   // the current date and time
│   │   ├── log        // the log message
│   │   ├── level      // the log level
│   │   └── mode       // the current mode
│   └── pub
│       └── mode       // set the new mode
├── StaticMode  // this is a basic mode that sets the LED strip to a static color
│   ├── sub
│   │   ├── brightness // the current brightness
│   │   └── hex        // the current color in hex format
│   └── pub
│       ├── brightness // set the new brightness
│       └── hex        // set the new color in hex format
…

Note: The system topic is used to publish and subscribe to system-related information, such as the current mode, status, and log messages. The other topics are used to control the LED strip and define custom modes.

Define your own custom modes

Dokumentation is coming soon (e.g. see the StaticMode for an example).

Services and classes

• ClockService: Provides timekeeping functionality (including NTP synchronization).
• LoggingService: Logs messages to the serial monitor and MQTT.
• MQTTService: Handles MQTT communication with the broker.
• LedService: Controls the LED strip using PWM signals.
• ControllerService: Manages tasks and schedules for the ESP32.

Troubleshooting

• Make sure the correct port is selected in the Makefile.
• Ensure PlatformIO is installed correctly by checking the installation instructions linked above.

Acknowledgements

• PlatformIO for providing a versatile environment for embedded development.
• MQTT protocol for enabling efficient communication between devices.

Author

• Friedjof Noweck