ハードウェアプロトコルキャプチャ は何をしますか？
非公式コミュニティスキル。法的助言ではありません。ユーザーが所有するデバイスのみをキャプチャしてください。
0. ルール
- デバイスが真実の源です。ドキュメントは間違っていたり古かったりする可能性があります。ユーザーのファームウェアを搭載した実機からのキャプチャが証拠となります。
- 情報源の優先順位: 1) メーカーの公式ドキュメント、2) ユーザー自身のハードウェアからのキャプチャ、3) サードパーティのドキュメント（ハードウェアで確認するまで未検証とマーク）。
- 最終ドキュメントの各エントリには、ステータス（ハードウェアで検証済み、公式ドキュメントのみ、未検証）を記載します。
- 未知のものを送信する前に、デバイスのパッチと設定をバックアップしてください。ファームウェア、ブートローダー、フラッシュ書き込み、出荷時リセットメッセージは、そのフォーマットを完全に理解するまで決して送信しないでください。
- プログラマーでないユーザーには、一度に1ステップずつ指示してください。最初は簡潔な回答を心がけてください。
1. 公式ドキュメントを探す
- メーカーのサポートページで、製品の「MIDI実装」または「MIDIデータフォーマット」ドキュメント、およびオーナーズマニュアルのMIDI実装チャートを探してください。例：KORGはminilogue xd MIDI実装を個別のテキストファイルとして公開しています（個人向け非営利ライセンスに同意した後にダウンロード可能）。それらのドキュメントへのリンクを提供してください。ライセンスが許可しない限り、公開リポジトリにコピーしないでください。
- ドキュメントのリビジョンと日付をデバイスのファームウェアバージョンと照合してください。ファームウェアアップデートによりフォーマットが変更される可能性があります。例：そのシンセサイザーのサードパーティライブラリでは、新しいファームウェアの一部のプリセットファイルが、仕様に記載されている1024バイト形式ではなく、448バイトのプログラムブロブを使用していると指摘されています（出典: oxur/minilogue-xd README）。常にユーザーの実際のファームウェアからダンプをテストしてください。
- コミュニティリスト（midi.guide、CC BY-SA 4.0など）は出発点として有用です。ライセンスと帰属表示を維持し、エントリを検証してください。
2. MIDIをキャプチャする（クラス準拠USB MIDIおよびDIN MIDI）
システム別ツール（各ツールがインストールされているか、インストール可能かを確認してください）:
- Linux:
amidiおよびaseqdump（ALSAユーティリティ）はrawポートおよびシーケンサイベント用。receivemidiおよびsendmidiはクロスプラットフォームのコマンドラインツールです。 - Windows: MIDI-OX または同等のモニター。
- macOS: Snoize MIDI Monitor または同等のもの。
方法:
- ベースラインを記録します：デバイスを接続し、モニターを起動し、何も触らないでください。
- 一度に1つのコントロールだけを変更します。メッセージを記録し、コントロールを最小、中間、最大に動かして、それぞれを記録します。
- 方向に注意してください：デバイス→ホスト（ノブを回した場合）とホスト→デバイス（メッセージをデバイスに送信した場合）。両方をテストします。
- デバイスが異なるモード（グローバル vs パート、レイヤー、シーケンサー、モーション）にある場合もテストしてください。同じコントロールが異なるメッセージを送信する可能性があるためです。
- テーブルを作成します：コントロール、メッセージタイプ、CCまたはNRPN番号またはSysExバイト、最小値、最大値、分解能（7ビットまたは14ビット）、方向、チャンネル処理、ステータス。
SysExの要求とダンプ:
- 文書化されたダンプ要求を使用し、ダンプをファイルに受信し、デバイス上の1つのパラメータだけを変更し、再度ダンプして、2つのファイルをdiffします。変更されたバイトは、そのパラメータが存在する場所を示します。
- SysExエンベロープを確認します：F0で開始、メーカーID、デバイスまたはモデルID、F7で終了。メーカーIDバイトに注意してください。
- 多くのデバイスは8ビットデータを7ビットSysExバイトにパックします。公式ドキュメントでパッキングルールを見つけ（例：KORGの7ビットから8ビットへのコーデックは仕様に記載されています）、diffする前にデコードしてください。
- チェックサムを見つけて検証するには、1つのパラメータを変更し、再計算します。推測しないでください。デバイスからのダンプと照合してテストしてください。
3. USBをキャプチャする（非クラス準拠デバイス、ベンダーアプリ）
デバイスがベンダードライバーまたはカスタムUSB制御メッセージを使用している場合（例：一部のオーディオインターフェースのミキサー）、MIDIポートにデータが流れない場合に必要です。
- WiresharkはUSB URB（ホストスタックが見た転送）を記録します。個々のUSBパケットではありません。生のパケットを取得するにはハードウェアスニファが必要です（出典: Wireshark wiki, USB capture setup）。
- Linux:
/dev/usbmon*デバイスがない場合はsudo modprobe usbmonを実行。バスNの場合はusbmonN、全バスの場合はusbmon0でキャプチャします。ユーザーはusbmonデバイスを読み取れる必要があります（グループ、udevルール、またはACL経由）（出典）。 - Windows: USBPcapを使用します（出典）。過去にマウスやキーボードの入力がブロックされる問題がありました。インストール前にwikiを確認してください。
- macOS:
sudo ifconfig XHC20 upでインターフェースXHC20を使用してキャプチャします。wikiによると、Catalina以降ではSystem Integrity Protectionを無効にする必要があるようです（出典）。可能であれば別のシステムを使用することをお勧めします。 - ベンダーの独自アプリがユーザーのデバイスと通信している様子をキャプチャします。例えば、仮想マシン内のWindowsゲストにデバイスをパススルーし、Linuxホストが該当バスをキャプチャする方法があります（出典: Wireshark wikiで説明されている方法）。
- 一度に1つの変更を行う方法を守ってください。ベンダーアプリで1つのアクションを実行し、キャプチャし、ログにマークします。
- 制御転送（リクエストタイプ、リクエスト、値、インデックス、データ）をテーブルにデコードします。各アクションを繰り返して、バイトが安定していることを確認します。
4. 許可されていることと許可されていないこと
- プログラムがユーザー自身のデバイスに送信するメッセージを観察し、公式ドキュメントを読むことは、プロトコルを学ぶ通常の方法です。
- 他人のソフトウェアを逆コンパイルまたは逆アセンブルしたり、そのコード、グラフィック、データテーブル、プリセットをコピーしたりしないでください。一部の法律では相互運用性のために限定的なリバースエンジニアリングを認める場合がありますが、ライセンス契約で禁止されている場合があり、ルールは国によって異なります。ワイヤーレベルキャプチャは、その問題を回避しながら同じ情報を提供します。
- ベンダーのドキュメント、工場出荷時パッチ、ファームウェア、ロゴを公開しないでください。それらにリンクしてください。
- コピープロテクションやライセンスを回避するためにキャプチャを使用しないでください。
5. MIDI実装ドキュメントを作成する
プロジェクトリポジトリに docs/MIDI-IMPLEMENTATION.md を作成します:
- ヘッダー: デバイス、テストしたファームウェアバージョン、日付、情報源（公式ドキュメントのタイトル、リビジョン、リンク、キャプチャ設定）。
- 全般的な規則: チャンネル、バイトオーダー、7ビットパッキング、チェックサム方式。
- コントロールテーブル: 名前、メッセージ、範囲、分解能、方向、備考、ステータス（ハードウェアで検証済み、公式のみ、未検証）。
- SysExセクション: 要求フォーマット、バイトオフセット付きダンプフォーマット、デコード方法、チェックサム、ユーザー自身のデバイスからの例（短い16進数）。
- 既知の癖と矛盾点（例：2つのドキュメントでCC番号が異なる場合）と、それぞれがどのように解決されたか。
- ユーザーが新しいファームウェアで繰り返し実行できるテストチェックリスト。
6. コントローラーが何かを送信する前の安全確認
- テーブルに検証済みまたは文書化済みとして記録されたメッセージのみを送信してください。
- 出力をスロットルおよびチャンク化してください。一部のデバイスはフラッドされるとメッセージをドロップします。
- 起動時に自動送信しないでください。最初に読み取り、ユーザーアクションがあった場合にのみ送信してください。
- 書き込み機能の隣には「バックアップから復元」ボタンを常に配置してください。
情報源
- Wireshark wiki, USB capture setup: https://wiki.wireshark.org/CaptureSetup/USB
- KORG, minilogue xd MIDI Implementation (support download page): https://www.korg.com/us/support/download/manual/0/811/4440/
- oxur/minilogue-xd (third-party Rust implementation of that spec): https://github.com/oxur/minilogue-xd