Buduras Mala Controller ☸️

A high-performance WS2812B LED controller firmware built on the ESP32-S2 (WEMOS LOLIN S2 Mini). Designed specifically for "Buduras Mala" (Buddhist Halos) and Stupa lighting, this project maps a continuous 1D LED strip into a 2D radial matrix using a zigzag wiring scheme.

It provides a rich set of customizable animations, a complete web-based configuration dashboard, and real-time live-tuning capabilities via a local WiFi Access Point.

---

🌟 Basic Description

• Module: ESP32-S2 (Specifically WEMOS LOLIN S2 Mini).
• WiFi: Broadcasts a standalone Access Point named BuduGunaRas (Password: gunadasa).
• Storage: Utilizes LittleFS to persistently store hardware configurations, UI schemas, and saved patterns (config.json, custom.json, patterns.json).
• Web Dashboard: A fully client-side index.html dashboard that communicates with the ESP32 via REST API to update limits, colors, and live-tune animations seamlessly without recompiling.

---

✨ Available Patterns

1. singleWipe: Wipes a single solid color across the rings or spokes.
2. continuousWipe: Continuously loops a sweeping palette of colors.
3. shimmer: Randomly flashes varying colors from your palette across the matrix, resembling twinkling stars.
4. radar: A scanning radar sweep that smoothly fades out behind its leading edge.
5. spiral: Sweeping, curving multi-colored spiral arms rotating outwards.
6. breathing: Smoothly pulses the brightness of the entire matrix in a continuous rhythm.
7. angularWave: Sweeps through the color spectrum in an angular, rotating rainbow wave.
8. matrix: A top-down (or center-out) digital rain effect dropping palette colors.
9. lotusBloom: A concentric rippling effect that mimics a blooming lotus flower.
10. dharmaWheel: Solid, rotating arms representing the spokes of the Dharmachakra.
11. orbitingStars: Individual stars orbiting the center at varying independent speeds.
12. holyAura: A smooth, organic, and cloudy noise-based plasma aura.
13. opposingFlow: Two distinct colors flowing in intersecting, opposite directions.
14. expandingStupa: A tiered, staggered wave expanding progressively, mimicking the rising tiers of a Stupa.

Note: Most patterns support customizable speed, palettes, expanding directions (forward), and switching mapping modes (isRing / isSpoke).

---

🛠 Building and Flashing Guide

This project is built using PlatformIO.

1. Install dependencies: Download Visual Studio Code and install the PlatformIO extension.
2. Open the project: Open the root buduras folder in VSCode.
3. Upload the Filesystem (Crucial Step): Before the UI or configurations will work, you must upload the data/ directory to the ESP32's LittleFS memory.

   pio run --target uploadfs --environment lolin_s2_mini

4. Upload the Firmware: Compile and upload the C++ code to the ESP32:

   pio run --target upload --environment lolin_s2_mini

---

📱 Usage Guide

Connecting to the Module

1. Power on the ESP32-S2.
2. On your phone or laptop, connect to the WiFi network BuduGunaRas (Password: gunadasa).
3. Simply open the index.html file in your preferred web browser (e.g., double-click it on your PC). The dashboard relies on Cross-Origin Resource Sharing (CORS) to talk directly to the default AP IP (http://192.168.4.1).

Hardware Configuration Specs

Through the dashboard, you can define your physical matrix via the Hardware Setup panel:

• numSpokes: The total count of wedges or strips radiating from the center.
• ledsPerSpoke: The number of LEDs on each individual spoke (the length).
• brightness: The master brightness limit (0 - 255). Keep this low during initial testing.
• maxMilliamps: The hardware safety limit. FastLED will automatically dim the LEDs if the calculated current exceeds this limit, protecting your power supply from burning out.

Wiring the WS2812B "Zigzag" Matrix

To allow a single data pin to seamlessly animate 2D radial shapes, the physical wiring must follow a continuous zigzag layout:

1. Start the data wire at the center origin (or bottom edge) of Spoke 0.
2. Wire the strip going OUTWARDS towards the edge.
3. Once at the edge, jump the data wire to the tip of Spoke 1.
4. Wire the strip going INWARDS back toward the center.
5. Jump the data wire to the base of Spoke 2.
6. Repeat (Outward → Inward → Outward → Inward) until all spokes are completed.

This physical setup matches the software's geometric coordinate mapping perfectly.

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.