Faire obéir une manette de jeu chinoise à un ESP32

Le banc d'essai : la carte ESP32-S31 Function-CoreBoard-1, l'écran ST7789 de 1,9 pouce et la manette BSP-G6. L'écran affiche EN LIGNE alors qu'aucun paquet de données n'est arrivé depuis 277 secondes : la liaison vit quand même.
Fig. 1 — Le banc d’essai : la carte ESP32-S31 Function-CoreBoard-1, l’écran ST7789 de 1,9 pouce et la manette BSP-G6. L’écran affiche EN LIGNE alors qu’aucun paquet de données n’est arrivé depuis 277 secondes : la liaison vit quand même.

Sur sa boîte, la manette promet du Bluetooth 5.3, le mode « HID standard » d’Android et celui des manettes Xbox. Branchée sur un microcontrôleur ESP32, elle s’est d’abord présentée comme un écran tactile à quatre doigts. Dans un autre mode, elle s’est annoncée comme une vraie manette de jeu, avec six axes et seize boutons, puis n’a rien envoyé par le canal qu’elle venait de décrire. Ses boutons passaient ailleurs, par un canal du fabricant que rien ne présentait comme une manette. Et une fois ce canal trouvé, il restait le plus délicat : faire en sorte que, dans une salle de compétition pleine de manettes identiques, la carte n’écoute que la sienne, et sache en une fraction de seconde qu’elle l’a perdue.

Cette manette doit piloter un robot à roues mecanum (des roues garnies de galets inclinés, qui laissent le robot se déplacer en crabe). Le robot est fait pour la compétition. Sa carte électronique n’existant pas encore, tout se met au point sur une carte de développement qui porte le même microcontrôleur. Voici ce qu’on attend de la liaison, et qui a guidé chaque étape :

  • lire tous les boutons, les deux sticks et les deux gâchettes analogiques, sans fil ;
  • ne se connecter qu’à notre manette, jamais à celle du voisin ;
  • savoir en moins d’une demi-seconde que la liaison est perdue, pour couper les moteurs ;
  • se reconnecter seule après un redémarrage de la carte ou une extinction de la manette, sans aucun geste en plus ;
  • que tout cela puisse être refait par quelqu’un d’autre, avec le programme fourni en fin d’article.

Le chemin a pris quatre essais. Chacun est né d’une limite du précédent.


Le matériel sur la table

La carte est une ESP32-S31 Function-CoreBoard-1 d’Espressif. Une carte de développement est une petite carte vendue par le fabricant d’un microcontrôleur : elle porte la puce, son alimentation, ses prises USB et un connecteur où sortent ses broches, pour écrire et essayer un programme avant que la carte définitive n’existe. Celle-ci porte un module ESP32-S31-WROOM-3 : deux cœurs RISC-V à 320 MHz, 16 Mo de mémoire flash, 16 Mo de mémoire vive externe, Wi-Fi 6, Bluetooth 5.4 et même une prise Ethernet. Ses broches sortent sur un connecteur de 40 broches, nommé J2 sur la carte.

La carte de développement ESP32-S31 Function-CoreBoard-1 d'Espressif dans sa boîte : deux cœurs RISC-V à 320 MHz, Wi-Fi 6, Bluetooth 5.4 et Ethernet.
Fig. 2 — La carte de développement ESP32-S31 Function-CoreBoard-1 d’Espressif dans sa boîte : deux cœurs RISC-V à 320 MHz, Wi-Fi 6, Bluetooth 5.4 et Ethernet.

Elle a deux prises USB-C. Celle marquée USB-DBG est l’USB natif de la puce : elle sert à téléverser le programme et à lire la console, sans aucun bouton à presser. C’est elle qu’on branche. La carte porte aussi deux boutons : RST, qui redémarre la puce, et BOOT, relié à la broche IO61, qui nous servira plus loin.

L’ESP32-S31 est une puce récente. ESP-IDF, le kit de développement officiel d’Espressif (les bibliothèques, le compilateur et les outils), la range encore, dans sa version 6.1, parmi les puces « en avant-première » : chaque commande doit le reconnaître par l’option --preview, sans quoi il refuse de compiler pour elle.

Pour voir ce que pense la carte sans garder un ordinateur branché, nous lui ajoutons un écran ST7789 de 1,9 pouce, 170 × 320 pixels, piloté par un bus SPI (une liaison série à horloge, où la carte envoie ses ordres et ses pixels sur deux fils). Le robot aura le même.

Reste la manette. C’est une BSP-G6, vendue pour jouer sur un téléphone. Son mode d’emploi a été perdu ; tout ce qui suit a donc été appris en l’interrogeant.

La boîte de la manette BSP-G6 : une manette sans fil au format Xbox, vendue pour les téléphones.
Fig. 3 — La boîte de la manette BSP-G6 : une manette sans fil au format Xbox, vendue pour les téléphones.
Le dos de la boîte : Bluetooth 5.3, mode HID standard d'Android, jeux X-input. Rien n'y décrit le canal par lequel les boutons passent réellement.
Fig. 4 — Le dos de la boîte : Bluetooth 5.3, mode HID standard d’Android, jeux X-input. Rien n’y décrit le canal par lequel les boutons passent réellement.

Au dos de la manette, sous l’étiquette, un interrupteur à cinq positions choisit son mode : V3, M, X, S et 2.4G. De part et d’autre, deux palettes marquées M1 et M2 tombent sous les doigts. Nous saurons à la fin du troisième essai à quoi elles servent.

Le dos de la manette : l'interrupteur à cinq positions, de V3 à 2.4G, et les deux palettes M1 et M2.
Fig. 5 — Le dos de la manette : l’interrupteur à cinq positions, de V3 à 2.4G, et les deux palettes M1 et M2.

Le programme est écrit en C++ avec ESP-IDF 6.1. Le Bluetooth y est géré par Bluedroid, la pile Bluetooth qu’ESP-IDF fournit (la pile est l’ensemble des couches de logiciel entre la radio et le programme).


Essai 01 : un écran pour voir ce que pense la carte

Avant d’écouter la manette, il fallait de quoi afficher ce qu’on entend. Huit fils femelle-femelle relient l’écran au connecteur J2, carte débranchée de l’USB pendant qu’on câble :

ÉcranBroche de J2 (sérigraphie)Broche de la puceRôle
GND34 (G)—masse
VCC36 (3V3)—alimentation 3,3 V
SCL20 (42)IO42horloge du bus SPI
SDA17 (43)IO43données du bus SPI
RES14 (48)IO48remise à zéro de l’écran
DC16 (46)IO46commande ou donnée
CS11 (49)IO49sélection de l’écran
BLK23 (37)IO37rétroéclairage

Deux pièges dans ce tableau. VCC va sur le 3,3 V, pas sur le 5 V : les signaux de l’ESP32 sont en 3,3 V, et un écran alimenté au même niveau ne reçoit jamais sur une entrée plus que sa propre alimentation. Et SCL et SDA ne sont pas un bus I²C, malgré les noms que leur donnent les vendeurs de modules : ce sont l’horloge et les données du bus SPI. Repérez-vous à la sérigraphie imprimée à côté de chaque broche de J2 plutôt qu’en comptant : c’est elle qui fait foi sur la carte que vous avez en main.

Dans le programme, ce câblage tient en quelques constantes :

constexpr gpio_num_t BROCHE_SCLK = GPIO_NUM_42;  // horloge SPI   J2 broche 20
constexpr gpio_num_t BROCHE_MOSI = GPIO_NUM_43;  // données SPI   J2 broche 17
constexpr ecran::Broches BROCHES_ECRAN = {
    .cs = GPIO_NUM_49,   // sélection       J2 broche 11
    .dc = GPIO_NUM_46,   // cmd. / donnée   J2 broche 16
    .rst = GPIO_NUM_48,  // remise à zéro   J2 broche 14
    .blk = GPIO_NUM_37,  // rétroéclairage  J2 broche 23
};
constexpr spi_host_device_t BUS_SPI = SPI3_HOST;
constexpr unsigned FREQUENCE_SPI_HZ = 20 * 1000 * 1000;

La puce ST7789 sait piloter des dalles de plusieurs tailles, et chacune a ses réglages. Pour les trouver, le premier programme dessinait une mire : un cadre blanc d’un pixel sur les quatre bords, un carré jaune dans un coin, quatre bandes rouge, verte, bleue et blanche. Chaque défaut possible y laisse une trace différente : un cadre coupé à gauche dit un décalage horizontal, des couleurs en négatif disent qu’il faut inverser, un rouge et un bleu échangés disent l’ordre des couleurs. La mire est sortie juste du premier coup, avec ces réglages :

// La dalle de 1,9 pouce, 170 × 320 : la puce a 240 colonnes de mémoire, la dalle
// n'en montre que les 170 du milieu, d'où le décalage de (240 − 170) / 2 = 35.
constexpr Dalle DALLE_1_9_POUCE = {170, 320, 35, 0, true, LCD_RGB_ELEMENT_ORDER_RGB};

Le true demande l’inversion des couleurs : les dalles IPS, comme celle-ci, affichent en négatif sans elle.

Un défaut est pourtant apparu plus tard, et il vaut d’être raconté. La mire, juste, est devenue d’un coup son négatif exact après qu’on eut bougé la carte : fond blanc, rouge devenu cyan, vert devenu magenta. Rien n’était abîmé. Au démarrage, le programme envoie à l’écran une suite d’ordres, dont l’ordre CASET (code 0x2A, en binaire 00101010), qui choisit les colonnes où écrire. L’explication la plus probable : un fil a fait un faux contact au mauvais moment, et deux de ces bits ont été lus à zéro. Il reste 00100000, soit 0x20, qui est l’ordre INVOFF, « cesse d’inverser les couleurs ». Un faux contact ne brouille pas forcément un ordre : il peut en fabriquer un autre, parfaitement valide. Le remède : enfoncer les fils, puis presser RST. Le programme renvoie toute la configuration à chaque démarrage.

L’écran affiche à 20 MHz sur des fils volants d’une dizaine de centimètres, sans erreur de transfert. Nous pouvons passer à la manette.

Le programme complet de cet essai, avec sa mire et ses quatre réglages, se télécharge en fin d’article, dans les programmes complets.


Essai 02 : la manette se prend pour un écran tactile

ESP-IDF fournit un exemple tout prêt pour lire un appareil Bluetooth de saisie : esp_hid_host, dans le dossier examples/bluetooth. Il cherche pendant quelques secondes les appareils HID autour de lui (Human Interface Device, la famille normalisée des claviers, souris et manettes), se connecte, puis écrit dans la console chaque rapport reçu, c’est-à-dire le paquet de quelques octets que l’appareil envoie quand un bouton change.

L’exemple n’a pas trouvé la manette tel quel. Il a fallu trois corrections :

  1. La manette était vue, puis écartée. L’exemple ne retient un appareil que si le service HID figure dans la liste complète des services que l’appareil annonce. La BSP-G6 le range dans la liste incomplète, que l’exemple ne lisait pas.
  2. La connexion n’était jamais tentée. Quand le Bluetooth Classique est actif, l’exemple ne se connecte qu’à un appareil nommé « HID Mouse Example », sa propre souris de démonstration. Il se connecte désormais au dernier appareil HID trouvé.
  3. La recherche s’arrêtait parfois sans rien dire. Ses deux attentes sont maintenant bornées dans le temps, et écrivent leur fin dans la console.

Interrupteur sur V3, HOME tenu trois secondes (le voyant rouge clignote vite : c’est le mode d’appairage), la manette s’est connectée. La console a donné son identité : nom « BSP-G6 », fabricant « ShanWan BM-835 », identifiants de fabricant et de produit 1949:0402.

Puis les rapports sont arrivés, et ils étaient étranges. Un seul rapport de 17 octets : quatre groupes de quatre octets, puis un dernier qui compte les doigts. La manette se décrivait comme un écran tactile à quatre doigts. Dans chaque groupe, le premier octet porte le numéro du doigt et son état, les trois suivants sa position. Le groupe 13 3d 44 ad, par exemple, se lit ainsi :

  • 13 : doigt n° 1 (le chiffre hexadécimal de gauche), posé (le 3 de droite ; un 2 dirait levé) ;
  • 3d 44 ad : deux nombres de 12 bits imbriqués, X = 0x43D = 1085 et Y = 0xAD4 = 2772.

C’est le « mode mapping » des manettes de téléphone, fait pour les jeux qui ne connaissent que l’écran tactile : un stick fait glisser un doigt virtuel, un bouton en pose un à un endroit fixe de l’écran. Ces endroits se règlent dans l’application du fabricant. Pour un robot, c’est inutilisable : la position d’un « bouton » dépendrait d’un réglage fait sur un téléphone.

Le programme de cet essai, l’exemple d’ESP-IDF avec ses trois corrections, se télécharge en fin d’article, dans les programmes complets.


Cinq positions, trois identités

L’interrupteur à cinq positions change donc la nature même de la manette. Trois positions ont été interrogées, avec la carte, un téléphone et un PC sous Windows :

PositionRadioSe présente commeAdresse radio
V3Bluetooth basse consommation (BLE)un écran tactile à quatre doigts, « BSP-G6 »01:26:05:15:BE:A2
XBluetooth Classiqueune manette Xbox One S, « Xbox Wireless Controller »83:26:05:15:BE:A2
2.4GBluetooth basse consommation (BLE)une manette de jeu, « BM769 24G » : six axes, seize boutons, une croix04:26:05:15:BE:A2

Les trois adresses ne diffèrent que par leur premier octet : une seule radio, trois identités. En X, la manette imite une manette Xbox en Bluetooth Classique, un format connu ; mais sous Windows elle ne fonctionnait qu’avec son câble branché. La position 2.4G réservait une surprise : on attendrait une liaison propriétaire à 2,4 GHz, avec une clé USB fournie ; c’est en fait du BLE (le Bluetooth basse consommation, qui émet lui aussi à 2,4 GHz). Et sa description est celle d’une vraie manette de jeu. Windows l’a inscrite comme « Contrôleur de jeu HID »… et rien n’a bougé dans son panneau de test, quels que soient les boutons pressés.

C’était pourtant la position la plus prometteuse. Il fallait voir ce qu’elle envoyait vraiment, sans rien supposer de son format.


Essai 03 : tout afficher, bit par bit

Le troisième programme ne décode rien. Il affiche chaque octet reçu sur une ligne de l’écran, avec ses huit bits en huit cases : un bit à 1 en bleu clair, un bit à 0 en bleu-gris foncé. Un bit qui vient de changer garde une demi-seconde une autre couleur : jaune pâle s’il passe à 1, kaki s’il retombe à 0. Un bouton se repère donc à la case qui s’allume en jaune pâle quand on le presse ; un stick fait clignoter plusieurs cases d’un ou deux octets à la fois. Sur la vidéo, le jaune pâle se voit vers la quatrième seconde ; le kaki ne dure qu’un instant, vers la neuvième.

Vidéo 1 — La grille de l’essai 03 : un octet par ligne, huit bits en huit cases, bleu clair pour 1 et bleu-gris foncé pour 0. Les cases jaune pâle viennent de passer à 1 sous les doigts. Le bandeau affiche pourtant RECHERCHE alors que les paquets arrivent : c’est un défaut, qui sera corrigé à l’essai 04.

Avant d’en arriver là, trois lignes de la console ont arrêté la manette, chacune à son tour.

La connexion tombait aussitôt, avec le code 0x3d : « échec de contrôle du chiffrement ». La carte avait lancé le chiffrement de la liaison avec une clé gardée d’un appairage précédent, que la manette ne reconnaissait plus ; l’essai 04 dira pourquoi. Le programme efface désormais toutes les clés à son démarrage.

Les tentatives suivantes étaient refusées par la radio, avec Cmd Disallowed. Dès qu’une fonction du BLE 5.0 est employée, la pile passe aux connexions « étendues » du BLE 5.0, que la radio refuse après une recherche faite à la manière du BLE 4.2. Une manette n’a pas besoin du BLE 5.0 : il est coupé dans les réglages du projet.

Puis la console s’est mise à défiler, deux cents fois par seconde : drop notif, handle 0x002e not registered. La pile recevait des paquets de la manette, et les jetait, parce que personne ne s’était abonné à leur source.

Pour comprendre ce message, il faut savoir comment un appareil BLE range ses données. Il les présente dans un catalogue, le GATT (le catalogue des données d’un appareil BLE), fait de services (des familles de données), eux-mêmes faits de caractéristiques (une donnée qu’on peut lire, écrire, ou recevoir d’office). Chaque élément du catalogue a un numéro d’adresse, son handle. Une caractéristique peut envoyer sa valeur d’elle-même, chaque fois qu’elle change : c’est une notification, et il faut s’y abonner pour la recevoir. Voici le catalogue de la manette en position 2.4G, tel que la carte l’a lu :

HandlesServiceCe qu’il contient
0x01 à 0x070x1800, accès génériquele nom « BSP-G6-HID », l’apparence
0x08 à 0x0B0x1801, attributs génériques—
0x0C à 0x120x180A, informationsfabricant « ShanWan BM-835 »
0x13 à 0x230x1812, HIDla description d’une manette de 10 octets. Aucun paquet n’y passe
0x24 à 0x290xFFFF, du fabricantmuet
0x2A à 0x2F91680001-…, du fabricantla caractéristique 91680003, handle 0x2E : tout passe par elle
0x30 à 0x3595990001-…, du fabricantmuet

Voilà le fin mot de l’histoire de Windows. Le service HID, le seul qu’écoutent Windows et le lecteur HID d’ESP-IDF, décrit bien une manette, mais ne transmet rien. Les boutons passent par un service du fabricant, identifié par un UUID (un identifiant de 128 bits) que rien ne rattache à une manette : 91680001-1111-6666-8888-0123456789AB. Il suffisait de s’abonner au bon handle (le numéro d’adresse d’une donnée dans la manette) pour que la grille s’anime.

S’abonner : ce que la carte n’avait pas fait

« Personne ne s’était abonné à leur source » : la phrase est courte, et elle cache le mécanisme le plus utile de tout le BLE. Il mérite qu’on s’y arrête.

Deux façons d’obtenir une donnée. Un central (l’appareil qui choisit à qui il se connecte, ici la carte) peut obtenir la valeur d’une caractéristique de deux façons. Il peut la lire : il envoie une demande par radio, le périphérique répond. C’est un coup de téléphone pour demander le score d’un match. Ou bien il peut s’abonner : le périphérique lui envoie la valeur de lui-même, chaque fois qu’elle change, par une notification. C’est le message qu’on reçoit à chaque but, sans avoir rien demandé. Pour une manette, la différence est grande. Lire ses boutons cent fois par seconde ferait cent demandes et cent réponses, et un appui arriverait en moyenne une demi-période en retard. Avec un abonnement, la manette ne parle que lorsqu’un bouton change, et le paquet part au rendez-vous radio suivant.

Un abonnement demande deux registres. Le mot « abonnement » est bien choisi : comme pour un journal, il faut que l’éditeur sache qu’il doit l’envoyer, et que chez vous quelqu’un relève le courrier. Une notification BLE passe ainsi par deux registres, un dans chaque appareil.

Les deux registres d'un abonnement BLE. ① Dans la carte, la pile Bluetooth tient la liste des handles à livrer et à qui. ② Dans la manette, le descripteur 0x2902 de la caractéristique dit si elle doit envoyer. ③ La notification part de la manette ; sans ligne pour son handle, la pile de la carte la jette.
Fig. 6 — Les deux registres d’un abonnement BLE. ① Dans la carte, la pile Bluetooth tient la liste des handles à livrer et à qui. ② Dans la manette, le descripteur 0x2902 de la caractéristique dit si elle doit envoyer. ③ La notification part de la manette ; sans ligne pour son handle, la pile de la carte la jette.

Le registre de la carte (① sur la figure). Une liaison radio peut être partagée par plusieurs programmes de la carte : à l’essai 03, le lecteur HID d’ESP-IDF et le nôtre écoutaient la même manette. Toutes les notifications de la liaison arrivent donc d’abord à la pile Bluetooth de la carte, qui doit décider à quel programme livrer chacune. Elle tient pour cela un registre : tel handle, tel programme. Un programme s’y inscrit par la fonction esp_ble_gattc_register_for_notify, en donnant le handle qu’il attend. Une notification dont le handle n’est dans aucune ligne n’est attendue par personne : la pile la jette, et l’écrit dans la console. C’est exactement le message de l’essai 03. Le lecteur HID s’était inscrit pour les handles de son service, 0x1B et 0x17 ; personne ne l’avait fait pour 0x2E, et deux cents paquets par seconde partaient à la corbeille.

Le registre de la manette (② sur la figure). Chaque caractéristique qui sait notifier porte une petite donnée de deux octets, son descripteur d’abonnement (en anglais Client Characteristic Configuration Descriptor, d’UUID 0x2902). Le central y écrit ce qu’il veut recevoir :

Valeur écriteCe que fait le périphérique
00 00il se tait : c’est la valeur au départ
01 00il notifie : il envoie la valeur à chaque changement, sans attendre de réponse
02 00il indique : il envoie la valeur, puis attend que le central accuse réception avant d’envoyer la suivante

Les deux octets se lisent à l’envers, poids faible d’abord : 01 00 est le nombre 1. Une indication est plus sûre, puisque chaque envoi est confirmé, mais elle coûte un aller-retour radio par valeur. Pour une manette, la notification convient mieux : si un paquet se perd, le suivant arrive au rendez-vous radio d’après, et il porte l’état complet de la manette, pas seulement ce qui a changé.

Les deux registres ne servent pas à la même chose. Le registre de la manette décide si elle envoie. Le registre de la carte décide si ce qui arrive est livré au bon programme. Sans le second, la carte jette ce qu’elle reçoit. Sans le premier, une manette qui suit la norme se tait. La BSP-G6, elle, envoyait déjà sur son canal sans que personne ait écrit dans son descripteur : à l’essai 03, il ne manquait que le registre de la carte.

Deux exemples ailleurs que chez notre manette.

  • Une ceinture cardiaque de sport annonce un service normalisé, 0x180D, dont la caractéristique 0x2A37 porte la fréquence cardiaque. Elle ne l’envoie qu’une fois que le téléphone a écrit 01 00 dans son descripteur d’abonnement. Une application qui l’oublie voit une ceinture connectée et muette : c’est l’image inverse de notre problème.
  • Le niveau de batterie d’un appareil (service 0x180F, caractéristique 0x2A19) se prête aux deux façons. Un téléphone peut le lire quand il affiche l’écran des appareils, ou s’y abonner pour être prévenu à chaque baisse.

Dans le programme, l’abonnement se fait dans cet ordre. Une fois le catalogue lu, la carte cherche le canal de la manette par son UUID, retient son handle, et s’inscrit dans le registre de sa pile (①) :

esp_gattc_char_elem_t canal = {};
uint16_t nombre = 1;
esp_bt_uuid_t uuid = {};
uuid.len = ESP_UUID_LEN_128;
std::memcpy(uuid.uuid.uuid128, UUID_DU_CANAL, 16);
if (esp_ble_gattc_get_char_by_uuid(interface_, session_, debut_du_service_, fin_du_service_, uuid, &canal,
                                   &nombre) != ESP_GATT_OK ||
    nombre == 0) {
    refuser(-6, "canal du fabricant introuvable dans son service");
    break;
}
handle_du_canal = canal.char_handle;
esp_ble_gattc_register_for_notify(interface_, adresse_liee_, canal.char_handle);

La pile confirme l’inscription par un événement (ESP_GATTC_REG_FOR_NOTIFY_EVT). La carte écrit alors 01 00 dans le descripteur d’abonnement de la manette (②), après l’avoir cherché parmi les descripteurs de la caractéristique :

void Liaison::ecrire_l_abonnement(uint16_t handle_de_caracteristique)
{
    esp_gattc_descr_elem_t descripteur = {};
    uint16_t nombre = 1;
    esp_bt_uuid_t uuid = {};
    uuid.len = ESP_UUID_LEN_16;
    uuid.uuid.uuid16 = UUID_DU_DESCRIPTEUR_D_ABONNEMENT;
    if (esp_ble_gattc_get_descr_by_char_handle(interface_, session_, handle_de_caracteristique, uuid, &descripteur,
                                               &nombre) == ESP_GATT_OK &&
        nombre > 0) {
        uint8_t valeur[2] = {0x01, 0x00};
        esp_ble_gattc_write_char_descr(interface_, session_, descripteur.handle, sizeof valeur, valeur,
                                       ESP_GATT_WRITE_TYPE_RSP, ESP_GATT_AUTH_REQ_NONE);
    }
}

ESP_GATT_WRITE_TYPE_RSP demande une écriture avec réponse : la manette confirme qu’elle a bien noté l’abonnement. À partir de là, chaque notification du handle 0x2E arrive dans la fonction recevoir_un_paquet du programme, que l’essai 04 détaille plus loin.

Un abonnement ne survit pas à la liaison. À chaque coupure, la pile de la carte vide les lignes de son registre qui concernaient cette liaison. Et la norme demande au périphérique de remettre son descripteur à 00 00 à chaque nouvelle connexion, sauf pour un central avec lequel il a été appairé, dont il garde les réglages. Notre carte, nous le verrons, se passe d’appairage : les deux registres sont donc vides à chaque reconnexion. C’est pourquoi le programme refait les deux inscriptions à chaque connexion, et non une seule fois au démarrage. Un programme qui ne s’abonne qu’au démarrage marche jusqu’à la première coupure, puis reste connecté et muet.

On ne s’abonne qu’à ce qu’on lit. S’abonner à toutes les caractéristiques d’un appareil « pour voir » est tentant pendant une enquête, mais chaque abonnement fait parler la radio. Le programme final ne s’inscrit que pour le handle 0x2E. Les notifications des autres handles sont jetées par la pile avant de l’atteindre ; un paquet d’un autre handle qui lui parviendrait quand même serait compté à l’écran comme « étranger », et ignoré.

Pour faire le même relevé sur une autre manette, il faut donc s’inscrire pour chaque caractéristique qui sait notifier. Quelques lignes suffisent ensuite, dans la fonction qui reçoit les événements du client GATT d’ESP-IDF, pour écrire dans la console chaque notification, avec son handle et ses octets :

case ESP_GATTC_NOTIFY_EVT:
    ESP_LOGI(TAG, "handle 0x%04X, %d octets", p->notify.handle, p->notify.value_len);
    ESP_LOG_BUFFER_HEX(TAG, p->notify.value, p->notify.value_len);
    break;

Le relevé, bouton par bouton

Chaque paquet du canal 0x2E fait 20 octets et commence toujours par 20 0F. Pour attribuer chaque case à son bouton, un premier passage a suivi un ordre convenu. Le second a été plus malin : chaque bouton a été pressé un nombre de fois différent, d’une à quatre fois, en deux groupes. Le nombre de clignotements d’une case désigne alors son bouton, quel que soit l’ordre dans lequel on les a pressés, et une erreur d’ordre ne peut plus fausser le relevé. Voici le résultat :

OctetContenuValeurs
0 et 1en-têtetoujours 0x20, 0x0F
3 et 4stick gauche, X puis Y0x80 au milieu ; X = 0xFF poussé à droite ; Y = 0x00 poussé en haut
5 et 6stick droit, X puis Ymême chose
7A, B, X, Y et la croixA 0x10 · B 0x20 · X 0x40 · Y 0x80 · haut 0x01 · bas 0x02 · gauche 0x04 · droite 0x08
8gâchettes tout ou rien, clics des sticks, boutons du centreLB 0x01 · RB 0x02 · clic gauche 0x04 · clic droit 0x08 · « double écran » 0x10 · « liste » 0x20 · HOME 0x40
10gâchette analogique gauchede 0x00 au repos à 0xFF enfoncée à fond
11gâchette analogique droitemême chose
13 à 16une seconde copie de la position des stickssens non établi

Les autres octets n’ont pas bougé, ou pas d’une façon qu’on ait su relier à un geste. Plusieurs boutons pressés ensemble s’additionnent bit à bit : 0x03 dans l’octet 8, ce sont les deux gâchettes tout ou rien. Le bouton T, au centre, n’envoie rien : c’est le bouton « turbo », qui fait répéter un autre bouton tant qu’on le tient.

Dans le programme final, ce tableau devient une table, et le décodage une boucle :

struct Bouton {
    const char *mot;
    uint8_t octet;
    uint8_t masque;
    int rang;  // ligne de l'écran (à partir de Y_BOUTONS)
    int x;
};
constexpr Bouton BOUTONS[] = {
    {"A", 7, 0x10, 0, 2},       {"B", 7, 0x20, 0, 26},      {"X", 7, 0x40, 0, 50},   {"Y", 7, 0x80, 0, 74},
    {"LB", 8, 0x01, 0, 106},    {"RB", 8, 0x02, 0, 138},    {"HAUT", 7, 0x01, 1, 2}, {"BAS", 7, 0x02, 1, 42},
    {"GAU", 7, 0x04, 1, 74},    {"DRO", 7, 0x08, 1, 106},   {"L3", 8, 0x04, 2, 2},   {"R3", 8, 0x08, 2, 26},
    {"SEL", 8, 0x10, 2, 50},    {"START", 8, 0x20, 2, 82},  {"HOME", 8, 0x40, 2, 130},
};

Commandes decoder(const uint8_t p[TAILLE_DU_PAQUET])
{
    Commandes c = {};
    for (int i = 0; i < NOMBRE_DE_BOUTONS; ++i) {
        if (p[BOUTONS[i].octet] & BOUTONS[i].masque) {
            c.boutons |= 1u << i;
        }
    }
    // 0x80 au milieu ; X = 0xFF à droite ; Y = 0x00 en haut, d'où l'inversion.
    c.stick_g_x = p[3] - 128;
    c.stick_g_y = 128 - p[4];
    c.stick_d_x = p[5] - 128;
    c.stick_d_y = 128 - p[6];
    c.gachette_g = p[10];
    c.gachette_d = p[11];
    return c;
}

Chaque ligne de BOUTONS dit où lire un bouton : dans quel octet, et avec quel masque (le nombre qui ne garde que le bit voulu). L’opération p[octet] & masque vaut zéro si le bit est à 0, autre chose s’il est à 1. Les deux derniers nombres placent le mot à l’écran. Ajouter un bouton, c’est ajouter une ligne à la table, sans toucher à la boucle. Les sticks sont recentrés autour de zéro, de −128 à +127, et l’axe vertical est retourné pour que « vers le haut » soit positif, comme sur un graphique.

Les deux palettes du dos

Restaient M1 et M2. Les presser n’allumait aucune case. Ce sont des touches de macro, vides d’origine : la manette peut y enregistrer une suite de boutons, puis la rejouer d’un seul appui. Le geste vient de la notice d’une manette G6 de la même famille, qui couvre la BSP-G6 :

  1. tenir le bouton « double écran » (deux rectangles superposés, au centre) et presser M1 ; au bout d’une seconde, le voyant clignote vite ;
  2. presser les boutons voulus, dans l’ordre, douze au plus ;
  3. presser M1 à nouveau : le voyant redevient fixe.

Enregistrée sur B, Y, X, A, la palette M1 fait passer l’octet 7 par 0x20, 0x80, 0x40 puis 0x10, environ un bouton toutes les 50 ms. La carte reçoit les boutons rejoués, et rien qui désigne la palette. Pour le robot, la conséquence est simple : une palette n’est jamais une commande de plus, seulement un raccourci vers des boutons existants. Les gâchettes analogiques sont d’ailleurs rejouées à fond, sans la course du doigt.

Le défaut que montre la vidéo

Regardez à nouveau le bandeau de la vidéo : il affiche RECHERCHE, alors que les paquets arrivent et que la grille s’anime. La radio n’y était pour rien. Sur la carte, deux programmes écoutaient la même liaison : le lecteur HID d’ESP-IDF, qui l’avait ouverte, et le nôtre, abonné au canal 0x2E. Le bandeau suivait le premier. Le lecteur HID avait refermé sa session, pour une raison que la console n’a pas montrée ; la nôtre restait ouverte, et la liaison avec elle.

Pour un robot, ce genre d’écart est grave : il dit « pas de manette » quand elle est là, et pourrait dire l’inverse. L’état affiché doit être celui de la liaison elle-même, et il ne doit y avoir qu’un programme pour l’écouter. Ce sera la première règle du quatrième essai.

Le programme de cet essai, celui de la grille, se télécharge en fin d’article, dans les programmes complets. Il suffit pour relever les octets d’une autre manette.


Essai 04 : une liaison qui ne parle qu’à sa manette

En compétition, des dizaines de manettes identiques peuvent s’annoncer dans la même salle. Deux exigences en découlent : la manette d’un autre ne doit jamais pouvoir se connecter au robot, et notre liaison ne doit pas pouvoir être perturbée sans que le robot le sache. Le quatrième programme a été écrit pour cela : c’est le programme final, à télécharger en fin d’article avec ceux des trois premiers essais, dans les programmes complets. Il ne passe plus par le lecteur HID d’ESP-IDF : en position 2.4G, il n’avait rien à lire.

En BLE, c’est le central qui choisit

Une liaison BLE réunit deux rôles. Le périphérique, ici la manette, s’annonce : il émet à intervalles réguliers une annonce (un court message radio qui dit « je suis là », avec son adresse). Le central, ici la carte, écoute ces annonces et choisit à qui il se connecte. Une manette ne peut donc pas s’imposer à un central qui ne l’appelle pas.

Toute la protection repose sur ce point. Une fois la manette connue, la carte retient son adresse et n’appelle plus qu’elle. ESP-IDF appelle cela une connexion directe :

void Liaison::ouvrir(const uint8_t adresse[6], esp_ble_addr_type_t type)
{
    if (ouverture_en_cours_ || liaison_ouverte_ || interface_ == ESP_GATT_IF_NONE) {
        return;
    }
    // « is_direct » : la radio guette les annonces de CETTE adresse, et d'elle
    // seule, jusqu'à 30 s (CONFIG_BT_BLE_ESTAB_LINK_CONN_TOUT). C'est ce qui
    // garantit qu'aucune autre manette ne peut être prise.
    esp_ble_gatt_creat_conn_params_t parametres = {};
    std::memcpy(parametres.remote_bda, adresse, 6);
    parametres.remote_addr_type = type;
    parametres.own_addr_type = BLE_ADDR_TYPE_PUBLIC;
    parametres.is_direct = true;
    parametres.is_aux = false;  // connexion BLE 4.2 : le 5.0 est coupé (sdkconfig.defaults)
    parametres.phy_mask = 0;
    if (esp_ble_gattc_enh_open(interface_, &parametres) == ESP_OK) {
        ouverture_en_cours_ = true;
    } else {
        ESP_LOGE(TAG, "connexion refusée par la pile ; nouvel essai dans 1 s");
        programmer(AFaire::Ouvrir, 1000 * 1000);
    }
}

Pendant trente secondes, la radio n’écoute que les annonces de cette adresse. Si la manette ne s’est pas annoncée, la tentative échoue, et le programme en relance aussitôt une autre, indéfiniment. La carte n’a donc jamais besoin de « rechercher » la manette : elle est en permanence prête à la reprendre, dès que celle-ci s’annonce. is_aux = false demande une connexion à la manière du BLE 4.2, pour la raison découverte à l’essai 03.

Appairer seulement sur un geste voulu

Reste à apprendre son adresse, une seule fois, sans risquer de retenir celle du voisin. Deux conditions doivent être réunies. D’abord un geste voulu : le bouton BOOT de la carte tenu trois secondes. Ensuite une manette tout près : la carte retient le meilleur appareil HID vu pendant une recherche de trois secondes, et ne l’accepte que si son signal atteint −60 dBm. Ce nombre est le RSSI (la force du signal reçu, en décibels rapportés au milliwatt) : −60 dBm correspond à quelques dizaines de centimètres. Une manette à l’autre bout de la salle n’a aucune chance d’être prise par erreur.

case Quoi::FinDeRecherche:
    recherche_en_cours_ = false;
    if (!appairage_) {
        break;
    }
    if (candidat_ && signal_du_candidat_ >= SEUIL_D_APPAIRAGE_DBM) {
        ESP_LOGI(TAG, "appairage avec " ESP_BD_ADDR_STR " (%d dBm)", ESP_BD_ADDR_HEX(adresse_du_candidat_),
                 signal_du_candidat_);
        ouvrir(adresse_du_candidat_, type_du_candidat_);
    } else {
        rechercher();  // personne d'assez proche : on recommence
    }
    break;

Le bouton BOOT a une particularité : la puce lit son niveau au démarrage, pour choisir entre lancer le programme et attendre un téléversement. Le tenir pendant un redémarrage ferait donc démarrer la carte en mode téléchargement. Le programme ne le lit qu’une fois lancé, toutes les 10 ms, dans une tâche à part :

// Le bouton BOOT : 3 s tenu, une seule fois par appui.
if (gpio_get_level(BROCHE_BOOT) == 0) {
    if (boot_presse_depuis == 0) {
        boot_presse_depuis = maintenant;
    }
    const int64_t tenu = maintenant - boot_presse_depuis;
    boot_tenu_ms = static_cast<int32_t>(tenu / 1000);
    if (tenu >= DUREE_POUR_APPAIRER_US && !boot_signale) {
        boot_signale = true;
        poster(evenement(Quoi::Boot));
    }
} else {
    boot_presse_depuis = 0;
    boot_signale = false;
    boot_tenu_ms = 0;
}

L’adresse retenue est rangée dans la mémoire de réglages de l’ESP32 (une zone de la mémoire flash, appelée NVS, qui survit aux coupures de courant). Un redémarrage de la carte ne l’efface pas ; seul un nouvel appui de trois secondes sur BOOT permet de changer de manette.

Le silence n’est pas une panne

La première version surveillait la liaison de la façon la plus évidente : si aucun paquet de données n’arrive pendant 200 ms, on coupe les moteurs. Posée sur la table, la manette s’est aussitôt retrouvée en « silence », moteurs coupés. Elle n’envoie de paquet de données que lorsqu’un bouton ou un stick change. Un stick tenu immobile à fond aurait coupé les moteurs, lui aussi, en pleine course.

Le dialogue n’est-il donc pas permanent, pour maintenir la connexion ? Il l’est, mais à un autre étage : celui de la radio. Une fois connectés, le central et le périphérique se donnent rendez-vous à intervalle fixe, et à chaque rendez-vous ils échangent un paquet, vide s’ils n’ont rien à dire. Ce rythme est l’intervalle de liaison. Si ces échanges cessent pendant un temps donné, le délai de supervision, la radio déclare la liaison perdue. Le battement de cœur existe déjà ; il suffisait de l’écouter au bon endroit.

À la connexion, la manette proposait un intervalle de 25 ms et un délai de supervision de 6 secondes. Six secondes de robot lancé à l’aveugle avant de savoir que la manette est perdue : c’est beaucoup trop. Or c’est le central qui fixe ces paramètres. La carte demande donc mieux, dès la connexion :

constexpr uint16_t INTERVALLE_MIN = 6;         // 7,5 ms
constexpr uint16_t INTERVALLE_MAX = 12;        // 15 ms
constexpr uint16_t DELAI_DE_SUPERVISION = 30;  // 300 ms

void Liaison::demander_les_parametres()
{
    esp_ble_conn_update_params_t parametres = {};
    std::memcpy(parametres.bda, adresse_liee_, 6);
    parametres.min_int = INTERVALLE_MIN;
    parametres.max_int = INTERVALLE_MAX;
    parametres.latency = 0;  // la manette répond à CHAQUE rendez-vous radio
    parametres.timeout = DELAI_DE_SUPERVISION;
    if (esp_ble_gap_update_conn_params(&parametres) != ESP_OK) {
        ESP_LOGW(TAG, "demande de paramètres de liaison refusée par la pile");
    }
}

Les unités sont celles de la norme Bluetooth : l’intervalle se compte en pas de 1,25 ms (6 pas font 7,5 ms, 12 pas font 15 ms), le délai de supervision en pas de 10 ms (30 pas font 300 ms). La latence est le nombre de rendez-vous que le périphérique a le droit de sauter pour économiser sa pile ; à zéro, il répond à chacun.

La norme impose une condition entre ces nombres, pour que la liaison ne soit pas déclarée perdue avant même d’avoir pu manquer un échange :

T_{\text{supervision}} > 2 \times (1 + \text{latence}) \times T_{\text{intervalle}}

Avec 15 ms d’intervalle et une latence nulle, il faut plus de 30 ms : nos 300 ms laissent passer une vingtaine de rendez-vous manqués avant de conclure. Pourquoi pas moins ? La norme interdit de descendre sous 100 ms, et un délai trop court ferait couper la liaison par le moindre brouillage passager, alors qu’il faut ensuite près d’une seconde pour la reprendre. Trop long, le robot roulerait à l’aveugle. 300 ms est un point de départ, que des essais en conditions de compétition devront ajuster. La manette a accepté ces paramètres : 15 ms et 300 ms. Sur le robot, les moteurs seront coupés à l’instant où la radio déclare la liaison perdue.

La clé que la manette oublie

Le premier programme du quatrième essai chiffrait la liaison. Lors de l’appairage (la première rencontre de deux appareils, où ils fabriquent une clé commune qu’ils gardent), la carte et la manette convenaient d’une clé, que la carte réutilisait ensuite à chaque reconnexion. Tant que la manette restait allumée, tout allait bien. Éteinte puis rallumée, elle refusait sa propre clé : la liaison tombait avec le code 0x3d, « échec de contrôle du chiffrement », à chaque tentative. Il ne s’agissait pas d’une clé absente, qui donnerait un autre code (0x06) ; tout se passe comme si la manette fabriquait une nouvelle clé à chaque démarrage.

La version chiffrée, bloquée : la manette rallumée ne reconnaît plus la clé de l'appairage, et la carte attend une vérification qui ne viendra pas. La liaison a encore les paramètres de la manette : 25 ms d'intervalle, 6000 ms de supervision.
Fig. 7 — La version chiffrée, bloquée : la manette rallumée ne reconnaît plus la clé de l’appairage, et la carte attend une vérification qui ne viendra pas. La liaison a encore les paramètres de la manette : 25 ms d’intervalle, 6000 ms de supervision.

La parade suivante a été de réappairer automatiquement la manette retenue, et elle seule, chaque fois que sa clé ne tenait plus. La manette n’a pas répondu. Elle n’accepte un appairage que dans son propre mode d’appairage, HOME tenu trois secondes, et la liaison mourait au bout de six secondes, faute de réponse.

Il restait une question : la manette exige-t-elle vraiment le chiffrement ? Elle ne l’exige pas. Sur son canal 0x2E, elle envoie ses paquets en clair, dès la connexion, sans attendre aucune clé. Le programme se passe donc de clé, par un seul réglage :

constexpr bool CHIFFRER = false;

Il faut alors être honnête sur ce qui reste protégé. La carte n’appelle que l’adresse retenue, et seul le bouton BOOT permet d’en changer : aucune autre manette ne peut être prise par erreur, ni s’imposer. Ce qui ne l’est plus : un appareil construit exprès pour se faire passer pour notre manette, en recopiant son adresse. En compétition, le risque courant est la manette du voisin, et il est écarté ; une attaque délibérée est d’un autre ordre, mais il fallait la nommer. Le chemin chiffré reste dans le programme : CHIFFRER à true le rétablit, pour une autre manette qui tiendrait sa clé.

Sans clé, la connexion se résume à trois gestes : vérifier que l’appareil connecté est bien la manette retenue, demander les paramètres de liaison, puis lire le catalogue pour trouver le canal :

if (!CHIFFRER) {
    // Sans clé : on fixe les paramètres de liaison, puis on lit le
    // canal. Hors appairage, l'adresse est forcément la retenue (la
    // carte n'en appelle pas d'autre) ; on le vérifie quand même.
    if (!appairage_ && std::memcmp(adresse_liee_, manette_.adresse, 6) != 0) {
        refuser(-3, "appareil autre que la manette retenue");
        break;
    }
    demander_les_parametres();
    lire_le_plan();
    break;
}

Un détail compte : au démarrage, en mode sans clé, le programme efface toutes les clés que la pile Bluetooth aurait gardées. Sinon, la pile s’en servirait d’elle-même si la manette demandait un jour le chiffrement, et l’ancienne clé échouerait avec ce même 0x3d.

Le catalogue de la manette, lui, est gardé en mémoire de réglages grâce au réglage CONFIG_BT_GATTC_CACHE_NVS_FLASH : à la reconnexion, la carte ne le redemande pas à la manette, ce qui raccourcit la reprise. Une fois le canal trouvé, la carte s’y abonne, des deux côtés, comme l’a montré l’essai 03 : dans sa propre pile d’abord, puis dans le descripteur d’abonnement de la manette. Les deux abonnements étant effacés à chaque coupure, ils sont refaits à chaque connexion, et c’est leur confirmation qui fait passer l’écran EN LIGNE.

Une seule tâche décide

Le programme est découpé en quatre tâches (des morceaux de programme qui tournent comme s’ils étaient seuls, que le petit système d’exploitation FreeRTOS fait alterner selon leur priorité) :

  • la pile Bluetooth appelle deux fonctions du programme à chaque événement radio. Un paquet de la manette y est traité sur place, en quelques microsecondes ; tout le reste est posté dans une file de messages (une boîte aux lettres entre deux tâches) ;
  • la tâche « liaison » vide cette file. Elle seule décide de ce que fait la liaison : se connecter, couper, appairer, refuser. Deux morceaux de programme qui décideraient chacun de leur côté finiraient par se contredire, comme à l’essai 03 ;
  • la tâche « guet » regarde le bouton BOOT toutes les 10 ms ;
  • la tâche « affichage » redessine dix fois par seconde les seules lignes de l’écran qui ont changé.

Le chemin le plus fréquent du programme est celui d’un paquet de la manette. Il ne fait que vérifier, recopier et compter :

void recevoir_un_paquet(uint16_t handle, const uint8_t *octets, uint16_t longueur)
{
    // Un paquet qui n'a pas la forme attendue (20 octets, commençant par 0x20
    // 0x0F, relevé de l'essai 03) n'est pas pris : il ne nourrit pas le guet.
    if (handle != handle_du_canal || longueur != TAILLE_DU_PAQUET || octets[0] != 0x20 || octets[1] != 0x0F) {
        paquets_etrangers++;
        return;
    }
    instant_du_dernier_paquet = esp_timer_get_time();
    portENTER_CRITICAL(&verrou_du_paquet);
    std::memcpy(dernier_paquet, octets, TAILLE_DU_PAQUET);
    portEXIT_CRITICAL(&verrou_du_paquet);
    paquets_recus++;
}

Le programme garde le dernier paquet, et non une file de paquets : le robot a besoin de l’état présent de la manette, pas de son historique. La copie se fait dans une section critique (un passage si court qu’on interdit aux autres tâches de s’y glisser pendant qu’il s’exécute), pour que l’affichage ne lise jamais un paquet à moitié recopié. Les compteurs, eux, sont des variables atomiques (std::atomic, des variables que deux tâches peuvent lire et écrire en même temps sans jamais lire une valeur à moitié écrite).

Le démarrage met tout en place dans un ordre précis :

file_de_la_liaison = xQueueCreate(48, sizeof(Evenement));
if (file_de_la_liaison == nullptr) {
    ESP_LOGE(TAG, "pas de mémoire pour la file de la liaison");
    return;
}
xTaskCreate(liaison, "liaison", 6 * 1024, nullptr, 4, nullptr);
xTaskCreate(guetter, "guet", 3 * 1024, nullptr, 6, nullptr);
xTaskCreate(afficher, "affichage", 6 * 1024, nullptr, 3, nullptr);

// 5. Le Bluetooth, en dernier : ses événements trouvent la file prête.
ESP_ERROR_CHECK(demarrer_le_bluetooth());

Le Bluetooth démarre en dernier : ses premiers événements trouvent ainsi la file et la tâche qui la vide déjà prêtes. Le guet a la priorité la plus haute (6), parce qu’il doit tourner toutes les 10 ms quoi qu’il arrive ; l’affichage la plus basse (3), parce qu’une image en retard ne coûte rien.

Un dernier détail d’écriture a coûté une compilation. La macro d’ESP-IDF qui prépare la configuration de la radio, BT_CONTROLLER_INIT_CONFIG_DEFAULT, ne donne pas de valeur à tous les champs de la structure pour l’ESP32-S31. Le C met les champs oubliés à zéro sans rien dire ; le C++ le signale, et ESP-IDF fait de tout signalement une erreur. On fait taire ce signalement-là, sur cette ligne seulement :

#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wmissing-field-initializers"
    esp_bt_controller_config_t config_radio = BT_CONTROLLER_INIT_CONFIG_DEFAULT();
#pragma GCC diagnostic pop

Les réglages du projet, enfin, tiennent dans le fichier sdkconfig.defaults. En voici le cœur : le Bluetooth en BLE seul, sans le Bluetooth Classique qui ne ferait qu’occuper la radio, et sans le BLE 5.0 :

CONFIG_BT_ENABLED=y
CONFIG_BT_BLUEDROID_ENABLED=y
CONFIG_BTDM_CTRL_MODE_BLE_ONLY=y
# CONFIG_BT_CLASSIC_ENABLED is not set
CONFIG_BT_BLE_ENABLED=y
CONFIG_BT_GATTC_ENABLE=y
CONFIG_BT_BLE_SMP_ENABLE=y
CONFIG_BT_BLE_42_FEATURES_SUPPORTED=y
# CONFIG_BT_BLE_50_FEATURES_SUPPORTED is not set
CONFIG_BT_GATTC_CACHE_NVS_FLASH=y

Ce que montre l’écran, et ce qu’il a mesuré

L’écran du quatrième essai ne montre plus des bits, mais l’état de la liaison. Le bandeau en donne l’étape :

BandeauCe qui se passe
SANS MANETTE (gris)aucune manette retenue : il faut appairer, BOOT tenu 3 s
APPAIRAGE (cyan)la carte cherche une manette en appairage, tout près d’elle
ATTENTE (orange)la carte attend que la manette retenue s’annonce
LECTURE (jaune)connectée : lecture du catalogue et abonnement au canal
EN LIGNE (vert)la liaison est établie, les commandes arrivent

Sous le bandeau viennent l’adresse de la manette retenue, puis les mesures : le débit de paquets, le temps écoulé depuis le dernier paquet de données, le nombre de coupures avec le code de leur cause, le temps de reprise après la dernière coupure, les refus, et les deux paramètres de la liaison. La ligne MOTEURS AUTORISES (verte) ou MOTEURS COUPES (rouge) dit ce que ferait le robot. Plus bas, chaque bouton pressé s’allume en jaune, et les gâchettes et les sticks s’affichent en nombres.

La photo d’ouverture résume tout le chapitre sur le silence : DERNIER PAQUET 277.8 S, aucun paquet de données depuis plus de quatre minutes et demie, et pourtant EN LIGNE, MOTEURS AUTORISES. Personne ne touchait la manette, et la radio continuait de battre toutes les 15 ms.

Les mesures, relevées le 20 novembre 2026 :

  • Redémarrage de la carte, manette restée allumée : la carte la reprend seule, sans aucun geste, en ligne moins d’une seconde et demie après le démarrage.
  • Manette éteinte puis rallumée (appui long sur HOME pour l’éteindre, appui court pour la rallumer) : la carte la reprend dès qu’elle s’annonce, une vingtaine de millisecondes après la liaison radio, le catalogue étant relu dans la mémoire de réglages.
  • Manette laissée au repos : elle a raccroché d’elle-même 5 min 11 s après sa mise en ligne, liaison ouverte comprise. C’est sa mise en veille automatique. La carte l’a vu à l’instant (coupure, cause 0x13 : l’appareil distant a mis fin à la liaison), et un appui sur HOME la remet en ligne.
La manette a raccroché (cause 13 : éteinte ou en veille). La carte l'a vu aussitôt : moteurs coupés, et elle attend qu'un appui sur HOME la ramène.
Fig. 8 — La manette a raccroché (cause 13 : éteinte ou en veille). La carte l’a vu aussitôt : moteurs coupés, et elle attend qu’un appui sur HOME la ramène.

Sur le robot, cette mise en veille aura une conséquence pratique : une manette posée cinq minutes pendant une pause doit être réveillée par HOME avant de reprendre la main. Rien de dangereux, puisque les moteurs sont coupés à l’instant où elle raccroche.


Refaire le montage

Ce qu’il vous faut

  • une carte ESP32-S31 Function-CoreBoard-1 d’Espressif, et un câble USB-C ;
  • un écran ST7789 de 1,9 pouce, 170 × 320 pixels, en module à huit broches (GND, VCC, SCL, SDA, RES, DC, CS, BLK) ;
  • huit fils femelle-femelle d’une dizaine de centimètres ;
  • une manette BSP-G6 (ShanWan BM-835). Une autre manette demandera son propre relevé, avec la méthode de l’essai 03 : son canal et la place de ses boutons ont toutes les chances d’être différents ;
  • ESP-IDF 6.1, installé selon la documentation d’Espressif (sous Windows, par son installateur, qui pose un terminal ESP-IDF tout réglé) ;
  • le projet complet, à télécharger en fin d’article.

Câbler

Suivez le tableau de l’essai 01, carte débranchée. Le seul fil à vérifier deux fois est celui du VCC : sur le 3V3 (broche 36 de J2), jamais sur le 5V.

Compiler et téléverser

Décompressez le projet dans un dossier dont le chemin ne contient ni espace ni accent, par exemple C:\esp\manette-ble-esp32-s31 sous Windows. Certains outils d’ESP-IDF 6.1 trébuchent sur les espaces, les accents et les tirets longs d’un chemin, et leurs messages d’erreur ne le disent pas clairement. Branchez la carte par sa prise USB-DBG, ouvrez le terminal ESP-IDF, placez-vous dans le dossier du projet, puis :

idf.py --preview set-target esp32s31
idf.py --preview build
idf.py --preview -p COM3 flash monitor

La première commande choisit la puce, la deuxième compile (plusieurs minutes la première fois, quelques secondes ensuite), la troisième téléverse puis affiche la console. Remplacez COM3 par le port de votre carte : Windows la voit comme un « Périphérique série USB » dans le Gestionnaire de périphériques, Linux comme /dev/ttyACM0. Aucun bouton à presser : le téléversement met lui-même la puce en mode téléchargement, puis la redémarre. On sort de la console par Ctrl+].

Appairer la manette

  1. Si la manette a déjà été connectée à un téléphone ou à un PC, faites-la-lui oublier dans ses réglages Bluetooth : une manette connectée ailleurs ne s’annonce plus.
  2. L’écran affiche SANS MANETTE. Tenez BOOT trois secondes : l’écran compte les secondes, puis passe sur APPAIRAGE.
  3. Placez l’interrupteur de la manette sur 2.4G, tenez HOME trois secondes (le voyant clignote vite), et posez-la à côté de la carte. L’écran affiche le nom de l’appareil vu et son signal : en vert s’il est assez proche, en orange s’il est trop loin.
  4. Attendez EN LIGNE, puis pressez chaque bouton : son nom s’allume en jaune.
  5. Vérifiez la reprise : pressez RST sur la carte, elle doit revenir en ligne seule ; éteignez la manette (HOME tenu longuement), rallumez-la d’un appui court, la carte doit la reprendre sans autre geste.

Quand ça ne marche pas

Ce que vous voyezCe que ça veut direCe que vous pouvez faire
L’écran s’éclaire mais reste uniforme, sans aucun textel’écran ne reçoit pas ses ordresvérifier SCL, SDA, DC, CS et RES un par un ; puis passer FREQUENCE_SPI_HZ à 10 MHz
Tout l’écran passe en négatif après qu’on a bougé un filun faux contact a changé un ordre en routeenfoncer les fils, puis presser RST
APPAIRAGE sans fin, nom affiché en orangela manette est trop loin (signal sous −60 dBm)la rapprocher de la carte
APPAIRAGE sans fin, aucun nom affichéla manette n’est pas en mode d’appairage, ou elle est connectée ailleursHOME tenu 3 s ; la faire oublier par le téléphone ou le PC
REFUS MOTIF 6le canal du fabricant est introuvablela manette n’est pas sur la position 2.4G
REFUS MOTIF 2la liaison n’était pas en ligne 10 s après la connexionrecommencer ; si ça se répète, lire la console
COUPURES, CAUSE 13la manette a raccroché : éteinte ou en veilleappui court sur HOME
COUPURES, CAUSE 08plus aucun échange radio pendant 300 msmanette trop loin, ou un obstacle métallique entre elle et la carte
ATTENTE qui durela manette retenue ne s’annonce pasla réveiller par HOME ; pour en changer, BOOT tenu 3 s

La console en dit davantage que l’écran : chaque changement d’état, chaque coupure avec sa cause, chaque refus, les paramètres de la liaison et le temps de reprise y sont écrits en clair.


Ce qui reste à éprouver

Tout ce qui précède a été mesuré sur un bureau, à quelques dizaines de centimètres. Une salle de compétition sera plus rude, et cinq essais restent à faire avant de faire confiance à cette liaison :

  • la distance : jusqu’où la liaison tient-elle, et revient-elle seule quand on se rapproche ?
  • la coupure franche : la manette enfermée dans une boîte métallique doit faire couper les moteurs en 300 ms environ, avec la cause 0x08 ;
  • le Wi-Fi chargé : un téléphone en point d’accès qui télécharge, posé contre la carte, fait-il tomber la liaison ? Si oui, 300 ms est trop court ;
  • un autre appareil : un téléphone qui tente de se connecter à la carte, ou une autre manette en appairage à côté, ne doit rien changer à l’écran ;
  • la manette prise ailleurs : carte éteinte, un téléphone peut-il voir notre manette, et s’y connecter ? Autrement dit, la manette s’annonce-t-elle à tous, ou seulement au dernier appareil qu’elle a connu ?

Le dernier point compte autant que les autres. La carte ne peut pas être trompée, mais rien ne dit encore que la manette, elle, ne peut pas être emmenée par quelqu’un d’autre pendant que le robot dort.


Ce qu’il faut retenir

La manette se faisait passer pour un écran tactile, puis pour une manette HID qui n’envoyait rien. Ses boutons passaient par un canal du fabricant, en clair, et c’est ce canal que la carte lit désormais : quinze boutons, les deux sticks et les deux gâchettes analogiques, à plus de 150 paquets par seconde dès qu’on bouge la manette.

Vidéo 2 — Le programme final : chaque bouton pressé s’allume en jaune, les sticks s’affichent de −128 à +127, et le débit monte à plus de 150 paquets par seconde dès qu’on bouge la manette, pour retomber à zéro au repos.

Dans une salle pleine de manettes identiques, la carte n’appelle plus que la sienne, et seul un appui de trois secondes sur BOOT lui en fait changer. Elle la reprend seule, sans aucun geste : moins d’une seconde et demie après un redémarrage de la carte, et dès que la manette s’annonce quand on la rallume. Même après près de vingt-sept minutes de veille, un seul appui sur HOME a suffi, sans recherche et sans rien demander.

De retour EN LIGNE après 1602,9 secondes de coupure, près de vingt-sept minutes de veille : deux coupures, toutes deux de cause 13 (la manette a raccroché), et aucun refus.
Fig. 9 — De retour EN LIGNE après 1602,9 secondes de coupure, près de vingt-sept minutes de veille : deux coupures, toutes deux de cause 13 (la manette a raccroché), et aucun refus.

La fraction de seconde, elle, est réglée mais pas encore éprouvée. La manette a accepté 300 ms de supervision au lieu des six secondes qu’elle proposait, et la carte voit à l’instant une manette qui raccroche ; reste à la couper franchement, dans une boîte métallique, pour mesurer ce que le robot mettrait vraiment à s’arrêter.

Trois idées ont fait le chemin, et elles valent bien au-delà de cette manette.

La description d’un appareil n’est pas ce qu’il fait. La manette se décrivait comme une manette HID, et parlait ailleurs. Afficher les octets bruts, sans rien supposer de leur format, a tranché en quelques minutes ce que des heures de lecture de descriptions n’auraient pas tranché.

En BLE, c’est le central qui choisit. Retenir une adresse et n’appeler qu’elle suffit à fermer la porte aux autres manettes, sans aucune clé.

Une liaison silencieuse n’est pas une liaison morte. Surveiller les données, c’était confondre une manette au repos avec une manette perdue. La radio échange un paquet à chaque rendez-vous, même vide : c’est là qu’il fallait regarder, et c’est le central qui règle combien de temps il tolère le silence.

Reste la question que seule une vraie salle de compétition tranchera : 300 ms de supervision, au milieu de dizaines de liaisons Wi-Fi et Bluetooth, est-ce assez court pour la sécurité, et assez long pour ne pas couper le robot à chaque brouillage ?


Les programmes complets

Chaque essai a son programme, complet et prêt à compiler. Les archives ne contiennent que les sources : il n’y a rien d’autre à télécharger qu’ESP-IDF, et chacune se compile avec les trois commandes de la partie « Compiler et téléverser ». Elles suivent l’histoire : chacune garde ce que l’essai a appris, et les défauts qu’il n’avait pas encore vus.

Essai 01, l’écran : essai-01-ecran-st7789.zip. Le programme dessine la mire, puis fait aller et venir un petit carré. Il ne demande que l’écran, câblé comme dans le tableau de l’essai 01. Les quatre réglages de la dalle, marqués « À RÉGLER », sont au début de main/essai_ecran.cpp.

Essai 02, la manette en Bluetooth : essai-02-manette-ble.zip. C’est l’exemple esp_hid_host d’ESP-IDF, avec ses trois corrections, marquées [essai 02] dans les sources ; sa licence, Unlicense ou CC0-1.0, est en tête de chaque fichier. Il n’affiche rien à l’écran : tout se lit dans la console. Sa recherche ne dure que cinq secondes, une seule fois, au démarrage : mettez la manette en appairage (interrupteur sur V3, HOME tenu trois secondes) avant de démarrer la carte, ou pressez RST juste après.

Essai 03, tout afficher, bit par bit : essai-03-manette-et-ecran.zip. C’est le programme de la grille de la vidéo 1, avec le pilote de l’écran et la recherche de l’essai 02 rangés dans components/. Sa recherche recommence toute seule tant qu’aucune manette n’est connectée. Il efface tous les appairages à chaque démarrage : après un RST, remettez la manette en appairage. Il garde le défaut du bandeau décrit plus haut.

Essai 04, la liaison blindée, le programme final : manette-ble-esp32-s31.zip. C’est celui que décrivent la partie « Refaire le montage » et la plupart des extraits de code. L’archive contient :

  • CMakeLists.txt, sdkconfig.defaults et partitions.csv : le projet, ses réglages et le découpage de la mémoire flash ;
  • main/essai_liaison.cpp : le programme, en neuf sections commentées (les réglages, les états de la liaison, le dernier paquet, les événements Bluetooth, la mémoire de réglages, la tâche « liaison », le guet du bouton BOOT, l’affichage, le démarrage du Bluetooth) ;
  • components/ecran_st7789/ : le pilote de l’écran, avec sa police de 3 × 5 pixels.

Tous les réglages qu’on peut vouloir changer sont regroupés au début de main/essai_liaison.cpp, dans la section « 0. Les réglages » : les broches de l’écran, la durée d’appui sur BOOT, les paramètres de liaison, le seuil de signal de l’appairage, et CHIFFRER.


Sources et filiation

  • Espressif, ESP32-S31 Function-CoreBoard-1, User Guide : brochage du connecteur J2, prises USB, boutons ; et le schéma de la carte, version 1.0 du 13 mai 2026.
  • Espressif, documentation d’ESP-IDF : API du client GATT et de la sécurité BLE de Bluedroid ; exemple examples/bluetooth/esp_hid_host, point de départ de l’essai 02.
  • Bluetooth SIG, Bluetooth Core Specification, volume 6, partie B (couche liaison) : intervalle de liaison, latence et délai de supervision, et la condition qui les relie.
  • Sitronix, fiche technique du ST7789V : codes des ordres CASET (0x2A) et INVOFF (0x20).
  • Notice de la manette G6, sur manuals.plus, consultée le 20 novembre 2026 : enregistrement et effacement des macros sur M1 et M2, bouton turbo.

Photographies et vidéo : Sébastien Debucquoi.

Les programmes des archives sont publiés sous la licence PolyForm Noncommercial 1.0.0 : vous pouvez les utiliser, les modifier et les partager pour un usage personnel, éducatif, de recherche ou associatif ; tout usage commercial demande l’accord écrit de l’auteur. Les fichiers d’Espressif qu’ils contiennent gardent leur propre licence.