191 lines
8.1 KiB
Markdown
191 lines
8.1 KiB
Markdown
# 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
|