하드웨어 프로토콜 캡처
비공식 커뮤니티 스킬입니다. 법적 조언이 아닙니다. 사용자가 소유한 장치만 캡처하세요.
0. 규칙
- 장치가 진실의 원천입니다. 문서는 틀리거나 오래될 수 있습니다. 실제 장치와 사용자의 펌웨어로 캡처한 것이 증거입니다.
- 자료 우선순위: 1) 제조사의 공식 문서, 2) 사용자 자체 하드웨어에서 캡처, 3) 타사 문서(하드웨어에서 확인할 때까지 미검증으로 표시).
- 최종 문서의 모든 항목에는 상태가 표시됩니다: 하드웨어에서 검증됨, 공식 문서 전용, 미검증.
- 알 수 없는 메시지를 보내기 전에 장치의 패치와 설정을 백업하세요. 포맷이 완전히 이해될 때까지 펌웨어, 부트로더, 플래시 쓰기 또는 공장 초기화 메시지를 절대 보내지 마세요.
- 비프로그래머에게는 한 번에 한 단계씩 알려주세요. 짧은 답변을 먼저 제공하세요.
1. 공식 문서 찾기
- 제조사 지원 페이지에서 해당 제품의 "MIDI 구현" 또는 "MIDI 데이터 포맷" 문서와 사용자 매뉴얼의 MIDI 구현 차트를 찾으세요. 예: KORG는 minilogue xd MIDI 구현을 별도의 텍스트 파일로 제공합니다(개인 비상업적 라이선스 동의 후 다운로드). 이러한 문서에 링크를 걸고, 라이선스가 허용하지 않는 한 공개 저장소에 복사하지 마세요.
- 문서의 개정판과 날짜를 장치의 펌웨어 버전과 대조하세요. 펌웨어 업데이트로 포맷이 변경될 수 있습니다. 예: 해당 신디사이저의 타사 라이브러리는 최신 펌웨어의 일부 프리셋 파일이 사양이 설명하는 1024바이트 포맷이 아닌 448바이트 프로그램 블롭을 사용한다고 지적합니다(V: oxur/minilogue-xd README). 항상 사용자의 실제 펌웨어에서 덤프를 테스트하세요.
- 커뮤니티 목록(예: midi.guide, CC BY-SA 4.0)은 유용한 시작점입니다. 라이선스와 저작자 표시를 유지하고, 항목을 검증하세요.
2. MIDI 캡처 (클래스 호환 USB MIDI 및 DIN MIDI)
시스템별 도구(설치되었거나 설치 가능한지 확인):
- Linux:
amidi및aseqdump(ALSA 유틸리티) - 원시 포트 및 시퀀서 이벤트용;receivemidi및sendmidi는 크로스 플랫폼 명령줄 도구입니다. - Windows: MIDI-OX 또는 유사 모니터.
- macOS: Snoize MIDI Monitor 또는 유사.
방법:
- 기준선 기록: 장치를 연결하고, 모니터를 시작하고, 아무것도 건드리지 마세요.
- 한 번에 하나의 컨트롤씩 변경하세요. 메시지를 기록한 다음, 컨트롤을 최소, 중간, 최대로 이동하고 각각을 기록하세요.
- 방향 기록: 장치 → 호스트(노브 이동) 및 호스트 → 장치(장치로 보낸 메시지). 둘 다 테스트하세요.
- 다른 모드(글로벌 대 파트, 레이어, 시퀀서, 모션)에서 장치를 테스트하세요. 동일한 컨트롤이 다른 메시지를 보낼 수 있습니다.
- 표 작성: 컨트롤, 메시지 유형, CC 또는 NRPN 번호 또는 SysEx 바이트, 최소, 최대, 해상도(7비트 또는 14비트), 방향, 채널 처리, 상태.
요청 및 덤프 SysEx:
- 문서화된 덤프 요청을 사용하고, 덤프를 파일로 받은 다음, 장치에서 정확히 하나의 매개변수를 변경하고 다시 덤프한 후 두 파일을 비교하세요(diff). 변경된 바이트는 해당 매개변수의 위치를 보여줍니다.
- SysEx 엔벨로프 확인: F0 시작, 제조사 ID, 장치 또는 모델 ID, F7 종료. 제조사 ID 바이트를 기록하세요.
- 많은 장치가 8비트 데이터를 7비트 SysEx 바이트로 패킹합니다. 공식 문서에서 패킹 규칙을 찾아(예: KORG의 7비트-8비트 코덱은 사양에 나열됨) diff 전에 디코딩하세요.
- 체크섬을 찾아 확인하려면 하나의 매개변수를 변경하고 다시 계산하세요. 추측하지 말고 장치 덤프를 기준으로 테스트하세요.
3. USB 캡처 (클래스 비호환 장치, 벤더 앱)
장치가 벤더 드라이버나 사용자 정의 USB 제어 메시지를 사용하고(예: 일부 오디오 인터페이스 믹서) MIDI 포트가 데이터를 전달하지 않을 때 필요합니다.
- Wireshark는 USB URB를 기록합니다. 이는 호스트 스택이 보는 전송이지 개별 USB 패킷이 아닙니다. 원시 패킷은 하드웨어 스니퍼가 필요합니다(V: Wireshark wiki, USB 캡처 설정).
- Linux:
/dev/usbmon*장치가 없으면sudo modprobe usbmon; 버스 N은usbmonN, 모든 버스는usbmon0에서 캡처; 사용자가 usbmon 장치를 읽을 수 있어야 합니다(그룹, udev 규칙 또는 ACL)(V). - Windows: USBPcap 사용(V). 과거에 마우스 또는 키보드 입력 차단 문제가 있었습니다. 설치 전에 위키를 확인하세요.
- macOS:
sudo ifconfig XHC20 up후 인터페이스XHC20사용; 위키에 따르면 Catalina 이상에서 System Integrity Protection을 비활성화해야 하는 것으로 보입니다(V). 가능하면 다른 시스템을 선호하세요. - 벤더 자체 앱이 사용자 장치와 통신하는 것을 캡처하세요. 예를 들어, 가상 머신의 Windows 게스트에 장치를 패스스루하고 Linux 호스트가 해당 버스에서 캡처합니다(V: Wireshark wiki에 설명된 방법).
- 동일한 한 번에 하나씩 변경하는 규칙을 따르세요: 벤더 앱에서 한 동작을 수행하고, 캡처하고, 로그에 표시하세요.
- 제어 전송(요청 유형, 요청, 값, 인덱스, 데이터)을 테이블로 디코딩하세요. 각 동작을 반복하여 바이트가 안정적인지 확인하세요.
4. 허용 및 금지
- 프로그램이 사용자 자신의 장치로 보내는 메시지를 관찰하고 공식 문서를 읽는 것은 프로토콜을 배우는 일반적인 방법입니다.
- 타인의 소프트웨어를 디컴파일하거나 디스어셈블하지 말고, 코드, 그래픽, 데이터 테이블 또는 프리셋을 복사하지 마세요. 일부 법률은 상호운용성을 위한 제한적인 역공학을 허용하지만, 라이선스 계약이 이를 금지할 수 있으며 규칙은 국가마다 다릅니다. 와이어 레벨 캡처는 이러한 문제 없이 동일한 사실을 제공합니다.
- 벤더 문서, 공장 패치, 펌웨어 또는 로고를 게시하지 마세요. 링크로 대체하세요.
- 캡처를 복사 방지 또는 라이선스 우회에 사용하지 마세요.
5. MIDI 구현 문서 작성
프로젝트 저장소에 docs/MIDI-IMPLEMENTATION.md 사용:
- 헤더: 장치, 테스트된 펌웨어 버전, 날짜, 소스(공식 문서 제목, 개정판 및 링크; 캡처 설정).
- 글로벌 규칙: 채널, 바이트 순서, 7비트 패킹, 체크섬 방법.
- 컨트롤 표: 이름, 메시지, 범위, 해상도, 방향, 참고 사항, 상태(하드웨어에서 검증됨, 공식 전용, 미검증).
- SysEx 섹션: 요청 포맷, 바이트 오프셋이 포함된 덤프 포맷, 디코딩 방법, 체크섬, 사용자 자체 장치의 예시(짧은 16진수).
- 알려진 특이사항 및 충돌(예: 두 문서가 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