SpeakingColors/claude-skills

---

name: hardware-protocol-capture description: Utiliser pour documenter comment un périphérique matériel musical est contrôlé via MIDI (CC, NRPN, SysEx) ou USB afin de construire un contrôleur, un éditeur ou un gestionnaire de patches : recherche de documentation officielle, capture du trafic depuis l'appareil de l'utilisateur, décodage des dumps de patches et rédaction d'un document d'implémentation MIDI vérifié.

Capture de protocole matériel

Compétence communautaire non officielle. N'est pas un conseil juridique. Capturer uniquement les appareils que l'utilisateur possède.

0. Règles

• L'appareil est la source de vérité. Les documents peuvent être erronés ou obsolètes ; une capture de l'appareil réel avec le firmware de l'utilisateur est la preuve.
• Ordre des sources : 1) les documents officiels du fabricant, 2) les captures du propre matériel de l'utilisateur, 3) les documents tiers (marquer comme non vérifié jusqu'à vérification sur le matériel).
• Chaque entrée dans le document final porte un statut : vérifié sur matériel, provenant uniquement de la documentation officielle, ou non vérifié.
• Sauvegarder les patches et paramètres de l'appareil avant d'envoyer quoi que ce soit d'inconnu. Ne jamais envoyer de messages de mise à jour du firmware, de bootloader, d'écriture flash ou de réinitialisation d'usine tant que leur format n'est pas entièrement compris.
• Donner une étape à la fois aux non-programmeurs. Des réponses courtes d'abord.

1. Trouver les documents officiels

• Rechercher un document "MIDI Implementation" ou "MIDI data format" pour le produit sur la page d'assistance du fabricant, ainsi que le tableau d'implémentation MIDI du manuel d'utilisation. Exemple : KORG publie l'implémentation MIDI du minilogue xd sous forme d'un fichier texte séparé (téléchargement après acceptation d'une licence personnelle non commerciale). Lier à ces documents ; ne pas les copier dans des dépôts publics sauf si leur licence le permet.
• Vérifier la révision et la date du document par rapport à la version du firmware de l'appareil. Les mises à jour du firmware peuvent modifier les formats. Exemple : une bibliothèque tierce pour ce synthétiseur note que certains fichiers de preset de firmware plus récent utilisent des blocs de programme de 448 octets, et non le format de 1024 octets décrit dans la spécification (V : README de oxur/minilogue-xd). Toujours tester un dump du firmware réel de l'utilisateur.
• Les listes communautaires (telles que midi.guide, CC BY-SA 4.0) sont des points de départ utiles. Conserver leur licence et attribution, et vérifier les entrées.

2. Capturer MIDI (USB MIDI class-compliant et DIN MIDI)

Outils par système (vérifier que chacun est installé ou installable) :

• Linux : amidi et aseqdump (utilitaires ALSA) pour les ports bruts et les événements séquenceur ; receivemidi et sendmidi sont des outils en ligne de commande multiplateformes.
• Windows : MIDI-OX ou un moniteur similaire.
• macOS : Snoize MIDI Monitor ou similaire.

Méthode :

1. Enregistrer une référence : connecter l'appareil, démarrer le moniteur, ne rien toucher.
2. Modifier un seul contrôle à la fois. Enregistrer le message, puis déplacer le contrôle à son minimum, milieu et maximum et enregistrer chacun.
3. Noter la direction : appareil vers hôte (bouton tourné) et hôte vers appareil (message envoyé à l'appareil). Tester les deux.
4. Tester avec l'appareil dans différents modes (global versus partie, couche, séquenceur, mouvement) car le même contrôle peut envoyer des messages différents.
5. Écrire un tableau : contrôle, type de message, numéro CC ou NRPN ou octets SysEx, min, max, résolution (7 bits ou 14 bits), direction, gestion des canaux, statut.

Requête et dump SysEx :

• Utiliser la demande de dump documentée, recevoir le dump dans un fichier, puis modifier exactement un paramètre sur l'appareil, dumper à nouveau, et différencier les deux fichiers. Les octets modifiés montrent où se trouve ce paramètre.
• Vérifier l'enveloppe SysEx : commence par F0, ID fabricant, ID appareil ou modèle, se termine par F7. Noter les octets d'ID fabricant.
• De nombreux appareils emballent des données 8 bits dans des octets SysEx 7 bits. Trouver la règle d'emballage dans le document officiel (par exemple, le codec 7 bits vers 8 bits de KORG est listé dans sa spécification) et décoder avant de différencier.
• Trouver et vérifier toute somme de contrôle en modifiant un paramètre et en recalculant. Ne pas deviner ; tester contre des dumps de l'appareil.

3. Capturer USB (appareils non class-compliant, applications propriétaires)

Nécessaire lorsqu'un appareil utilise un pilote propriétaire ou des messages de contrôle USB personnalisés (par exemple certains mélangeurs d'interfaces audio) et qu'aucun port MIDI ne transporte les données.

• Wireshark enregistre les URB USB, qui sont des transferts tels que vus par la pile hôte, non des paquets USB individuels ; les paquets bruts nécessitent un analyseur matériel (V : wiki Wireshark, configuration capture USB).
• Linux : sudo modprobe usbmon s'il n'y a pas de périphériques /dev/usbmon* ; capturer sur usbmonN pour le bus N, ou usbmon0 pour tous les bus ; l'utilisateur doit pouvoir lire les périphériques usbmon (groupe, règle udev ou ACL) (V).
• Windows : utiliser USBPcap (V). Des problèmes passés incluent le blocage de la souris ou du clavier ; vérifier le wiki avant d'installer.
• macOS : la capture utilise l'interface XHC20 après sudo ifconfig XHC20 up ; le wiki indique que l'intégrité du système doit apparemment être désactivée sur Catalina et versions ultérieures (V). Préférer un autre système si possible.
• Capturer la propre application du fabricant communiquant avec l'appareil de l'utilisateur, par exemple à partir d'un invité Windows dans une machine virtuelle avec l'appareil passé en travers tandis qu'un hôte Linux capture sur le bus correspondant (V : méthode décrite sur le wiki Wireshark).
• Appliquer la même discipline un-changement-à-la-fois : effectuer une action dans l'application du fabricant, capturer, la marquer dans le journal.
• Décoder les transferts de contrôle (type de requête, requête, valeur, index, données) dans un tableau. Répéter chaque action pour confirmer que les octets sont stables.

4. Autorisé et interdit

• Observer les messages qu'un programme envoie à son propre appareil, et lire la documentation officielle, est la manière normale d'apprendre un protocole.
• Ne pas décompiler ou désassembler le logiciel de quelqu'un d'autre, et ne pas copier son code, graphiques, tables de données ou presets. Certaines lois autorisent la rétro-ingénierie limitée pour l'interopérabilité, mais les contrats de licence peuvent l'interdire et les règles varient selon les pays. La capture au niveau du fil donne les mêmes faits sans cette question.
• Ne pas publier de documents du fabricant, de patches d'usine, de firmware ou de logos. Lier vers eux.
• Ne pas utiliser les captures pour contourner la protection contre la copie ou les licences.

5. Rédiger le document d'implémentation MIDI

Utiliser docs/MIDI-IMPLEMENTATION.md dans le dépôt du projet :

• En-tête : appareil, version du firmware testée, date, sources (titre du document officiel, révision et lien ; configuration de capture).
• Conventions globales : canal, ordre des octets, emballage 7 bits, méthode de somme de contrôle.
• Tableau des contrôles : nom, message, plage, résolution, direction, notes, statut (vérifié sur matériel, officiel uniquement, non vérifié).
• Section SysEx : formats de requête, formats de dump avec décalages d'octets, comment décoder, somme de contrôle, exemples (hex court) provenant du propre appareil de l'utilisateur.
• Bizarreries et conflits connus (par exemple deux documents en désaccord sur un numéro CC), avec comment chacun a été résolu.
• Une liste de contrôle de test que l'utilisateur peut répéter sur un nouveau firmware.

6. Vérifications de sécurité avant que le contrôleur n'envoie quoi que ce soit

• Envoyer uniquement les messages enregistrés dans le tableau comme vérifiés ou documentés.
• Limiter et fragmenter la sortie ; certains appareils ignorent les messages lorsqu'ils sont submergés.
• Ne jamais envoyer automatiquement au démarrage ; lire d'abord, envoyer uniquement sur action de l'utilisateur.
• Conserver un bouton "restaurer depuis une sauvegarde" à côté de toute fonction d'écriture.

Sources

• Wiki Wireshark, configuration capture USB : https://wiki.wireshark.org/CaptureSetup/USB
• KORG, minilogue xd MIDI Implementation (page de téléchargement de l'assistance) : https://www.korg.com/us/support/download/manual/0/811/4440/
• oxur/minilogue-xd (implémentation Rust tierce de cette spécification) : https://github.com/oxur/minilogue-xd