GT911タッチが動作しない？I2Cアドレス、リセットタイミング、コンフィグ、座標の対処法

まずはここから：症状を照合する

手順には順番に従って取り組んでください。以下のレジスタアドレスとタイミングは、Linuxの goodix ドライバー、Espressifの esp_lcd_touch_gt911 コンポーネント、およびESPHomeのドキュメントに基づいています。リンクはSourcesセクションにあります。

1. GT911の電源確認とI2C応答の確認

電源とプルアップ

GoodixコントローラーのLinuxデバイスツリーバインディングでは、2つの電源、すなわち AVDD28（アナログ）と VDDIO（ロジックI/Oレール）が定義されています。モジュールやFPCでは、通常どちらもホスト側コネクタから供給されるため、ファームウェアを疑う前にコネクタで電圧を計測してください。また、SDAとSCLにはバス上のどこかにプルアップ抵抗が必要です。多くのディスプレイモジュールにはこれが実装されていません。

バスのスキャン

I2Cスキャナーのスケッチまたは i2cdetect を実行してください。GT911は2つの7ビットアドレスのいずれかで応答します：

8ビット表記のペアは、Linuxドライバーのリセットコード内のコメントに由来します。ベンダーの資料に「アドレス0xBA」と記載されていても、それは7ビットの 0x5D と同じデバイスです。Arduino、ESP-IDF、Linuxでは 0x5D を指定してください。

プロダクトIDの読み取り

GT911のレジスタは16ビットアドレスです。Linuxドライバーは 0x8140 から6バイトを読み取ります。先頭の4バイトがASCIIテキストとしてのプロダクトID、残りの2バイトがファームウェアバージョン（リトルエンディアン）です。GT911は文字列 911 を返します。 911 が読めた場合は、バス・電源・アドレスのいずれも正常であり、問題はこのリストの先にあります。

いずれのアドレスでも応答がない場合は、リセットラインがLowに固定されていないか確認してください。多くのモジュールでは、RSTはGT911への入力ピンであり、コントローラーが動作する前にホスト側からHighに駆動する（またはボード上でプルアップする）必要があります。

2. リセットとアドレス選択シーケンスを正しく行う

GT911は、リセットが解除される瞬間のINTピンのレベルによってI2Cアドレスを決定します。Linuxバインディングの説明によれば、INTラインは「リセットの解除時にデバイスによってサンプリングされ、I2Cクライアントアドレスを選択します」。

Linuxドライバが使用するシーケンス

1. RSTをLowにして10 ms以上待つ(ドライバは20 ms待ちます)。
2. INTを希望するアドレスに対応するレベルに設定します:0x14ならHigh、0x5DならLowです。
3. 100 µs以上待ちます。
4. RSTをHighにして5 ms以上待つ(ドライバは6〜10 ms待ちます)。
5. INTを50 ms間Lowにした後、INTを入力に切り替えます。

ステップ4の間にINTがフロートすると、電源投入のたびにアドレスが変わることがあります。これが「書き込み後は動くがコールドブートでは動かない」という典型報告の原因です。

ESP-IDF: esp_lcd_touch_gt911

Espressifのコンポーネントは、ESP_LCD_TOUCH_IO_I2C_GT911_ADDRESSを0x5D、ESP_LCD_TOUCH_IO_I2C_GT911_ADDRESS_BACKUPを0x14と定義しています。アドレス選択シーケンスが実行されるのは、次の3つがすべて設定されている場合のみです:

• rst_gpio_numが実GPIOである(GPIO_NUM_NCではない)こと、
• int_gpio_numが実GPIOであること、
• driver_dataが、dev_addrに希望するアドレスを設定したesp_lcd_touch_io_gt911_config_tを指していること。

いずれも満たさない場合は、I2C address initialization procedure skipped - using default GT9xx setupというログを出力し、通常のリセットのみを行います。この場合、アドレスはボードの配線によって決まるため、渡すI2CパネルIOのアドレスをスキャン結果と一致させる必要があります。コンポーネントのESP_LCD_TOUCH_IO_I2C_GT911_CONFIG()におけるデフォルトのI2Cクロックは100 kHzです。

ホストがINTを制御しないボード

INTがホストに接続されていない場合、ホストはアドレスを選択できないため、両方のアドレスをスキャンして応答する方を使用します。たとえばSunton ESP32-8048S043Cでは、GT911の割り込みはデフォルトではGPIOに配線されていません(当社のボードページを参照)。ESPHomeのGT911ページには、INTがIOエキスパンダ経由の場合でも、起動時にアドレス設定のためピンが使用される一方、タッチは割り込み駆動ではなくポーリングで取得される旨の記載があります。

3. 検出されるがタッチイベントが発生しない

ステータスレジスタの読み出しとクリア

タッチデータは0x814Eから始まります。先頭バイトはステータスバイトです:

• ビット7(0x80):バッファ準備完了。このビットがセットされている場合のみ、新規データが有効です。
• ビット0〜3:タッチポイント数。Linuxドライバは設定された最大数を超える数を拒否します。
• ビット4:キー(ボタン)が押されています。

続く各タッチポイントは8バイトで、トラックID、X、Y、サイズがリトルエンディアンの16ビット値で格納されます。

読み出し後、Linuxドライバとesp_lcd_touch_gt911の両方とも、0x814Eに0を書き込みます。自作ドライバの場合も同様にしてください。この書き込みを省略すると、最初のタッチしか検出できない自作ドライバになる典型的な原因となります。

割り込みエッジの一致

トリガタイプはGT911自身のコンフィギュレーションに含まれています:0x804Dにあるコンフィグバイトのビット0〜1です(コンフィグ開始アドレス0x8047からのオフセット6)。Linuxドライバは次のようにマッピングします:

GPIO割り込みの設定も合わせてください。esp_lcd_touch_gt911では、levels.interrupt = 1で立ち上がりエッジ割り込み、0で立ち下がりエッジ割り込みを選択します。

INTラインがない場合はポーリングで対応

HMI用途であればポーリングで十分機能します。ESPHomeはinterrupt_pinを設定しない場合、デフォルトで50 ms間隔（update_interval）でポーリングします。Linuxドライバーは割り込みを使用する場合、1フレームの処理を諦めるまで最大20 ms、レディービットを待ちます。

4. タッチ位置がずれる

GT911に保存されている解像度を確認する

GT911は、ディスプレイの解像度ではなく、コントローラーのコンフィグレーションに書き込まれた解像度で座標を報告します。Linuxドライバーによれば、X最大値は0x8048、Y最大値は0x804Aにあるリトルエンディアン16ビット値です。まずこれらを読み取ってください。コントローラーが1024×600に設定されていてパネルが800×480の場合、タッチ位置は指の右下にずれ、遠い側の端は画面外に出てしまいます。対処としては、スケーリングするか、ドライバーのリミットをコントローラーの値に合わせてください。

各スタックがリミット値を取得する場所：

生値からキャリブレーションする

ESPHomeのタッチスクリーンのページでは、on_touchラムダでtouch.x_rawとtouch.y_rawをログ出力し、画面端のピクセル位置で四隅を数回タッチし、その生値の最小値と最大値をキャリブレーション値として入力する方法が推奨されています。この手法はどのプラットフォームでも使えます。生のXとYを出力し、四隅をタッチして、その範囲を画面にマッピングしてください。

向きは次の順序で修正します。まずXとYを正しい軸に合わせ（swap_xy）、次に逆方向に動く軸を反転させます（mirror_x / mirror_y）。ディスプレイの論座標(0, 0)は左上でなければなりません。

5. GT911コンフィグの書き換え：最終手段

コンフィグレーションブロックは0x8047から始まります。GT911の場合、Linuxドライバーはこれを186バイトとして扱います。

• バイト0（0x8047）：コンフィグバージョン。
• バイト1〜4：XおよびY解像度（ステップ4を参照）。
• バイト5（0x804C）：最大タッチ点数、下位4ビット。
• バイト6（0x804D）：割り込みトリガタイプ、下位2ビット。
• バイト184（0x80FF）：チェックサム。バイト0〜183の合計の8ビット2の補数。
• バイト185（0x8100）：config_fresh。1でなければなりません。

Linuxドライバー自体がコンフィグを書き込むのは、INTとRSTの両GPIOを保持し、かつファームウェアファイル（デフォルト名はgoodix_911_cfg.bin、またはgoodix,config-nameプロパティで指定した名前）を見つけた場合のみです。ファイルがなければ、チップに既に保存されているコンフィグを使用します。

書き込む前に、必ず186バイトすべてを読み出して保存してください。解像度と向きは、可能な限りソフトウェア側で修正してください。別のタッチパネル向けに作られたコンフィグブロックは、お使いのパネルでタッチが動作しなくなる原因になり得るため、どうしても変更が必要な場合はパネルのサプライヤーからファイルを入手してください。

静電容量式タッチモジュールの選び方

新しい設計にCTPディスプレイを選定する場合は、サンプルを発注する前にサプライヤーに3つの点を確認してください。どのタッチコントローラーを使用しているか、出荷時のI2Cアドレスは何か、そしてINTとRSTがコネクタまで配線されているかです。サイズ、インターフェース、ホストプロセッサの情報をAsk an Engineerからお送りいただければ、ご提案するモジュールとともにこの3つの回答をお届けします。