Boutons et interrupteurs
NodeBlue regroupe sous la catégorie « boutons » les modules qui transforment une fermeture de contact physique en un signal numérique propre — boutons poussoirs, interrupteurs à bascule/SPDT, boutons analogiques (un bouton lu à travers un pont diviseur résistif sur une broche ADC), et le motif de balayage matriciel qui permet à un petit nombre de GPIO de lire un nombre bien plus grand de contacts. Les lecteurs de broche numérique de base (nDigitalInput, nDigitalInt) y trouvent aussi leur place — ce sont les briques de plus bas niveau que les modules supérieurs enveloppent.
Les lecteurs numériques de base
Ce sont le socle de la famille — pas d'anti-rebond, pas de bascule, juste « est-ce que cette broche est haute ou basse en ce moment ».
| Module | Ce qu'il fait | Quand y recourir |
|---|---|---|
| nDigitalInput | Lit une broche numérique à chaque tick de Sync. La sortie u8 vaut 0 / 1 (avec inversion optionnelle). Mode de polarisation configurable. | Le signal que vous lisez est déjà propre — une sortie au niveau logique d'une autre puce, un opto-isolateur, un étage d'entrée à trigger de Schmitt. |
| nDigitalInt | Même idée, mais déclenché par une interruption de broche (CHANGE / RISING / FALLING) plutôt que par un Sync. Il s'ajoute au groupe InterruptSync. La broche doit pouvoir gérer les interruptions sur le microcontrôleur cible. | Vous ne pouvez pas vous permettre la latence du polling — une impulsion de tachymètre, un index d'encodeur matériel, un événement externe pouvant survenir entre deux ticks. |
Aucun des deux ne fait d'anti-rebond. Pour un contact mécanique qui rebondit dans l'air, utilisez plutôt nButton.
Voir Examples/02-Digital/DigitalIn.
Boutons poussoirs — nButton
nButton est le cheval de bataille pour un contact momentané câblé entre une broche numérique et la masse (ou Vcc).
| Paramètre | Description |
|---|---|
| Broche | Broche numérique à laquelle le bouton est câblé. |
| Polarisation | INPUT_PULLUP, INPUT, etc. Choisissez la polarisation correspondante pour que l'état non appuyé soit un niveau logique stable. |
| Anti Rebond | Temps d'anti-rebond en ms. 10 est une valeur par défaut sûre pour des interrupteurs tact « clicky » ; les boutons d'arcade à longue course peuvent nécessiter 20 à 30. |
| DebounceMode | Valeur par défaut du modèle DM_SAFE — voir les modes d'anti-rebond ci-dessous. |
| Inverser | Inverse la logique pour que « appuyé » soit lu comme 1, quel que soit le rail auquel vous avez câblé le commun. |
La sortie est un unique port u8 qui vaut 1 tant que le bouton est maintenu, 0 sinon. Il se connecte automatiquement à tout *Packer en aval (la chaîne de tampon HID).
Voir Examples/02-Digital/Button.
Modes d'anti-rebond
Le paramètre partagé DebounceMode, présent sur chaque module de la famille des boutons, détermine comment le firmware élimine les parasites de la lecture brute. DM_SAFE est la bonne réponse pour presque tous les interrupteurs mécaniques ; les autres modes sont là pour les cas particuliers où vous préférez optimiser la vitesse ou traiter des profils de rebond spécifiques.
Variantes de bouton poussoir pour des sorties de type valeur
Le nButton de base produit un booléen. Les variantes ci-dessous produisent plutôt une sortie de type analogique — utile lorsque le bouton agit comme un modificateur sur une valeur numérique plutôt que comme un événement numérique.
| Module | Entrées | Sortie | Ce qu'il fait |
|---|---|---|---|
| nButtonGain | Gain (f32), In (u8) | f32 | Tant que le bouton est appuyé, la sortie est égale à l'entrée Gain multipliée par le paramètre Gain. Relâché, la sortie vaut 0. Utilisation typique en sim-racing : modificateur « flat-shift » sur une valeur de gaz tant qu'une palette est maintenue. |
| nButtonToggle | Toggle, On, Off (u8 chacun) | u8 | Bascule à verrouillage. Chaque appui sur Toggle inverse l'état ; On force 1 ; Off force 0. L'état verrouillé se maintient d'un cycle à l'autre (contrairement à un nButton momentané). |
| nButtonGainToggle | Gain (f32), In (u8) | f32 | La variante à bascule de nButtonGain — la sortie Gain × multiplicateur est verrouillée par le front montant de In et déverrouillée par le suivant. |
Chacun de ces modules peut aussi piloter directement une broche physique (le paramètre Broche est optionnel — le laisser sur PIN_UNUSED rend le module purement « piloté par câblage »). Les commandes Polarisation / Anti Rebond / Inverser sont masquées lorsqu'aucune broche n'est câblée.
Voir Examples/02-Digital/ButtonToggleLed pour un nButtonToggle pilotant une LED.
Interrupteurs à bascule / SPDT — nToggleSwitch
Une bascule physique a soit deux positions (SPDT — un contact mobile, deux broches extérieures), soit trois positions (centre-off). nToggleSwitch est un module modèle qui gère les deux cas :
- En interne, il instancie un ou deux
nButton(un par broche extérieure) partageant les mêmes réglages Polarisation / Anti Rebond / Inverser. - La sortie est un port par broche extérieure — un seul vaut
1à la fois (ou aucun, pour la position centrale d'une bascule à 3 positions).
| Paramètre | Description |
|---|---|
| Broche 1 / Broche 2 | Les deux GPIO des broches extérieures. Pour un interrupteur à 2 positions, seul Broche 1 est utilisé. |
| Nb Sorties | 1 pour un comportement centre-off / deux positions, 2 pour un SPDT complet ou 3 positions. |
| Polarisation / Anti Rebond / Inverser | Partagés entre les deux boutons internes. |
La position centrale d'une bascule à 3 positions est implicite — lorsqu'aucune broche n'est mise à la masse, les deux sorties valent 0.
Un seul bouton sur une broche analogique — nAnalogButton
Lorsque vous voulez placer un seul bouton sur une broche déjà configurée en entrée ADC, nAnalogButton est le bon lecteur. Il lit la broche analogique et utilise un comparateur à hystérésis pour décider si la tension se trouve dans la plage « appuyé ».
| Paramètre | Description |
|---|---|
| Broche | La broche analogique. |
| Ref ADC / Résolution | Réglage de l'étage d'entrée analogique — mêmes commandes que nAnalogInput. |
| Anti Rebond | Temps d'anti-rebond (ms). Souvent moins critique que pour les boutons numériques, car le comparateur du domaine analogique lisse déjà les brefs parasites. |
| Inverser | Inverse le sens « tension haute = appuyé » si vous avez câblé la résistance sur l'autre rail. |
| Threshold (haut / bas) | Les seuils de commutation du comparateur, en unités ADC brutes, volts, pourcentage ou comptes non signés (sélectionné par le sous-champ Units). L'hystérésis est l'écart entre les deux — définissez-le assez large pour qu'un appui sur le bouton ne fasse pas osciller entre les deux états. |
La sortie est un u8 — 1 lorsque le comparateur indique « appuyé », 0 sinon.
Pour plusieurs boutons partageant une broche analogique, voir la section suivante.
Plusieurs boutons sur une seule broche analogique
Lorsque vous voulez lire plusieurs boutons via une seule broche ADC, vous avez deux options selon que vous avez besoin ou non de détecter des appuis simultanés.
Échelle de résistances — un bouton à la fois
Le schéma le plus simple : chaque bouton est câblé à travers une résistance différente dans une échelle de résistances, de sorte que chaque appui produit une tension analogique distincte. Le module nResLadder (traité dans le tutoriel sur les multiplexeurs) décode cette tension en un index de position.
La chaîne canonique :
nAnalogInput→nResLadder→nDeMultiplexer→ sorties de boutons individuelles
C'est exactement la chaîne à l'intérieur de nJoycoder. La contrainte : un seul bouton peut être appuyé à la fois — si deux le sont, la tension résultante se situe quelque part entre deux valeurs connues et le décodeur choisit la plus proche, ce qui est faux pour les deux.
BODAC — plusieurs boutons appuyés simultanément
Pour la détection d'appuis multiples, l'astuce BODAC (Buttons Organized as a Digital to Analog Converter) est la bonne réponse. Chaque bouton commute une résistance dont la valeur est une puissance de deux différente, de sorte que la combinaison parallèle de n'importe quel sous-ensemble de boutons appuyés produit une valeur analogique unique que le firmware peut décoder pour retrouver l'ensemble exact. Jusqu'à 5 boutons sur une seule broche analogique, n'importe quelle combinaison en même temps, sans diode requise.
Le module nBodac gère le décodage. Le côté matériel est décrit sur la page produit BODAC ; un câblage typique est présenté dans cet exemple de câblage. Une résistance de pull-up de 1,6 kΩ sur la ligne analogique est requise — plusieurs cartes ElectroSeed l'incluent déjà à bord (la famille MMWB et la série SamD21 WB), de sorte que pour ces cartes, il vous suffit de connecter le circuit imprimé BODAC et de vous passer du pull-up externe.
| Paramètre | Description |
|---|---|
| Broche | Broche analogique lisant la tension de l'échelle BODAC. |
| Nb Boutons | 2 à 5. |
| Anti Rebond | Temps d'anti-rebond en ms. |
| K0..K4 | Constantes de calibration — la valeur ADC attendue quand seul ce bouton est appuyé. Les valeurs par défaut correspondent aux valeurs de résistance standard du circuit BODAC ; les entrées Cal / CalStop permettent au firmware de les apprendre à partir d'un balayage de calibration en direct plutôt que de se fier aux valeurs nominales. |
| Ref ADC / Résolution / Moyenne | Réglage de l'étage d'entrée analogique. |
Sortie : un u8 par bouton (0/1), plus un port tampon Msg transportant le texte de progression de la calibration — câblez-le vers un affichage série / tableau de bord / Nextion pendant que vous calibrez.
Un tutoriel dédié couvre le BODAC de bout en bout : BODAC — boutons analogiques à appuis multiples.
Beaucoup de boutons sur peu de broches — nDigitalMatrix
Pour des nombres de boutons plus importants qui ne tiennent pas sur une seule broche analogique (plus d'environ 5), la réponse classique est une matrice de boutons : N lignes × M colonnes de boutons câblées de sorte que chaque ligne et chaque colonne soit une seule broche du microcontrôleur. La matrice lit N × M boutons avec N + M GPIO — une matrice 4×4 donne 16 boutons sur 8 broches, une matrice 8×8 donne 64 boutons sur 16 broches. L'effort de câblage n'en vaut la peine que lorsque vous avez beaucoup de boutons à lire ; pour moins d'environ 10 boutons, le BODAC ou la lecture broche par broche est plus simple.
nDigitalMatrix est le scanner : il parcourt les lignes une par une, pilotant chacune à son tour, et relit les broches de colonne pour voir quels boutons de cette ligne sont appuyés. Il fait cela en un seul tick de Sync — assez vite pour que l'utilisateur ne perçoive aucun délai.
| Paramètre | Description |
|---|---|
| Nb Lignes / Nb Colonnes | Jusqu'à 8 × 8 (= 64 boutons). |
| Broches de ligne (r0..r7) / Broches de colonne (c0..c7) | Les broches du microcontrôleur pour chaque ligne / colonne. |
| Anti Rebond | Temps d'anti-rebond en ms — appliqué par bouton après le balayage. |
| Niveau Scan | Indique si le balayage pilote chaque ligne à 0 (matrice active-bas avec pull-ups de colonne, l'arrangement courant) ou à 1. |
La sortie est un unique u32 avec un bit par position de la matrice — le firmware empaquette toute la matrice dans un seul entier, de sorte qu'en aval vous n'avez qu'un seul fil transportant l'état de chaque bouton. Injectez-le dans un nBitUnPacker pour le redécouper en signaux de boutons individuels, ou dans une chaîne nBitPacker → nSerializer → nHID pour envoyer toute la matrice sous forme de 64 boutons HID d'un seul coup.
Une matrice de boutons nue peut produire des rapports de touches « fantômes » lorsque trois touches sont appuyées simultanément en formant un L — le balayage ne peut pas distinguer le vrai troisième appui d'un appui « fantôme » au coin opposé. La solution standard consiste à placer une diode en série avec chaque bouton (anode côté bouton, cathode côté ligne de colonne), afin que le courant ne puisse circuler que dans un seul sens autour de la matrice. Le module nDigitalMatrix suppose que vous l'avez fait côté matériel ; rien dans le firmware ne peut compenser des diodes manquantes. (Le BODAC ne nécessite aucune diode — c'est la réponse bien plus simple lorsque ≤ 5 boutons suffisent.)
Voir Examples/02-Digital/ButtonMatrixHid.
Encodage de touches HID — nKey
nKey est le pont entre « un bouton a été appuyé » et « un clavier HID veut ce code de touche ». Il fait partie de la catégorie HID plutôt que Input, car il s'agit d'émettre un message de clavier USB, et non de lire du matériel.
Deux modes, choisis dans le paramètre Mode :
| Mode | Forme de l'entrée | Ce qu'il émet |
|---|---|---|
| KEY_MODULE_MODE_NUMBER | Une seule entrée Index (u8). | Recherche l'entrée Index dans la table interne et émet ses codes Press / Release. Utilisé en aval d'une chaîne nResLadder / nDeMultiplexer lorsque plusieurs boutons ont tous besoin de leur code HID depuis la même table de correspondance. |
| (mode par entrée) | Un port d'entrée par entrée de la table (jusqu'à 16). | Chaque entrée est un déclencheur sur front montant qui déclenche le code de touche correspondant. Utilisé lorsque chacun des N boutons pilote sa propre broche. |
La sortie comporte deux ports :
- Press (
u16) — le code d'usage HID à presser (par ex.KEY_A,MODIFIERKEY_SHIFT,KEY_MEDIA_PLAY_PAUSE). - Release (
u16) — le code à relâcher.
Câblez-les vers les entrées correspondantes de nKeyboard (USB) ou nBLEKeyboard (BLE).
Les 16 champs de texte (Text 1 .. Text 16) acceptent soit un seul caractère (a, 5, ,), soit l'une des constantes nommées de keylayouts.h (KEY_F1, MODIFIERKEY_CTRL, KEY_MEDIA_VOLUME_INC, KEY_SYSTEM_SLEEP, …). Le type de port Key de l'IDE effectue l'autocomplétion sur les constantes nommées.
Voir Examples/09-USB/Keyboard et les paires radio/hôte dans Boards/MM_NRF_Host/NRF_Host_To_HID_Keyboard / Boards/NRF_Dongle/NRF52_Dongle_Keyboard.
Assembler le tout
Un motif courant pour une boîte à boutons avec des types d'entrée mixtes :
Boutons poussoirs →
nButton× N →nBitPacker(1 bit chacun) →nSerializer→nHIDBascules à 2 positions →
nToggleSwitch(1 sortie) → même chaîne de packer.Boutons à échelle de résistances (croix de joystick, pavé de navigation — un seul appuyé à la fois) →
nAnalogInput→nResLadder→nDeMultiplexer→ même chaîne de packer.Boutons BODAC (jusqu'à 5 boutons, n'importe quelle combinaison en même temps) →
nAnalogInput→nBodac→ 5 sorties de boutons → même chaîne de packer.Matrice de boutons (8×8 = 64 boutons, pour de grands nombres de boutons) →
nDigitalMatrix→nBitUnPacker→ 64 fils →nBitPacker→nSerializer→nHID. Ou évitez le dépaquetage et injectez leu32directement dans lenBitPacker(un champ de 64 bits — même fil, moins de connexions).
Pour une sortie clavier HID au lieu de boutons de manette, remplacez l'étage final par nKey → nKeyboard (USB) ou nKey → nBLEKeyboard (BLE).
Ensuite, place aux entrées rotatives qui agissent aussi comme des boutons (Joycoders, encodeurs à poussoir, commutateurs à rotation libre) et aux modèles qui les enveloppent : Encodeurs et entrées rotatives.