{"id":50512768,"url":"https://github.com/tamaygz/esp-wled-projects","last_synced_at":"2026-06-02T21:31:06.974Z","repository":{"id":358341147,"uuid":"1240435206","full_name":"tamaygz/esp-wled-projects","owner":"tamaygz","description":"Mono-repo for DIY WLED lighting projects on ESP32/ESP8266 with Home Assistant, PlatformIO, wiring docs, diagrams, and printable enclosures.","archived":false,"fork":false,"pushed_at":"2026-05-16T21:55:34.000Z","size":4230,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T23:30:59.784Z","etag":null,"topics":["esp32","esp8266","home-assistant","home-automation","iot","kicad","led-controller","neopixel","openscad","platformio","sk6812","wled","ws2812b"],"latest_commit_sha":null,"homepage":null,"language":"OpenSCAD","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/tamaygz.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-16T06:02:22.000Z","updated_at":"2026-05-16T21:25:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tamaygz/esp-wled-projects","commit_stats":null,"previous_names":["tamaygz/esp-wled-projects"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tamaygz/esp-wled-projects","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamaygz%2Fesp-wled-projects","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamaygz%2Fesp-wled-projects/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamaygz%2Fesp-wled-projects/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamaygz%2Fesp-wled-projects/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tamaygz","download_url":"https://codeload.github.com/tamaygz/esp-wled-projects/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tamaygz%2Fesp-wled-projects/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33838215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","esp8266","home-assistant","home-automation","iot","kicad","led-controller","neopixel","openscad","platformio","sk6812","wled","ws2812b"],"created_at":"2026-06-02T21:31:02.562Z","updated_at":"2026-06-02T21:31:06.969Z","avatar_url":"https://github.com/tamaygz.png","language":"OpenSCAD","funding_links":[],"categories":[],"sub_categories":[],"readme":"# esp-wled-projects\n\n\u003e DIY LED lighting projects powered by **WLED** on ESP32 / ESP8266 — fully integrated with Home Assistant.\n\nThis repository has two layers:\n\n- the **meta main folder**, which contains the reusable project system\n- the **project folders**, which contain individual lighting builds\n\nThe meta main folder is there to make new project creation repeatable instead of ad-hoc. It contains the shared `_template/` skeleton, Copilot agents and instructions under `.github/` and `AGENTS.md`, the parts register in [tools/parts-register/parts.json](./tools/parts-register/parts.json), shared generators in [tools/](./tools/), and the integration conventions for WLED, Home Assistant, diagrams, and enclosures. Together, those pieces are meant to help a project consumer move from idea to implementation faster: reuse known parts and pinouts, scaffold the right files, generate diagrams and enclosures consistently, and keep firmware, hardware, and Home Assistant artifacts aligned.\n\nEach actual project folder is then a self-contained build with its own firmware config, wiring docs, power budget, 3D models, and generated diagrams.\n\n## Meta Layer At A Glance\n\nIf you want to create a new project from this repo, the root-level meta layer is the part that helps you.\n\n| Meta asset | What it contains | How it helps when creating a new project |\n|------------|------------------|------------------------------------------|\n| [_template/](./_template/) | Base folder skeleton | Gives every new project the same starting structure and required files |\n| [tools/parts-register/parts.json](./tools/parts-register/parts.json) | Shared parts registry | Reuses known dimensions, electrical facts, and board pinouts instead of re-researching them |\n| [tools/](./tools/) | Shared generators and helpers | Produces diagrams, renders enclosures, and uploads SPIFFS assets consistently |\n| [.github/instructions/](./.github/instructions/) | Scoped Copilot rules | Keeps edits to firmware, hardware, diagrams, and new-project docs aligned with repo conventions |\n| [.github/prompts/](./.github/prompts/) | Reusable slash-command workflows | Speeds up scaffolding, diagram generation, and enclosure generation |\n| [.github/agents/](./.github/agents/) | Planner, reviewer, and hardware-debug agents | Guides planning, real-build debugging, and final coherence checks |\n| [AGENTS.md](./AGENTS.md) and [.github/copilot-instructions.md](./.github/copilot-instructions.md) | Always-on repo guidance | Explains how the meta layer is supposed to be used and what rules always apply |\n\n### How The Meta Layer Helps\n\n1. Start from `_template/` instead of inventing a structure from scratch.\n2. Use the parts register before looking up dimensions, pinouts, or PSU data again.\n3. Let the planner prompt or agent drive the first pass when requirements are still forming.\n4. Generate diagrams and enclosure artifacts from shared tools so outputs stay consistent across projects.\n5. Use the hardware-debug agent when a physical build fails and the fault is still unclear.\n6. Run the reviewer step before considering a new project scaffold or meta change complete.\n\n---\n\n## Ideal Workflow — New Project\n\n### 1 · Plan\n\nUse the **ESP/WLED Project Planner** agent in Copilot chat, or work through these steps manually:\n\n| Step | What to do |\n|------|-----------|\n| Concept | Decide installation type, LED run length, colour capability, sound-reactive? |\n| LED strip | Pick chipset (SK6812 RGBW, WS2812B RGB, WS2811 12 V) based on colour needs and run length |\n| Power budget | `N_leds × 20 mA × channels` + 20 % headroom → select PSU |\n| ESP32 | ESP32-WROOM-32 for most projects; ESP32-S3 for native USB / \u003e3 buses |\n| GPIO plan | Assign data lines to GPIO 16 / 17 / 18; level shifter required (3.3 V → 5 V) |\n| HA effects | Decide if [hacs-wledext-effects](https://github.com/tamaygz/hacs-wledext-effects) is needed for state-driven effects |\n\nStart with [tools/parts-register/parts.json](./tools/parts-register/parts.json) during planning so you can reuse known board, LED strip, PSU, connector, and cutout data before searching the web again.\n\n### 2 · Scaffold\n\n```bash\ncp -r _template/ my-project/\n```\n\nThen fill in order:\n\n1. `specs.md` — concept, requirements, acceptance criteria, **Home Assistant** section\n2. `hardware/bom/bom.md` — parts list + current budget\n3. `hardware/wiring/WIRING.md` — GPIO assignments, power rails, injection points\n4. `gen_diagrams_config.py` — copy from `reefs/`, update values\n5. `firmware/cfg.json` — set unique mDNS hostname: `\"id\": {\"mdns\": \"my-project\"}`\n\nOr use the **`/new-project`** prompt in Copilot chat to scaffold automatically.\n\n### 2.5 · Review The Scaffold\n\nWhen the scaffold or meta-layer update is in place, switch to the **ESP/WLED Project Reviewer** agent or use the planner's review handoff. The review step checks repo-instruction coherence, missing files, register-backed hardware facts, and whether user-facing docs match the current project state.\n\n### 3 · Generate Diagrams\n\n```bash\npython tools/gen_diagrams.py my-project       # all 4 types\npython tools/gen_diagrams.py my-project --type concept   # real-world views only\n```\n\nFour diagram types are produced:\n\n| Type | Output | What it shows |\n|------|--------|---------------|\n| `blocks` | `concept-system.png` | System block: PSU → ESP32 → level shifter → LED strips → HA |\n| `concept` | `concept-side-view.png` · `concept-top-view.png` | Real-world: wall cross-section + floor-plan with lamp positions |\n| `wiring` | `wiring-physical.svg` | Color-coded physical wiring with pin labels |\n| `schematic` | `schematic-*.png` | Electrical schematics (level shifter + power) |\n\nAll outputs land in `my-project/docs/` — never hand-edit them. Or use the **`/gen-diagrams`** prompt in Copilot chat.\n\n### 4 · Generate Enclosure\n\nUse the **`/gen-enclosure`** prompt in Copilot chat, or run the helper directly after the SCAD is in place:\n\n```powershell\npwsh tools/render_enclosure.ps1 -Project my-project -ScadName my-project-enclosure\n```\n\nProduces `my-project/mechanical/enclosure/`:\n\n- `my-project-base.stl`, `my-project-lid.stl` — print-ready\n- `my-project-{base,lid}-{iso,top}.png` — 4 preview PNGs, committed alongside the STLs\n\nLid closure defaults to **snap-on** (no screws). Source of truth: [.github/skills/enclosure-gen/SKILL.md](.github/skills/enclosure-gen/SKILL.md).\n\n### 5 · Build \u0026 Flash\n\n```bash\n# Inside the WLED repo, with firmware/platformio_override.ini alongside platformio.ini:\npio run -e esp32dev_my-project -t upload\n```\n\nFirst boot → connect to `wled-ap` hotspot → configure WiFi credentials via Captive Portal.\n\n### 6 · Connect to Home Assistant\n\n1. Enable native WLED integration: **Settings → Devices \u0026 Services → Add → WLED**\n2. Device auto-discovers via mDNS (`my-project.local`)\n3. Verify light entities appear and on/off / brightness / colour work\n4. (Optional) Install [hacs-wledext-effects](https://github.com/tamaygz/hacs-wledext-effects) for state-driven effects\n\n### 7 · Export \u0026 Commit\n\n```bash\n# Export config from WLED web UI → backup\n# Place files in firmware/cfg.json and design/effects/presets.json\ngit add .\ngit commit -m \"feat(my-project): initial project setup\"\n```\n\n---\n\n## Project Folder Convention\n\n```\n[project]/\n├── firmware/               # platformio_override.ini, cfg.json, presets.json\n├── hardware/\n│   ├── wiring/             # KiCad schematics, wiring notes, PDFs\n│   ├── pcb/                # KiCad PCB files, Gerbers\n│   └── bom/                # bom.md — parts list + power budget\n├── mechanical/\n│   └── enclosure/          # YAPP_Box SCAD + STLs + preview PNGs + print settings\n├── design/\n│   ├── led-map/            # 2D pixel maps, segment plans\n│   └── effects/            # WLED presets.json, palettes, ha-automations.yaml\n├── docs/                   # Auto-generated diagrams (PNG/SVG) — do not hand-edit\n├── gen_diagrams.py         # Diagram script — imports from tools/diagram_gen\n├── gen_diagrams_config.py  # DIAGRAM_CONFIG dict for this project\n└── specs.md                # Project PRD / spec sheet\n```\n\nSee [_template/](./_template/) for a ready-to-copy skeleton.\n\n---\n\n## AI Agent Support\n\nThis repo is configured for GitHub Copilot (VS Code Insiders) and GitHub cloud agents.\n\n| Customization | What it does |\n|-----------|-------------|\n| Always-on instructions | `.github/copilot-instructions.md` — full project conventions |\n| `AGENTS.md` | Root agent guidance shared across coding agents |\n| `firmware.instructions.md` | Auto-loaded when editing `platformio_override.ini`, `cfg.json` |\n| `hardware.instructions.md` | Auto-loaded when editing wiring / BOM / PCB files |\n| `new-project.instructions.md` | Auto-loaded when editing `specs.md` or `_template/` |\n| `diagram-gen.instructions.md` | Auto-loaded when editing diagram generators or `docs/` |\n| `/new-project` prompt | Scaffolds a full project folder from `_template/` |\n| `/gen-diagrams` prompt | Runs `tools/gen_diagrams.py` with validation |\n| `/gen-enclosure` prompt | Generates YAPP_Box SCAD + renders STLs and preview PNGs |\n| `ESP/WLED Project Planner` custom agent | Guided planning: requirements → LED → power → GPIO → HA → scaffold |\n| `ESP/WLED Project Reviewer` custom agent | Reviews scaffold/meta coherence, upgrades docs, and checks current customization conventions |\n| `ESP/WLED Realworld Hardware Debug` custom agent | Step-by-step real build triage: captures actual hardware, checks wiring/power/config assumptions, compares against project definitions, and guides the next diagnostic step |\n| `enclosure-gen` skill | Reusable enclosure reference and YAPP_Box workflow support |\n| `.github/hooks/README.md` | Documents the repo hook policy and recommended first deterministic hook use cases |\n\n### How To Use The Agents\n\n- Use **ESP/WLED Project Planner** when you are starting a new build or the requirements are still vague. Give it the project idea, LED goals, installation constraints, and Home Assistant expectations.\n- Use **ESP/WLED Project Reviewer** after scaffolding or broad meta changes. It is the cleanup and coherence pass that checks missing files, instruction drift, register-backed facts, and doc completeness.\n- Use **ESP/WLED Realworld Hardware Debug** when a physical setup is not working and you do not yet know whether the problem is power, wiring, GPIO choice, firmware config, part substitution, or Home Assistant. Start it with the project name and a symptom such as `reefs flickers`, `curtaincinemalights no Wi-Fi`, or `something isn't working`.\n- Let the agents hand off where appropriate: planner for build definition, hardware-debug for real-world triage, reviewer for final doc and meta alignment.\n\n### Which Doc To Read\n\n| If you need to understand... | Read this first |\n|------------------------------|-----------------|\n| what this repo is and how the meta layer helps | [README.md](./README.md) |\n| how an agent should behave in this repo | [AGENTS.md](./AGENTS.md) |\n| the full always-on repo conventions | [.github/copilot-instructions.md](./.github/copilot-instructions.md) |\n| file-specific editing rules | [.github/instructions/](./.github/instructions/) |\n| the parts register schema and sourcing rules | [tools/parts-register/README.md](./tools/parts-register/README.md) |\n| hook policy and whether a hook should exist at all | [.github/hooks/README.md](./.github/hooks/README.md) |\n\n### Working In VS Code Insiders\n\n- Run `Chat: Open Customizations` to manage prompts, instructions, skills, agents, hooks, and plugins.\n- Type `/agents`, `/prompts`, `/instructions`, `/skills`, or `/hooks` in chat for quick entry to the relevant customization UI.\n- Use Chat diagnostics to inspect which customizations loaded and to catch metadata issues quickly.\n- If you open only a project subfolder instead of the repo root, enable `chat.useCustomizationsInParentRepositories` so these root-level customizations are discovered.\n- When an agent needs input for an important choice, it should use the VS Code structured ask-question flow with suggested options and free-form input enabled.\n- Prefer planner → reviewer handoffs for guided workflows; use hooks only for deterministic automation such as validation or policy enforcement.\n\n---\n\n## Common Tools\n\n| Tool | Purpose | Link |\n|------|---------|------|\n| WLED web installer | Flash pre-built firmware | https://install.wled.me |\n| WLED custom build | Online build with usermods | https://wled-compile.github.io |\n| KiCad | Schematic / PCB | https://kicad.org |\n| OpenSCAD | Parametric 3D models (enclosure rendering) | https://openscad.org |\n| YAPP_Box v3 | Parametric box generator (shared at `tools/yapp/`) | https://github.com/mrWheel/YAPP_Box |\n| PlatformIO | Build \u0026 flash from source | https://platformio.org |\n| hacs-wledext-effects | State-driven HA effects | https://github.com/tamaygz/hacs-wledext-effects |\n| WLED-MM (MoonModules) | Sound-reactive fork | https://github.com/MoonModules/WLED-MM |\n| LedFX | PC-based audio reactive | https://ledfx.app |\n\n---\n\n## Resources\n\n- [WLED Docs](https://kno.wled.ge) — official documentation\n- [WLED GitHub](https://github.com/wled/WLED)\n- [r/WLED](https://reddit.com/r/WLED)\n- [WLED Discord](https://discord.gg/QAh7wJHrRM)\n- [QuinLED](https://quinled.info) — WLED-dedicated hardware\n\n---\n\n## Included Projects\n\nI built this repo mostly for myself as a structured workspace for planning, building, documenting, and reusing WLED-based lighting projects. The projects currently included are:\n\n| Project | Status | LEDs | Controller | Description |\n|---------|--------|------|------------|-------------|\n| [reefs](./reefs/) | wip | SK6812 RGBW 60/m × 2 | ESP32-WROOM-32 | Driftwood ambient lamps, Home Assistant integrated |\n| [curtaincinemalights](./curtaincinemalights/) | wip | SK6812 RGBW 60/m, ~180 LEDs · 3 m | ESP8266 D1 Mini | Cinema curtain LED sync — center-fill mirrors curtain position, State Sync + Chase + Breathe via hacs-wledext-effects |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftamaygz%2Fesp-wled-projects","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftamaygz%2Fesp-wled-projects","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftamaygz%2Fesp-wled-projects/lists"}