WLED Touch Remote is a dedicated touchscreen controller for WLED over your local Wi-Fi network. It runs on the ESP32 Cheap Yellow Display (CYD) or the Guition ESP32-P4 display and controls power, brightness, presets, colors, effects, palettes, and live LED preview through WLED's standard JSON API.
It works with current WLED firmware and requires no custom WLED build or controller-side configuration. The remote can run from 5 V or, on supported capacitive displays, from a Li-Ion battery cell. See the bill of materials.
- Support the project
- Features
- Screenshots
- Flash it
- Set up Wi-Fi and WLED
- Settings
- Supported hardware
- Bill of materials
- 3D-printed case
- Development
- ESP-NOW (deprecated)
- Contributing
If you enjoy WLED Touch Remote, please consider sponsoring its development. It has taken many hours of development and testing to build, and donations help fund ongoing improvements, new features, and wider hardware support.
- Power and brightness control
- Preset selection, creation, and renaming
- Colors, effects, palettes, speed, and intensity controls
- Live LED preview and responsive state updates from the selected controller
- Automatic discovery of WLED controllers on the local network, with manual IP-address entry when discovery is unavailable
- Optional built-in mobile hotspot for WLED setups without an existing Wi-Fi network
- Control of one or all discovered controllers
- On-device settings for screen orientation and inactivity behavior
- Web installer support for browser-based flashing
The easiest option is the web installer:
- Open the web installer.
- Connect your display using a data-capable USB cable.
- Click Install and choose the ESP32 serial port.
- On the remote, open Settings → Wi-Fi, choose your 2.4 GHz network, and enter its password.
- The remote finds WLED instances advertised on the LAN. Open Settings → Control Target to choose one or control all discovered controllers.
- If a controller is not discovered, choose WLED IP from the Wi-Fi screen and enter its IPv4 address.
The remote and WLED controller must be on the same routed local network.
For a portable installation, open Settings → Mobile hotspot, enable it, and optionally edit the displayed SSID and password.
Configure each WLED controller to join that network, then select it from Control Target (or enter its address with WLED IP if discovery is unavailable). Enabling the hotspot disconnects the remote from its saved Wi-Fi; disabling it stops the hotspot and reconnects to the saved network.
The Settings tab lets you change:
- The controller or controllers to control
- Wi-Fi network
- Mobile hotspot name and on/off state
- Display orientation
- Inactivity behavior:
- Always on
- Dim
- Display off
- Eco: display stays on while the WLED instance is on, then turns off after 30 seconds when the WLED instance is off.
- Software updates from stable GitHub Releases
Settings are saved on the ESP32 and restored after reboot.
Open Settings → Software Update → Check for Updates to compare the installed semantic version with the newest compatible stable GitHub Release. Drafts and prereleases are ignored. The remote only accepts the application firmware asset for its own board (esp32-cyd, jc4880p443, or jc8048w550c), downloads it, and verifies the GitHub-provided SHA-256 digest before committing it to the OTA partition.
Keep the remote powered and connected to Wi-Fi during installation. A download, validation, or install failure aborts the pending OTA image and leaves the currently running firmware intact.
Supported devices:
- Guition ESP32-P4 JC4880P443, 4.3-inch display - highly recommended
- Guition JC2432W328C - recommended capacitive CYD
- Guition JC8048W550C, 5-inch 800x480 display (untested)
- ESP32-024 and ESP32-2432S028-style resistive CYDs - largely supported but not recommended
On first boot, the firmware shows a one-time touch setup screen to confirm the touch hardware.
CYDs come in capacitive and resistive versions. The capacitive version is preferred for its more responsive touch, slightly nicer display, and wider support. Only capacitive CYDs support Li-Ion batteries. Check for the BAT connector before buying because several variants exist.
Most resistive CYDs are also supported, but they are not recommended. There are too many resistive variants to guarantee support for all of them.
Search for JC2432W328C or Capacitive CYD on AliExpress or Amazon. Guition is the recommended brand for capacitive displays. Avoid its resistive displays because they are unlikely to be supported.
Some currently available capacitive CYDs:
- https://www.amazon.com/DIYmalls-Touchscreen-ESP-WROOM-32-Development-JC2432W328C
- https://www.aliexpress.us/item/3256806545687380.html
If you can source the ESP32-P4, it will provide a nicer experience due to its larger and more powerful display:
- Slim version: four M3×10 bolts
- Battery version: four M3×20 bolts
- CYDs usually include a JST-PB 1.25 mm four-pin connector, which you can use to add buttons.
- For battery operation, use a JST-PB 1.25 mm two-pin connector. If necessary, carefully split a four-pin connector in half.
Optional snap-fit cases are available on MakerWorld: FigCYD CYD case with optional battery.
An ESP32-P4 case is also available on MakerWorld: WLED Touch Remote based on ESP32-P4.
Choose one of the two case styles:
-
Slim case: A clean remote without an internal battery, suited to a wall or control cabinet with continuous USB-C or 5 V power.
-
Battery case: A portable build with an 18650 Li-Ion cell and holder.
Assembly:
- Print the case parts from MakerWorld for the slim or battery version.
- Press the CYD into the front shell, checking that the USB-C port, reset button, and side button line up.
- Snap the back shell into place. Bolts are optional because the case is snap-fit, but they make it more secure.
- Slim: four M3×10 bolts
- Battery: four M3×20 bolts
For the slim case, you can stop here. For the battery case:
- Remove the printed supports from the button opening, bolt holes, and battery-holder area.
- Free the side power-button piece and make sure it moves smoothly before installing the CYD.
- Install the 18650 holder and route the wires so they do not pinch when the case closes.
The slim case can be powered through USB-C or through the board's GND and 5V connector.
- Double-tap the power button to turn on.
- Hold the power button for 10 seconds to turn off.
- If you connect USB while running on battery, the device may restart. This is normal behavior for the CYD battery circuitry.
- Double-check polarity before powering the board. The case photos show the intended wiring path and board orientation.
Install PlatformIO, then run:
pio run -e esp32-cyd
pio run -e esp32-cyd -t uploadFor the JC4880P443, use pio run -e jc4880p443; for the JC8048W550C, use pio run -e jc8048w550c. See platformio.ini for all available environments and include/app_config.h for board-specific options.
A native SDL simulator is included for screenshots and UI checks:
brew install sdl2
# 320x240 ESP32-CYD
pio run -e macos
.pio/build/macos/program
# 480x800 ESP32-P4 JC4880P443
pio run -e macos-jc4880p443
.pio/build/macos-jc4880p443/program
# 800x480 ESP32-S3 JC8048W550C
pio run -e macos-jc8048w550c
.pio/build/macos-jc8048w550c/programEach command opens a resizable SDL window. Click or drag in the window to simulate touch input; close the window to exit.
ESP-NOW support is deprecated in favor of standard Wi-Fi. Use Wi-Fi for new installations.
Issues and pull requests are welcome. Keep changes focused and touch-friendly on both the 320×240 CYD and the Guition ESP32-P4 JC4880P443 4.3-inch display.
Useful areas for contributions include:
- UI polish
- Documentation
- Hardware compatibility reports for CYD variants
- New features
See Acknowledgements for related projects and libraries that helped shape this project.