Linux USBタッチスクリーンのトラブルシューティング：evtestとlibinputによる実践的ワークフロー

USBタッチスクリーンがUSBデバイス一覧に表示されても、アプリケーションが使用可能なタッチ入力を受信できない場合があります。障害のあるレイヤーを特定するには、デバイス識別、カーネルイベントノード、接触イベント、libinput、アプリケーションの順にパスをテストします。各比較が特定の問いに答えられるよう、テスト中は同じタッチスクリーンと同じ動作を使用してください。.

このLinux USBタッチスクリーントラブルシューティングワークフローは、evdevインターフェースを公開するタッチコントローラーを対象としています。読み取り専用の診断コマンドを使用し、再現可能なベンチ手順を提案します。作成時に対象のタッチスクリーンは接続されていません。コマンドはドキュメントに対して確認されており、この手順は完了したハードウェア認定ではありません。.

1. 環境を記録し、USBデバイスを見つける

可能な場合は、既知のタッチスクリーン1台から始めてください。ノートでは、ディスプレイ接続とタッチ接続を分けて記載してください。映像が正常に表示されていても、USBタッチコントローラーが列挙されたことを証明するものではありません。.

uname -r

カーネルリリースと利用可能なツールを記録します。パッケージ名、アクセス権限、ツールのバージョンはディストリビューションによって異なります。コマンドが見つからない場合は、テストの該当部分を実行する前に、ディストリビューションの文書化されたプロセスを通じて適切なツールを入手してください。.

lsusb USBデバイスを一覧表示します。.^[8] 妥当と思われるコントローラーのエントリーを、ハードウェアドキュメントまたは既存のデバイス記録と照合します。製品名は汎用的な場合があるため、ベンダーIDと製品IDも保持してください。USB列挙だけでは、カーネルがタッチイベントノードを作成したことや、GUIがそれを使用できることを証明するものではありません。.

で /proc/bus/input/devices, で、候補となる入力デバイスとそのイベントハンドラーを探します。Linuxはカーネル入力イベントを、次のようなevdevノードを通じてユーザースペースに公開します： /dev/input/event7.^[1] コントローラーが複数の入力インターフェースを公開する場合があります。名前に「USB」が含まれているという理由だけでノードを選択しないでください。“

期待されるUSB識別情報が存在しない場合は、まずその列挙の問題を解決してください。接続構成と、デバイスが一貫して表示されるかどうかを記録します。以降のイベントテストでは、識別された入力パスを持たないデバイスを診断することはできません。.

2. タッチをキャプチャする前にイベントノードを確認する

以下のすべてのコマンドで、, N はプレースホルダーです。お使いのマシンで特定したイベント番号に置き換えてください。文字 N をそのまま入力しないでください。.

udevadm info --query=property --name=/dev/input/eventN

udevadm info はデバイスデータベースから情報を読み取ります。利用可能な場合、USB識別子、シリアル番号、またはデバイスパスは、ノードをコントローラーに結び付けるのに役立ちます。.^[7] プロパティは異なる場合や存在しない場合があります。再接続後に同じイベント番号が同じデバイスを識別すると仮定するのではなく、キャプチャとともに出力を保存してください。.

evtest はデバイスの機能を表示し、その後イベントを監視します。ノードの読み取りには、多くの場合昇格された権限が必要です。.^[2] テストシステムに適した権限を使用してください。ノードを誰でも書き込み可能なアクセスに変更しないでください。 Ctrl+C を押して各監視セッションを終了します。.

すべての指を離した状態から始めます。1本の指で中央を1回タッチしてから離します。この操作が候補ノードでイベントを生成することを確認します。絶対軸およびマルチタッチフィールドの機能を確認します。無関係なコントロールのみを公開するノードは、必要なタッチインターフェースではありません。.

複数のノードが候補として残る場合は、1つのセッションを終了し、次の候補を検査します。各ノードをその識別情報と観察された応答に結び付けるメモを保持します。これにより、誤ったインターフェースからの無応答をコントローラー障害と解釈することを避けられます。.

Do not add --grab. を追加しないでください。排他的グラブは入力を受信するクライアントを変更し、以降のアプリケーション比較に干渉します。.

3. トレースを判断する前にイベント語彙を読む

入力レポートは状態ベースです。変化しない値は再び現れる必要はありません。. EV_ABS は絶対軸イベントを識別し、 SYN_REPORT は入力フレームを区切ります。. SYN_DROPPED はクライアントのイベントキューのオーバーフローを示します。.^[3] そのマーカーを含むキャプチャは不完全です。より短いキャプチャを繰り返し、損失を報告してください。不完全なシーケンスを使用して、リリースの欠落やハードウェア障害を証明しないでください。.

デバイスに対して表示される軸の限界値を読んでください。これらは生の入力単位であり、必ずしもLCDピクセルではありません。生のX最大値に近い値は、アプリケーションがポインターを数値的に同一のピクセル座標に配置すべきであることを意味しません。.

位置の変化だけでなく、接触のライフサイクルも探してください。正確なフィールドは機能に依存します。すべてのデバイスが圧力を報告する、複数の接触をサポートする、または同じプロトコルを使用すると仮定しないでください。.

タイプBマルチタッチプロトコルを使用するデバイスの場合、スロットは状態を保持します。非負の ABS_MT_TRACKING_ID は接触を識別し、; -1 はそのリリースを示します。. ABS_MT_POSITION_X そして ABS_MT_POSITION_Y その位置を記述する。. ABS_MT_SLOT 選択されたスロットが変更されていない場合は省略できる。.^[4]

したがって、静止している指は繰り返し座標を生成する必要がない。移動している指のみを列挙したトレースでも、2つのアクティブなコンタクトを記述できる。他の指を欠落と判断する前に、保持されている状態を再構築すること。.

4. 5点および2ストロークの生入力テストを実行する

保持する evtest 確認済みのノード上で実行する。実行間でキャプチャを比較可能にするために、以下の提案プロトコルを使用する。これは基本的なカバレッジと連続性を確認するものであり、普遍的な精度閾値を設定するものではない。.

1. 中央を1回タップし、短時間保持してから完全に離す。.
2. 左上、右上、右下、左下の領域で繰り返す。各ポイントはベゼル上ではなく、アクティブタッチ領域の内側に明確に位置させること。.
3. 使用可能領域を横切る遅い水平ストロークを1回描き、然后离す。.
4. 遅い垂直ストロークを1回描き、然后离す。.
5. 疑わしい動作があれば、それを単独でより短いキャプチャで繰り返す。.

各タップについて、新しいコンタクトが出現するか、その位置が報告された軸限界内にあるか、最終的なリフトがコンタクトを終了させるかを記録する。5点間の位置を比較する。それらは再現可能な空間パターンを形成すべきだが、生軸の方向は表示画像と異なる場合がある。各生軸が各物理的移動に対して増加するか減少するかを文書化し、これをプロジェクトの意図する向きと比較する。回転またはミラーリングされたアセンブリでは、物理的な左上が両方の軸の最小値に対応する必要はない。.

各ストロークについて、移動に対応する位置変化のシーケンスを探す。突然のジャンプ、予期しないコンタクトの終了、または意図した領域の一部を繰り返しカバーしなくなる値を記録する。回転されたアセンブリでは、物理的な水平ストロークが主に他の生軸を変化させる場合がある。その観察は有用な証拠であり、自動的な欠陥ではない。.

何か問題があるように見える場合は、同じ動作を繰り返す。異常が同じ場所で繰り返されるか、予測不能に発生するかを記録する。どちらのパターンもさらなる調査の指針となり得るが、どちらか一方だけでは故障部品を特定できない。.

基本的な観察が成功したとは、再現可能なカバレッジを伴う完全な押下、移動、および解放が行われることである。これは生産精度、レイテンシ、環境性能、または長期信頼性を確立するものではない。それらにはアプリケーション固有の受け入れ基準と別個の認定計画が必要である。.

5. サポートされている場合にのみマルチコンタクトをテストする

文書化されたデバイス機能とイベントインターフェースが意図するマルチタッチテストをサポートしている場合にのみ進める。サポートしていない場合は、シングルコンタクトの結果を2本指テストの失敗として解釈するのではなく、制限事項として記録する。.

サポートされているタイプBデバイスの場合、1本の指を左側付近に置いて静止させる。2本目の指を右側付近に置く。2本目の指のみを移動させ、それを離し、次に1本目の指を移動させて離す。最後に役割を入れ替えて繰り返す。.

両方の指を離した状態でキャプチャを開始し、フレーム間でコンタクトIDと保持されたスロット状態を追跡する。有用な観察は、2つの識別可能なアクティブコンタクト、意図したコンタクトに関連する移動、一方のコンタクトがアクティブなまま他方のコンタクトが解放されること、および最後のコンタクトの解放である。選択されたスロットまたは静止座標は、各フレームで繰り返されない場合がある。.

意図した動作を明確にするために、2本の指を十分に離しておく。このテストは、報告されたライフサイクルが手順に従っているかを確認するものである。コンタクト数の認定や最小間隔の測定ではない。.

生シーケンスが曖昧な場合は、疑問の原因となった遷移のみを繰り返す。「2本目の指ダウン、2本目の指アップ、1本目の指アップ」という短いキャプチャは、無関係なジェスチャーを多数含む長いセッションよりもレビューしやすい。.

6. 同じ物理的動作でlibinputと比較する

終了 evtest, その後、libinputを検査する:

sudo libinput list-devices

libinput list-devices はlibinputが認識したデバイス、その機能、および組み込みデフォルトを表示する。実際のデスクトップ設定は報告しない。.^[5] 確認済みのイベントノードを見つけ、報告されたタッチ機能を検査する。自動解析のために固定の出力列レイアウトに依存しないこと。.

libinput debug-events は別のコンテキストでイベントを監視する。その動作はコンポジタやアプリケーションと異なる場合がある。.^[6] 中央タップ、水平ストローク、および最終解放を繰り返す。サポートされている場合は、2コンタクトシーケンスを繰り返す。セッションを以下で終了する Ctrl+C.

生タッチが整合しているが、libinputがノードを期待通りに認識しない場合は、両方の出力を保存する。次の調査は認識、分類、またはテストされたユーザースペース環境に関するものである。比較により問題が絞り込まれたが、パネルまたはコントローラファームウェアが欠陥であることは証明されていない。.

両方のツールが整合したタッチを示す場合は、実際のアプリケーションに進む。別個のlibinputテストでは、コンポジタのディスプレイ関連付け、回転、またはアプリケーションのイベント処理を認定できない。.

7. 修正を推測せずに故障層を特定する

An open device handle does not prove an exclusive grab. Likewise, no events do not prove failed hardware: a wrong node, access condition, grab, or driver path can produce a silent capture. Avoid changing several settings at once; doing so removes the controlled comparison.

In the application, repeat the same five points and strokes. Record whether the mismatch affects the whole desktop, one output, or one application. Inspect the configuration actually used by that compositor or toolkit. This guide does not prescribe a universal calibration matrix.

8. Prepare a small, reproducible technical handoff

Provide the display and touch-controller models, USB identifiers, kernel release, tool versions, confirmed event node, and capability output. Include a short event excerpt tied to exact physical actions, plus the observed difference between raw input, libinput, and the application. State whether the capture contains any dropped-event marker.

Also describe the host, display orientation, connected outputs, touch connection, and application environment. Remove unrelated output. A concise reproduction gives another engineer a better starting point than a large log labeled only “touch does not work.”

For broader module requirements, see the touchscreen module guide; for a separate platform architecture discussion, see Android touch and HDMI touch. To request project-specific review, send RJY the model details and the bounded test record. RJY can discuss documented display and touch-module requirements from that record. Compatibility and any adaptation of an existing module still require verification for the actual controller, host, software, and application.

参考文献

1. Linux kernel documentation: input subsystem introduction.
2. Debian manual: evtest.
3. Linux kernel documentation: input event codes.
4. Linux kernel documentation: multi-touch protocol.
5. libinput documentation: helper tools.
6. Debian manual: libinput debug-events.
7. systemd documentation: udevadm.
8. Debian manual: lsusb.