Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
167 lines (127 loc) · 5.18 KB

DEVELOPMENT.md

File metadata and controls

167 lines (127 loc) · 5.18 KB
Raw

SpoolBuddy Development Workflow

Overview

This document describes the UI development workflow using EEZ Studio and the LVGL simulator.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   EEZ Studio    │────▶│  Sync Script    │────▶│   Simulator     │
│  (UI design)    │     │                 │     │   (quick test)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                                               │
        │                       ┌───────────────────────┘
        │                       │
        ▼                       ▼
┌─────────────────────────────────────────┐
│            Firmware Flash               │
│         (final device test)             │
└─────────────────────────────────────────┘

Quick Start

# 1. Make changes in EEZ Studio, then Build/Export

# 2. Sync EEZ output to firmware and simulator
cd firmware
./update_eez_screens.sh

# 3. Build and test in simulator
cd ../lvgl-simulator-sdl/build
cmake --build . -j
./simulator

# 4. When ready, build and flash firmware
cd ../../firmware
cargo build --release

File Organization

Location Content
eez/ EEZ Studio project
eez/src/ui/ EEZ Studio output (source of truth for UI layout)
firmware/components/eez_ui/ Symlinks to EEZ + custom code
lvgl-simulator-sdl/ui/ Symlinks to both EEZ and firmware custom code

EEZ-Generated Files (via symlinks)

These files are generated by EEZ Studio and should not be manually edited:

  • screens.c / screens.h - Screen layouts and widget creation
  • images.c / images.h - Image references
  • ui_image_*.c - Image data
  • styles.c / styles.h - Style definitions
  • structs.h - Data structures
  • fonts.h - Font references
  • vars.h - Variables
  • actions.h - Action declarations

Custom Code Files (preserved)

These files contain our custom logic and are never overwritten by EEZ:

File Purpose
ui.c Screen navigation, button wiring, tick loop
ui_backend.c Backend communication, AMS display, printer status
ui_printer.c Printer add/edit/delete, discovery
ui_wifi.c WiFi settings and connection
ui_settings.c Settings screen tabs and navigation
ui_nvs.c NVS persistence (ESP32) / mock (simulator)
ui_scale.c Scale calibration and tare
ui_update.c Firmware update UI
ui_internal.h Shared types, macros, and declarations

Sync Script

The firmware/update_eez_screens.sh script:

  1. Applies LVGL 9.x compatibility fixes to EEZ output
  2. Fixes EEZ-generated code bugs (empty parameters, undefined enums)
  3. Creates symlinks from firmware to EEZ output
  4. Creates symlinks from simulator to EEZ output
  5. Preserves all custom code files

Simulator

The LVGL simulator (lvgl-simulator-sdl/) allows testing UI changes without flashing:

  • Uses SDL2 for display rendering
  • Connects to the backend server at http://localhost:3000
  • Mock implementations for WiFi, OTA, scale (no real hardware)
  • Same UI code as firmware via #ifdef ESP_PLATFORM guards

First-time Setup

cd lvgl-simulator-sdl
mkdir -p build && cd build
cmake ..
cmake --build . -j

Running

cd lvgl-simulator-sdl/build
./simulator

Press ESC or close the window to exit.

Adding New Custom Code

When adding new custom UI functionality:

  1. Create the file in firmware/components/eez_ui/ (e.g., ui_newfeature.c)
  2. Add #ifdef ESP_PLATFORM guards for platform-specific code
  3. Add the file to CUSTOM_FILES array in update_eez_screens.sh
  4. Run ./update_eez_screens.sh to create simulator symlink
  5. Add mock implementations to lvgl-simulator-sdl/sim_mocks.c if needed

Platform Compatibility Pattern

Use this pattern for code that differs between firmware and simulator:

#ifdef ESP_PLATFORM
// ESP32 firmware: real implementation
#include "esp_log.h"
#define MY_LOG(fmt, ...) ESP_LOGI("tag", fmt, ##__VA_ARGS__)
extern void real_hardware_function(void);
#else
// Simulator: mock/stub implementation
#define MY_LOG(fmt, ...) printf("[tag] " fmt "\n", ##__VA_ARGS__)
static void real_hardware_function(void) { /* mock */ }
#endif

Troubleshooting

Simulator won't build after EEZ changes

cd lvgl-simulator-sdl/build
rm -rf CMakeCache.txt CMakeFiles
cmake ..
cmake --build . -j

Symlinks broken

cd firmware
./update_eez_screens.sh

EEZ output has errors

The sync script automatically fixes common issues:

  • lv_img_dsc_t → lv_image_dsc_t (LVGL 9.x)
  • Empty lv_image_set_pivot() / lv_image_set_rotation() calls
  • LV_LABEL_LONG_undefined → LV_LABEL_LONG_WRAP
  • Duplicate settings identifier → settings_main