Add 8MB variant of the Waveshare panel

Author: theoutfield

CHANGELOG.md

@@ -1,4 +1,30 @@
 cmake_minimum_required(VERSION 3.22)
 
+# PiLab Panel flash-size variant selection.
+# Default remains 16MB to preserve the original v6.45.41 build behavior.
+# Build 8MB variant with:
+#   idf.py -B build_8mb -DPILAB_FLASH_SIZE=8MB build
+# Build 16MB variant with:
+#   idf.py -B build_16mb -DPILAB_FLASH_SIZE=16MB build
+set(PILAB_FLASH_SIZE "16MB" CACHE STRING "PiLab Panel flash variant: 8MB or 16MB")
+set_property(CACHE PILAB_FLASH_SIZE PROPERTY STRINGS "8MB" "16MB")
+
+if(PILAB_FLASH_SIZE STREQUAL "8MB")
+    set(SDKCONFIG_DEFAULTS
+        "sdkconfig.defaults.common"
+        "sdkconfig.defaults.8mb"
+    )
+elseif(PILAB_FLASH_SIZE STREQUAL "16MB")
+    set(SDKCONFIG_DEFAULTS
+        "sdkconfig.defaults.common"
+        "sdkconfig.defaults.16mb"
+    )
+else()
+    message(FATAL_ERROR "Unsupported PILAB_FLASH_SIZE='${PILAB_FLASH_SIZE}'. Use 8MB or 16MB.")
+endif()
+
+message(STATUS "PiLab Panel flash variant: ${PILAB_FLASH_SIZE}")
+message(STATUS "PiLab Panel sdkconfig defaults: ${SDKCONFIG_DEFAULTS}")
+
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(PiLab_Panel)

CMakeLists.txt

@@ -50,13 +50,30 @@ The local tag database is the normalization layer. Future drivers such as PiLink
 Primary target:
 
 - Waveshare ESP32-S3 7-inch RGB LCD touch panel
-- ESP32-S3 with PSRAM, commonly the N16R8-style configuration
+- ESP32-S3 with PSRAM
 - 800x480 RGB LCD
 - GT911 touch controller
 - CH422G I/O expander used by the Waveshare board
 
 The firmware is not a generic ESP32-S3 display project. It contains board-specific display, touch, reset, and backlight handling for this Waveshare panel.
 
+### Flash / PSRAM variants
+
+The Waveshare ESP32-S3 7-inch LCD board appears to exist in at least two memory configurations:
+
+- 16MB Flash / 8MB PSRAM
+- 8MB Flash / 8MB PSRAM
+
+Both variants use the same PiLab Panel source code, but they require different ESP-IDF flash-size settings and different partition tables.
+
+If the wrong firmware is flashed, the install may appear to complete, but the board can reboot before Wi-Fi starts. A typical monitor message for flashing the 16MB firmware onto an 8MB board is:
+
+```text
+Detected size(8192k) smaller than the size in the binary image header(16384k)
+```
+
+If you see that message, build or flash the 8MB variant.
+
 ## Repository layout
 
 ```text
@@ -73,23 +90,53 @@ panel_web/
   tools/               Web build helper scripts
 
 tools/
-  embed_web_assets.py  Converts built HTML into C source for firmware embedding
+  embed_web_assets.py      Converts built HTML into C source for firmware embedding
+  build_8mb.ps1           Builds the 8MB flash variant
+  build_16mb.ps1          Builds the 16MB flash variant
+  copyFirmware.ps1        Copies built firmware into the web flasher folder
+
+webflasher/
+  index.html              ESP Web Tools browser flasher page
+  manifest_8mb.json       Web flasher manifest for 8MB flash boards
+  manifest_16mb.json      Web flasher manifest for 16MB flash boards
+  firmware/8mb/           8MB build output copied here for GitHub Pages
+  firmware/16mb/          16MB build output copied here for GitHub Pages
 
 docs/
   Architecture, build, validation, diagnostics, and contributor notes
 ```
 
 ## Quick start
 
-### Build firmware only
+### 1. Set the ESP-IDF target
+
+Run this once after cloning or unpacking the project:
 
 ```bash
 idf.py set-target esp32s3
-idf.py build
-idf.py flash monitor
 ```
 
-### Connect to the panel
+### 2. Choose the correct flash variant
+
+PiLab Panel now supports separate 8MB and 16MB flash builds.
+
+Use the 16MB build for original Waveshare ESP32-S3N16R8-style boards:
+
+```bash
+idf.py -B build_16mb -DPILAB_FLASH_SIZE=16MB build
+idf.py -B build_16mb flash monitor
+```
+
+Use the 8MB build for Waveshare boards that report 8MB flash:
+
+```bash
+idf.py -B build_8mb -DPILAB_FLASH_SIZE=8MB build
+idf.py -B build_8mb flash monitor
+```
+
+The `-B` option keeps each variant in a separate build folder. This is important because ESP-IDF stores the selected sdkconfig in the build directory.
+
+### 3. Connect to the panel
 
 After flashing, connect a PC, tablet, or phone to:
 
@@ -99,26 +146,84 @@ Password: pilabpanel
 URL:      http://192.168.4.1
 ```
 
+If the panel has been configured to join your Wi-Fi network, it may also be reachable by mDNS:
+
+```text
+http://pilab-panel.local
+```
+
 ### Rebuild the web editor and firmware
 
+The zip intentionally does not include `node_modules`. To rebuild the browser editor and embed it into the ESP32 firmware:
+
 ```bash
 cd panel_web
 npm install
 npm run build
 npm run embed
 cd ..
-idf.py build
-idf.py flash monitor
 ```
 
-The zip intentionally does not include `node_modules`.
+Then build the firmware variant you need:
+
+```bash
+idf.py -B build_16mb -DPILAB_FLASH_SIZE=16MB build
+```
+
+or:
+
+```bash
+idf.py -B build_8mb -DPILAB_FLASH_SIZE=8MB build
+```
+
+## Flash variant files
+
+The project uses these files for the two hardware variants:
+
+```text
+sdkconfig.defaults.common
+sdkconfig.defaults.16mb
+sdkconfig.defaults.8mb
+partitions_16mb.csv
+partitions_8mb.csv
+```
+
+`CMakeLists.txt` selects the correct sdkconfig defaults from the `PILAB_FLASH_SIZE` option.
+
+The default is still 16MB if no option is provided.
+
+## Updating the web flasher firmware files
+
+After building a firmware variant, copy the generated ESP-IDF binaries into the `webflasher` folder.
+
+For the 16MB variant:
+
+```powershell
+.\tools\copyFirmware.ps1 -Variant 16mb -BuildDir build_16mb
+```
+
+For the 8MB variant:
+
+```powershell
+.\tools\copyFirmware.ps1 -Variant 8mb -BuildDir build_8mb
+```
+
+The web flasher has two manifests:
+
+```text
+webflasher/manifest_16mb.json
+webflasher/manifest_8mb.json
+```
+
+The GitHub Pages web flasher page provides separate install buttons for the 8MB and 16MB firmware builds.
 
 ## Main documentation
 
 Start with these files:
 
 - [`docs/USER_GUIDE.md`](docs/USER_GUIDE.md)
 - [`docs/BUILD_AND_FLASH.md`](docs/BUILD_AND_FLASH.md)
+- [`README_FLASH_VARIANTS.md`](README_FLASH_VARIANTS.md)
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
 - [`docs/RUNTIME_LIFECYCLE.md`](docs/RUNTIME_LIFECYCLE.md)
 - [`docs/DIAGNOSTICS.md`](docs/DIAGNOSTICS.md)

README.md

@@ -0,0 +1,5 @@
+# Name,   Type, SubType, Offset,   Size,     Flags
+nvs,      data, nvs,     0x9000,   0x6000,
+phy_init, data, phy,     0xf000,   0x1000,
+factory,  app,  factory, 0x10000,  4M,
+storage,  data, spiffs,          , 8M,

partitions_16mb.csv

@@ -0,0 +1,7 @@
+# PiLab Panel ESP32-S3 8MB flash partition table
+# Fits Waveshare ESP32-S3-Touch-LCD-7 variants with 8MB Flash / 8MB PSRAM.
+# Name,   Type, SubType, Offset,   Size,     Flags
+nvs,      data, nvs,     0x9000,   0x6000,
+phy_init, data, phy,     0xf000,   0x1000,
+factory,  app,  factory, 0x10000,  4M,
+storage,  data, spiffs,  0x410000, 0x3F0000,

partitions_8mb.csv

@@ -1,8 +1,12 @@
+# PiLab Panel common ESP32-S3 defaults
+# Variant-specific flash size and partition table settings are in:
+#   sdkconfig.defaults.8mb
+#   sdkconfig.defaults.16mb
+
 # Target
 CONFIG_IDF_TARGET="esp32s3"
 
-# Flash / PSRAM for Waveshare ESP32-S3-Touch-LCD-7 N16R8 style module
-CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
+# Flash bus / PSRAM for Waveshare ESP32-S3-Touch-LCD-7 style modules
 CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
 CONFIG_ESPTOOLPY_FLASHFREQ_80M=y
 CONFIG_SPIRAM=y
@@ -13,15 +17,10 @@ CONFIG_SPIRAM_USE_MALLOC=y
 # v5.21 PSRAM diagnostic: allow small malloc() allocations to spill into PSRAM.
 # LVGL 9 object/spec-attribute/label allocations are often small; the previous
 # 4096 byte threshold strongly biased those allocations toward scarce internal
-# RAM.  This keeps only very tiny allocations internal by default.
+# RAM. This keeps only very tiny allocations internal by default.
 CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL=64
 CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL=32768
 
-# Use this partition file by default
-CONFIG_PARTITION_TABLE_CUSTOM=y
-CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
-CONFIG_PARTITION_TABLE_FILENAME="partitions.csv"
-
 # FreeRTOS/LVGL friendliness
 CONFIG_ESP_MAIN_TASK_STACK_SIZE=16384
 CONFIG_FREERTOS_HZ=1000
@@ -41,3 +40,9 @@ CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM=y
 # Diagnostic LVGL build testing: keep the task watchdog enabled, but wait longer
 # before panic so large staged screen builds can prove whether they complete.
 CONFIG_ESP_TASK_WDT_TIMEOUT_S=10
+# PiLab Panel ESP32-S3 16MB flash variant
+# For Waveshare ESP32-S3-Touch-LCD-7 boards that report 16MB flash.
+CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_16mb.csv"
+CONFIG_PARTITION_TABLE_FILENAME="partitions_16mb.csv"

sdkconfig.defaults

@@ -0,0 +1,6 @@
+# PiLab Panel ESP32-S3 16MB flash variant
+# For Waveshare ESP32-S3-Touch-LCD-7 boards that report 16MB flash.
+CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_16mb.csv"
+CONFIG_PARTITION_TABLE_FILENAME="partitions_16mb.csv"

sdkconfig.defaults.16mb

@@ -0,0 +1,6 @@
+# PiLab Panel ESP32-S3 8MB flash variant
+# For Waveshare ESP32-S3-Touch-LCD-7 boards that report 8MB flash.
+CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_8mb.csv"
+CONFIG_PARTITION_TABLE_FILENAME="partitions_8mb.csv"

sdkconfig.defaults.8mb

@@ -0,0 +1,42 @@
+# PiLab Panel common ESP32-S3 defaults
+# Variant-specific flash size and partition table settings are in:
+#   sdkconfig.defaults.8mb
+#   sdkconfig.defaults.16mb
+
+# Target
+CONFIG_IDF_TARGET="esp32s3"
+
+# Flash bus / PSRAM for Waveshare ESP32-S3-Touch-LCD-7 style modules
+CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
+CONFIG_ESPTOOLPY_FLASHFREQ_80M=y
+CONFIG_SPIRAM=y
+CONFIG_SPIRAM_MODE_OCT=y
+CONFIG_SPIRAM_SPEED_80M=y
+CONFIG_SPIRAM_USE_MALLOC=y
+
+# v5.21 PSRAM diagnostic: allow small malloc() allocations to spill into PSRAM.
+# LVGL 9 object/spec-attribute/label allocations are often small; the previous
+# 4096 byte threshold strongly biased those allocations toward scarce internal
+# RAM. This keeps only very tiny allocations internal by default.
+CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL=64
+CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL=32768
+
+# FreeRTOS/LVGL friendliness
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=16384
+CONFIG_FREERTOS_HZ=1000
+CONFIG_LOG_DEFAULT_LEVEL_INFO=y
+
+# Workaround for ESP-IDF 6.0.1 / GCC 15.x internal compiler error seen while
+# compiling esp_lcd/rgb/esp_lcd_panel_rgb.c with debug optimization (-Og) on Windows.
+# Build IDF components with size optimization (-Os) instead of debug optimization.
+# CONFIG_COMPILER_OPTIMIZATION_DEBUG is not set
+CONFIG_COMPILER_OPTIMIZATION_SIZE=y
+# CONFIG_COMPILER_OPTIMIZATION_PERF is not set
+# CONFIG_COMPILER_OPTIMIZATION_NONE is not set
+
+# Allow AngelScript compiler task stack to live in PSRAM.
+CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM=y
+
+# Diagnostic LVGL build testing: keep the task watchdog enabled, but wait longer
+# before panic so large staged screen builds can prove whether they complete.
+CONFIG_ESP_TASK_WDT_TIMEOUT_S=10

sdkconfig.defaults.common

@@ -0,0 +1,9 @@
+# Build PiLab Panel for Waveshare ESP32-S3-Touch-LCD-7 16MB Flash / 8MB PSRAM boards.
+$ErrorActionPreference = "Stop"
+$Root = Resolve-Path (Join-Path (Split-Path -Parent $MyInvocation.MyCommand.Path) "..")
+Push-Location $Root
+try {
+    idf.py -B build_16mb -DPILAB_FLASH_SIZE=16MB build
+} finally {
+    Pop-Location
+}