ESP3D-X Repository Overview

ESP3D-X Repository Overview

Purpose

ESP3D-X is an ESP-IDF 5.x firmware project for a touchscreen CNC pendant running on ESP32/ESP32-S3 hardware. It provides a multi-transport, multi-firmware-target pendant UI for CNC machines controlled by FluidNC, grbl, or grblHAL. The firmware handles real-time GCode streaming, machine status display, jog control, probing, file management, and remote access — all on a single constrained MCU with no external PSRAM on the primary target board.

---

End-to-End Architecture

Top-Level Module Map

---

Boot and Initialization Sequence

---

Core Data Flow

---

FreeRTOS Task Layout

---

CNC GCode Flow-Control State Machine

---

Transport Selection (Build-time)

---

WiFi / CNC Product Model

---

Core Modules Reference

Module	Path	Primary Documentation
Board Support Packages	boards/*/components/bsp/	docs/guides/board_build_guidelines.md
Hardware Peripheral Drivers	hardware/	docs/architecture/display_drivers.md, docs/architecture/Input_system.md
Core Platform & Infrastructure	main/core/, components/esp3d_log/	docs/guides/esp32_memory_constraints.md, docs/guides/esp3d_log_guide.md
UI Framework & Screens	main/display/	docs/architecture/screens_architecture.md, docs/architecture/screen_transitions_flow.md, docs/ui_resources/theme_palette.md, docs/ui_resources/ui_style_guide.md
CNC Firmware Integration	main/modules/gcode_host/, main/target/	docs/architecture/gcode_host_architecture.md, docs/architecture/gcode_host_streaming_flow.md
Communication Transports	main/modules/serial/, bt_serial/, bt_ble/, usb_serial/, socket_client/, websocket_client/	docs/architecture/connection_management.md, docs/architecture/websockets_protocol.md
Network & Web Services	main/modules/network/, wifi/, http/, websocket_server/, mdns/, ssdp/	docs/features/feature_resource_matrix.md, docs/features/mdns.md
Storage & Configuration	main/modules/filesystem/, update/, config_file/	docs/architecture/shared_sd_mechanism_V2.0.md, docs/ui_resources/development.md
Build & Development Tools	tools/	docs/guides/tools.md, docs/guides/board_build_guidelines.md
Log Backends	main/modules/log/	docs/guides/esp3d_log_guide.md

Key Architecture Documents

Document	Topic
docs/architecture/connection_management.md	Transport lifecycle, connection states (U/T/C/?/A)
docs/architecture/gcode_host_architecture.md	Core + CNC domain split, CMake wiring
docs/architecture/gcode_host_streaming_flow.md	State machine, pause/resume/abort, flow gates
docs/architecture/esp3d_message_priority_system.md	Normal vs high-priority message routing
docs/architecture/screens_architecture.md	Screen registration, GenericScreen base
docs/architecture/screen_transitions_flow.md	Safe timer-based transition idiom
docs/architecture/Input_system.md	Encoder, buttons, switch, potentiometer pipeline
docs/architecture/display_drivers.md	SPI/I80/RGB driver stack, orientation math
docs/architecture/shared_sd_mechanism_V2.0.md	SD bus arbitration between ESP32 and MCU
docs/features/feature_resource_matrix.md	Feature compatibility, WiFi/CNC SKU model
docs/guides/esp32_memory_constraints.md	Heap fragmentation, worst-case RAM budgets
docs/guides/esp3d_log_guide.md	Logging macros, backends, runtime hooks
docs/ui_resources/development.md	ui_resources partition binary format, SD update pipeline
docs/ui_resources/theme_palette.md	26 semantic color tokens, per-theme RGBA values
docs/ui_resources/ui_style_guide.md	ThemeStyles architecture, apply* function catalog
docs/guides/ui_resources_guide.md	Adding icons and fonts, SD-card update workflow
docs/hardware/pibot-cnc-pendant-hardware-documentation.md	Physical pendant hardware reference

Build Commands

# Build for a specific board/variant
idf.py build

# Flash and monitor
idf.py flash monitor

# Multi-board build (via build manager)
python tools/build_scripts/build_mgr.py

# Generate UI resources partition
python tools/build_scripts/generate_resources.py

# Launch UI Studio (theme/image/font editor)
cd tools/ui_studio && python app.py

---

Module Documentation

Module	Content
Board_Support_Packages	The 18 supported boards: BSP, factory apps, bootloaders, build scripts
Hardware_Peripheral_Drivers	Display drivers (SPI/I80/RGB), touch, physical inputs, buses, buzzer
Core_Platform_&_Infrastructure	Entry point, esp3d_core, [ESPxxx] commands, observable values, logs, translations
UI_Framework_&_Screens	LVGL framework, reusable components, generic and CNC screens (FluidNC/grbl/grblHAL)
CNC_Firmware_Integration	G-code host, streaming, FluidNC / grbl / grblHAL protocol parsers
Communication_Transports	UART, Bluetooth SPP/BLE, USB OTG, TCP sockets, WebSocket client
Network_&_Web_Services	WiFi, HTTP/WebUI server, WebSocket server, mDNS, SSDP, authentication
Storage_&_Configuration	File systems (flash/SD), update service, INI config file
Build_&_Development_Tools	Build scripts, firmware simulator, UI Studio, communication clients
embedded_webui	Minimal embedded web page (terminal, files, update) served from flash
logging_backends	Backends de journalisation (seriemoniteur, SD, reseau)

---

Related modules

• logging_backends

Developer Guides (tutorials)

Practical guides to extend the firmware (extracted from the DeepWiki analysis):

• guide_development — overview of the guides
• guide_build_system — build system and feature flags
• guide_adding_screens — add a screen
• guide_adding_settings — add a persistent setting
• guide_adding_realtime_values — add a real-time value
• guide_extending_gcode — extend G-code support
• guide_translations — work with translations
• guide_custom_ui_components — create a UI component
• guide_debugging — debugging and testing

Additional references:

• settings_reference — complete settings catalog (NVS keys, types, defaults)
• glossary — project glossary

Design documents (repository)

• features.md
• feature_resource_matrix.md
• esp32_memory_constraints.md
• user_documentation