Aller au contenu principal

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 :

SectionCe qu'elle configure
NomNom du produit affiché à l'hôte.
IDUn 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.
BoutonsCombien 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'axe8 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 switches0 à 4 hat switches à quatre directions.
LEDNombre de LED pilotées par l'hôte (pensez à la LED CapsLock, mais en plus flexible).
Axe FFBCombien 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 sous ElectroSeed <Nom>. Avec nHIDPro, 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.
  • 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) ───────────┘

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
nKeyboardConstruire un clavier USB HID — c.-à-d. le PC voit la carte comme un clavier qui tape des caractères.
nKeyMapper 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.

Examples/09-USB/Joystick.

Choisir un exemple de départ​

Le dossier d'exemples contient un échantillon abouti pour presque chaque forme de projet HID :

Forme du projetExemple
Joystick autonomeJoystick
Récepteur de gamepad sans filNRF52_DongleHID
Volant de sim-racingHIDWheel, FFBWheel
PédalierPedals_1A, Pedals_Hx711_2A
Boîte de vitessesDIY_Shifter, GearShifterWithJoystick
Button box (16 boutons)MixingBox_6A
ClavierKeyboard

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.