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). 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

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:

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.