# LVGL Reference Index > **类别：reference** | **芯片：cross-platform** | **主题：LVGL 图形库参考索引** > Top-level index for all LVGL version references, migration guides, and ESP32 compatibility notes. > Structured for AI agent consumption during ESP32 GUI development tasks. --- ## Directory Structure ``` references/lvgl/ ├── README.md # This file - top-level index ├── migration/ │ ├── v8-to-v9.md # Definitive v8 -> v9 migration guide │ └── version-matrix.md # Feature/widget/API matrix across versions ├── v8.2/ # v8.2 API reference (if populated) ├── v8.3/ # v8.3 API reference (if populated) ├── v8.4/ # v8.4 API reference (if populated) ├── v9.0/ # v9.0 API reference (if populated) ├── v9.1/ # v9.1 API reference (if populated) ├── v9.2/ # v9.2 API reference (if populated) ├── v9.3/ # v9.3 API reference (if populated) ├── v9.4/ # v9.4 API reference (if populated) └── v9.5/ # v9.5 API reference (if populated) ``` --- ## Version Selection Guide ### Quick Decision Tree ``` Starting a new ESP32 GUI project? ├── ESP32-S3 or ESP32-P4 (with PSRAM)? │ └── Use v9.5 (latest stable, full feature set) ├── ESP32 original with PSRAM? │ └── Use v9.5 (good fit with PSRAM for buffers) ├── ESP32-C3/C6/H2 (no PSRAM)? │ └── Use v8.4 (lower memory footprint) ├── Need maximum community examples/tutorials? │ └── Start with v8.3 (most content available) └── Need GPU acceleration or vector graphics? └── Use v9.5 (only option with draw pipeline + ThorVG) Migrating an existing project? ├── Currently on v7? │ └── Migrate directly to v9.5 (skip v8) ├── Currently on v8 and working fine? │ ├── Need v9 features? → Migrate to v9.5 │ └── No new needs? → Stay on v8.4 └── Currently on v9.0-v9.4? └── Upgrade to v9.5 (backward compatible within v9) ``` --- ## Version Timeline ``` 2020 2021 2022 2023 2024 2025 | | | | | | v7.0 v8.0 v8.3 v8.3.9 v9.0 v9.1 v9.2 v9.5 May Jun Jul Aug Jan Mar Aug Feb | | | v7.9 v8.4 v9.4 Jan Mar Oct | v9.3 Jun ``` ### Major Version Eras - v7 era：Versions=7.0 - 7.9, Period=May 2020 - Jan 2021, Key Characteristics=Legacy style system, basic layout - v8 era：Versions=8.0 - 8.4, Period=Jun 2021 - Mar 2024, Key Characteristics=Flexbox/grid, CSS-like styles, mature ecosystem - v9 era：Versions=9.0 - 9.5+, Period=Jan 2024 - present, Key Characteristics=New driver API, draw pipeline, observer, built-in drivers --- ## Migration Guides - v8.x to v9.x：Document=[migration/v8-to-v9.md](migration/v8-to-v9.md), Effort Level=High - Version comparison：Document=[migration/version-matrix.md](migration/version-matrix.md), Effort Level=Reference ### Migration Effort Summary - v8.3：To=v8.4, Breaking Changes=None, Compatibility Layer=N/A, Estimated Effort=Trivial (recompile) - v8.x：To=v9.0+, Breaking Changes=Major, Compatibility Layer=`lv_api_map_v8.h` (partial), Estimated Effort=2-5 days typical - v9.x：To=v9.y, Breaking Changes=None, Compatibility Layer=N/A, Estimated Effort=Trivial (recompile) - v7.x：To=v9.x, Breaking Changes=Extreme, Compatibility Layer=`lv_api_map_v7.h` + `v8.h`, Estimated Effort=5-10 days typical --- ## ESP32 Compatibility Summary ### Recommended LVGL Version by ESP32 Chip - ESP32 (original)：PSRAM=None, Recommended LVGL=v8.4, Rationale=RAM too limited for v9 - ESP32 (original)：PSRAM=4MB+, Recommended LVGL=v9.5, Rationale=PSRAM compensates for v9 RAM usage - ESP32-S2：PSRAM=None, Recommended LVGL=v8.4, Rationale=320KB RAM, too tight for v9 - ESP32-S2：PSRAM=2MB+, Recommended LVGL=v9.5, Rationale=Viable with PSRAM - ESP32-S3：PSRAM=2-8MB, Recommended LVGL=v9.5, Rationale=Ideal target for v9 - ESP32-C3：PSRAM=None, Recommended LVGL=v8.4, Rationale=No PSRAM, 400KB RAM - ESP32-C5：PSRAM=None, Recommended LVGL=v8.4, Rationale=Limited RAM, no PSRAM - ESP32-C6：PSRAM=None, Recommended LVGL=v8.4 or v9.5, Rationale=512KB RAM, monitor usage - ESP32-H2：PSRAM=None, Recommended LVGL=v8.4, Rationale=320KB RAM, BLE-focused chip - ESP32-P4：PSRAM=Up to 32MB, Recommended LVGL=v9.5, Rationale=Best ESP32 for GUI workloads ### ESP-IDF Version Compatibility - v8.3/v8.4：ESP-IDF 4.4=Yes, ESP-IDF 5.0=Yes, ESP-IDF 5.1=Yes, ESP-IDF 5.2+=Yes - v9.0-v9.2：ESP-IDF 4.4=Yes, ESP-IDF 5.0=Yes, ESP-IDF 5.1=Yes, ESP-IDF 5.2+=Yes - v9.3-v9.5：ESP-IDF 4.4=No, ESP-IDF 5.0=Yes, ESP-IDF 5.1=Yes, ESP-IDF 5.2+=Yes ### Integration Methods for ESP32 1. **ESP Component Registry** (recommended for ESP-IDF): Add `lvgl/lvgl` to `idf_component.yml` 2. **esp_lvgl_port**: Official ESP-IDF LVGL port with driver integration (supports v8 and v9) 3. **PlatformIO**: Add to `platformio.ini` lib_deps 4. **Arduino Library Manager**: Search "lvgl" in Library Manager 5. **Git submodule**: Manual integration into project --- ## Version Folder Contents Each version folder (`v8.2/`, `v8.3/`, etc.) is intended to contain: - API reference summaries for that specific version - Widget documentation snapshots - Configuration templates (`lv_conf.h` defaults) - ESP32-specific notes and tested configurations - Known issues and workarounds ### Currently Populated - `v8.2/`：Status=Empty, Contents=Placeholder - `v8.3/`：Status=Empty, Contents=Placeholder - `v8.4/`：Status=Empty, Contents=Placeholder - `v9.0/`：Status=Empty, Contents=Placeholder - `v9.1/`：Status=Empty, Contents=Placeholder - `v9.2/`：Status=Empty, Contents=Placeholder - `v9.3/`：Status=Empty, Contents=Placeholder - `v9.4/`：Status=Empty, Contents=Placeholder - `v9.5/`：Status=Empty, Contents=Placeholder --- ## Key Differences Between Major Versions (Summary) ### v8 Highlights - Flexbox and grid layout support - CSS-like cascading style system with local styles per widget - `lv_disp_drv_t` / `lv_indev_drv_t` struct-based driver model - `lv_meter` widget for gauge displays - `lv_msg` messaging system - `lv_coord_t` coordinate type - Buffer sizes in pixels - Abbreviated API names (`btn`, `img`, `disp`, `scr`) ### v9 Highlights - New display/indev API: opaque types with setter functions - Draw pipeline architecture (task-based, GPU-extensible) - Parallel rendering support - Observer pattern replacing `lv_msg` - Built-in drivers (SDL, Linux FB, TFT_eSPI, ST7789, ILI9341) - `lv_scale` widget (replaces `lv_meter` ticks) - ThorVG vector graphics on Canvas - Full-word API names (`button`, `image`, `display`, `screen`) - `lv_color_t` always RGB888 internally - Buffer sizes in bytes - Kconfig full support - Built-in OS abstraction (pthread, FreeRTOS) - Runtime color format adjustment - `lv_coord_t` removed (use `int32_t`) --- ## External Resources - LVGL Official Docs (latest)：URL=https://docs.lvgl.io/master/, Description=v9.6 development docs - LVGL v8.3 Docs：URL=https://docs.lvgl.io/8.3/, Description=Last major v8 docs - LVGL GitHub：URL=https://github.com/lvgl/lvgl, Description=Source code and releases - LVGL Forum：URL=https://forum.lvgl.io/, Description=Community support - ESP Component Registry：URL=https://components.espressif.com/components/lvgl/lvgl, Description=ESP-IDF integration - lv_api_map_v8.h：URL=https://github.com/lvgl/lvgl/blob/master/src/lv_api_map_v8.h, Description=v8 compatibility macros - ESP32 LVGL Tips：URL=https://docs.lvgl.io/master/integration/chip_vendors/espressif/tips_and_tricks.html, Description=ESP32-specific optimization