The Matrix Portal has two onboard buttons labeled "Down" and "Up" that can be used to control the lights.
I checked the MatrixPortal Pinout page and discovered that Down is connected to GPIO 7 and Up is connected to GPIO 6.
Open up the LED settings screen in WLED under "Config". Scroll to the button setup section and set button 1 to use GPIO 7 and button 2 to use GPIO 6, with the type for both set as "Pushbutton"
Click save.
Button Default Behaviors
For buttons 1 & 2:
- Short press: Cycles through effects.
- Long press: Increases and slightly decreases brightness.
- Double press: Cycles through color palettes.
I advise against using button 0. WLED's buttons have some default behaviors written in, and one of button 0's default behaviors is that when it's pressed for more than a few seconds, it resets your microcontroller to factory settings, or resets your WiFi network, or any number of potentially confusing things. I originally had button 0 selected, and I held the button down a bit too long, and .. POOF. All my settings and presets were wiped out.
Let's override the defaults and get these buttons to do what we want.
I'd like the Down button (button 1) to turn the screen on and off, and the Up button (button 2) to cycle through my presets (rather than all the effects modes, as in the default behavior).
This only uses the "short press" feature -- each button can also have a long press and a double-click set up as well if you'd like.
Head to the Time & Macros config screen. Scroll down to the Button actions area.
For button 1, enter the number assigned to the two control presets you made on the last page. My Next_FX preset is number 9, so I entered 9 under "short press",
For button 2, my Toggle preset is number 10, so I've got that set up as a "short press".
Troubleshooting
If your button isn't working, here are some things to try:
- Double check both the LED preferences page and the Time & Macros page to be sure your settings are correct, and have saved.
- Be sure your presets are correctly numbered. WLED gets confused if the presets have non-sequential IDs (so make sure they're numbered 1, 2, 3 rather than 2, 5, 7).
- If your preset file gets corrupted, make sure you entered the code correctly. Forgetting the curly braces or quotes in the Next_FX preset code can make your board hang. If it hangs, you may need to reinstall WLED and repeat the setup process. Find config backup tools under the Security & Updates config settings.
- If you add more presets, you'll need to update the Next_FX preset code to include them all. In the guide they toggle through 1-3. Be sure additional presets are sequentially numbered and update Next_FX to include all the presets you'd like.
Page last edited November 10, 2025
Text editor powered by tinymce.