ci: build HUB75 envs in release workflow

.github/platformio_release.ini.template

@@ -0,0 +1,44 @@
+; ----------------------------------------------------------------------------
+; platformio_release.ini.template
+; ----------------------------------------------------------------------------
+; Copied to platformio_release.ini by the release CI workflow
+; (.github/workflows/release.yml -> build.yml with `release: true`)
+; in order to extend the matrix of `default_envs` built and published
+; for tagged releases.
+;
+; This file overrides `[platformio].default_envs` from platformio.ini via
+; `extra_configs`. It MUST list every env that should be released - including
+; the regular CI default_envs - because it fully replaces the parent value.
+;
+; Do NOT commit a generated platformio_release.ini (it's in .gitignore).
+; ----------------------------------------------------------------------------
+
+[platformio]
+default_envs = nodemcuv2
+               esp8266_2m
+               esp01_1m_full
+               nodemcuv2_160
+               esp8266_2m_160
+               esp01_1m_full_160
+               nodemcuv2_compat
+               esp8266_2m_compat
+               esp01_1m_full_compat
+               esp32dev
+               esp32dev_debug
+               esp32_eth
+               esp32_wrover
+               lolin_s2_mini
+               esp32c3dev
+               esp32c3dev_qio
+               esp32S3_wroom2
+               esp32s3dev_16MB_opi
+               esp32s3dev_8MB_opi
+               esp32s3dev_8MB_qspi
+               esp32s3_4M_qspi
+               usermods
+               ; HUB75 release-only envs
+               esp32dev_hub75
+               esp32dev_hub75_forum_pinout
+               adafruit_matrixportal_esp32s3
+               esp32s3dev_16MB_opi_hub75 ;; MoonHub
+               esp32s3dev_4MB_qspi_hub75 ;; HD-WF2

.github/workflows/build.yml

@@ -3,6 +3,11 @@ name: WLED Build
 # Only included into other workflows
 on:
   workflow_call:
+    inputs:
+      release:
+        description: 'Build the release env matrix (uses .github/platformio_release.ini.template)'
+        type: boolean
+        default: false
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
@@ -14,6 +19,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
+    - name: Apply release config
+      if: inputs.release
+      run: cp .github/platformio_release.ini.template platformio_release.ini
     - uses: actions/setup-python@v5
       with:
         python-version: '3.12'
@@ -38,6 +46,9 @@ jobs:
         environment: ${{ fromJSON(needs.get_default_envs.outputs.environments) }}
     steps:
     - uses: actions/checkout@v4
+    - name: Apply release config
+      if: inputs.release
+      run: cp .github/platformio_release.ini.template platformio_release.ini
     - name: Set up Node.js
       uses: actions/setup-node@v4
       with:
@@ -54,8 +65,8 @@ jobs:
               ~/.platformio/.cache
               ~/.buildcache
               build_output
-        key: pio-${{ runner.os }}-${{ matrix.environment }}-${{ hashFiles('platformio.ini', 'pio-scripts/output_bins.py') }}-${{ hashFiles('wled00/**', 'usermods/**') }}
-        restore-keys: pio-${{ runner.os }}-${{ matrix.environment }}-${{ hashFiles('platformio.ini', 'pio-scripts/output_bins.py') }}-
+        key: pio-${{ runner.os }}-${{ matrix.environment }}-${{ hashFiles('platformio.ini', '.github/platformio_release.ini.template', 'pio-scripts/output_bins.py') }}-${{ hashFiles('wled00/**', 'usermods/**') }}
+        restore-keys: pio-${{ runner.os }}-${{ matrix.environment }}-${{ hashFiles('platformio.ini', '.github/platformio_release.ini.template', 'pio-scripts/output_bins.py') }}-
     - name: Set up Python
       uses: actions/setup-python@v5
       with:

.github/workflows/release.yml

@@ -12,6 +12,8 @@ jobs:
 
   wled_build:
     uses: ./.github/workflows/build.yml
+    with:
+      release: true
 
   release:
     name: Create Release

.gitignore

@@ -16,6 +16,7 @@ __pycache__/
 
 esp01-update.sh
 platformio_override.ini
+platformio_release.ini
 replace_fs.py
 wled-update.sh
 

platformio.ini

@@ -38,6 +38,7 @@ data_dir = ./wled00/data
 build_cache_dir = ~/.buildcache
 extra_configs =
   platformio_override.ini
+  platformio_release.ini
 
 [common]
 # ------------------------------------------------------------------------------
@@ -713,3 +714,89 @@ monitor_filters = esp32_exception_decoder
 board_build.flash_mode = dio
 custom_usermods = *   ; Expands to all usermods in usermods folder
 board_build.partitions = ${esp32.extreme_partitions}  ; We're gonna need a bigger boat
+
+
+
+# ------------------------------------------------------------------------------
+# Hub75 examples
+# ------------------------------------------------------------------------------
+# Note: some panels may experience ghosting with default full brightness. use -D WLED_HUB75_MAX_BRIGHTNESS=239 or lower to fix it.
+
+[hub75]
+;; Shared values for all HUB75 build envs.
+
+;; Core HUB75 flags - common to every HUB75 build
+build_flags =
+  -D WLED_ENABLE_HUB75MATRIX -D NO_GFX
+  -D WLED_DEBUG_BUS
+  -D LED_TYPES=TYPE_HUB75MATRIX_HS
+  ; -D WLED_DEBUG
+
+;; Default I2S mic pins disabled (HUB75 uses GPIOs that would otherwise clash).
+;; Envs that wire up a real mic should NOT include this and define I2S_*PIN themselves.
+i2s_disable_flags = -D SR_DMTYPE=1 -D I2S_SDPIN=-1 -D I2S_CKPIN=-1 -D I2S_WSPIN=-1 -D MCLK_PIN=-1  ;; Disable to prevent pin clash
+
+;; Pinned HUB75 driver libraries
+lib_deps = https://github.com/mrfaptastic/ESP32-HUB75-MatrixPanel-DMA.git#f17fb7fe9d487e9643f919eb5aeedea8d9d1f8d7 ;; 3.0.14
+
+;; Extra flags shared by all S3-based HUB75 builds
+s3_build_flags =
+  -DARDUINO_USB_CDC_ON_BOOT=1 ;; -DARDUINO_USB_MODE=1      ;; for boards with USB-OTG connector only (USBCDC or "TinyUSB")
+  -DBOARD_HAS_PSRAM
+  -DLOLIN_WIFI_FIX ; seems to work much better with this (sets lower TX power)
+  -D WLED_WATCHDOG_TIMEOUT=0
+  -D S3_LCD_DIV_NUM=20 ;; Attempt to fix wifi performance issue when panel active with S3 chips
+
+
+[env:esp32dev_hub75]
+extends = env:esp32dev
+upload_speed = 921600
+build_flags = ${common.build_flags} ${esp32_idf_V4.build_flags} ${hub75.build_flags} ${hub75.i2s_disable_flags}
+              -DARDUINO_USB_CDC_ON_BOOT=0 ;; this flag is mandatory for "classic ESP32" when building with arduino-esp32 >=2.0.3
+              -D WLED_RELEASE_NAME=\"ESP32_HUB75\"
+lib_deps = ${esp32_idf_V4.lib_deps}
+           ${hub75.lib_deps}
+
+[env:esp32dev_hub75_forum_pinout]
+extends = env:esp32dev_hub75
+build_flags = ${common.build_flags} ${esp32_idf_V4.build_flags} ${hub75.build_flags} ${hub75.i2s_disable_flags}
+              -DARDUINO_USB_CDC_ON_BOOT=0
+              -D WLED_RELEASE_NAME=\"ESP32_HUB75_forum_pinout\"
+              -D ESP32_FORUM_PINOUT ;; enable for SmartMatrix default pins
+
+[env:esp32s3dev_4MB_qspi_hub75]
+; HD-WF2 - NOTE: this board has NO PSRAM, so BOARD_HAS_PSRAM must not be set
+; (BOARD_HAS_PSRAM causes the DMA library to allocate only in SPIRAM, which fails without PSRAM)
+extends = env:esp32s3dev_8MB_qspi
+board_build.partitions = ${esp32.extended_partitions} ;; 1.65MB firmware, 700KB filesystem
+build_unflags = -DBOARD_HAS_PSRAM
+build_flags = ${common.build_flags} ${esp32s3.build_flags} ${hub75.build_flags} ${hub75.s3_build_flags} ${hub75.i2s_disable_flags}
+              -D WLED_RELEASE_NAME=\"ESP32-S3_HD-WF2\"
+              -D HD_WF2_PINOUT ;; Huidu HD-WF2 specific GPIO wiring
+lib_deps = ${esp32s3.lib_deps}
+           ${hub75.lib_deps}
+
+[env:adafruit_matrixportal_esp32s3]
+; ESP32-S3 processor, 8 MB flash, 2 MB of PSRAM, dedicated driver pins for HUB75
+extends = env:esp32s3dev_8MB_qspi
+board = adafruit_matrixportal_esp32s3_wled ; modified board definition: removed flash section that causes FS erase on upload
+build_flags = ${common.build_flags} ${esp32s3.build_flags} ${hub75.build_flags} ${hub75.s3_build_flags} ${hub75.i2s_disable_flags}
+              -D WLED_RELEASE_NAME=\"ESP32-S3_Adafruit_Matrixportal\"
+              -D ARDUINO_ADAFRUIT_MATRIXPORTAL_ESP32S3
+lib_deps = ${esp32s3.lib_deps}
+           ${hub75.lib_deps}
+;; board_build.partitions = tools/partitions-8MB_spiffs-tinyuf2.csv ;; supports adafruit UF2 bootloader
+
+[env:esp32s3dev_16MB_opi_hub75]
+;; MOONHUB HUB75 adapter board (lilygo T7-S3 with 16MB flash and octal PSRAM)
+extends = env:esp32s3dev_8MB_opi
+board = lilygo-t7-s3
+board_build.partitions = ${esp32.extreme_partitions}   ;; for 16MB flash (overrides large_partitions for 8MB)
+;; Note: real I2S mic pins are wired here, so we do NOT include ${hub75.i2s_disable_flags}.
+build_flags = ${common.build_flags} ${esp32s3.build_flags} ${hub75.build_flags} ${hub75.s3_build_flags}
+              -D WLED_RELEASE_NAME=\"ESP32-S3_16MB_opi_HUB75\"
+              -D MOONHUB_S3_PINOUT ;; HUB75 pinout
+              -D LEDPIN=14 -D BTNPIN=0 -D RLYPIN=15 -D IRPIN=-1 -D AUDIOPIN=-1 ;; defaults that avoid pin conflicts with HUB75
+              -D SR_DMTYPE=1 -D I2S_SDPIN=10 -D I2S_CKPIN=11 -D I2S_WSPIN=12 -D MCLK_PIN=-1  ;; I2S mic
+lib_deps = ${esp32s3.lib_deps}
+           ${hub75.lib_deps}

platformio_override.sample.ini

@@ -193,7 +193,8 @@ build_flags = ${common.build_flags} ${esp8266.build_flags}
 
 # ------------------------------------------------------------------------------
 # Optional: build flags for speed, instead of optimising for size.
-# Example of usage: see [env:esp32S3_PSRAM_HUB75]
+# Add ${Speed_Flags.build_flags} / ${Speed_Flags.build_unflags} to your own env
+# in platformio_override.ini to opt in.
 # ------------------------------------------------------------------------------
 
 [Speed_Flags]
@@ -554,102 +555,4 @@ custom_usermods =
   https://github.com/wled/wled-usermod-example.git#main
 
 
-# ------------------------------------------------------------------------------
-# Hub75 examples
-# ------------------------------------------------------------------------------
-# Note: some panels may experience ghosting with default full brightness. use -D WLED_HUB75_MAX_BRIGHTNESS=239 or lower to fix it.
-
-[env:esp32dev_hub75]
-board = esp32dev
-upload_speed = 921600
-platform = ${esp32_idf_V4.platform}
-platform_packages =
-build_unflags = ${common.build_unflags}
-build_flags = ${common.build_flags}
-  -D WLED_RELEASE_NAME=\"ESP32_hub75\"
-  -D WLED_ENABLE_HUB75MATRIX -D NO_GFX
-  -D WLED_DEBUG_BUS
-  ; -D WLED_DEBUG
-  -D SR_DMTYPE=1 -D I2S_SDPIN=-1 -D I2S_CKPIN=-1 -D I2S_WSPIN=-1 -D MCLK_PIN=-1  ;; Disable to prevent pin clash
-
-lib_deps = ${esp32_idf_V4.lib_deps}
-  https://github.com/mrfaptastic/ESP32-HUB75-MatrixPanel-DMA.git#3.0.11
-
-monitor_filters = esp32_exception_decoder
-board_build.partitions = ${esp32.default_partitions}
-board_build.flash_mode = dio
-custom_usermods = audioreactive
-
-[env:esp32dev_hub75_forum_pinout]
-extends = env:esp32dev_hub75
-build_flags = ${common.build_flags}
-              -D WLED_RELEASE_NAME=\"ESP32_hub75_forum_pinout\"
-              -D WLED_ENABLE_HUB75MATRIX -D NO_GFX 
-              -D ESP32_FORUM_PINOUT ;; enable for SmartMatrix default pins
-              -D WLED_DEBUG_BUS
-              -D SR_DMTYPE=1 -D I2S_SDPIN=-1 -D I2S_CKPIN=-1 -D I2S_WSPIN=-1 -D MCLK_PIN=-1  ;; Disable to prevent pin clash
-; -D WLED_DEBUG
-
-
-[env:adafruit_matrixportal_esp32s3]
-; ESP32-S3 processor, 8 MB flash, 2 MB of PSRAM, dedicated driver pins for HUB75
-board = adafruit_matrixportal_esp32s3_wled ; modified board definition: removed flash section that causes FS erase on upload
-;; adafruit recommends to use arduino-esp32 2.0.14
-;;platform = espressif32@ ~6.5.0
-;;platform_packages = platformio/framework-arduinoespressif32 @ 3.20014.231204 ;; arduino-esp32 2.0.14
-platform = ${esp32s3.platform}
-platform_packages =
-upload_speed = 921600
-build_unflags = ${common.build_unflags}
-build_flags = ${common.build_flags} ${esp32s3.build_flags} -D WLED_RELEASE_NAME=\"ESP32-S3_8M_qspi\"
-  -DARDUINO_USB_CDC_ON_BOOT=1 ;; -DARDUINO_USB_MODE=1      ;; for boards with USB-OTG connector only (USBCDC or "TinyUSB")
-  -DBOARD_HAS_PSRAM
-  -DLOLIN_WIFI_FIX ; seems to work much better with this (sets lower TX power)
-  -D WLED_WATCHDOG_TIMEOUT=0
-  -D WLED_ENABLE_HUB75MATRIX -D NO_GFX
-  -D S3_LCD_DIV_NUM=20 ;; Attempt to fix wifi performance issue when panel active with S3 chips
-  -D ARDUINO_ADAFRUIT_MATRIXPORTAL_ESP32S3
-  -D WLED_DEBUG_BUS
-  -D SR_DMTYPE=1 -D I2S_SDPIN=-1 -D I2S_CKPIN=-1 -D I2S_WSPIN=-1 -D MCLK_PIN=-1  ;; Disable to prevent pin clash
-
-
-lib_deps = ${esp32s3.lib_deps}
-  https://github.com/mrfaptastic/ESP32-HUB75-MatrixPanel-DMA.git#aa28e2a ;; S3_LCD_DIV_NUM fix
 
-board_build.partitions = ${esp32.large_partitions}                  ;; standard bootloader and 8MB Flash partitions
-;; board_build.partitions = tools/partitions-8MB_spiffs-tinyuf2.csv ;; supports adafruit UF2 bootloader
-board_build.f_flash = 80000000L
-board_build.flash_mode = qio
-monitor_filters = esp32_exception_decoder
-custom_usermods = audioreactive
-
-[env:esp32S3_PSRAM_HUB75]
-;; MOONHUB HUB75 adapter board (lilygo T7-S3 with 16MB flash and PSRAM)
-board = lilygo-t7-s3
-platform = ${esp32s3.platform}
-platform_packages =
-upload_speed = 921600
-build_unflags = ${common.build_unflags}
-              ${Speed_Flags.build_unflags}    ;; optional: removes "-Os" so we can override with "-O2" in build_flags
-build_flags = ${common.build_flags} ${esp32s3.build_flags} -D WLED_RELEASE_NAME=\"esp32S3_16MB_PSRAM_HUB75\"
-              ${Speed_Flags.build_flags}      ;; optional: -O2 -> optimize for speed instead of size
-              -DARDUINO_USB_CDC_ON_BOOT=1 ;; -DARDUINO_USB_MODE=1      ;; for boards with USB-OTG connector only (USBCDC or "TinyUSB")
-              -DBOARD_HAS_PSRAM
-              -DLOLIN_WIFI_FIX ; seems to work much better with this (sets lower TX power)
-              -D WLED_WATCHDOG_TIMEOUT=0
-              -D WLED_ENABLE_HUB75MATRIX -D NO_GFX 
-              -D S3_LCD_DIV_NUM=20 ;; Attempt to fix wifi performance issue when panel active with S3 chips
-              -D MOONHUB_S3_PINOUT ;; HUB75 pinout
-              -D WLED_DEBUG_BUS
-              -D LEDPIN=14 -D BTNPIN=0 -D RLYPIN=15 -D IRPIN=-1 -D AUDIOPIN=-1 ;; defaults that avoid pin conflicts with HUB75
-              -D SR_DMTYPE=1 -D I2S_SDPIN=10 -D I2S_CKPIN=11 -D I2S_WSPIN=12 -D MCLK_PIN=-1  ;; I2S mic
-
-lib_deps = ${esp32s3.lib_deps}
-           https://github.com/mrfaptastic/ESP32-HUB75-MatrixPanel-DMA.git#aa28e2a ;; S3_LCD_DIV_NUM fix
-
-;;board_build.partitions = ${esp32.large_partitions}               ;; for 8MB flash
-board_build.partitions = ${esp32.extreme_partitions}               ;; for 16MB flash
-board_build.f_flash = 80000000L
-board_build.flash_mode = qio
-monitor_filters = esp32_exception_decoder
-custom_usermods = audioreactive

wled00/bus_manager.cpp

@@ -858,6 +858,14 @@ BusHub75Matrix::BusHub75Matrix(const BusConfig &bc) : Bus(bc.type, bc.start, bc.
   DEBUGBUS_PRINTLN("MatrixPanel_I2S_DMA - Matrix Portal S3 config");
   mxconfig.gpio = { 42, 41, 40, 38, 39, 37,  45, 36, 48, 35, 21, 47, 14, 2 };
 
+#elif defined(HD_WF2_PINOUT) // Huidu HD-WF2 ESP32-S3 (no PSRAM)
+
+  // https://www.aliexpress.com/item/1005002258734810.html
+  // https://github.com/mrcodetastic/ESP32-HUB75-MatrixPanel-DMA/issues/433
+  DEBUGBUS_PRINTLN("MatrixPanel_I2S_DMA - HD-WF2 S3 config");
+  // HUB75_I2S_CFG::i2s_pins _pins={R1_PIN, G1_PIN, B1_PIN, R2_PIN, G2_PIN, B2_PIN, A_PIN, B_PIN, C_PIN, D_PIN, E_PIN, LAT_PIN, OE_PIN, CLK_PIN};
+  mxconfig.gpio = { 2, 6, 10, 3, 7, 11, 39, 38, 37, 36, 21, 33, 35, 34 };
+
 #elif defined(CONFIG_IDF_TARGET_ESP32S3) && defined(BOARD_HAS_PSRAM)// ESP32-S3 with PSRAM
 
 #if defined(MOONHUB_S3_PINOUT)
@@ -1078,6 +1086,7 @@ uint32_t BusHub75Matrix::getPixelColor(unsigned pix) const {
 
 void BusHub75Matrix::setBrightness(uint8_t b) {
   _bri = b;
+  if (!_valid || !display) return;
   display->setBrightness(_bri); 
 }
 

wled00/bus_manager.h

@@ -171,7 +171,7 @@ class Bus {
     inline  bool     containsPixel(uint16_t pix) const          { return pix >= _start && pix < _start + _len; }
 
     static inline std::vector<LEDType> getLEDTypes()            { return {{TYPE_NONE, "", PSTR("None")}}; } // not used. just for reference for derived classes
-    static constexpr size_t   getNumberOfPins(uint8_t type)     { return isVirtual(type) ? 4 : isPWM(type) ? numPWMPins(type) : isHub75(type) ? 5 : is2Pin(type) + 1; } // credit @PaoloTK
+    static constexpr size_t   getNumberOfPins(uint8_t type)     { return isVirtual(type) ? 4 : isPWM(type) ? numPWMPins(type) : isHub75(type) ? 5 : is2Pin(type) + 1; } // credit @PaoloTK; for HUB75 the 5 slots store config params (panelW, panelH, chain, rows, cols), not GPIO pins
     static constexpr size_t   getNumberOfChannels(uint8_t type) { return hasWhite(type) + 3*hasRGB(type) + hasCCT(type); }
     static constexpr bool hasRGB(uint8_t type) {
       return !((type >= TYPE_WS2812_1CH && type <= TYPE_WS2812_WWA) || type == TYPE_ANALOG_1CH || type == TYPE_ANALOG_2CH || type == TYPE_ONOFF);

wled00/cfg.cpp

@@ -30,8 +30,10 @@ static constexpr bool validatePinsAndTypes(const unsigned* types, unsigned numTy
   // Pins provided < pins required -> always invalid
   // Pins provided = pins required -> always valid
   // Pins provided > pins required -> valid if excess pins are a product of last type pins since it will be repeated
-  return (sumPinsRequired(types, numTypes) > numPins) ? false :
-          (numPins - sumPinsRequired(types, numTypes)) % Bus::getNumberOfPins(types[numTypes-1]) == 0;
+  // HUB75 types use their pin slots for config params, not GPIO - skip GPIO pin validation for them
+  return Bus::isHub75(types[numTypes-1]) ? true :
+         (sumPinsRequired(types, numTypes) > numPins) ? false :
+         (numPins - sumPinsRequired(types, numTypes)) % Bus::getNumberOfPins(types[numTypes-1]) == 0;
 }
 
 

wled00/data/settings_leds.htm

@@ -7,6 +7,7 @@
 	<style> html { visibility: hidden; } </style> <!-- prevent white & ugly display while loading, unhidden in loadResources() -->
 	<script>
 		var maxD=1,maxI2S=0,maxRMT=0,maxA=1,chipID=0,maxM=4000,maxPB=2048,maxL=1664,maxCO=5,maxBT=4; //maximum bytes for LED allocation: 4kB for 8266, 32kB for 32
+		var hasPSRAM=false; // set from /json/info on page load
 		var customStarts=false,startsDirty=[];
 		function off(n)    { gN(n).value = -1;}
 		// these functions correspond to C macros found in const.h
@@ -38,6 +39,10 @@
 		function S() {
 			getLoc();
 			if(localStorage.getItem('ASc')==='true') d.Sf.AS.checked=true;
+			fetch(getURL('/json/info'))
+				.then(r => r.ok ? r.json() : {})
+				.then(info => { hasPSRAM = Number(info.psrSz ?? 0) > 0 || Number(info.psram ?? 0) > 0; })
+				.catch(() => {});
 			loadJS(getURL('/settings/s.js?p=2'), false, ()=>{
 				d.ledTypes = [/*{i:22,c:1,t:"D",n:"WS2812"},{i:42,c:6,t:"AA",n:"PWM CCT"}*/]; // filled from GetV()
 				d.um_p = [];
@@ -147,7 +152,7 @@
 				if (isHub75(t)) {
 					let p = parseInt(d.Sf["L2"+n].value)||1, r = parseInt(d.Sf["L3"+n].value)||1, c = parseInt(d.Sf["L4"+n].value)||1, h = parseInt(d.Sf["L1"+n].value)||1;
 					if (r*c !== p) {alert(`HUB75 error: panels≠rows×cols`); e.stopPropagation(); return false;}
-					if (h >= 64 && p > 1) {alert(`HUB75 error: height >= 64, only single panel allowed`); e.stopPropagation(); return false;}
+					if (h >= 64 && p > 1 && !hasPSRAM) {alert(`HUB75 error: height >= 64, only single panel allowed`); e.stopPropagation(); return false;}
 					if(isS3()) {
 					  alert("HUB75 changes require a reboot"); // TODO: only throw this if panel config changed?
 					}