mangoo1/esp_lcd_touch_gsl3680

Readme (ja)

# esp_lcd_touch_gsl3680

([English](README.md) | [中文](README_zh.md) | 日本語)

ESP-IDF 向け Silead GSL3680 静電容量式タッチドライバ。
[`esp_lcd_touch`](https://components.espressif.com/components/espressif/esp_lcd_touch)
インターフェースを実装しています。

## インストール

```bash
idf.py add-dependency "mangoo1/esp_lcd_touch_gsl3680^1.0.0"
```

または `main/idf_component.yml` に追加：

```yaml
dependencies:
  mangoo1/esp_lcd_touch_gsl3680: "^1.0.0"
```

## 使い方

コントローラは I2C アドレス `0x40` です。リセットと割り込みは**負論理**です。

```c
#include "esp_lcd_gsl3680.h"

// 1. 既存の I2C マスターバスを共用します
esp_lcd_panel_io_i2c_config_t io_cfg = ESP_LCD_TOUCH_IO_I2C_GSL3680_CONFIG();
io_cfg.scl_speed_hz = 400 * 1000;

esp_lcd_panel_io_handle_t io = NULL;
ESP_ERROR_CHECK(esp_lcd_new_panel_io_i2c(i2c_bus, &io_cfg, &io));

// 2. x_max/y_max はパネルのネイティブ解像度に合わせます
esp_lcd_touch_config_t tp_cfg = {
    .x_max = 800,
    .y_max = 1280,
    .rst_gpio_num = GPIO_NUM_22,
    .int_gpio_num = GPIO_NUM_21,
    .levels = {
        .reset     = 0,   // 負論理
        .interrupt = 0,   // 負論理
    },
    .flags = {
        .swap_xy  = 0,
        .mirror_x = 0,
        .mirror_y = 1,
    },
};

esp_lcd_touch_handle_t tp = NULL;
ESP_ERROR_CHECK(esp_lcd_touch_new_i2c_gsl3680(io, &tp_cfg, &tp));
```

### 座標の取得

```c
uint16_t x[1], y[1], strength[1];
uint8_t count = 0;

esp_lcd_touch_read_data(tp);
if (esp_lcd_touch_get_coordinates(tp, x, y, strength, &count, 1)) {
    printf("タッチ位置 %d,%d\n", x[0], y[0]);
}
```

### LVGL との連携

```c
#include <esp_lvgl_port.h>

const lvgl_port_touch_cfg_t touch_cfg = {
    .disp   = lv_display_get_default(),
    .handle = tp,
};
lvgl_port_add_touch(&touch_cfg);
```

### 向きの設定

`swap_xy` / `mirror_x` / `mirror_y` はディスプレイパネルの向き設定と一致させて
ください。ずれているとタッチ座標が表示内容と合いません。実行時に変更することも
できます：

```c
esp_lcd_touch_set_mirror_y(tp, true);
```

### タッチを任意扱いにする

タッチパネルが実装されていない可能性がある場合は、先にアドレスをプローブして
おくと、タッチなしのボードでも起動できます：

```c
if (i2c_master_probe(i2c_bus, ESP_LCD_TOUCH_IO_I2C_GSL3680_ADDRESS, 100) != ESP_OK) {
    ESP_LOGW(TAG, "タッチコントローラが見つかりません。スキップします");
    return;
}
```

## 起動時間

初期化時にコントローラへファームウェアを転送します。**約 800ms** かかるため、
起動シーケンスに余裕を持たせ、ウォッチドッグの短いコンテキストからは呼ばないで
ください。

## 既知の問題

ファームウェア転送後、ドライバは以下を出力します：

```
gsl3680 startup_chip failed read 0xb0 = 5a,5a,5a,5a
```

その後、成功として処理を継続します。`5a5a5a5a` はプレースホルダのパターンで
あり、チップが実際の起動ステータスを返していないことを示します。転送自体は成功
しており I2C にも応答しますが、**原因は未特定**です。

## ベンダーソースからの修正

ジェスチャー判定における整数型のバグ 2 件：

**`chazhi` が `uint16_t` だった。** `distance - pre_distance` という**符号付き**
の差分を保持するため、`chazhi < -900` のピンチアウト分岐に到達できず、縮小
ジェスチャーが一度も発火しませんでした。`int32_t` に修正。

**`distance` も `uint16_t` だった。** 距離の**二乗**
`(x1-x2)² + (y1-y2)²` を保持し、800×1280 パネルでは 2278400 に達してオーバー
フローしていました。`pre_distance` は元々 `uint32_t` で型が不一致でした。両方を
`uint32_t` に統一。

## 動作確認環境

Guition JC8012P4A1C — ESP32-P4、10.1" 800×1280 JD9365 パネル、ESP-IDF v6.0.2。

ファームウェア転送とコントローラの初期化は確認済みです。**座標の取得については
体系的な検証を行っていません。**

## ライセンス

**GPL-2.0-or-later。**

`gsl_point_id.c` は Silead のタッチトラッキングアルゴリズムで、Linux カーネルの
`drivers/input/touchscreen/mediatek/gslX680/`（© 2010–2016 Silead Inc.）に由来
します。同一ライブラリにリンクされるため、**コンポーネント全体が
GPL-2.0-or-later** となります。

**プロジェクトが MIT または Apache ライセンスの場合**、これらのソースを自分の
ツリーに取り込まないでください。コードベース全体が GPL になってしまいます。
コンポーネントとして依存すれば、ライセンス境界は保たれます。

`esp_lcd_gsl3680.c` とヘッダは Guition JC8012P4A1C のベンダー SDK 由来で、元
ファイルにライセンス表記はありませんでした。ここでは同一条件で配布します。