captura-de-protocolo-de-hardware

---

name: captura-de-protocolo-de-hardware description: Use ao documentar como um dispositivo de hardware musical é controlado via MIDI (CC, NRPN, SysEx) ou USB, para que se possa construir um controlador, editor ou bibliotecário: encontrar documentação oficial, capturar tráfego do próprio dispositivo do usuário, decodificar dumps de patches e escrever um documento verificado de implementação MIDI.

Captura de protocolo de hardware

Skill comunitária não oficial. Não é aconselhamento jurídico. Capture apenas dispositivos que o usuário possui.

0. Regras

• O dispositivo é a fonte da verdade. Documentos podem estar errados ou desatualizados; uma captura do dispositivo real com o firmware do usuário é a prova.
• Ordem das fontes: 1) documentos oficiais do fabricante, 2) capturas do hardware do próprio usuário, 3) documentos de terceiros (marque como não verificado até ser checado no hardware).
• Cada entrada no documento final carrega um status: verificado no hardware, apenas de documento oficial, ou não verificado.
• Faça backup dos patches e configurações do dispositivo antes de enviar qualquer coisa desconhecida. Nunca envie mensagens de firmware, bootloader, gravação flash ou reset de fábrica até que seu formato seja totalmente compreendido.
• Dê um passo de cada vez para não-programadores. Respostas curtas primeiro.

1. Encontre os documentos oficiais

• Procure por um documento "MIDI Implementation" ou "MIDI data format" para o produto na página de suporte do fabricante, além do gráfico de implementação MIDI no manual do proprietário. Exemplo: KORG publica a Implementação MIDI do minilogue xd como um arquivo de texto separado (baixe após aceitar uma licença pessoal e não comercial). Link para esses documentos; não os copie em repositórios públicos a menos que sua licença permita.
• Verifique a revisão e data do documento em relação à versão do firmware do dispositivo. Atualizações de firmware podem alterar formatos. Exemplo: uma biblioteca de terceiros para esse sintetizador observa que alguns arquivos de presets de firmware mais recente usam blobs de programa de 448 bytes, não o formato de 1024 bytes que a especificação descreve (V: oxur/minilogue-xd README). Sempre teste um dump do firmware real do usuário.
• Listas da comunidade (como midi.guide, CC BY-SA 4.0) são pontos de partida úteis. Mantenha sua licença e atribuição, e verifique as entradas.

2. Capture MIDI (USB MIDI compatível com classe e DIN MIDI)

Ferramentas por sistema (verifique se cada uma está instalada ou é instalável):

• Linux: amidi e aseqdump (utilitários ALSA) para portas raw e eventos de sequenciador; receivemidi e sendmidi são ferramentas de linha de comando multiplataforma.
• Windows: MIDI-OX ou um monitor similar.
• macOS: Snoize MIDI Monitor ou similar.

Método:

1. Grave uma linha de base: conecte o dispositivo, inicie o monitor, não toque em nada.
2. Altere um controle de cada vez. Grave a mensagem, mova o controle para seu mínimo, meio e máximo e grave cada um.
3. Anote a direção: dispositivo para host (botão girado) e host para dispositivo (mensagem enviada ao dispositivo). Teste ambas.
4. Teste com o dispositivo em diferentes modos (global versus parte, camada, sequenciador, motion) porque o mesmo controle pode enviar mensagens diferentes.
5. Escreva uma tabela: controle, tipo de mensagem, número CC ou NRPN ou bytes SysEx, min, max, resolução (7 bits ou 14 bits), direção, tratamento de canal, status.

SysEx de solicitação e dump:

• Use a solicitação de dump documentada, receba o dump em um arquivo, altere exatamente um parâmetro no dispositivo, faça o dump novamente e diferencie os dois arquivos. Os bytes alterados mostram onde aquele parâmetro reside.
• Verifique o envelope SysEx: começa com F0, ID do fabricante, IDs do dispositivo ou modelo, termina com F7. Anote os bytes do ID do fabricante.
• Muitos dispositivos empacotam dados de 8 bits em bytes SysEx de 7 bits. Encontre a regra de empacotamento no documento oficial (por exemplo, o codec de 7 para 8 bits da KORG está listado em sua especificação) e decodifique antes de diferenciar.
• Encontre e verifique qualquer checksum alterando um parâmetro e recalculando. Não adivinhe; teste contra dumps do dispositivo.

3. Capture USB (dispositivos não compatíveis com classe, aplicativos do fabricante)

Necessário quando um dispositivo usa um driver proprietário ou mensagens de controle USB personalizadas (por exemplo, alguns mixers de interfaces de áudio) e nenhuma porta MIDI carrega os dados.

• Wireshark grava URBs USB, que são transferências como vistas pela pilha do host, não pacotes USB individuais; pacotes brutos precisam de um sniffer de hardware (V: wiki do Wireshark, configuração de captura USB).
• Linux: sudo modprobe usbmon se não houver dispositivos /dev/usbmon*; capture em usbmonN para o barramento N, ou usbmon0 para todos os barramentos; o usuário deve poder ler os dispositivos usbmon (grupo, regra udev ou ACL) (V).
• Windows: use USBPcap (V). Problemas passados incluíram entrada de mouse ou teclado bloqueada; verifique o wiki antes de instalar.
• macOS: a captura usa a interface XHC20 após sudo ifconfig XHC20 up; o wiki diz que a Proteção de Integridade do Sistema aparentemente precisa ser desabilitada no Catalina e posteriores (V). Prefira outro sistema se possível.
• Capture o aplicativo do próprio fabricante se comunicando com o dispositivo do usuário, por exemplo, de um convidado Windows em uma máquina virtual com o dispositivo passado enquanto um host Linux captura no barramento correspondente (V: método descrito no wiki do Wireshark).
• Faça a mesma disciplina de uma alteração de cada vez: execute uma ação no aplicativo do fabricante, capture, marque-a no log.
• Decodifique transferências de controle (tipo de requisição, requisição, valor, índice, dados) em uma tabela. Repita cada ação para confirmar que os bytes são estáveis.

4. Permitido e não permitido

• Observar as mensagens que um programa envia ao próprio dispositivo do usuário e ler a documentação oficial é a forma normal de aprender um protocolo.
• Não descompile nem desmonte o software de outra pessoa, e não copie seu código, gráficos, tabelas de dados ou presets. Algumas leis permitem engenharia reversa limitada para interoperabilidade, mas acordos de licença podem proibi-la e as regras variam por país. A captura no nível do fio fornece os mesmos fatos sem essa questão.
• Não publique documentos do fabricante, patches de fábrica, firmware ou logotipos. Link para eles.
• Não use capturas para contornar proteção contra cópia ou licenciamento.

5. Escreva o documento de implementação MIDI

Use docs/MIDI-IMPLEMENTATION.md no repositório do projeto:

• Cabeçalho: dispositivo, versão do firmware testada, data, fontes (título do documento oficial, revisão e link; configuração da captura).
• Convenções globais: canal, ordem dos bytes, empacotamento de 7 bits, método de checksum.
• Tabela de controles: nome, mensagem, faixa, resolução, direção, notas, status (verificado no hardware, apenas oficial, não verificado).
• Seção SysEx: formatos de requisição, formatos de dump com offsets de bytes, como decodificar, checksum, exemplos (hex curto) do próprio dispositivo do usuário.
• Peculiaridades e conflitos conhecidos (por exemplo, dois documentos discordando sobre um número CC), com como cada um foi resolvido.
• Uma lista de verificação de testes que o usuário pode repetir em novo firmware.

6. Verificações de segurança antes do controlador enviar algo

• Envie apenas mensagens registradas na tabela como verificadas ou documentadas.
• Acelere e divida a saída em pedaços; alguns dispositivos descartam mensagens quando inundados.
• Nunca envie automaticamente ao iniciar; leia primeiro, envie apenas por ação do usuário.
• Mantenha um botão "restaurar do backup" próximo a qualquer recurso de gravação.

Fontes

• Wiki do Wireshark, configuração de captura USB: https://wiki.wireshark.org/CaptureSetup/USB
• KORG, Implementação MIDI do minilogue xd (página de download de suporte): https://www.korg.com/us/support/download/manual/0/811/4440/
• oxur/minilogue-xd (implementação Rust de terceiros dessa especificação): https://github.com/oxur/minilogue-xd