{"id":25530846,"url":"https://github.com/bsodium/esp-string-lights","last_synced_at":"2026-04-14T04:32:02.376Z","repository":{"id":278356303,"uuid":"935145774","full_name":"BSoDium/esp-string-lights","owner":"BSoDium","description":"MQTT-enabled controller for string lights, designed for ESP32","archived":false,"fork":false,"pushed_at":"2025-02-19T10:38:38.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-19T11:22:27.549Z","etag":null,"topics":["esp32","mqtt","openhabian","platformio"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BSoDium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-19T01:23:10.000Z","updated_at":"2025-02-19T10:38:41.000Z","dependencies_parsed_at":"2025-02-19T11:33:25.263Z","dependency_job_id":null,"html_url":"https://github.com/BSoDium/esp-string-lights","commit_stats":null,"previous_names":["bsodium/esp-string-lights"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BSoDium%2Fesp-string-lights","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BSoDium%2Fesp-string-lights/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BSoDium%2Fesp-string-lights/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BSoDium%2Fesp-string-lights/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BSoDium","download_url":"https://codeload.github.com/BSoDium/esp-string-lights/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239753997,"owners_count":19691225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","mqtt","openhabian","platformio"],"created_at":"2025-02-20T00:22:20.759Z","updated_at":"2026-01-16T00:30:16.090Z","avatar_url":"https://github.com/BSoDium.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP32 String Lights Controller\n\nMQTT-enabled controller for string lights with multiple effects, designed for ESP32.\n\n## Features\n\n- MQTT control integration\n- Physical button control\n- Multiple lighting effects\n- Persistent state across power cycles\n- HomeAssistant compatible\n\n## Hardware Setup\n\n- ESP32 development board\n- Relay module (connected to pin 16)\n- Push button (connected to pin 2)\n- Transistor for effect control (base connected to pin 4)\n- LED string lights (connected through relay)\n\n### Wiring Diagram\n\n```mermaid\ngraph LR\n    subgraph Controller board\n      subgraph ESP32\n        H([fa:fa-minus \u0026nbsp;Common GND]) --\u003e|GND| A[fa:fa-microchip \u0026nbsp;ESP32]\n        A --\u003e|3.3V| I([fa:fa-plus \u0026nbsp;Common 3.3V])\n      end\n\n      A --\u003e|Pin 16| B[fa:fa-toggle-off \u0026nbsp;Relay]\n      B --\u003e|GND| H\n      I --\u003e|3.3V| B\n      C[fa:fa-circle-dot \u0026nbsp;Button] --\u003e|Pin 2| A\n      I --\u003e|3.3V| C\n      A --\u003e|Pin 4 - Base| D[fa:fa-toggle-off \u0026nbsp;Transistor]\n      G[fa:fa-bolt \u0026nbsp;HI-Link power adapter] --\u003e|3.3V| I\n      H --\u003e|GND| G\n    end\n\n    subgraph Original controller board\n      D --\u003e|GND - Emitter| E[fa:fa-lightbulb \u0026nbsp;String lights]\n      E --\u003e|≈ 3.3V - Collector| D\n      E --\u003e|GND| A\n\n      F([fa:fa-plug \u0026nbsp;220V AC power]) ==\u003e|Live 220V| B\n      B ==\u003e|Live 220V| E\n      E ==\u003e|Neutral| F\n      F ==\u003e|Live 220V| G\n      G ==\u003e|Neutral| F\n    end\n\n    linkStyle 1 stroke: red\n    linkStyle 2 stroke: yellow\n    linkStyle 4 stroke: red\n    linkStyle 5 stroke: yellow\n    linkStyle 6 stroke: red\n    linkStyle 7 stroke: yellow\n    linkStyle 11 stroke: red\n    linkStyle 13 stroke: #926243, stroke-width:4px\n    linkStyle 14 stroke: #926243, stroke-width:4px\n    linkStyle 15 stroke: #016FDE, stroke-width:4px\n    linkStyle 16 stroke: #926243, stroke-width:4px\n    linkStyle 17 stroke: #016FDE, stroke-width:4px\n```\n\n## Software Configuration\n\n1. Copy `src/config.h.template` to `src/config.h`\n2. Edit `src/config.h` with your credentials:\n   ```cpp\n   const char *ssid = \"YOUR_WIFI_SSID\";\n   const char *password = \"YOUR_WIFI_PASSWORD\";\n   const char *mqtt_server = \"YOUR_MQTT_SERVER\";\n   ```\n\n## MQTT Topics\n\n- `home/livingroom/string-light` - Power control (ON/OFF)\n- `home/livingroom/string-light/effect` - Effect control\n\n### Available Effects\n\n- IN_WAVES\n- SEQUENTIAL\n- SLO_GLO\n- CHASING\n- FADE\n- TWINKLE\n- STATIC\n- COMBINATION\n\n## Operation\n\n### Physical Control\n- Short press button: Cycle through effects\n- Light indicates effect change through blink patterns\n\n### MQTT Control\n- Send \"ON\"/\"OFF\" to power topic\n- Send effect name to effect topic\n\n## Flowchart\n\n```mermaid\nflowchart\n\n  subgraph Initialization\n    Start@{ shape: sm-circ, label: \"Start\" }\n    A[Connect to WiFi]\n    B[Connect to MQTT]\n    C[Subscribe to topics]\n  end\n\n\n  subgraph Main Loop\n    E{MQTT }\n    D{Button press}\n    F[Update effect]\n    G[Update power state]\n    H[Update lights]\n  end\n\n  Start --\u003e A\n  A --\u003e|Success| B\n  B --\u003e|Success| C\n  C --\u003e|Success| E\n\n  E --\u003e|Effect message| F\n  F --\u003e|Update effect| H\n  \n  E --\u003e|Power message| G\n  G --\u003e|Update power| H\n  E --\u003e|Disconnected| B\n  E --\u003e|No message| D\n  \n  D --\u003e|Yes| F\n  D --\u003e|No| E\n  \n  H --\u003e|Success| D\n```\n\n## Development\n\nBuilt using PlatformIO. Main components:\n- WiFi connection management\n- MQTT client for remote control\n- Effect cycling logic\n- Hardware interrupt handling\n\n### Building\n\n1. Install PlatformIO\n2. Configure credentials in `src/config.h`\n3. Build and upload:\n   ```bash\n   pio run -t upload\n   ```\n\n## Troubleshooting\n\n1. **No MQTT Connection**\n   - Check MQTT server address\n   - Verify WiFi credentials\n   - ESP32 will attempt 10 reconnections\n\n2. **Effect Not Changing**\n   - Verify transistor connections\n   - Check effect name spelling in MQTT messages\n   - Monitor serial output for debugging\n\n## Security Note\n\n`config.h` is gitignored to prevent credential leaks. Always use the template file as reference and keep your credentials secure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsodium%2Fesp-string-lights","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbsodium%2Fesp-string-lights","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsodium%2Fesp-string-lights/lists"}