1. Què és TinyUSB?

TinyUSB és una llibreria open‑source escrita en C que implementa el protocol USB per a microcontroladors. Permet que un microcontrolador actuï com a:

• Dispositiu USB (teclat, ratolí, port sèrie, MIDI, etc.)
• Host USB (en alguns casos avançats)

En termes simples:

TinyUSB permet que un microcontrolador es comporti com un dispositiu USB real, reconegut pel sistema operatiu sense drivers especials.

2. TinyUSB i ESP32: què has de saber

⚠️ No tots els ESP32 tenen USB natiu.

✅ ESP32 compatibles amb TinyUSB

Només els models amb USB integrat:

• ESP32‑S2
• ESP32‑S3
• (ESP32‑P4 en versions recents)

❌ ESP32 NO compatibles

• ESP32 clàssic (WROOM, WROVER, etc.)

En aquests casos, el connector USB només és un convertidor USB‑sèrie (CP2102, CH340…). TinyUSB no hi funciona.

3. Què pots fer amb TinyUSB + ESP32?

Amb un ESP32‑S2 o S3, pots crear dispositius USB reals:

🔹 Teclat USB (HID)

• Teclats personalitzats
• Macro‑keypads
• Automatització de PCs
• Stream Deck DIY

🔹 Ratolí o joystick

• Controls personalitzats
• Projectes de joc

🔹 Port sèrie USB (CDC)

• Comunicació PC ↔ ESP32 sense UART
• Debug i configuració avançada

🔹 MIDI USB

• Controladors MIDI
• Sintetitzadors DIY
• Plugins reconeguts com a dispositius professionals

🔹 Dispositius compostos

• Teclat + port sèrie
• MIDI + botons
• Tot amb un sol cable USB

Tot això funciona sense drivers a: ✅ Windows
✅ Linux
✅ macOS

4. Entorn recomanat (el més fàcil)

✅ Arduino IDE + core ESP32

És la forma més ràpida de començar.

Requisits:

• Arduino IDE
• Core ESP32 actualitzat (≥ 2.x)
• Placa ESP32‑S2 o ESP32‑S3

Selecció de placa:

Eines → Placa → ESP32 Arduino → ESP32S2 / ESP32S3 Dev Module

5. Exemple mínim: teclat USB amb TinyUSB

Aquest exemple fa que l’ESP32 escrigui text automàticament quan el connectes al PC.

#include "USB.h"
#include "USBHIDKeyboard.h"

USBHIDKeyboard Keyboard;

void setup() {
  USB.begin();        // Inicialitza TinyUSB
  Keyboard.begin();   // Inicialitza el teclat HID

  delay(2000);        // Temps perquè el PC reconegui el dispositiu

  Keyboard.print("Hola des de l'ESP32 amb TinyUSB!");
  Keyboard.press(KEY_ENTER);
  Keyboard.releaseAll();
}

void loop() {
  // Res
}

👉 El sistema operatiu creu que és un teclat real.

6. Enviar tecles i combinacions

Tecla simple

Keyboard.press('a');
Keyboard.releaseAll();

Combinació (exemple: Ctrl + C)

Keyboard.press(KEY_LEFT_CTRL);

Algunes tecles útils

• KEY_ENTER
• KEY_ESC
• KEY_LEFT_CTRL
• KEY_LEFT_SHIFT
• KEY_LEFT_ALT
• KEY_F1 … KEY_F12

7. Usar botons físics (teclat real)

Un botó connectat al GPIO 0:

#define BUTTON_PIN 0

void setup() {
  pinMode(BUTTON_PIN, INPUT_PULLUP);

  USB.begin();
  Keyboard.begin();
}

void loop() {
  if (digitalRead(BUTTON_PIN) == LOW) {
    Keyboard.press('a');
    delay(100);
    Keyboard.releaseAll();
    delay(300);
  }
}

Cada cop que premis el botó → s’escriu una A.

8. Exemple de macro (ús real)

Obrir el terminal a Windows (Win + R → cmd):

Keyboard.press(KEY_LEFT_GUI);
Keyboard.press('r');
Keyboard.releaseAll();

delay(300);

Keyboard.print("cmd");
Keyboard.press(KEY_ENTER);
Keyboard.releaseAll();

9. Teclat USB + port sèrie USB

Molt útil per debug o control remot:

#include "USB.h"
#include "USBHIDKeyboard.h"

USBHIDKeyboard Keyboard;

void setup() {
  USB.begin();
  Serial.begin(115200);
  Keyboard.begin();
}

void loop() {
  if (Serial.available()) {
    char c = Serial.read();
    Keyboard.print(c);
  }
}

10. Errors habituals

❌ No apareix com a teclat

• Placa incorrecta
• Cable USB només de càrrega
• USB‑OTG no activat

❌ Es reinicia en connectar

• Falta delay() inicial
• Alimentació insuficient

❌ Tecles incorrectes

• El layout depèn del sistema operatiu (ES / EN), no de l’ESP32

11. Quan Arduino no és suficient

Per projectes avançats:

• ESP‑IDF + TinyUSB directe
• Descriptors USB manuals
• N‑Key rollover
• Teclats complexos o professionals

A nivell baix es treballa amb:

• tud_hid_report()
• callbacks HID
• definició manual d’interfícies USB