硬體協定捕捉 是做什麼的？
非官方社群技能。不構成法律建議。僅捕捉使用者所擁有的設備。
0. 規則
- 設備本身是真理的來源。文件可能錯誤或過時；從真實設備上以使用者目前的韌體所捕捉的流量才是證據。
- 來源優先順序：1) 製造商的官方文件，2) 從使用者自己的硬體捕捉的資料，3) 第三方文件（在硬體驗證前標記為未驗證）。
- 最終文件中的每一項都附帶一個狀態：經過硬體驗證、僅來自官方文件、或未驗證。
- 在發送任何未知訊息之前，請備份設備的音色和設定。在完全了解韌體、引導程式、快閃寫入或恢復出廠設定訊息之前，切勿發送它們。
- 對非程式設計師使用者一次只給一個步驟。先給簡短回答。
1. 尋找官方文件
- 在製造商的支援頁面上尋找產品的「MIDI 實作」或「MIDI 資料格式」文件，以及使用手冊中的 MIDI 實作圖表。範例：KORG 發布了 minilogue xd MIDI 實作文件，作為一個獨立的文字檔（下載前需接受個人、非商業用途的授權條款）。連結到此類文件；除非其授權條款允許，否則不要將其複製到公開存儲庫中。
- 核對文件的修訂版本和日期與設備的韌體版本。韌體更新可能會更改格式。範例：某個合成器的第三方函式庫指出，來自較新韌體的一些預設檔案使用 448 位元組的程式 blob，而不是規格描述的 1024 位元組格式（參見：oxur/minilogue-xd README）。始終測試來自使用者實際韌體的傾印。
- 社群清單（例如 midi.guide，採用 CC BY-SA 4.0 授權）是很好的起點。保留其授權條款和出處，並驗證條目。
2. 捕捉 MIDI（符合規範的 USB MIDI 和 DIN MIDI）
各系統的工具（確認已安裝或可安裝）：
- Linux：
amidi和aseqdump（ALSA utils）用於原始埠和序列事件；receivemidi和sendmidi是跨平台的命令列工具。 - Windows：MIDI-OX 或類似的監控器。
- macOS：Snoize MIDI Monitor 或類似的工具。
方法：
- 記錄基準線：連接設備，啟動監控器，不要觸碰任何東西。
- 一次變更一個控制項。記錄該訊息，然後將控制項移動到其最小值、中間值和最大值，並分別記錄。
- 注意方向：設備到主機（旋鈕被轉動）和主機到設備（訊息發送到設備）。兩者都要測試。
- 在設備的不同模式下進行測試（全域與聲部、疊加層、音序器、動態控制），因為相同的控制項可能發送不同的訊息。
- 建立一個表格：控制項、訊息類型、CC 或 NRPN 編號或 SysEx 位元組、最小值、最大值、解析度（7 位元或 14 位元）、方向、通道處理、狀態。
請求和傾印 SysEx：
- 使用文件中記錄的傾印請求，將傾印內容接收至一個檔案，然後在設備上精確變更一個參數，再次傾印，並對比兩個檔案。被變更的位元組顯示了該參數的位置。
- 檢查 SysEx 封包結構：以 F0 開頭，製造商 ID，設備或型號 ID，以 F7 結尾。記下製造商 ID 位元組。
- 許多設備將 8 位元資料打包成 7 位元的 SysEx 位元組。在官方文件中找到打包規則（例如，KORG 的 7 位元轉 8 位元編碼器在其規格中列出），並在進行差異比對前先解碼。
- 透過變更一個參數並重新計算來尋找並驗證任何校驗和。不要猜測；針對來自設備的傾印進行測試。
3. 捕捉 USB（非符合規範的設備、供應商應用程式）
當設備使用供應商驅動程式或自訂 USB 控制訊息（例如某些音訊介面的混音器）且沒有 MIDI 埠攜帶資料時，需要此步驟。
- Wireshark 記錄 USB URB，這是主機堆疊所看到的傳輸，而非個別的 USB 資料包；原始資料包需要硬體嗅探器（參見：Wireshark wiki，USB 捕捉設定）。
- Linux：如果沒有
/dev/usbmon*設備，請執行sudo modprobe usbmon；在匯流排 N 上捕捉usbmonN，或在所有匯流排上捕捉usbmon0；使用者必須能夠讀取 usbmon 設備（透過群組、udev 規則或 ACL）（參見）。 - Windows：使用 USBPcap（參見）。過去曾發生阻擋滑鼠或鍵盤輸入的問題；安裝前請先查看 wiki。
- macOS：在
sudo ifconfig XHC20 up後，透過介面XHC20進行捕捉；wiki 指出在 Catalina 及更新版本上似乎必須停用系統完整性保護（參見）。如果可能，請優先使用其他系統。 - 捕捉供應商自己的應用程式與使用者設備的通訊，例如，在虛擬機器中運行一個 Windows 客戶機，將設備傳遞給客戶機，同時讓 Linux 主機在對應的匯流排上進行捕捉（參見：Wireshark wiki 上描述的方法）。
- 遵循同樣的一次變更一項的法則：在供應商應用程式中執行一個動作，捕捉，並在日誌中標記它。
- 將控制傳輸（請求類型、請求、數值、索引、資料）解碼成一個表格。重複每個動作以確認位元組是穩定的。
4. 允許與不允許的事項
- 觀察程式發送到使用者自己設備的訊息，以及閱讀官方文件，是學習協定的正常方式。
- 請勿反編譯或反組譯他人的軟體，也不要複製其程式碼、圖形、資料表格或預設檔案。某些法律允許有限的逆向工程以實現互通性，但授權合約可能禁止，且各國法規不盡相同。線路層級捕捉可以在沒有此問題的情況下提供相同的事實。
- 請勿發布供應商文件、原廠音色、韌體或標誌。請連結到它們。
- 請勿使用捕捉來繞過複製保護或授權。
5. 撰寫 MIDI 實作文件
在專案儲存庫中使用 docs/MIDI-IMPLEMENTATION.md：
- 檔頭：設備名稱、測試的韌體版本、日期、來源（官方文件標題、修訂版本和連結；捕捉設定）。
- 全域慣例：通道、位元組順序、7 位元打包方式、校驗和方法。
- 控制項表格：名稱、訊息、範圍、解析度、方向、備註、狀態（經硬體驗證、僅官方文件、未驗證）。
- SysEx 章節：請求格式、包含位元組偏移量的傾印格式、如何解碼、校驗和、來自使用者自己設備的範例（簡短十六進位）。
- 已知的怪癖和衝突（例如兩份文件對同一個 CC 編號有不同意見），以及每項問題的解決方式。
- 一份測試清單，讓使用者可以在新韌體上重複執行。
6. 控制器發送任何訊息前的安全檢查
- 僅發送表格中記錄為已驗證或已記錄在文件中的訊息。
- 調整節流並對輸出進行分塊；某些設備在收到大量訊息時會丟棄封包。
- 切勿在啟動時自動發送；先讀取，僅在使用者操作時才發送。
- 在任何寫入功能旁邊保留一個「從備份還原」按鈕。
來源
- Wireshark wiki，USB 捕捉設定：https://wiki.wireshark.org/CaptureSetup/USB
- KORG，minilogue xd MIDI 實作（支援下載頁面）：https://www.korg.com/us/support/download/manual/0/811/4440/
- oxur/minilogue-xd（該規格的第三方 Rust 實作）：https://github.com/oxur/minilogue-xd