Current architecture save point:
FORGEUI_IMAGE_AND_LINE__31_OF_39_STANDARD_WIDGETS_ESP32P4_PROVEN__2026-08-01.
ForgeUI Studio is an open-source, AI-assisted visual HMI and embedded GUI designer for ESP32-P4. It combines a drag-and-drop Canvas, reusable Interactive Assets, AI Layout tools, Browser Preview, native LVGL 9 generation, integrated ESP-IDF Build & Flash, and standalone ESP-IDF project export.
ForgeUI exists to shorten the path from an interface idea to editable embedded firmware without putting a web runtime on the device. The Studio is a development tool; exported interfaces compile as native LVGL C inside ESP-IDF.
Design visually. Generate native LVGL. Own the firmware.
- Native embedded output: no browser, Electron, HTML, CSS, JavaScript or Node.js runtime is deployed to the microcontroller.
- Editable AI assistance: AI-generated layouts and artwork enter the same normal component and asset workflows as manually created content.
- Application-friendly runtime: supported controls expose generated setters and genuine-user hooks while permanent product logic stays developer-owned.
- Hardware-led validation: features are distinguished between automated, preview, generated, build and physical ESP32-P4 proof.
- Standalone ownership: exported ESP-IDF projects remain usable without ForgeUI Studio, OpenAI or a ForgeUI runtime.
- Drag-and-drop, free-form Canvas placement and resizing
- Registry-driven Widget Tray with search and accessible insertion
- Authoritative per-widget Registry metadata for Runtime APIs, UserEvents, input semantics, child ownership, documentation and feature-gate preparation
- Data-driven Board Profiles shared by live and Standalone Export
- Export-Time Feature Gating across generated C, CMake and dependencies
- Component properties, semantic themes and uploaded artwork
- Browser Preview
- Layout Designer with Smart Regions and Auto Arrange
- AI-assisted layout, theme and artwork workflows
- Five reusable Interactive Asset types
- Standard LVGL component runtime APIs and hooks
- Collision-safe Runtime APIs and
95_UserEvents - Native QR Code component and generated text setter
- Built-in System Runtime with Display, Wi-Fi and Storage interfaces
- Local conversion of artwork into LVGL-ready C assets
- Client and server export validation
- Integrated ESP-IDF Build & Flash
- Standalone ESP-IDF project export
The active Registry contains only supported widgets. Legacy placeholder types such as AnimImage, ImageButton, Lottie, Menu and ObjxTempl are quarantined from the Tray, root Canvas drop surface, active Inspector/AI catalogue and export; they are not advertised as implemented Standard widgets.
Drag and Drop or AI Layout
↓
Editable ForgeUI components
↓
Canvas
↓
Browser Preview
↓
Generate native LVGL
↓
Build and Flash with ESP-IDF
↓
Develop the application or export a standalone project
AI features require configured OpenAI API access. Normal Studio editing, imported-asset processing, preview, LVGL generation, validation, build and export do not require OpenAI.
ForgeUI’s Layout Designer uses reusable definitions rather than separate hard-coded renderers. The currently implemented template is:
- Dashboard
Industrial HMI, Control Panel, Monitoring, SCADA Overview and Mobile / Portrait are roadmap candidates, not implemented templates.
Dashboard creates ordinary editable ForgeUI components with labelled Smart Region Boxes. Its Header, Status, Main, Controls and Footer workflow has been manually verified on Canvas and Browser Preview. Layout Designer-specific physical ESP32-P4 proof is not claimed. Dashboard uses the normal component persistence, undo/redo, Canvas, Browser Preview and LVGL export paths.
See ForgeUI Layout Designer for the detailed authoring workflow.
Interactive Assets are reusable artwork-backed controls:
- Interactive Button — Normal and Pressed input
- Interactive Toggle Switch — OFF and ON input
- Interactive Three-Position Toggle Switch — LEFT, CENTER and RIGHT input
- Interactive Light — application-controlled OFF and ON output
- Interactive Status Indicator — application-controlled OFF and ON output
They share Creator workflows, AI state-artwork generation, registry persistence, Canvas assignment, visible-artwork fitting, Browser Preview, native LVGL export and generated developer integration.
At a high level:
User input → generated FG_On_* hook → developer application
Developer application → generated FG_Set_* API → displayed output
Exact names are generated from component names and are declared in the exported headers.
ForgeUI generates native LVGL objects and semantic runtime APIs for supported Standard components, including value displays, charts, text entry, selections, progress, images, container visibility and actions.
- Interactive semantic state uses silent setters plus genuine-user hooks.
- Output-only state uses setters without hooks.
- Presentation-only components remain API-free.
- QR Code exposes a silent generated Text setter and no hook.
Generated implementation and public declarations normally live in
90_Studio_Export.c/.h; Standard Fi Icon presentation setters use the dedicated
generated 96_FiRuntime.c/.h boundary. Genuine-user hooks are declared through
95_UserEvents.h; live Studio regeneration preservation-merges matching hook
bodies in 95_UserEvents.c.
Detailed signatures and ownership belong in 03 — Generated Export API Code Map, not this front page.
This generated developer surface is the beginning of the ForgeUI Runtime SDK direction. It is not yet a separately packaged SDK product. See 07 — Runtime SDK Direction.
Current Standard-widget milestone evidence:
- Slider: PROVEN through live and Standalone ESP32-P4 touch/runtime paths.
- Spinner: PROVEN through live and Standalone ESP32-P4 native animation.
- List: PROVEN through Registry, Tray, Canvas, Inspector, Browser Preview,
native LVGL export, collision-safe
95_UserEvents, feature gating, live ESP32-P4 firmware and Standalone Export. List intentionally has no setter. - Spinbox: PROVEN through Registry, Tray, Canvas, Inspector, Browser
Preview, native LVGL export, Runtime SDK,
95_UserEvents, export-time gating, live ESP32-P4 firmware and Standalone Export. - Clock and Wi-Fi Status: PROVEN. Their complete software slices share Canvas/Browser/LVGL presentation. Clock consumes RTC time; Wi-Fi Status consumes the existing backend snapshot with no duplicate manager, setter or UserEvent architecture.
The registry contains 39 Standard widgets; 34 are physically proven (87%) and 5 remain. Text, Clock and Wi-Fi Status join Image, Line, TabView, TileView, Button, Heading, Box and Divider as PROVEN. Image uses native uploaded-asset Contain scaling with persistent source dimensions; Line uses native endpoint geometry and styling. Icon is READY FOR FINAL HARDWARE RE-PROOF and is not included in the proven total. Dedicated Dashboard widgets have not started.
The Board Selector is backed by a data-driven profile registry. The current supported production profile is the Waveshare ESP32-P4 WiFi6 Touch LCD 7B (esp32p4, 1024 × 600). Project feature and transport selection is persisted after hydration and shared by live Build & Flash and standalone export. The profile owns ESP-Hosted SDIO/SPI settings and SDMMC host, pin, width, frequency and power settings. Generated sdkconfig.defaults, 00_ForgeUI_Features.h, CMake sources/components and idf_component.yml are validated together; standalone packaging never copies a stale live sdkconfig.
The proven target is:
- Waveshare ESP32-P4-WiFi6-Touch-LCD-7B
- 1024 × 600
- ESP-IDF 5.5.4
- LVGL 9.2.2
Recorded physical proof includes the established Standard component groups, all five Interactive Asset runtime paths within their documented scopes, generated semantic theme parity, Display/Brightness, the generated Wi-Fi Manager, reusable System keyboard, Storage Browser, ESP-Hosted connectivity through the board’s ESP32-C6, SD storage and simultaneous Wi-Fi/SD operation.
Spinbox proof on ESP-IDF 5.5.4 and LVGL 9.2.2 includes drag/drop, Canvas controls, Inspector synchronization, Browser parity, signed and decimal values, rollover, clamp, native touch increment/decrement, multiple instances, collision-safe generated APIs/hooks, silent setters, exactly one hook per effective user action, feature gating and live/Standalone parity. Spinbox is a native selected-digit editor; use NumberInput for free-form numeric text entry.
The repository does not currently advertise ESP32-S3 or additional board export support. Preview or automated validation is not treated as physical proof. For the authoritative feature-by-feature evidence level, see 04 — Feature Status.
Implemented generated tools are Settings, Brightness, Diagnostics, Wi-Fi Manager, Storage Browser and the private native keyboard. Wi-Fi Manager/dialogs and Storage UI/worker resources are created on demand and destroyed safely on Back; Wi-Fi/ESP-Hosted and SD backend state remains separately alive. Launcher cards follow enabled generated features instead of always showing unavailable placeholders.
The connected lazy-lifecycle Application-page serial probe recorded 45,795 bytes current internal free heap, 43,871 bytes minimum-ever, a 27,648-byte largest block and 62 LVGL objects. Operator-driven repeated touchscreen lifecycle validation remains open. The flashed build contains a compact FPS/RAM overlay, but its direct managed-LVGL edit is absent from current source and needs a reproducible ForgeUI-owned patch.
ForgeUI generates platform UI alongside the application:
- System Launcher
- Display / Brightness
- Wi-Fi Manager
- Storage Browser
- reusable native LVGL keyboard for System text entry
Generated pages own presentation and UI intent. The non-generated firmware backends remain authoritative for Wi-Fi transport, credentials, reconnect policy and filesystem operations.
A standalone export is a normal ESP-IDF project:
- open it directly in Visual Studio Code;
- build, flash and debug it with the normal ESP-IDF workflow;
- add application modules, drivers, GPIO, sensors and product logic;
- call generated UI APIs from application code;
- implement genuine-user reactions in the exported developer hook layer.
The exported project is developer-owned. Studio does not manage it after export, and the device requires no separately installed ForgeUI runtime, ForgeUI Studio service, OpenAI connection, subscription or phone-home service. Permanent application code belongs in developer-owned modules and 95_UserEvents.*, never as a manual source-of-truth patch in replaceable 90_Studio_Export.*.
See 05 — Developer Hardware Integration for practical GPIO, sensor, task, queue, network and hardware examples.
ForgeUI’s current bootstrap workflow targets Windows development.
- Install Git, Node.js 20, Python and ESP-IDF 5.5.x.
- Clone this repository.
- Run
FIRST_TIME_FORGEUI_SETUP.bat. - Start ForgeUI Studio using the provided launcher.
- Create a screen, open Browser Preview, then generate or build the firmware.
For the complete setup sequence, use Getting Started with ForgeUI Studio.
The ForgeUI Developer Portal is the public onboarding site. Repository documentation remains the detailed engineering reference.
| Document | Use it for |
|---|---|
| 01 — Spine | Product architecture, proven milestones and current direction |
| 02 — Developer Code Map | Studio ownership, implementation, extension and debugging |
| 03 — Generated Export API Code Map | Generated firmware APIs, hooks, files and export boundaries |
| 04 — Feature Status | Current implementation and evidence status |
| 05 — Internal Developer Guide | Architecture, widget pipeline, parity, testing and proof workflow |
| 05 — Developer Hardware Integration | Connecting ForgeUI to application code, drivers and hardware |
| 06 — OpenAI API Setup | Configuring optional OpenAI-assisted layouts and artwork |
| 07 — Runtime SDK Direction | Long-term generated SDK concept and evolution rules |
| 09 — Fi Runtime Guide | Canonical Fi pipeline, 90/95/96 ownership, generated presentation APIs and optional click hooks |
| Layout Designer Guide | Preset, Smart Region, Auto Arrange and AI Fill workflow |
| QR Code Guide | QR authoring, preview, export and validation |
| Spinbox Guide | Proven native digit editor, integer-backed decimals, APIs and physical evidence |
esp32p4-ui-studio/
├── studio/ ForgeUI Studio web application and export server
├── firmware/ ESP-IDF reference firmware and generated live output
├── docs/ Feature guides, images and archived historical documents
├── tools/ Setup and startup tooling
├── 01–07 Current architecture, status, developer and SDK documents
└── README.md Public project front page
Contributions should preserve the existing ownership boundaries, extend authoritative registries and generators instead of duplicating them, and keep generated files replaceable. Claims should identify whether evidence is automated, manually previewed, generated, built, flashed or physically exercised.
ForgeUI builds on open-source projects including LVGL, ESP-IDF, React, Next.js and Chakra UI. Review the repository and firmware license/attribution files before redistribution.
- GitHub repository
- ForgeUI Developer Portal
- Contact:
forgeui.esp32@gmail.com
Standard Fi Icons now generate optional component-name-based presentation APIs
in 96_FiRuntime.c/.h and optional click hooks in 95_UserEvents. Runtime API
generation defaults on; click defaults off. The canonical 92% icon renderer and
used-asset gating remain shared by Canvas, Browser Preview, Live and Standalone.
The overall feature is SOFTWARE COMPLETE / PARTIALLY PHYSICALLY PROVEN and
does not change the current 34/39 Standard widget proof total. ESP32-P4 evidence proves
the 90 → 95 click path across three independent collision-safe callbacks, with
exactly one callback per deliberate tap and none at startup. The 90 → 96
presentation path remains pending hardware proof for color, opacity, hide/show,
pre-bind retention, repeated silent setters, independent instances and
Standalone parity; click-disabled non-interaction also remains open. Icon and
the complete Fi Runtime are not yet fully PROVEN. See the
Fi Runtime Guide.