kevincoooool/ksdiy_s31_43_bsp

Readme

# KSDIY ESP32-S31 4.3-inch RGB In-cell BSP

[中文说明](README_CN.md)

ESP-IDF board support package for the KSDIY ESP32-S31 board with a
**YDP430BET010-V1, 480 x 800, ST7102 RGB LCD and ST7123 in-cell touch**.
It integrates the panel, shared reset, PWM backlight, I2C touch and LVGL 9.
This is a board-specific BSP, not a generic driver for every ST7102 module.

## Supported configuration

| Item | Configuration |
|---|---|
| Target | ESP32-S31 |
| ESP-IDF | >= 6.1 with ESP32-S31 support; bring-up used the 6.2 development tree |
| LVGL | 9.6.x |
| Framebuffer / LVGL | RGB565, 16 bits per pixel, allocated in PSRAM |
| LCD peripheral | RGB565 -> RGB888 hardware conversion, 24-bit slots |
| Physical data bus | 18 GPIOs: upper six bits of B, G and R |
| Panel COLMOD | `0x77` (RGB888), not `0x55` |
| Default pixel clock | 25.2 MHz; fixed porches give approximately 43.9 Hz |
| Touch | ST7123, 7-bit I2C address `0x55`, polling by default |

The full 18-line mapping was checked on the board using primary colors,
gray ramps, individual data bits and white text. The previous 16-wire/0x55
configuration produced repeating ramps and colored text fringes.
This is not a color calibration or a claim of validation on other boards.

**Do not change LVGL to RGB888 just because the panel output is RGB888.**
The framebuffer stays RGB565; conversion happens in the LCD peripheral.
Do not configure `data_width=18`: this BSP uses 24 peripheral bit slots,
six NC entries and 18 connected data GPIOs. This is not an RGB666/MDT setup.

## Installation

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

Include the standard BSP entry point:

```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)) {  // 0: wait forever
        lv_obj_t *label = lv_label_create(lv_screen_active());
        lv_label_set_text(label, "Hello, 4.3-inch RGB in-cell");
        lv_obj_center(label);
        bsp_display_unlock();
    }
}
```

Initialize from a task. Use the display lock around application LVGL calls.
The BSP owns one display, one touch device and I2C controller 0. Do not create
another owner for the same bus, reset the touch separately, or delete borrowed
panel/touch handles. Initialization failures follow the existing
`ESP_ERROR_CHECK` policy. Shutdown/deinitialization is not provided in 0.1.0.

## Project configuration

Enable PSRAM and choose the flash/PSRAM settings appropriate to your board.
The examples include defaults for the tested 16 MB flash / octal 250 MHz PSRAM
board. Do not copy those electrical settings to a different board blindly.

Minimum relevant LVGL settings:

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

Configure the BSP under **Component config -> KSDIY ESP32-S31 4.3-inch RGB in-cell BSP**.
Settings include pixel clock, bounce buffer size, GPIOs, touch interrupt/polling,
I2C speed/address, backlight polarity and diagnostics. Bounce lines must divide
800 exactly; the default is 40 lines, requiring two 38,400-byte SRAM buffers.
ESP32-S31 has no GPIO29 or GPIO41; select valid, distinct output pins and respect
the board's other peripheral connections.

## Default wiring

| Signal | GPIO / mapping |
|---|---|
| LCD command SDA / SCK / CS | 12 / 13 / 14; 9-bit 3-wire SPI |
| PCLK / DE / VSYNC / HSYNC | 15 / 16 / 17 / 18 |
| B2..B7, FPC DB0..DB5 | 19, 35, 37, 38, 39, 40 -> peripheral D2..D7 |
| G2..G7, FPC DB6..DB11 | 42, 43, 44, 45, 46, 47 -> peripheral D10..D15 |
| R2..R7, FPC DB12..DB17 | 48, 49, 50, 51, 52, 53 -> peripheral D18..D23 |
| Peripheral D0/1, D8/9, D16/17 | Not connected; `GPIO_NUM_NC` |
| Shared LCD + touch reset | 10, active low, reset once |
| Backlight | 11, 5 kHz PWM, active high |
| Touch SCL / SDA / INT | 5 / 6 / 57 |

GPIO40 and GPIO53 are active data outputs. Do not tie them to neighboring bits.
GPIO58 is not used as the touch interrupt; the BSP avoids reconfiguring it for
optional AXP interrupt monitoring because it is the S31 default UART0 TX.

## Examples

| Example | Behavior |
|---|---|
| `basic` | Start display/touch and show a label |
| `widgets_benchmark` | Widgets page, Benchmark page, touch navigation and FPS/CPU |
| `color_test` | Preserved raw colors, bit weights, gray ramps and clock comparison |

```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
```

Replace `widgets_benchmark` with `basic` or `color_test` for the other examples.
To work from a source archive, enter the corresponding `examples/` directory;
the example manifest's `override_path` uses the local BSP copy.

Color-test functions are retained. Raw tests, title-pixel audit and startup I2C
scans are disabled by default. The title audit is meaningful only for the
monochrome diagnostic title, not arbitrary color interfaces.
The default LVGL adapter mode is `NONE`; dynamic content can tear. Anti-tearing,
higher frame rates and long-term stress behavior require separate validation.

## API and compatibility

See [API.md](API.md) for the BSP API. Existing `ksdiy_lvgl_port.h`,
`ksdiy_rgb_color.h`, `ksdiy_board_pins.h` and `ksdiy_st7102_rgb.h` includes are
retained. The source files now live under `src/`; initialization-table details
are private. Examples and application UI are not linked into the BSP library.

## License and attribution

New BSP integration is Apache-2.0. Adapted OSPTEK panel initialization material
also carries CC-BY-4.0 attribution obligations. The package declares
`Apache-2.0 AND CC-BY-4.0`; see [LICENSE](LICENSE),
[LICENSES/CC-BY-4.0.txt](LICENSES/CC-BY-4.0.txt) and [NOTICE](NOTICE).
Vendor IC datasheets and hardware drawings are not included.