kevincoooool/ksdiy_s31_43_bsp

Readme (zh)

# KSDIY ESP32-S31 4.3 寸 RGB In-cell 屏幕 BSP

[English](README.md)

面向 KSDIY ESP32-S31 开发板和 YDP430BET010-V1 屏幕的 ESP-IDF 板级组件：
480×800 ST7102 RGB LCD、ST7123 In-cell 触摸、共用复位、PWM 背光及 LVGL 9。
这是指定板卡的 BSP，不是任意 ST7102 模组都可直接套用的通用驱动。

## 安装与使用

```sh
idf.py add-dependency "kevincoooool/ksdiy_s31_43_bsp^0.1.0"
```

```c
#include "bsp/esp-bsp.h"

void app_main(void)
{
    bsp_display_start();
    ESP_ERROR_CHECK(bsp_display_brightness_set(80));
    if (bsp_display_lock(0)) {
        lv_obj_t *label = lv_label_create(lv_screen_active());
        lv_label_set_text(label, "Hello RGB in-cell");
        lv_obj_center(label);
        bsp_display_unlock();
    }
}
```

需要支持 ESP32-S31 的 ESP-IDF >=6.1、LVGL 9.6.x 和 PSRAM。
已验证的点屏环境使用 ESP-IDF 6.2 开发树。示例的 Flash/PSRAM 参数针对
16 MB Flash、Octal 250 MHz PSRAM 板卡，其他硬件应使用自己的电气参数。
普通应用通过 `bsp_display_lock()` / `bsp_display_unlock()` 保护 LVGL 操作。
`timeout_ms=0` 表示一直等待锁。

## 必须保持一致的颜色设置

- LVGL 与帧缓冲使用 **RGB565/16 bpp**。
- LCD 外设硬件把 RGB565 转为 RGB888，`data_width=24`。
- 面板使用 `COLMOD=0x77`，每色只连接高 6 位，共 **18 根实际数据线**。
- 六个未引出的低位槽位为 `GPIO_NUM_NC`，不是 GPIO0。
- 这不是 RGB666/MDT 配置，也不能把外设位宽直接设为 18。
- 默认 PCLK=25.2 MHz，固定 porch 下帧率约 43.9 Hz。

板上原始色条、灰阶、单个位和白字已验证改善：旧的 16 线/0x55 接法会导致
梯度周期性回绕、灰/青跳变和字体彩边。单纯三原色显示正确不能证明位权正确。
该验证不是仪器校色，也不代表其他模组或所有运行条件均已验证。

## 默认引脚

| 功能 | GPIO |
|---|---|
| 命令 SDA / SCK / CS | 12 / 13 / 14，9-bit 三线 SPI |
| PCLK / DE / VSYNC / HSYNC | 15 / 16 / 17 / 18 |
| B2–B7（FPC DB0–DB5） | 19, 35, 37, 38, 39, 40 |
| G2–G7（FPC DB6–DB11） | 42, 43, 44, 45, 46, 47 |
| R2–R7（FPC DB12–DB17） | 48, 49, 50, 51, 52, 53 |
| LCD+TP 共用复位 | 10，仅复位一次 |
| 背光 PWM | 11，高有效，5 kHz |
| 触摸 SCL / SDA / INT | 5 / 6 / 57，I2C 地址 0x55 |

GPIO40/B7、GPIO53/R7 都是有效数据输出，不能与相邻 GPIO 短接。
GPIO58 不是触摸中断，组件不会为了监测 AXP 中断将默认 UART0 TX 改成输入。
本组件占用 I2C 控制器 0；不要重复创建同一总线，也不要单独复位 In-cell 触摸。

## 配置

`menuconfig -> Component config -> KSDIY ESP32-S31 4.3-inch RGB in-cell BSP`
可以调整引脚、PCLK、bounce 行数、触摸轮询/中断、I2C 参数、背光极性及诊断开关。
引脚不能冲突，ESP32-S31 无 GPIO29、GPIO41。Bounce 行数必须整除 800，默认 40 行，
两个 RGB565 SRAM bounce 缓冲共 76,800 字节。

建议相关项目配置：

```ini
CONFIG_SPIRAM=y
CONFIG_FREERTOS_HZ=1000
CONFIG_LV_COLOR_FORMAT_RGB565=y
CONFIG_LV_MEM_SIZE=131072
```

## 示例

```sh
idf.py create-project-from-example "kevincoooool/ksdiy_s31_43_bsp^0.1.0:widgets_benchmark"
cd widgets_benchmark
idf.py set-target esp32s31
idf.py -p PORT build flash monitor
```

- `basic`：初始化显示和触摸，显示文字。
- `widgets_benchmark`：启动 Widgets，右下角切换 Benchmark，显示 FPS/CPU，测试结束显示汇总。
- `color_test`：保留纯色、灰阶、单个位、黑白硬边和 PCLK 对照，方便后续检查接线。

组件默认关闭启动色条、白字源数据审计和 I2C 扫描；测试函数仍在源代码中。
颜色测试中点击色块仅切换 PCLK，固定 mode 0。标题审计只用于单色诊断标题，
不能把普通彩色 Widgets 误判为错误数据。

当前默认防撕裂模式为 NONE，动态画面仍可能撕裂；更高帧率、其他防撕裂模式和
长期压力测试需另行验证。初始化异常沿用 `ESP_ERROR_CHECK` 策略。
0.1.0 提供单实例启动，不提供停止/反初始化接口；借出的 panel/touch 句柄不能由应用删除。

## 目录与兼容性

标准入口为 `bsp/esp-bsp.h`，API 见 [API.md](API.md)。保留旧的
`ksdiy_lvgl_port.h`、`ksdiy_rgb_color.h`、`ksdiy_board_pins.h` 和
`ksdiy_st7102_rgb.h`，现有应用无需立即改用新接口。
实现位于 `src/`，初始化表头文件位于 `priv_include/`，示例与组件库分离。

新增 BSP 代码采用 Apache-2.0；适配的 OSPTEK 初始化数据另保留 CC-BY-4.0 署名要求。
组件许可证表达式为 `Apache-2.0 AND CC-BY-4.0`，详见 LICENSE、LICENSES 和 NOTICE。
发布包不包含芯片手册、工程原理图或用户照片。