# lvgl_prot_st7789

**Repository Path**: NetADs/lvgl_prot_st7789

## Basic Information

- **Project Name**: lvgl_prot_st7789
- **Description**: drv_lcd_st7789v驱动层与LVGL的薄桥接组件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# lvgl_port_st7789

LVGL 与 ST7789V 硬件驱动的桥接组件。通过 `drv_lcd_st7789v` 驱动芯片。

本组件是 LVGL（GUI 框架）和裸机 ST7789V 驱动之间的**粘合层**——两者互不知晓对方的存在。

```
  LVGL  ──flush_cb──→  lvgl_port_st7789  ──lcd_draw_bitmap──→  drv_lcd_st7789v
```

---

## 为什么独立成组件？

| 桥接代码放在... | 问题 |
|---|---|
| `drv_lcd_st7789v` 内部 | 强制裸机/裸画图用户依赖 LVGL |
| 应用层 `main.c` | 难以跨项目复用；应用与驱动内部耦合 |
| **独立组件** | 职责清晰；可复用；GUI 框架可替换 |

---

## 目录结构

```
lvgl_port_st7789/
├── CMakeLists.txt              # 构建入口 — REQUIRES lvgl + drv_lcd_st7789v
├── idf_component.yml           # 组件清单
├── Kconfig                     # 绘制缓冲区行数 / 双缓冲开关
├── include/
│   └── lvgl_port_st7789.h      # 公共 API
├── src/
│   └── lvgl_port_st7789.c      # flush 回调 + 初始化序列（约 130 行）
└── README.md
```

---

## 快速开始

### 1. 添加到项目

```yaml
# main/idf_component.yml
dependencies:
  lvgl_port_st7789:
    path: ../../components/lvgl_port_st7789
```

### 2. 通过 menuconfig 配置

```
idf.py menuconfig
  → Component config
    → LVGL Port for ST7789V
      - 绘制缓冲区行数（默认：20）
      - 双缓冲（默认：关闭）
```

### 3. 编写 `main.c`

```c
#include "lvgl_port_st7789.h"
#include "lvgl.h"

void app_main(void)
{
    /* 一行搞定 — LCD + LVGL + flush 回调全部就绪 */
    lcd_config_t cfg = LCD_CONFIG_DEFAULT();
    cfg.orientation = LCD_ORIENTATION_LANDSCAPE;
    ESP_ERROR_CHECK(lvgl_port_st7789_init(&cfg));

    /* LVGL 已就绪 */
    lv_obj_t *label = lv_label_create(lv_screen_active());
    lv_label_set_text(label, "Hello ST7789V!");

    while (1) {
        lv_timer_handler();
        vTaskDelay(pdMS_TO_TICKS(5));
    }
}
```

---

## API 参考

### `lvgl_port_st7789_init()`

一站式初始化。内部流程：
1. 调用 `lcd_init()` — 硬件初始化
2. 通过 `lcd_get_resolution()` 获取当前分辨率
3. 调用 `lv_init()` — 初始化 LVGL 库
4. 创建与分辨率匹配的 LVGL display
5. 按 Kconfig 配置分配绘制缓冲区
6. 注册 flush 回调 → `lcd_draw_bitmap()`

### `lvgl_port_st7789_set_orientation()`

运行时切换屏幕方向。同时更新 ST7789V 的 MADCTL 寄存器和 LVGL 显示分辨率。UI 元素需由调用方重新布局。

### `lvgl_port_st7789_get_lcd_handle()`

返回底层 `lcd_handle_t`，用于直接访问驱动功能（背光、睡眠、gamma 曲线）。

### `lvgl_port_st7789_get_display()`

返回 LVGL 的 `lv_display_t *` 指针。

### `lvgl_port_st7789_deinit()`

释放 LVGL display、绘制缓冲区和 LCD 驱动。

---

## Kconfig 配置项

| 配置项 | 默认值 | 说明 |
|---|---|---|
| `LVGL_PORT_ST7789_BUF_LINES` | 20 | 绘制缓冲区大小（按显示行数）。20 行 × 320 像素 × 2 字节 = 12.8 KB |
| `LVGL_PORT_ST7789_DOUBLE_BUF` | n | 启用双缓冲——内存翻倍，但减少撕裂 |

---

## 使用者项目的 sdkconfig.defaults

```ini
# 必须：SPI 驱动 IRAM 访问（pre_cb 回调需要）
CONFIG_SPI_MASTER_IN_IRAM=y

# 必须：LVGL 色彩深度与 ST7789V 一致（RGB565）
CONFIG_LV_COLOR_DEPTH_16=y

# 必须：关闭 LVGL 字节交换（驱动内部已处理）
CONFIG_LV_COLOR_16_SWAP=n

# 推荐：足够栈空间用于 LVGL + SPI 轮询
CONFIG_ESP_MAIN_TASK_STACK_SIZE=4096
```

---

## 依赖关系

| 依赖 | 版本 | 角色 |
|---|---|---|
| ESP-IDF | ≥ 5.0.0 | 构建系统 + driver/ledc/spi |
| `drv_lcd_st7789v` | ≥ 1.1.0 | 硬件驱动（本地路径） |
| `lvgl/lvgl` | ≥ 9.0, < 10 | GUI 框架 |

---

## 线程安全

非线程安全——与 LVGL 和 drv_lcd_st7789v 的约束一致。
所有 API 调用必须在同一个 RTOS 任务中进行（通常为 LVGL timer 任务）。

---

## 许可证

MIT License — 与 drv_lcd_st7789v 和 LVGL 兼容。