Core_Platform_&_Infrastructure is the foundational layer of the ESP3D-X CNC pendant firmware. It owns the complete firmware lifecycle from the ESP-IDF app_main entry point through all subsystem initialization, and provides the shared services every other module depends on: persistent settings, the inter-module message bus, the [ESPxxx] command dispatcher, an observable runtime state system, a structured logging subsystem with pluggable backends, a multi-language translation service, and a centralized user-activity tracking system. All other modules (UI, CNC integration, network, transports) build on the services defined here.
Core Platform & Infrastructure
entry_point
esp3d_core
esp3d_commands
esp3d_log
values
translations
esp3d_activity_manager
ESP3DXNetwork ESP3DXStream ESP3DXUi (LVGL task Core 1) ESP3DTranslationService ESP3DValues esp3d_log_init() ESP3DSettings board_init() nvs_flash ESP3DX::begin() app_main() ESP-IDF Runtime ESP3DXNetwork ESP3DXStream ESP3DXUi (LVGL task Core 1) ESP3DTranslationService ESP3DValues esp3d_log_init() ESP3DSettings board_init() nvs_flash ESP3DX::begin() app_main() ESP-IDF Runtime app_main() [Core 0] ESP3DX::begin() esp3d_log_init() nvs_flash_init() board_init() - display, touch, LVGL tick validate NVS schema / reset() if needed initialize() - allocate buffer pool begin() - pin LNG1 blob from partition begin() - spawn tft_ui_task on Core 1 begin() - GCode pipeline begin() - WiFi or BT networkTask
ESP3DValues
esp3d_log
Screen Callback LVGL Task (Core 1) Update Queue (30 slots) ESP3DValues Transport Task (Core 0) Screen Callback LVGL Task (Core 1) Update Queue (30 slots) ESP3DValues Transport Task (Core 0) loop [every LVGL tick] set_value(index, "1.234", Update) enqueue (or replace duplicate) handle() dequeue → write buffer pool snapshot subscriber list invoke callbacks (outside mutex) update LVGL widget (safe on Core 1) Sub-module Path Role entry_pointmain/main.cppThin app_main bridge → ESP3DX::begin() esp3d_coremain/core/ESP3DX, ESP3DSettings, ESP3DJsonSettings, ESP3DClient/ESP3DMessage, ESP3DCommands, esp3d_hal, LVGL snapshot utilities, system message history, string helpersesp3d_commandsmain/core/commands/[ESP0]–[ESP950] handler implementationsesp3d_logcomponents/esp3d_log/Severity-gated macros (esp3d_log, _d, _w, _e), mutex-serialized output, 5 pluggable backends, runtime hook API valuesmain/modules/values/ESP3DValues pub/sub bus — single-block pool, circular update queue, subscriber linked lists, all callbacks on Core 1esp3d_activity_managercomponents/esp3d_activity_manager/BSP input aggregation → inactivity timeout → backlight fade/wake, first-touch suppression translationsmain/modules/translations/ESP3DTranslationService — LNG1 blob binary search in mmapped flash, English .rodata fallback, SD-card language pack update
Constraint Detail LVGL runs on Core 1 only Never call LVGL APIs from Core 0 tasks or ISRs ESP3DValues::handle() called from LVGL taskAll subscriber callbacks are therefore UI-safe Log macros compile to zero at ESP3D_LOG=0 Always wrap in {} to prevent dangling if when logging is stripped NVS writes serialized by mutex Non-recursive; never call write from within a read callback Buffer pool single-block allocation Minimizes heap fragmentation on ~10 KB available heap (BT mode) std::string in hot paths forbiddenUse snprintf into fixed buffers; protect any std::string with try/catch(std::bad_alloc)
Document Content docs/guides/esp32_memory_constraints.mdHeap fragmentation playbook; worst-case RAM budgets per config docs/guides/esp3d_log_guide.mdLog macro levels, backend selection, runtime hook registration docs/architecture/connection_management.mdHow transports set connection_status and server_status observable values docs/architecture/gcode_host_architecture.mdHow GCode handlers write CNC values into ESP3DValues docs/architecture/screens_architecture.mdHow UI screens subscribe to values and respond via callbacks docs/ui_resources/development.mdui_resources partition format; font/image/language blob pipelinedocs/features/feature_resource_matrix.mdFeature-flag compatibility matrix; mutual exclusion rules cmake/sanity_check.cmakeBuild-time enforcement of feature flag constraints
