Construire des périphériques USB HID
Une grande partie des projets NodeBlue se résume à « faire en sorte que le PC voie cette carte comme un clavier / gamepad / joystick / souris, et lui fournir des valeurs ». L'IDE rend cela étonnamment simple — vous n'écrivez pas de descripteur HID à la main ; vous composez votre périphérique à partir d'un petit ensemble de modules conscients du HID, y insérez les entrées correspondantes, et le firmware produit un périphérique USB fonctionnel que l'hôte énumère comme un périphérique standard.
Le tutoriel Contrôleurs de jeu couvrait le testeur côté IDE des périphériques HID ; celui-ci couvre leur construction.
Le cœur : nHID / nHIDPro
Le module nHID est le périphérique HID central. Chaque instance est un endpoint USB que l'hôte voit comme un périphérique. Sa boîte de dialogue d'édition est riche parce qu'elle porte l'intégralité du descripteur HID :
| Section | Ce qu'elle configure |
|---|---|
| Nom | Nom du produit affiché à l'hôte. |
| ID | Un petit nombre écrit dans le champ bcdDevice du périphérique USB. Le VID et le PID sont fixés par la carte, si bien que deux cartes du même modèle seraient indiscernables pour l'hôte (et pour l'IDE) — l'ID est ce qui permet d'en brancher plusieurs à la fois tout en les distinguant. |
| Boutons | Combien de boutons numériques (1–128). |
| Axes (X, Y, Z, RX, RY, RZ, S0, S1) | Quels axes le périphérique expose. |
| Précision d'axe | 8 ou 16 bits, signé ou non signé — le format de données pouvant être choisi pour chaque axe. |
| Axe caché | Nombre d'axes cachés — voir ci-dessous. |
| Hat switches | 0 à 4 hat switches à quatre directions. |
| LED | Nombre de LED pilotées par l'hôte (pensez à la LED CapsLock, mais en plus flexible). |
| Axe FFB | Combien d'axes portent du retour de force (voir le tutoriel FFB). |
| Type (Pro uniquement) | Generic / Fanatec / Custom. Voir nHID face à Pro ci-dessous. |
Axes cachés
Un axe caché est un axe dont la valeur est envoyée dans le rapport d'entrée HID mais n'est pas déclarée comme axe de contrôleur de jeu dans le descripteur de périphérique côté OS. La vue standard des contrôleurs de jeu de l'OS ne l'affiche pas ; il n'apparaît dans aucune liste d'axes du panneau de configuration. Mais les octets sont bien là dans le rapport — une application qui dialogue directement avec le périphérique via son interface HID brute (SimHub, votre propre outil de calibration, une application compagnon côté fabricant…) peut les lire.
Deux raisons courantes d'utiliser des axes cachés :
- Des entrées mixées que vous voulez tout de même exposer pour le réglage. Deux palettes d'embrayage passées par un ClutchManager avec une stratégie de bite point (« point de patinage ») se fondent en un seul axe d'embrayage que le simulateur voit. Les deux palettes brutes peuvent être transportées comme axes cachés afin que SimHub (ou une interface personnalisée) puisse les lire et laisser l'utilisateur régler le bite point par rapport à la course réelle de la palette — le simulateur ne voit toujours que la sortie combinée.
- La télémétrie du périphérique. Niveau de batterie, qualité de la liaison radio, la lecture d'un capteur interne que vous voulez qu'une application compagnon affiche — tout ce que vous aimeriez remonter à côté des données du gamepad sans polluer la liste d'axes de l'OS. Les cartes sans fil l'utilisent typiquement pour l'état de la batterie et de la liaison.
Un axe caché n'est qu'un port de plus sur votre nSerializer : alimentez-le avec la valeur que vous voulez remonter, le firmware la place dans le rapport à la position que le descripteur HID réserve.
nHID face à nHIDPro
Les deux modules parlent la même forme d'entrée (un tampon portant un rapport HID entièrement mis en forme — voir ci-dessous). Ce que nHIDPro ajoute :
- Pas de préfixe « ElectroSeed ». Compilé avec
nHID, le périphérique apparaît sur l'hôte sousElectroSeed <Nom>. AvecnHIDPro, le préfixe est supprimé, l'hôte voit exactement le Nom que vous avez saisi. - Sélecteur de type de périphérique — Pro offre un paramètre Type avec trois préréglages :
- Generic — un gamepad / joystick HID générique, la même forme que produit
nHID. - Fanatec — le périphérique s'annonce comme une base de volant Fanatec. Utilisez ceci pour convertir un vrai volant Fanatec : l'hôte (le simulateur) traite votre carte comme la base, si bien que les sorties du volant atteignent le jeu via la chaîne de pilotes Fanatec normale.
- Custom — expose une longue liste de contrôles de personnalisation incluant le VID / PID, les chaînes fabricant / produit, la version, la fréquence de scrutation, etc. — pour les cas où le pilote hôte recherche une signature de périphérique spécifique.
- Generic — un gamepad / joystick HID générique, la même forme que produit
- Rapport personnalisé supplémentaire. Un second rapport HID peut être attaché à côté du rapport standard. Particulièrement utile pour les périphériques personnalisés SimHub, où SimHub s'attend à dialoguer avec un identifiant de rapport non standard portant sa propre charge utile (pour les bandeaux LED).
Comment l'entrée arrive — la chaîne canonique
nHID n'a pas un port d'entrée par bouton / axe / hat. Il a une seule entrée tampon. Le tampon est le rapport HID complet — boutons empaquetés en bits, axes en un ou deux octets chacun, hats empaquetés ensemble — mis en forme dans l'ordre que déclare le descripteur HID du firmware.
Vous assemblez ce tampon avec les modules de data-packing. Le motif est uniforme pour chaque module de la famille HID « sortant » — nHID, nHIDPro, nBLEGamePad et les deux modules radio nNRF24 / nNRF52. Tous les quatre acceptent le même format de tampon sur leur unique entrée. Choisissez le transport en choisissant le module ; la construction du rapport ne change pas.
buttons ──────► nBitPacker ─────┐
│
hat switch (nHatSwitch output) ─┤──► nSerializer ──► nHID / nHIDPro / nBLEGamePad / nNRF24 / nNRF52
│
axes (analog values) ───────────┘
nBitPackerempaquette N signaux de boutons numériques dans un tableau d'octets (un bit chacun). Tutoriel data-packing → famille BitPacker.nSerializerconcatène le mot de boutons empaqueté, chaque valeur d'axe et le hat en un seul tampon dans l'ordre du rapport HID. Tutoriel data-packing → Serializer / UnSerializer.- Le module de la famille HID transmet ce tampon — à l'hôte via USB (
nHID/nHIDPro), via BLE (nBLEGamePad), ou via une liaison radio NodeBlue (nNRF24/nNRF52).
Passer d'une construction HID filaire à une construction sans fil se fait en changeant un seul module : même sortie de Serializer, consommateur différent. C'est pourquoi le dossier d'exemples propose côte à côte les motifs HIDWheel et NRF52_DongleHID.
Boutons
Les signaux sources sont des modules Button anti-rebondis (ou tout ce qui en amont émet 0/1). Chaque bouton alimente une entrée d'un nBitPacker ; le Nb Entrées du packer correspond au nombre de boutons, chaque entrée occupant un bit. La sortie du packer est un tableau d'octets que le Serializer insère dans le rapport.
La sortie de nBitPacker est un tableau d'octets, dont la taille est de ⌈N / 8⌉ octets pour N entrées de bouton (donc 9 à 16 boutons produisent un tampon de 2 octets, 17 à 24 boutons un tampon de 3 octets, etc.). Quelle que soit la largeur, vous câblez ce tableau dans une entrée du Serializer et le Serializer l'insère dans le rapport.
Axes
Tout module produisant une valeur — nAnalogInput, un capteur d'angle magnétique (AS5600), une cellule de charge, la valeur comptée d'un nHWEncoder — alimente directement une entrée du Serializer. Son type doit correspondre à la précision déclarée sur nHID :
- 8 bits non signé →
u8(0..255) - 8 bits signé →
s8(-128..127) - 16 bits non signé →
u16(0..65535) - 16 bits signé →
s16(-32768..32767)
Utilisez un module Range pour remapper ce que votre capteur produit dans le type sous lequel l'axe a été déclaré.
Une chaîne de pédalier typique :
HX711 → FloatIIRFilter (lissage) → RangeModule (apprend les extrêmes, sort dans la plage d'axe déclarée) → entrée du Serializer pour cet axe.
Un volant typique :
AS5600 → RangeDeadZone (marges de fin de course si nécessaire) → entrée du Serializer.
Hat switches
Un hat à quatre directions (D-pad / POV) est une seule valeur numérique : 0 = haut, 1 = droite, 2 = bas, 3 = gauche, 8 (ou -1) = centré. Le module nHatSwitch enveloppe quatre entrées numériques (haut / bas / gauche / droite) dans cette valeur unique. Sa sortie va dans un port du Serializer comme un axe.
Claviers — nKeyboard et nKey
Deux variantes distinctes :
| Module | À utiliser quand |
|---|---|
| nKeyboard | Construire un clavier USB HID — c.-à-d. le PC voit la carte comme un clavier qui tape des caractères. |
| nKey | Mapper une valeur d'entrée numérique vers une table configurable de frappes — appuyer sur un bouton envoie l'une de N touches / chaînes préconfigurées. |
nKey est le pilier des button boxes. Définissez une table d'entrées ; la valeur sur l'entrée choisit quelles frappes de quelle entrée sont envoyées. Mode choisit le style de recherche : par index (une valeur codée 1-parmi-N), par caractère, etc.
Le projet Examples/09-USB/Keyboard montre le clavier minimal. PS2ToUSBKeyboard fait le pont entre un ancien clavier PS/2 et l'USB ; PS2ToUSBKeyboardRadio ajoute une liaison NRF24 sans fil pour que le clavier puisse se trouver ailleurs.
Joystick (analogique)
Le module autonome nJoystick est un petit tout-en-un — deux axes analogiques (X / Y) sur des broches ADC configurées, plus un bouton, avec anti-rebond intégré et un filtre de moyennage. Déposez-le et câblez sa sortie sur une paire d'axes nHID pour un stick analogique classique.
Pour des sticks construits à partir de pièces séparées (capteur + bouton + Range), câblez les pièces directement sur nHID sans nJoystick.
Choisir un exemple de départ
Le dossier d'exemples contient un échantillon abouti pour presque chaque forme de projet HID :
| Forme du projet | Exemple |
|---|---|
| Joystick autonome | Joystick |
| Récepteur de gamepad sans fil | NRF52_DongleHID |
| Volant de sim-racing | HIDWheel, FFBWheel |
| Pédalier | Pedals_1A, Pedals_Hx711_2A |
| Boîte de vitesses | DIY_Shifter, GearShifterWithJoystick |
| Button box (16 boutons) | MixingBox_6A |
| Clavier | Keyboard |
Inspirez-vous de la correspondance la plus proche — les motifs de câblage se répètent.
Suite dans la famille de classe HID : MIDI — le cousin instrument de musique du HID. Puis le Protocole NodeBlue Interface que l'IDE utilise pour dialoguer avec une carte en cours d'exécution, et enfin — pour piloter des choses qui bougent — Moteurs et drivers de moteurs.