https://github.com/bsodium/esp-string-lights
MQTT-enabled controller for string lights, designed for ESP32
https://github.com/bsodium/esp-string-lights
esp32 mqtt openhabian platformio
Last synced: 8 months ago
JSON representation
MQTT-enabled controller for string lights, designed for ESP32
- Host: GitHub
- URL: https://github.com/bsodium/esp-string-lights
- Owner: BSoDium
- Created: 2025-02-19T01:23:10.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-02-19T10:38:38.000Z (8 months ago)
- Last Synced: 2025-02-19T11:22:27.549Z (8 months ago)
- Topics: esp32, mqtt, openhabian, platformio
- Language: C++
- Homepage:
- Size: 12.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ESP32 String Lights Controller
MQTT-enabled controller for string lights with multiple effects, designed for ESP32.
## Features
- MQTT control integration
- Physical button control
- Multiple lighting effects
- Persistent state across power cycles
- HomeAssistant compatible
## Hardware Setup
- ESP32 development board
- Relay module (connected to pin 16)
- Push button (connected to pin 2)
- Transistor for effect control (base connected to pin 4)
- LED string lights (connected through relay)
### Wiring Diagram
```mermaid
graph LR
subgraph Controller board
subgraph ESP32
H([fa:fa-minus Common GND]) -->|GND| A[fa:fa-microchip ESP32]
A -->|3.3V| I([fa:fa-plus Common 3.3V])
end
A -->|Pin 16| B[fa:fa-toggle-off Relay]
B -->|GND| H
I -->|3.3V| B
C[fa:fa-circle-dot Button] -->|Pin 2| A
I -->|3.3V| C
A -->|Pin 4 - Base| D[fa:fa-toggle-off Transistor]
G[fa:fa-bolt HI-Link power adapter] -->|3.3V| I
H -->|GND| G
end
subgraph Original controller board
D -->|GND - Emitter| E[fa:fa-lightbulb String lights]
E -->|≈ 3.3V - Collector| D
E -->|GND| A
F([fa:fa-plug 220V AC power]) ==>|Live 220V| B
B ==>|Live 220V| E
E ==>|Neutral| F
F ==>|Live 220V| G
G ==>|Neutral| F
end
linkStyle 1 stroke: red
linkStyle 2 stroke: yellow
linkStyle 4 stroke: red
linkStyle 5 stroke: yellow
linkStyle 6 stroke: red
linkStyle 7 stroke: yellow
linkStyle 11 stroke: red
linkStyle 13 stroke: #926243, stroke-width:4px
linkStyle 14 stroke: #926243, stroke-width:4px
linkStyle 15 stroke: #016FDE, stroke-width:4px
linkStyle 16 stroke: #926243, stroke-width:4px
linkStyle 17 stroke: #016FDE, stroke-width:4px
```
## Software Configuration
1. Copy `src/config.h.template` to `src/config.h`
2. Edit `src/config.h` with your credentials:
```cpp
const char *ssid = "YOUR_WIFI_SSID";
const char *password = "YOUR_WIFI_PASSWORD";
const char *mqtt_server = "YOUR_MQTT_SERVER";
```
## MQTT Topics
- `home/livingroom/string-light` - Power control (ON/OFF)
- `home/livingroom/string-light/effect` - Effect control
### Available Effects
- IN_WAVES
- SEQUENTIAL
- SLO_GLO
- CHASING
- FADE
- TWINKLE
- STATIC
- COMBINATION
## Operation
### Physical Control
- Short press button: Cycle through effects
- Light indicates effect change through blink patterns
### MQTT Control
- Send "ON"/"OFF" to power topic
- Send effect name to effect topic
## Flowchart
```mermaid
flowchart
subgraph Initialization
Start@{ shape: sm-circ, label: "Start" }
A[Connect to WiFi]
B[Connect to MQTT]
C[Subscribe to topics]
end
subgraph Main Loop
E{MQTT }
D{Button press}
F[Update effect]
G[Update power state]
H[Update lights]
end
Start --> A
A -->|Success| B
B -->|Success| C
C -->|Success| E
E -->|Effect message| F
F -->|Update effect| H
E -->|Power message| G
G -->|Update power| H
E -->|Disconnected| B
E -->|No message| D
D -->|Yes| F
D -->|No| E
H -->|Success| D
```
## Development
Built using PlatformIO. Main components:
- WiFi connection management
- MQTT client for remote control
- Effect cycling logic
- Hardware interrupt handling
### Building
1. Install PlatformIO
2. Configure credentials in `src/config.h`
3. Build and upload:
```bash
pio run -t upload
```
## Troubleshooting
1. **No MQTT Connection**
- Check MQTT server address
- Verify WiFi credentials
- ESP32 will attempt 10 reconnections
2. **Effect Not Changing**
- Verify transistor connections
- Check effect name spelling in MQTT messages
- Monitor serial output for debugging
## Security Note
`config.h` is gitignored to prevent credential leaks. Always use the template file as reference and keep your credentials secure.