🛠 Clavier USB HID via l'USB-OTG natif (TinyUSB)

Objectifs

Transformer l'ESP32-S3 en périphérique USB HID (clavier) grâce à son contrôleur USB-OTG natif sur GPIO19 (D-) et GPIO20 (D+), via la pile TinyUSB intégrée au core Arduino. C'est l'un des grands écarts avec l'ESP32 classique : aucune puce additionnelle n'est nécessaire. Vous découvrirez aussi la contrainte majeure du double USB du S3 : le mode « TinyUSB (OTG) » et le mode « Hardware CDC and JTAG » se disputent les mêmes broches ; on ne peut pas tout faire en même temps sans un second connecteur physique.

Matériel

• 1 carte ESP32-S3 avec USB sur GPIO19/20 (DevKitC-1 v1.1, Feather S3, XIAO en mode OTG)
• 1 bouton poussoir entre GPIO1 et GND
• 1 second port USB (ou un second ordinateur/testeur) pour reflasher si le HID prend la main
• IDE Arduino avec core esp32 récent

Code complet

// Clavier HID sur USB-OTG natif (GPIO19/20) via TinyUSB
// Outils Arduino : USB Mode = "TinyUSB Device" (ou "OTG"), USB CDC = Disabled
#include "Arduino.h"
#include "USB.h"
#include "USBHIDKeyboard.h"

USBHIDKeyboard Keyboard;
const uint8_t BTN = 1;
uint8_t etatPrecedent = HIGH;
unsigned long dernierBord = 0;

void setup {
  pinMode(BTN, INPUT_PULLUP);
  Keyboard.begin;
  if (!USB.begin) {
    // pas de hot-plug possible ici : le host verra le HID au prochain branchement
  }
}

void loop {
  uint8_t état = digitalRead(BTN);
  if (état == LOW && etatPrecedent == HIGH && millis - dernierBord > 120) {
    dernierBord = millis;
    Keyboard.begin;                 // s'assure que le HID est pret
    Keyboard.print("ESP32-S3 dit bonjour ");
    Keyboard.write(KEY_RETURN);
    Keyboard.end;
  }
  etatPrecedent = état;
  delay(10);
}

Vérification attendue

Après téléversement et rebranchement du câble, l'ordinateur détecte un nouveau périphérique « USB Keyboard » (hidusb) sans pilote. Un appui sur le bouton saisit la ligne « ESP32-S3 dit bonjour » suivie d'Entrée dans n'importe quel champ de texte actif. L'énumération USB passe par les broches GPIO19/20, les seules reliées au contrôleur OTG du S3.

Erreurs fréquentes

• Oublier de basculer le menu « USB Mode » sur TinyUSB : avec le mode Hardware CDC+JTAG, USB.begin échoue silencieusement car GPIO19/20 ne sont pas routés vers l'OTG.
• Perdre le port de flash : en mode TinyUSB, le port série d'énumération disparaît si le programme plante avant USB.begin ; prévoir un bouton BOOT/RESET pour entrer en mode téléchargement ROM, ou garder un second câble sur l'UART0 (GPIO43/44).
• Attendre un rebranchement : beaucoup d'hôtes ne ré-énumèrent pas à chaud ; après un flash, débrancher/rebrancher le câble est souvent nécessaire.
• Layout clavier : Keyboard.write suppose un layout US ; pour un AZERTY français, utiliser les modificateurs ou la classe KeyboardFR selon les versions du core.
• Confondre les deux USB : le port « COM » de la console (Serial/JTAG) et le HID OTG peuvent coexister uniquement si la carte câble physiquement les deux contrôleurs sur deux connecteurs distincts.