# WLED setup for the RITHESH LED display

> **⚠️ Do the LED timing pre-check first.** The board uses **XL-5050RGBC-2812B** LEDs (a WS2812B-style part from
> XINGLIGHT). Before any board is ordered, 5–10 of these LEDs must be tested on an ESP32-C3 running WLED (see
> [Timing pre-check](#1-led-timing-pre-check-before-ordering-the-board)). **If the test fails, do not order the board.**
> Standard WLED is used; a custom build is only considered if the timing test shows it is needed.

## What you need

- The RITHESH board (or, for the pre-check, an ESP32-C3 development board and 5–10 XL-5050RGBC-2812B LEDs)
- A **USB-C to USB-C** cable and a charger labelled **5 V ⎓ 3 A** (or a USB-C PD charger of 15 W or more)
- A computer with **Google Chrome or Microsoft Edge** (the web installer needs Web Serial)
- Your Wi-Fi name and password (2.4 GHz; the ESP32-C3 does not use 5 GHz)

## The settings this board needs

| Setting | Value | Where in WLED |
|---------|-------|---------------|
| LED type | WS281x | Config → LED Preferences |
| Color order | GRB (check during testing) | LED Preferences |
| Data GPIO | **10** | LED Preferences → LED output 1 |
| Length | **107** LEDs | LED Preferences |
| Maximum PSU Current | **2000 mA** (brightness limiter **on**) | LED Preferences |
| Button 0 | GPIO **5**, type **Pushbutton** | LED Preferences → Button setup |
| Button action | short press = on/off (WLED's default for button 0) | Config → Time & Macros (leave default) |
| 2D matrix (optional, for letter effects) | 41 × 7, one panel, with `ledmap.json` | Config → 2D Configuration |

Other pins on the board, for reference only: GPIO9 = BOOT button, EN = RESET button, GPIO20/21 = RX/TX test pads,
GPIO0/1 = USB-C CC sense (not used by WLED), GPIO18/19 = USB.

---

## 1. LED timing pre-check (before ordering the board)

1. Wire 5–10 XL-5050RGBC-2812B LEDs in a chain on a small breakout:
   - 5 V and GND to each LED, with a 100 nF capacitor per LED
   - an ESP32-C3 board's GPIO drives DIN through a 74AHCT1G125 level shifter and a 33 Ω resistor, the same as on the real board
2. Install WLED on the ESP32-C3 (steps 2–3 below) and set LED type WS281x, the data GPIO you used, and the LED count.
3. Check (pass criteria from `requirements.md`, "Prototype plan"):
   - Solid red, green, blue and white at low and full (limited) brightness, with no flicker or wrong colours.
   - Colour changes, effects (e.g. **Chase**, **Rainbow**) and brightness changes for **30 minutes** with no random flashes.
   - Every LED is correct after a power cycle (plug out / in) and after pressing reset.
   - With an oscilloscope, the "0" bit high time on the data line is about **400 ns**.
4. **Pass** = all of the above. Record the result (photo, scope screenshot, notes) before ordering.
   **Fail** → do not order. Options: a different color order or LED type in WLED, a different LED part, or (last resort)
   a custom WLED build with adjusted timing.

## 2. Install WLED (first time, over USB)

1. Plug the board into the computer with the USB-C cable.
2. Open **https://install.wled.me** in Chrome or Edge.
3. Pick the latest **stable** WLED release, click **Install**, and choose the serial port that appears
   (often "USB JTAG/serial debug unit").
4. If no port appears or the install fails, put the ESP32-C3 into download mode:
   **hold BOOT, tap RESET, then release BOOT**, and click Install again.
5. When the installer finishes, it can set up Wi-Fi straight away (enter your Wi-Fi name and password).

## 3. Wi-Fi setup (if you skipped it in the installer)

1. On your phone or laptop, join the Wi-Fi network **WLED-AP** (password **wled1234**).
2. A setup page opens (or browse to **http://4.3.2.1**). Choose **WIFI SETTINGS**, pick your home network,
   type the password and **Save & Connect**.
3. The board joins your Wi-Fi. Find it with the WLED phone app, or open **http://wled.local**, or look up its
   address in your router.
4. Tip: in WIFI SETTINGS, change the access-point password and set a device name (e.g. `rithesh`).

## 4. Enter the board settings

Open the WLED page in a browser → **Config** → **LED Preferences**:

1. Maximum PSU current **2000 mA**, and tick "Enable automatic brightness limiter".
2. LED output 1: type **WS281x**, color order **GRB**, length **107**, GPIO **10**.
3. Button 0: GPIO **5**, **Pushbutton**. Remove any other button that uses a pin not on this board.
4. **Save**. The board restarts.

Why 2000 mA? It is the whole-board limit from `requirements.md`: WLED keeps the LEDs (plus ~120 mA for the ESP32)
under 2 A, below the eFuse limit (2.49–2.90 A) and the 3 A charger. Full white is dimmed to about 30 %; single colours
can be brighter.

## 5. Make effects follow the word "RITHESH" (optional)

The LEDs are wired in a zig-zag inside each letter, so a plain 1D effect runs up and down the letters rather than
left to right. Two map files fix that:

| File | Use |
|------|-----|
| `ledmap.json` | **2D map**: places the 107 LEDs on a 41 × 7 grid (7 letters × 5 columns + 1-column gaps). 2D effects then show on the letters. |
| `ledmap1.json` | **1D map**: orders the LEDs from left to right (column by column), so 1D effects sweep across the word. |

To install:

1. Open **http://wled.local/edit** (or the board's address + `/edit`).
2. Upload `ledmap.json`, and optionally `ledmap1.json`.
3. For 2D:
   - Config → **2D Configuration** → **2D Matrix**
   - 1 panel, width **41**, height **7**, starting top-left, horizontal, not serpentine
   - Save
4. Restart the board. WLED loads `ledmap.json` automatically. `ledmap1` can be picked per preset in the segment settings.
5. If the letters look scrambled, delete the map files in `/edit` and restart. Everything still works without them.

`led-order.csv` lists the physical order LED1 → LED107 (WLED index 0 → 106) with each LED's letter, row, column and
position on the board.

## 6. Testing the finished board

1. Plug in a 5 V 3 A USB-C charger. The display should stay dark until WLED starts, with no random flashes (the data line has a pull-down).
2. In WLED set brightness low (~20 %) and a solid colour. **All 107 LEDs** should light.
3. Run the **Chase** effect: the dot must travel R → I → T → H → E → S → H in the order of `led-order.csv`
   (LED1 is at the top-left of the "R", next to the printed "LED1 →").
4. Press **ON/OFF**: the display turns off and on.
5. Raise the brightness to maximum with white: WLED should hold the current near 2 A.
   The board should only get slightly warm. The TP2 (5V_OUT) test pad should stay above about 4.7 V.
6. Optional: measure the TP8 (ILM) pad, about 0.21 V per amp of board current.

## 7. USB recovery (if the board stops responding)

1. Unplug, then hold **BOOT**, plug in (or tap **RESET**), and release **BOOT**. The ESP32-C3 is now in download mode.
2. Re-install WLED from **https://install.wled.me** (step 2). Your settings may be erased. Re-enter step 4.
3. A backup helps: **Config → Security & Updates → Backup configuration** saves your settings to a file.
4. The RX / TX / GND test pads (TP9, TP10, TP5) give a 3.3 V serial console if USB itself is not working.