Protocole NodeBlue Interface (NBI)
Le NodeBlue Interface (NBI) est le protocole de commande que l'IDE NodeBlue utilise pour dialoguer avec une carte en cours d'exécution — lire les valeurs de sortie en direct, définir des valeurs de paramètres, les enregistrer en EEPROM, interroger l'identité du firmware, lister les plages d'axes. C'est aussi le canal par lequel le tableau de bord de l'IDE pilote ses widgets, et le canal utilisé pour communiquer entre deux cartes NodeBlue sur n'importe quel transport.
Ce tutoriel présente ce qu'est le NBI, comment câbler l'endpoint côté carte (nNodeBlueInterface), comment définir vos propres codes de message via nNodeBlueInterfaceIn, et les transports typiques sur lesquels il fonctionne (USB, USB-Serial, BLE, NRF24, Nextion).
Ce que le protocole transporte
Chaque paquet NBI est l'une d'un petit ensemble fixe de commandes. L'IDE les utilise constamment pendant une session ; l'utilisateur y pense rarement, mais savoir qu'elles existent permet de comprendre le tableau de bord, la page de test des contrôleurs de jeu et les exemples d'hôte radio.
| Commande | Direction | Ce qu'elle fait |
|---|---|---|
| SET_INPUT | hôte → carte | Définit le port d'entrée d'un module à une valeur — comme si un fil sur le canevas avait transporté cette valeur. |
| SET_OUTPUT | hôte → carte | Envoie une valeur en sortie d'un port de sortie d'un module — utilisé pour injecter des lectures simulées. |
| GET_OUTPUT | hôte → carte | Demande la valeur actuelle sur le port de sortie d'un module. La carte répond avec les octets bruts. |
| SET_PARAM | hôte → carte | Change un paramètre d'un module en RAM (non persistant après un reset). |
| SAVE_PARAM | hôte → carte | Change le paramètre et le persiste en EEPROM. |
| GET_PARAM | hôte → carte | Lit la valeur actuelle d'un paramètre. |
| INIT | hôte → carte | Ré-exécute la logique de démarrage du projet sans redémarrer. |
| CLEAR_STORAGE | hôte → carte | Efface le stockage de paramètres en EEPROM. |
| GET_AXIS_INFOS | hôte → carte | Liste les min/max/plage apprise en cours pour chaque axe (utilisé par l'interface de calibration de l'IDE). |
| GET_FREEMEM | hôte → carte | RAM libre, en octets. |
| GET_FW_INFO | hôte → carte | Identité du firmware — VID/PID, nom, version NodeBlue, nom du projet. |
| GET_EEPROM_SIZE / READ_EEPROM / WRITE_EEPROM | hôte → carte | Lecture/écriture EEPROM brute pour les outils de sauvegarde-restauration. |
| (personnalisé) | hôte → carte | Tout ce que vous avez déclaré avec nNodeBlueInterfaceIn. |
Chaque paquet est préfixé par l'octet d'en-tête 0x03, puis le code de commande, puis l'adresse du module cible ou le CRC-de-nom, l'index du paramètre/port, et les octets de valeur. Les réponses aux commandes GET renvoient uniquement les octets bruts de la valeur, sans écho de la commande ni de l'adresse — un hôte qui envoie plusieurs GET en vol doit donc les sérialiser et s'appuyer sur une corrélation FIFO.
L'endpoint côté carte — nNodeBlueInterface
nNodeBlueInterface est le module qui effectue l'analyse du protocole côté carte. Il accepte un flux d'octets entrant sur son entrée Rx, en décode les paquets NBI, les dispatche vers le bon module (SET_INPUT sur le module X, GET_OUTPUT sur le module Y, etc.) et émet toute réponse sur sa sortie Tx.
| Paramètre | Description |
|---|---|
| Sync | Généralement MainLoop — les paquets sont traités à chaque itération de la boucle. InputSync est aussi valide et procure un temps de réponse plus rapide au prix de plus de travail par tick. |
| ref | Un nom choisi par l'utilisateur (par défaut « Interface »). D'autres modules (nNodeBlueInterfaceIn, nNodeBlueNextion) référencent un endpoint NBI par son nom, si bien que plusieurs endpoints peuvent coexister sur la même carte — par exemple un sur USB-Serial pour l'IDE, un autre sur NRF24 pour la communication inter-cartes. |
Les deux ports sont de type cBuffer (petits tampons de taille fixe — chaque paquet NBI tient bien en dessous de 256 octets). Vous câblez le Rx sur le transport que vous utilisez et le Tx sur l'entrée d'envoi de ce même transport.
Quand l'IDE injecte automatiquement un NBI Raw-HID
L'IDE possède une règle d'auto-injection afin qu'un projet « vide » fraîchement démarré dialogue quand même avec l'hôte. Lorsque le canevas ne contient aucun module USB (pas de nHID, nHIDPro, nUSBSerial*, nUSBToSerial*) et que la cible n'est pas une Teensy, l'IDE ajoute silencieusement un nHID (RawHID, 0 bouton, rapport de config de 31 octets) plus un nNodeBlueInterface câblé à travers lui, avant la compilation. Cela donne au Board Server un canal USB-HID pour parler NBI, pour tout projet qui ne déclare pas explicitement son propre transport USB.
| Situation | Ce qui se passe |
|---|---|
| Projet vide, carte non-Teensy | RawHID + NBI auto-injectés. L'hôte parle NBI sur USB-HID sans aucun travail de votre part. |
| Carte Teensy | La pile USB de la Teensy expose toujours une interface RawHID quel que soit votre choix de type USB, donc l'IDE l'utilise directement — aucune injection nécessaire. |
Vous avez déclaré un nHID / nHIDPro / nUSBSerial* | Pas d'auto-injection. Si vous voulez que l'IDE dialogue avec la carte en cours d'exécution, vous devez ajouter vous-même un nNodeBlueInterface et le câbler à travers l'endpoint Config de votre HID (la paire d'entrée/sortie Config apparaît dès que le paramètre Config Report du module est non nul) ou à travers le Rx/Tx de l'un des modules nUSBSerial*. Oubliez cela et l'hôte n'a aucun moyen de lire les paramètres, de piloter le tableau de bord ou de lire les infos d'axes — la carte fonctionne toujours, mais le côté IDE devient muet. |
Projet BLE uniquement (nBLEGamePad, nBLEKeyboard, nBLEuart, etc.) sans module USB | L'auto-injection a quand même lieu (le BLE ne compte pas comme un module USB) — l'hôte peut donc parler NBI sur USB-HID pendant que le gamepad vu par l'utilisateur est en BLE. |
| Vous voulez du NBI sur BLE | Ajoutez explicitement nBLEuart et nNodeBlueInterface, câblés ensemble — il n'y a pas de chemin BLE-NBI automatique. |
Vous déposez un nNodeBlueInterface sur le canevas dans l'une de trois situations : (a) vous avez un module USB et devez rétablir le chemin de dialogue avec l'hôte, (b) vous voulez du NBI sur un transport qui n'est pas géré automatiquement (UART matériel, canal NRF24, ligne série Nextion), ou (c) vous voulez définir des codes de message personnalisés avec nNodeBlueInterfaceIn (section suivante).
Se connecter à un transport série / radio
Deux motifs typiques :
NBI sur UART matériel (carte à carte via une paire de fils) :
nSerial(sortie Rx) →nNodeBlueInterface(entrée Rx)nNodeBlueInterface(sortie Tx) →nSerial(entrée Tx)
NBI sur radio NRF24 (carte à carte sans fil) :
nNRF24(sortie Rx du canal) →nNodeBlueInterface(Rx)nNodeBlueInterface(Tx) →nNRF24(entrée Tx du canal)
Le côté radio ajoute en dessous la couche de fiabilité de la radio NodeBlue — le NBI ne réinvente pas la retransmission, il s'appuie sur les garanties de transport que la liaison fournit.
Voir Examples/04-Communication/NodeBlueInterfaceSerial.
Codes de message personnalisés — nNodeBlueInterfaceIn
Les commandes NBI standard couvrent la lecture/écriture des modules du projet. Pour les messages au niveau applicatif — « l'hôte veut m'envoyer une couleur RGB de 3 octets », « l'hôte veut pousser une ligne LCD de 12 caractères » — vous utilisez nNodeBlueInterfaceIn pour déclarer un nouveau code et récupérer le corps sous forme de tampon sur le canevas.
| Paramètre | Description |
|---|---|
| Interface | Le nom ref de l'endpoint nNodeBlueInterface auquel s'attacher. Menu déroulant peuplé à partir des modules nNodeBlueInterface du canevas. |
| Code | Un unique caractère (ou un littéral d'octet 0xNN) qui identifie votre message personnalisé. Utilisez toute valeur qui n'entre pas en collision avec les codes de commande NBI intégrés — les codes intégrés commencent à 0xEE et décroissent, et les lettres ASCII majuscules 'A'/'F'/'H'/'N' sont réservées pour ACK / Features / Hello / Device Name. Les lettres minuscules et les chiffres sont toujours sûrs. |
| Longueur | Longueur du corps en octets (fixée à la compilation). |
La sortie est un Buffer de taille Len — le corps de chaque paquet entrant avec ce code, déposé sur le canevas dès que le paquet arrive.
Exemple : l'hôte pousse une couleur RGB par trame
nNodeBlueInterfaceIn avec Code = 'C' et Len = 3 donne une sortie tampon de 3 octets. Reliez-la à un nBufferSplit pour obtenir R / G / B en valeurs individuelles, puis à nNeoPixel. Côté hôte, envoyez 0x03 'C' R G B et la LED se met à jour en un tick de MainLoop après l'arrivée du paquet.
Exemple : l'hôte envoie une ligne Nextion par tunneling NBI
Voir Examples/04-Communication/NodeBlueInterfaceSerial — l'hôte envoie une chaîne avec un code personnalisé et la carte la pousse vers un afficheur Nextion.
NBI sur Nextion — nNodeBlueNextion
Les afficheurs Nextion parlent un protocole UART qui leur est propre (commandes texte comme t0.txt="Hello"). Pour permettre à un nNodeBlueInterface de partager le même UART qu'un afficheur Nextion — courant lorsqu'une carte possède un Nextion plus une liaison de contrôle NBI-sur-USB-Serial depuis le tableau de bord — déposez un module nNodeBlueNextion sur le canevas aux côtés de nNextionInterface.
nNodeBlueNextion est un module « annotation » sans port — sa seule présence indique au firmware de multiplexer les paquets NBI et les commandes Nextion sur la même ligne série. Le Nextion ignore tout flux d'octets qui commence par l'en-tête NBI 0x03 ; réciproquement, l'analyseur NBI ignore le trafic ASCII Nextion, de sorte que les deux coexistent sans confusion.
C'est ce qui fait fonctionner les widgets du tableau de bord de l'IDE même lorsque le seul UART disponible de la carte est déjà câblé à un Nextion.
NBI face au protocole de canal radio
NodeBlue possède deux protocoles inter-périphériques distincts que l'on confond souvent :
| Concept | À utiliser pour | Module(s) |
|---|---|---|
| Canaux radio NodeBlue | Flux de données carte à carte à haut débit — capteurs, valeurs d'axes, bitmaps de boutons. Huit canaux à fiabilité gérée par liaison, charge utile fixe de 31 octets. | nNRF24, nNRF52. |
| NodeBlue Interface (NBI) | Commandes — l'hôte pilote la carte, lit les paramètres, lit les infos d'axes, messages applicatifs personnalisés. | nNodeBlueInterface par-dessus n'importe quel transport. |
Un projet multi-cartes typique utilise les deux à la fois :
Carte base-volant ↔ carte button-box : données partagées sur les canaux radio
nNRF24(position du volant, bits de boutons, télémétrie FFB).Hôte (tableau de bord PC) ↔ carte base-volant : NBI sur USB-HID ou USB-Serial (calibrer les axes, enregistrer les paramètres, interroger l'ID du firmware).
Les deux protocoles s'ignorent mutuellement ; vous choisissez celui qui convient au type de message que vous envoyez.
Déprécié : nSimpleHostInterface
Les projets plus anciens (avant 2022 environ) utilisaient nSimpleHostInterface pour la même tâche. Il est toujours dans l'IDE pour l'import de projets hérités, mais dès le premier import le module est silencieusement remplacé par un nNodeBlueInterface — le hook checkImport effectue la substitution et préserve les fils. N'ajoutez pas de nouveaux modules nSimpleHostInterface ; choisissez nNodeBlueInterface à sa place.
Exemples
- 04-Communication/NodeBlueInterfaceSerial — NBI nu sur un port série, avec
nNodeBlueInterfaceIntransportant un code personnalisé.
Beaucoup des exemples multi-cartes sous Boards/ utilisent le NBI implicitement via des chaînes radio + USB — ouvrez-en un pour voir le câblage réel de l'endpoint sur chaque carte.
Suite : maintenant que vous avez vu comment les cartes échangent des événements, apprenez à piloter un mouvement physique avec les modules moteur — Moteurs et drivers.