suyushi/esp32-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial: knowledge base

Browse Source
This commit is contained in:
suyushi
2026-08-05 17:25:09 +08:00
parent bfabe83832
commit 5700eb4115
35 changed files with 5140 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/lvgl_README.md
+190
View File
@@ -0,0 +1,190 @@
# 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