WLED Projects & Hardware Development

A comprehensive workspace for WLED controller projects, custom hardware development, and ESP RainMaker integration.

Latest Update (v2.1.0): Added API and Firmware Development guides - See Changelog

Related Project: POI-LED - Performance props, visual LED art, and portable battery-powered LED controllers

Directory Structure

WLed/
├── projects/               # WLED project implementations
│   ├── wled-controllers/  # Standard WLED controller builds
│   ├── custom-builds/     # Custom firmware modifications
│   └── experimental/      # Experimental features and prototypes
│
├── hardware/              # Hardware design files
│   ├── schematics/       # Circuit schematics
│   ├── pcb-designs/      # PCB layout files
│   ├── bom/              # Bill of Materials
│   └── datasheets/       # Component datasheets
│
├── docs/                  # Documentation
│   ├── guides/           # Step-by-step guides
│   ├── api/              # API documentation
│   └── troubleshooting/  # Common issues and solutions
│
├── firmware/              # Firmware development
│   └── libraries/        # Custom libraries
│
├── integrations/          # Third-party integrations
│   └── rainmaker/        # ESP RainMaker integration
│
└── resources/            # Additional resources
    ├── images/           # Images and diagrams
    ├── videos/           # Video tutorials
    └── references/       # Reference materials

Quick Start

1. WLED Projects

Navigate to projects/ to find or create WLED controller projects:

• wled-controllers/: Production-ready controller implementations
• custom-builds/: Modified WLED firmware with custom features
• experimental/: Testing new features and concepts

2. Hardware Development

All hardware-related files are in hardware/:

• Design schematics in schematics/
• PCB layouts in pcb-designs/
• Component lists in bom/
• Reference datasheets in datasheets/

3. Rainmaker Integration

See integrations/rainmaker/ for the complete guide on integrating WLED with ESP RainMaker.

Documentation

Essential Guides

Getting Started:

• Quick Start Guide - Get started quickly
• Build System Guide - Multi-configuration build system
• Project Setup Guide - Organize your projects

Hardware & Components:

• Hardware Review Checklist - MANDATORY verification before modifying any hardware docs
• Power Supply Selection Guide - Choose the right power supply
• Wire Selection Guide - Choose the right wire for your project
• LED Type Selection Guide - Compare and select LED types (WS2811, WS2812B, WS2815, etc.)
• Level Shifter Guide - Interface ESP32 (3.3V) with LEDs (5V)
• Fuse Selection Guide - Protect your projects with proper fusing
• Hardware Development Guide - Design custom controllers

Sensors & Integration:

• Sensor Integration Guide - PIR, light sensors, microphones, temperature sensors
• Optional Components Guide - Buttons, encoders, displays, IR remotes

Application-Specific:

• Staircase Lighting Guide - Complete guide for staircase automation with PIR sensors

Software & Integration:

• WLED API Guide - REST, JSON, MQTT, WebSocket control and automation
• Firmware Development Guide - Compile, customize, and develop WLED firmware
• WLED-Rainmaker Integration Guide - Cloud connectivity
• Reliability & Maintenance - Long-term operation

Professional LED Software (Shared with POI-LED):

• xLights Guide - Professional LED sequencing
• Jinx! Guide - LED matrix control
• LedFx Guide - Music-reactive effects
• Hyperion Guide - Ambilight for TVs

Troubleshooting:

• Common Issues Guide - Solve problems quickly

Resources

• WLED Official Documentation
• ESP RainMaker Documentation
• ESP32 Datasheet

Build System

This repository includes a sophisticated build system for easy multi-configuration development:

Quick Build

# Build a project
./build-manager.sh build projects/wled-controllers/basic-esp32-controller

# Flash to device
./build-manager.sh flash projects/wled-controllers/basic-esp32-controller /dev/ttyUSB0

# Interactive mode
./build-manager.sh

Features

• ✅ Multiple build configurations per project
• ✅ Automated CI/CD with GitHub Actions
• ✅ One-command building and flashing
• ✅ Project templates for quick starts
• ✅ Centralized configuration management

See BUILD_SYSTEM.md for complete documentation.

Example Projects

See PROJECTS_OVERVIEW.md for complete project catalog.

1. Basic ESP32 Controller ✅

Location: projects/wled-controllers/basic-esp32-controller/

• Standard WLED setup for ESP32
• Supports 30-500 LEDs
• 8 build configurations
• Complete documentation

Quick start:

cd projects/wled-controllers/basic-esp32-controller
./build.sh build
./build.sh flash esp32_basic /dev/ttyUSB0

2. Sound Reactive Controller ✅

Location: projects/wled-controllers/sound-reactive-controller/

• Music-synchronized LED visualization
• I2S digital microphone (INMP441)
• FFT analysis and beat detection
• 9 build variants

Quick start:

cd projects/wled-controllers/sound-reactive-controller
./build.sh build sound_reactive
./build.sh flash sound_reactive /dev/ttyUSB0

3. Moon/Ambient Lighting ✅

Location: projects/wled-controllers/moon-ambient-lighting/

• RGBW (SK6812) for true white light
• Circadian rhythm support
• Sunrise/sunset simulation
• Moon phase effects
• PIR motion sensor integration
• BH1750 ambient light sensor
• 10 build variants

Quick start:

cd projects/wled-controllers/moon-ambient-lighting
./build.sh build moon_basic
./build.sh flash moon_basic /dev/ttyUSB0

4. Multi-Channel Controller ✅

Location: projects/wled-controllers/multi-channel-controller/

• 4-8 independent LED outputs
• Professional installations
• Synchronized or independent control
• Fused outputs per channel
• Up to 3200 total LEDs
• 11 build configurations
• Architectural/commercial focus

Quick start:

cd projects/wled-controllers/multi-channel-controller
./build.sh build multi_4ch
./build.sh flash multi_4ch /dev/ttyUSB0

---

See PROJECTS_OVERVIEW.md for detailed comparison and selection guide.

Getting Started

1. Review the documentation in docs/guides/
2. Check existing projects in projects/ for examples
3. For Rainmaker integration, follow the dedicated guide in integrations/rainmaker/
4. Hardware designs can be found in hardware/

Project Management

Each project should include:

• README.md with project description
• Source code or firmware files
• Configuration files
• Testing documentation
• Hardware requirements (if applicable)

Contributing

When adding new projects:

1. Create a new directory in the appropriate projects/ subdirectory
2. Include comprehensive README.md
3. Document hardware requirements
4. Add schematics to hardware/ if custom PCB is involved
5. Update this main README if needed

Related Projects

POI-LED - Performance Props & Visual LED Art

Location: ../POI-Led/

Companion repository for battery-powered LED performance props, POI spinning tools, LED hoops, and stage lighting.

Key Differences:

Aspect	WLED-Projects (This Repo)	POI-LED
Focus	Static installations, home lighting	Performance props, portable
Power	AC/DC mains powered	Battery powered (18650, LiPo)
Use Cases	Home, architectural, sensors	Stage shows, flow arts, POV display
Control	WiFi, home automation	Wireless, standalone playback
Runtime	Continuous (mains)	1-2 hours (battery)

Shared Technologies:

• ✅ ESP32 platform
• ✅ WLED/ARGB firmware
• ✅ Same LED types (WS2812B, APA102, SK6812)
• ✅ E1.31, DDP, Art-Net protocols
• ✅ xLights, LedFx, Hyperion, Jinx! software

Integration Guide: POI-LED Integration

POI-LED Documentation:

• POI-LED README
• Product Catalog
• POI Hardware Guide
• Happy Smart Light Products

---

Notes

• Keep firmware libraries organized in firmware/libraries/
• Store all images and media in resources/
• Document troubleshooting steps in docs/troubleshooting/