[WLED custom build for Adafruit MatrixPortal S3] Unknown board ID adafruit_matrixportal_esp32s3

[Anderl94]

What happened?

I’m trying to build WLED for the adafruit matrixportal s3 using PlatformIO, but the build fails immediately with the following error:

UnknownBoard: Unknown board ID 'adafruit_matrixportal_esp32s3'

To Reproduce Bug

pio run -e adafruit_matrixportal_esp32s3

Expected Behavior

It appears that the board definition for adafruit_matrixportal_esp32s3 may be missing from the current ESP32 platform package used by PlatformIO.
If this board is intended to be supported, it likely needs to be added to the corresponding framework package, or the WLED configuration may need to be updated accordingly.

Please advise whether this board should be included in the PlatformIO ESP32 board definitions or if the configuration requires adjustment.

Install Method

Self-Compiled

What version of WLED?

nightly

Which microcontroller/board are you seeing the problem on?

ESP32-S3

Relevant log/trace output

Anything else?

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[DedeHai]

use #5026 and see my note in ‎platformio_override.sample.ini

[softhack007]

It appears that the board definition for adafruit_matrixportal_esp32s3 may be missing from the current ESP32 platform

this observation is correct; the matrixportal board needs a newer platform version than what we use by default. You might want to try this

platform = espressif32@ ~6.5.0
platform_packages = platformio/framework-arduinoespressif32 @ 3.20014.231204 ;; arduino-esp32 2.0.14

if you don't want to exchange the platform, copy this adafruit_matrixportal_esp32s3.json to your local WLED boards/ folder.

You might also need a special partitions file partitions-8MB_spiffs-tinyuf2.csv (copy to wled tools/, and change the build environment accordingly) to preserve the adafruit bootloader - otherwise some features of the board will behave in strange ways.

If this board is intended to be supported, it likely needs to be added to the corresponding framework package

well "intended to be supported" is a big statement - i would rather say "some users were able to build WLED for their matrixportal", and we just added the correct PIN definitions for the board to our HUB75 driver. that's all.

good luck and have fun :-)

[softhack007]

Edit: this information might help:

• Problem with installing WLEDMM on Adafruit Matrix Portal S3 MoonModules/WLED-MM#205 (comment)

The adafruit matrixportal seems to be very "special", and users said its better to use adafruit tools instead of our "default" web-based installers.

[softhack007]

PS: there is a comment on the github pages of the HUB75 hardware driver used in WLED

'Adafruit MatrixPortal S3' in particular does not work well with this library. Do not buy if you want to use with this library and WiFi. mrcodetastic/ESP32-HUB75-MatrixPanel-DMA#258 (comment)

https://github.com/mrcodetastic/ESP32-HUB75-MatrixPanel-DMA?tab=readme-ov-file#other-hardware-notes

Its very likely that this comment is also true when you run WLED on the matrixportal.

Our builds already include the recommended workaround - however its just a workaround, we cannot fix badly designed hardware in software. Make sure this is part of your custom build_flags

  -D S3_LCD_DIV_NUM=20 ;; Attempt to fix wifi performance issue when panel active with S3 chips
  -DLOLIN_WIFI_FIX ;; optional -  try this in case you Wifi does not connect or WLED-AP does not show up

[DedeHai]

@softhack007 FYI: I did add my workaround here: https://github.com/DedeHai/WLED/blob/5552c05b5e6cc1a997abda170fe823dfc6c64fa1/platformio_override.sample.ini#L565 as mentioned in my initial comment

[softhack007]

@DedeHai Maybe we should add the adafruit_matrixportal_esp32s3.json file to our WLED boards folder? I haven't tested if the matrixPortal works with our default platform (arduino-esp32 2.0.9), however adafruit seems to recommend using at least arduino-esp32 2.0.14.

If you agree, I can add these changes to your HUB75 PR 🤔 however i don't have a matrixportal board for testing.

[DedeHai]

yea, thats what I just suggested. I do have a matrix portal and the workaround I linked above does work for me.

[softhack007]

ok, i'll add the changes to my new PR#5107 first, please check if you get a working WLED build out of it 👍

It might be necessary that you re-install the standard adafruit bootloader first - after this, you can build & upload from VSCode as always. The partitions file will make sure that the adafruit bootloader is kept.

follow adafruit instructions to install and run the factory-reset-and-bootloader firmware: https://learn.adafruit.com/adafruit-matrixportal-s3/factory-reset#factory-reset-and-bootloader-repair-3107941
(use the adafruit web flasher aka "WebSerial ESPTool Method")

[DedeHai]

why would I need the adafruit bootloader? isn't that asking for trouble? In my HUB75 builds I just copy-paste the matrix portal json and not changing anything else.

[softhack007]

why would I need the adafruit bootloader? isn't that asking for trouble

On the contrary - the adafruit bootloader seems to initialize parts of the board hardware; i have an older -S2 from adafruit (QT Py ESP32-S2), and on that board i needed their bootloader to prevent some crazy random behaviour - hence my recommendation to use it. The adafruit "UF2" bootloader is included in the arduino-esp32 framework, so it will be compatible.

Just try it on your board; no problem to comment out the "partitions" line and keep the WLED partitions file it that works best for you.

Edit: you actually found a good point about asking for troubles - our web installer sites must also include the right bootloader image if we use adafruit UF2 partitions.