At the time of writing, the standard web installer for WLED does not support the MatrixPortal S3. For this project you'll install a MoonModules fork of WLED that's written for the ESP32-S3 chipset.
More information about the MoonModules project can be found here
For this installation, use the Adafruit WebSerial ESPTool. Download the matrix_wled.bin file linked below and save it on your computer.
Navigate to Adafruit WebSerial ESPTool in your web browser.
Find the BOOT button on your MatrixPortal S3. Hold it down while you plug it into your computer via the USB port. This will get you into bootloader mode.
Click "connect" in the WebSerial ESPtool menu bar and select the MatrixPortal as your serial port.
Click the top "Choose a file" button and upload the matrix_wled.bin file you downloaded earlier. Click "Program".
Once the program is finished running you'll get a prompt to reset your board. Click the reset button.
If everything worked, all the lights on the front of your MatrixPortal will turn yellow. Success!
Check your WiFi settings and look for a new network called WLED-AP. This is your MatrixPortal's access point network. Join the network to connect to your MatrixPortal. The next step will be to configure your WiFi credentials and get WLED set up for your matrix.
Click "WiFi Settings" in the window that pops up when you join WLED-AP. Enter your WiFi credentials and then enter a name you can remember in the mDNS field a little further down. This is what you'll type into your location bar in your browser to access the WLED controls.
Click "save", then rejoin your regular WiFi network and type the mDNS name plus ".local" into the location bar (i.e. stainedglass.local).
Now you can control your MatrixPortal from any web browser or smartphone that's connected to your WiFi network.
Troubleshooting
If you can't connect to your MatrixPortal as a serial port in the ESPTool interface:
- Check to see if you're using a charge-only USB cable. These are increasingly common but you need a cable that will carry data. Use a known good cable.
- Try rebooting your computer. Sometimes the USB ports get "stuck" in a connected state
- Be sure you're holding the BOOT button down as you plug the board into your computer
- For more help, check the Factory Reset page of the Matrix Portal S3 guide
If you can connect and upload the file, but when it finishes you don't get yellow lights or don't see the WLED_AP WiFi network:
- Did you erase the flash memory first?
- Try refreshing the page between erasing flash memory and loading the code
- Try unplugging the board / resetting between erasing and loading
- Try a factory reset (see above) and then give it another go
- Is your WiFi network 5GHZ only? You need a 2.4GHZ network to connect in access point mode. Try it again at your local coffee shop or your neighbor's house
Page last edited November 11, 2025
Text editor powered by tinymce.
