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

Objetivos

Transformar el ESP32-S3 en un dispositivo USB HID (teclado) gracias a su controlador USB-OTG nativo en GPIO19 (D-) y GPIO20 (D+), mediante la pila TinyUSB integrada en el core de Arduino. Esta es una de las grandes diferencias con el ESP32 clásico: no se necesita ningún chip adicional. También descubrirás la principal restricción del doble USB del S3: el modo «TinyUSB (OTG)» y el modo «Hardware CDC and JTAG» comparten los mismos pines; no es posible usar ambos simultáneamente sin un segundo conector físico.

Material

• 1 placa ESP32-S3 con USB en GPIO19/20 (DevKitC-1 v1.1, Feather S3, XIAO en modo OTG)
• 1 botón pulsador entre GPIO1 y GND
• 1 segundo puerto USB (o un segundo ordenador/probador) para volver a grabar si el HID toma el control
• IDE de Arduino con core esp32 reciente

Código completo

// 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 etat = digitalRead(BTN);
  if (etat == 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 = etat;
  delay(10);
}

Verificación esperada

Tras la carga y reconexión del cable, el ordenador detecta un nuevo dispositivo «USB Keyboard» (hidusb) sin necesidad de controladores. Una pulsación del botón escribe la línea «ESP32-S3 dice hola» seguida de Intro en cualquier campo de texto activo. La enumeración USB pasa por los pines GPIO19/20, los únicos conectados al controlador OTG del S3.

Errores frecuentes

• Olvidar cambiar el menú «USB Mode» a TinyUSB: con el modo Hardware CDC+JTAG, USB.begin falla silenciosamente porque GPIO19/20 no están enrutados hacia el OTG.
• Perder el puerto de grabación: en modo TinyUSB, el puerto serie de enumeración desaparece si el programa falla antes de USB.begin; ten previsto un botón BOOT/RESET para entrar en modo de descarga ROM, o mantén un segundo cable en la UART0 (GPIO43/44).
• Esperar una reconexión automática: muchos anfitriones no vuelven a enumerar en caliente; tras una grabación, a menudo es necesario desenchufar y volver a enchufar el cable.
• Distribución del teclado: Keyboard.write asume una distribución US; para una distribución AZERTY francesa, utiliza modificadores o la clase KeyboardFR según las versiones del core.
• Confundir los dos USB: el puerto «COM» de la consola (Serial/JTAG) y el HID OTG solo pueden coexistir si la placa conecta físicamente los dos controladores a dos conectores distintos.