PiLab-Panel

Build and Flash Guide

This project has two build layers:

1. the Vue/Vite web editor under panel_web/
2. the ESP-IDF firmware under the repository root

The firmware embeds the built web editor as a generated C source file.

Required tools

• ESP-IDF 6.x configured for ESP32-S3 development
• Python from the ESP-IDF environment
• Node.js and npm for rebuilding the web editor
• USB cable connected to the Waveshare ESP32-S3 panel

The project has been developed around ESP-IDF 6.0.x behavior. Newer ESP-IDF versions may work, but should be tested carefully because display, PSRAM, LVGL, and compiler behavior can be sensitive.

Firmware-only build

Use this when the embedded web assets are already generated and you only want to rebuild the firmware.

idf.py set-target esp32s3
idf.py build
idf.py flash monitor

Clean firmware build

Use this after changing ESP-IDF config defaults, partition settings, managed components, or when the build behaves strangely.

idf.py fullclean
idf.py set-target esp32s3
idf.py build
idf.py flash monitor

Web editor build

The zip does not include node_modules. Install dependencies before rebuilding the web editor.

cd panel_web
npm install
npm run build
npm run embed
cd ..

npm run build creates the browser app output in panel_web/dist/.

npm run embed runs:

python ../tools/embed_web_assets.py dist/panel.html ../main/web/panel_web_assets.c

That command regenerates main/web/panel_web_assets.c, which is compiled into the firmware.

Full web + firmware rebuild

cd panel_web
npm install
npm run build
npm run embed
cd ..
idf.py set-target esp32s3
idf.py build
idf.py flash monitor

Partition layout

The project uses partitions.csv. The important partition for the HMI workflow is the storage partition, which is mounted as SPIFFS and stores saved HMI/layout/script state.

Current partition intent:

• factory app partition for firmware
• SPIFFS storage partition for saved panel data

ESP-IDF component notes

ESP-IDF 6 no longer provides the old built-in json component. This project uses the managed espressif/cjson component through main/idf_component.yml.

Do not add json to REQUIRES in main/CMakeLists.txt.

Common build issues

Web changes do not appear on the device

Rebuild and embed the web assets, then rebuild and flash firmware:

cd panel_web
npm run build
npm run embed
cd ..
idf.py build flash monitor

Old state keeps reappearing

The saved HMI layout/script can remain in SPIFFS after reflashing firmware. If you need a completely clean device state, erase flash before flashing again:

idf.py erase-flash
idf.py flash monitor

Build fails after ESP-IDF config changes

Run:

idf.py fullclean
idf.py build

Files generated by the web build

Do not hand-edit generated web asset files unless you are doing a quick emergency test.

Generated/derived files include:

panel_web/dist/*
main/web/panel_web_assets.c

Edit source files under:

panel_web/src/

This site is open source. Improve this page.