{"id":42351039,"url":"https://github.com/chiefenne/lvgl_simulator","last_synced_at":"2026-01-27T16:04:22.259Z","repository":{"id":326214871,"uuid":"1104537077","full_name":"chiefenne/LVGL_Simulator","owner":"chiefenne","description":"Complete LVGL v9.4 project template with desktop simulator for rapid GUI development. Build interfaces on macOS/Linux/Windows, then deploy to ESP32. Shared GUI code, custom fonts, and modern C++17.","archived":false,"fork":false,"pushed_at":"2025-11-27T09:42:45.000Z","size":4153,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-29T09:53:15.132Z","etag":null,"topics":["cpp","embedded","esp32","gui","lvgl","sdl2","simulator"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chiefenne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-26T10:49:39.000Z","updated_at":"2025-11-28T01:08:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chiefenne/LVGL_Simulator","commit_stats":null,"previous_names":["chiefenne/lvgl_simulator"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chiefenne/LVGL_Simulator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiefenne%2FLVGL_Simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiefenne%2FLVGL_Simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiefenne%2FLVGL_Simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiefenne%2FLVGL_Simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chiefenne","download_url":"https://codeload.github.com/chiefenne/LVGL_Simulator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chiefenne%2FLVGL_Simulator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28816422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T12:25:15.069Z","status":"ssl_error","status_checked_at":"2026-01-27T12:25:05.297Z","response_time":168,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","embedded","esp32","gui","lvgl","sdl2","simulator"],"created_at":"2026-01-27T16:03:51.579Z","updated_at":"2026-01-27T16:04:22.251Z","avatar_url":"https://github.com/chiefenne.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LVGL Project Template and Simulator\n\nA complete LVGL v9.4 project template with desktop simulator and embedded firmware support. Build once, run everywhere - from desktop preview to ESP32 hardware.\n\n\u003e **Note:** This is a personal project template tailored to my workflow. If you're looking for other LVGL simulator options, check out the [official LVGL PC port](https://github.com/lvgl/lv_port_pc_vscode) or the [LVGL GUI Builder](https://github.com/qdsang/lv_gui_builder).\n\n**The key advantage:** Develop your GUI entirely on your computer (macOS, Linux, or Windows) without the slow upload-test-debug cycle of embedded development. The simulator lets you iterate quickly - make changes, rebuild in seconds, and see results immediately. No need to flash firmware, wait for uploads, or physically interact with hardware during GUI development.\n\nThe GUI code is **completely independent** from the program logic - you design the interface, perfect the look and feel, and test the user experience entirely in the simulator. Once satisfied, the same GUI code deploys to your embedded device without modification. The separation means you can develop beautiful, responsive interfaces fast on your desktop, then integrate with hardware logic later.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/example_01_new.png\" width=\"320\"\u003e\u003cbr\u003e\n  \u003cem\u003eLVGL Simulator running on macOS for 320×240 display size\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/example_02.gif\" width=\"320\"\u003e\u003cbr\u003e\n  \u003cem\u003eNavigation menu with HOME, previous/next, and settings buttons\u003c/em\u003e\n\u003c/p\u003e\n\n## Features\n\n- **Desktop Simulator**: Fast GUI development with SDL2 (macOS/Linux/Windows)\n- **Embedded Ready**: ESP32/PlatformIO firmware skeleton included\n- **Shared GUI Code**: Write your interface once, use it everywhere\n- **Page-Based Navigation**: Multi-page architecture with built-in navigation system\n- **Full-Screen Rendering**: Optimized for smooth 320×240 displays\n- **Custom Fonts**: Easy integration of LVGL-converted fonts\n- **Modern C++17**: Clean, maintainable codebase\n\n## Project Structure\n\n```\nLVGL_Template/\n├── simulator/              # Desktop preview (macOS/Linux/Windows)\n│   ├── main.cpp           # SDL2 wrapper for LVGL\n│   ├── sim_state.cpp      # Mock data provider\n│   └── build_sim.sh       # One-click build script\n│\n├── firmware/              # ESP32/PlatformIO project\n│   ├── platformio.ini\n│   └── src/\n│       ├── main.cpp       # Arduino setup()/loop()\n│       └── state_provider.cpp  # Hardware data interface\n│\n├── gui/                   # Shared GUI code\n│   ├── gui.cpp/h         # Main GUI initialization\n│   ├── gui_data.h        # Data structure interface\n│   ├── fonts/            # Custom LVGL fonts (.c files)\n│   └── pages/            # Screen implementations\n│       ├── page_home.cpp/h\n│       └── ...\n│\n├── lvgl/                 # LVGL library (v9.4.0)\n└── template_files/       # Configuration templates\n```\n\n## Quick Start\n\n### Prerequisites\n\n- **macOS/Linux**: clang/gcc, CMake, SDL2\n- **macOS**: `brew install sdl2 cmake`\n- **Ubuntu/Debian**: `sudo apt install libsdl2-dev cmake build-essential`\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/yourusername/LVGL_Template_2025.git\n   cd LVGL_Template_2025\n   ```\n\n2. **Download and build LVGL**\n   ```bash\n   curl -L https://github.com/lvgl/lvgl/archive/refs/tags/v9.4.0.tar.gz -o lvgl.tar.gz\n   tar -xzvf lvgl.tar.gz\n   rm lvgl.tar.gz\n   mv lvgl-9.4.0 lvgl\n   cp template_files/lv_conf.h lvgl/\n   ```\n\n3. **Build LVGL library**\n   ```bash\n   cd lvgl\n   mkdir -p build \u0026\u0026 cd build\n   cmake .. -DCMAKE_BUILD_TYPE=Release -DLVGL_BUILD_STATIC=ON\n   # for 8 processors\n   make -j8\n   # we go from lvgl/build to lvgl\n   cd ..\n   ln -sf build/lib/liblvgl.a liblvgl.a\n   # we go from lvgl to the templates root folder\n   cd ..\n   ```\n\n4. **Build and run simulator**\n   ```bash\n   bash simulator/build_sim.sh\n   ./binaries/lvgl_simulator_macOS\n   ```\n\n   **Note:** The build script `simulator/build_sim.sh` must be run from the project root directory and is currently configured for macOS. For Linux or Windows, you'll need to adapt the compiler flags and library paths in the script.\n\n## Customization\n\n### Adding Custom Fonts\n\n1. Convert TTF fonts using [LVGL Font Converter](https://lvgl.io/tools/fontconverter)\n2. Save the generated `.c` file to `gui/fonts/`\n3. Declare in `fonts.h`:\n   ```cpp\n   extern const lv_font_t lv_font_yourfont_24;\n   #define FONT_CUSTOM (\u0026lv_font_yourfont_24)\n   ```\n4. Fonts are automatically compiled by `build_sim.sh`\n\n### Creating New Pages\n\n1. Create `gui/pages/page_yourname.cpp` and `.h`\n2. Implement `page_yourname_create(lv_obj_t* parent)`\n3. Add to `gui.h` enum and `gui.cpp` switch statement\n\n### Styling\n\nModify colors and layout constants in `gui/gui.cpp`:\n```cpp\nstatic const lv_color_t COLOR_HEADER = lv_color_hex(0x1C5C8C);\nstatic const lv_coord_t HEADER_HEIGHT = 36;\n```\n\n## Configuration\n\n- **Display size**: Edit `HRES` and `VRES` in `simulator/main.cpp`\n- **Color depth**: Set `LV_COLOR_DEPTH` in `lvgl/lv_conf.h` (default: 16-bit RGB565)\n- **Render mode**: Full-screen rendering enabled by default for stability\n\n## Architecture Notes\n\n### GUI Layout Structure\n\nThe template uses a **three-area layout** that can be adapted to your application needs:\n\n- **Header Area** (36px): Displays page title and navigation context\n- **Content Area** (dynamic): Main application content, changes per page\n- **Footer Area** (32px): Navigation and settings controls\n\n**Current Implementation:**\n- Footer contains a HOME button for navigation\n- Ready to expand with additional navigation controls\n\n**Planned Enhancements:**\n- 4-button footer layout: HOME, ◄ (backward), ► (forward), SETTINGS (⚙)\n- Navigation arrows using LVGL symbols or custom icons\n- Settings button with gear symbol instead of text\n- Header updates to show current page context\n\nThis layout structure is defined in `gui/gui.cpp` and can be customized for different screen sizes and application requirements.\n\n### Rendering Strategy\n\nThe simulator uses **full-screen rendering mode** for simplicity and reliability:\n- Set via `lv_display_set_render_mode(disp, LV_DISPLAY_RENDER_MODE_FULL)`\n- Always redraws the entire 320×240 display on updates\n- Avoids partial update complications (stride handling, offset calculations)\n- Performance is excellent for this display size (~76KB per frame)\n- Eliminates rendering artifacts from incomplete updates\n\n### Font Compilation\n\nCustom fonts must be compiled as C (not C++) to avoid name mangling:\n```bash\nclang -c gui/fonts/*.c  # Preserves extern \"C\" linkage\n```\nThe build script automatically handles this for all `.c` files in `gui/fonts/`.\n\n## Troubleshooting\n\n**Black screen or corrupted graphics?**\n- Ensure `LV_COLOR_DEPTH` matches SDL pixel format (RGB565 = 16-bit)\n- Verify draw buffer is properly initialized\n\n**Font linking errors?**\n- Check fonts are being compiled with `clang -c` (not `clang++`)\n- Verify font declarations in `fonts.h` match `.c` file names\n\n**Button rendering issues?**\n- Full-screen render mode is enabled by default to prevent partial update artifacts\n\n## License\n\nThis template is provided as-is for educational and commercial use. LVGL is licensed under MIT.\n\n## Contributing\n\nContributions welcome! Please open an issue or PR for improvements.\n\n## Resources\n\n- [LVGL Documentation](https://docs.lvgl.io/)\n- [LVGL Forum](https://forum.lvgl.io/)\n- [Font Converter](https://lvgl.io/tools/fontconverter)\n- [Image Converter](https://lvgl.io/tools/imageconverter)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchiefenne%2Flvgl_simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchiefenne%2Flvgl_simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchiefenne%2Flvgl_simulator/lists"}