硬件协议捕获
非官方社区技能。非法律建议。仅捕获用户拥有的设备。
0. 规则
- 设备是事实来源。文档可能错误或过时；从真实设备上使用用户固件进行的捕获才是证据。
- 来源顺序：1) 制造商的官方文档，2) 从用户自己的硬件捕获的数据，3) 第三方文档（在硬件上验证前标记为未验证）。
- 最终文档中的每条记录都带有状态：已在硬件上验证、仅来自官方文档、或未验证。
- 在发送任何未知内容之前，备份设备的音色和设置。除非完全理解其格式，否则切勿发送固件、引导加载程序、闪存写入或恢复出厂设置消息。
- 对于非程序员，一次只给一个步骤。先给简短答案。
1. 查找官方文档
- 在制造商的支持页面查找该产品的“MIDI实现”或“MIDI数据格式”文档，以及用户手册中的MIDI实现图表。例如：KORG发布的minilogue xd MIDI实现是一个单独的文本文件（接受个人非商业许可后下载）。链接到此类文档；除非其许可证允许，否则不要将其复制到公共仓库中。
- 检查文档的修订版和日期与设备固件版本的对应关系。固件更新可能会改变格式。例如：该合成器的第三方库指出，某些来自更新固件的预设文件使用448字节程序块，而不是规范描述中的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