ESP32 als Bluetooth-Tastatur (BLE HID): Makro-Pad mit Touch-Sensoren & Rotary Encoder bauen

Was BLE HID eigentlich bedeutet

HID steht für Human Interface Device – die Geräteklasse, unter der Betriebssysteme Tastaturen, Mäuse und Gamepads einsortieren. Das Entscheidende daran: Diese Klasse ist standardisiert und in jedem Betriebssystem seit Jahrzehnten fest eingebaut. Wenn dein ESP32 sich als HID-Tastatur meldet, muss auf der Gegenseite nichts installiert werden. Kein Treiber, keine App, keine Freigabe.

Über Bluetooth Low Energy läuft das über ein GATT-Profil namens HID over GATT (HOGP). Der ESP32 kündigt beim Pairing an: „Ich bin eine Tastatur, hier ist mein Report-Descriptor.“ Von da an schickt er nur noch kleine Datenpakete – im Kern eine Liste gedrückter Tasten plus ein Byte für die Modifier (Strg, Shift, Alt, GUI).

Das brauchst du

1Bibliothek installieren

Die Standardbibliothek für dieses Projekt heißt ESP32-BLE-Keyboard von T-vK. Sie ist nicht im Bibliotheksverwalter der Arduino IDE gelistet, die Installation läuft daher über ZIP:

1. Lade das Repository T-vK/ESP32-BLE-Keyboard als ZIP herunter.
2. Arduino IDE → Sketch → Bibliothek einbinden → .ZIP-Bibliothek hinzufügen.
3. Board auf ESP32 Dev Module stellen, Partition Scheme auf Huge APP – der BLE-Stack ist groß.

2Erster Test: Der ESP32 tippt von selbst

Dieser Sketch braucht keinerlei Peripherie. Nach dem Hochladen taucht auf deinem Handy oder Rechner ein Bluetooth-Gerät namens „MAKEROO Makropad“ auf. Koppeln, dann ein beliebiges Textfeld öffnen:

#include <BleKeyboard.h>

// Name, Hersteller, Startwert Akkustand in Prozent
BleKeyboard bleKeyboard("MAKEROO Makropad", "MAKEROO", 100);

void setup() {
  Serial.begin(115200);
  Serial.println("Starte BLE-Tastatur ...");
  bleKeyboard.begin();
}

void loop() {
  if (bleKeyboard.isConnected()) {
    Serial.println("Verbunden - tippe Testtext");

    bleKeyboard.print("Hallo von MAKEROO");
    delay(500);

    // Enter druecken und wieder loslassen
    bleKeyboard.write(KEY_RETURN);
    delay(500);

    // Kombination: Strg + A (alles markieren)
    bleKeyboard.press(KEY_LEFT_CTRL);
    bleKeyboard.press('a');
    delay(60);
    bleKeyboard.releaseAll();

    delay(5000);
  } else {
    Serial.println("Warte auf Kopplung ...");
    delay(1000);
  }
}

Drei Methoden reichen für fast alles: print() tippt Text, write() drückt und löst eine Taste sofort wieder, press() hält sie gedrückt bis zum releaseAll(). Genau diese Trennung brauchst du für Tastenkombinationen.

3Das Umlaut-Problem – und wie du es löst

Jetzt kommt der Punkt, an dem die meisten Projekte hängenbleiben. Eine HID-Tastatur sendet keine Zeichen, sondern Positionen. Der Report enthält „Taste an Position 0x1D wurde gedrückt“ – welcher Buchstabe daraus wird, entscheidet allein das Tastaturlayout des Betriebssystems.

Die Bibliothek geht von einem US-Layout aus. Steht dein Rechner auf Deutsch, ergibt das vorhersagbare Verschiebungen:

Die Tabelle lässt sich in beide Richtungen lesen – und genau das nutzt die folgende Hilfsfunktion aus. Sie übersetzt deutschen Text in die US-Tasten, die auf einem deutschen Layout die gewünschten Zeichen erzeugen:

// Tippt deutschen Text korrekt auf einem System mit DE-Tastaturlayout
void tippeDeutsch(const char* text) {
  for (const char* p = text; *p; p++) {
    char c = *p;

    switch (c) {
      // vertauschte Buchstaben
      case 'y': bleKeyboard.write('z'); break;
      case 'z': bleKeyboard.write('y'); break;
      case 'Y': bleKeyboard.write('Z'); break;
      case 'Z': bleKeyboard.write('Y'); break;

      // Umlaute liegen auf den US-Satzzeichen
      case 'a': bleKeyboard.write(';');  break;   // ae
      case 'o': bleKeyboard.write('\''); break;   // oe
      case 'u': bleKeyboard.write('[');  break;   // ue

      // Sonderzeichen
      case '-': bleKeyboard.write('/');  break;
      case '/': bleKeyboard.write('&');  break;
      case '_': bleKeyboard.write('?');  break;

      default:  bleKeyboard.write(c);   break;
    }
    delay(8);   // gibt langsamen Hosts Zeit
  }
}

4Verkabelung

Die TTP223-Module laufen mit 3,3 V und liefern am SIG-Pin ein sauberes HIGH-Signal. Der KY-040 kommt ebenfalls mit 3,3 V zurecht:

5Das Makro-Pad: Touch-Tasten mit Entprellung

Kapazitive Sensoren prellen nicht mechanisch, aber sie reagieren so schnell, dass ein einziger Fingertipp ohne Flankenerkennung dutzende Makros auslöst. Die Lösung ist immer dieselbe: nur auf den Wechsel von LOW nach HIGH reagieren und danach kurz sperren.

#include <BleKeyboard.h>

BleKeyboard bleKeyboard("MAKEROO Makropad", "MAKEROO", 100);

const uint8_t TOUCH_PINS[3] = { 4, 5, 18 };
const uint8_t ANZAHL_TASTEN = 3;
const unsigned long SPERRZEIT = 220;   // ms

bool          letzterZustand[ANZAHL_TASTEN] = { false, false, false };
unsigned long letzterWechsel[ANZAHL_TASTEN] = { 0, 0, 0 };

void makroKopieren() {
  bleKeyboard.press(KEY_LEFT_CTRL);
  bleKeyboard.press('c');
  delay(40);
  bleKeyboard.releaseAll();
}

void makroEinfuegenAlsText() {
  // Strg + Shift + V - haeufigstes Makro ueberhaupt
  bleKeyboard.press(KEY_LEFT_CTRL);
  bleKeyboard.press(KEY_LEFT_SHIFT);
  bleKeyboard.press('v');
  delay(40);
  bleKeyboard.releaseAll();
}

void makroFensterWechseln() {
  bleKeyboard.press(KEY_LEFT_ALT);
  bleKeyboard.press(KEY_TAB);
  delay(40);
  bleKeyboard.releaseAll();
}

void setup() {
  Serial.begin(115200);
  for (uint8_t i = 0; i < ANZAHL_TASTEN; i++) {
    pinMode(TOUCH_PINS[i], INPUT);
  }
  bleKeyboard.begin();
  Serial.println("Makropad bereit");
}

void loop() {
  if (!bleKeyboard.isConnected()) {
    delay(50);
    return;
  }

  unsigned long jetzt = millis();

  for (uint8_t i = 0; i < ANZAHL_TASTEN; i++) {
    bool aktuell = digitalRead(TOUCH_PINS[i]) == HIGH;

    // nur steigende Flanke, und nur nach Ablauf der Sperrzeit
    if (aktuell && !letzterZustand[i] &&
        jetzt - letzterWechsel[i] > SPERRZEIT) {

      letzterWechsel[i] = jetzt;
      Serial.printf("Taste %u ausgeloest\n", i + 1);

      switch (i) {
        case 0: makroKopieren();          break;
        case 1: makroEinfuegenAlsText();  break;
        case 2: makroFensterWechseln();   break;
      }
    }
    letzterZustand[i] = aktuell;
  }

  delay(5);
}

6Rotary Encoder als Lautstärkeregler

Media-Tasten sind ein eigener Teil des HID-Standards – der Consumer Control-Report. Die Bibliothek bringt sie als Konstanten mit, sodass Lautstärke, Play/Pause und Titelsprung ohne Umwege funktionieren. Der Encoder wird per Interrupt ausgewertet, damit keine Rastung verlorengeht:

#define ENC_CLK 32
#define ENC_DT  33
#define ENC_SW  25

volatile int8_t  encoderDelta = 0;
volatile uint8_t letzterAB    = 0;

// Zustandstabelle fuer die Quadraturauswertung
const int8_t QUAD_TABELLE[16] = {
   0, -1,  1,  0,
   1,  0,  0, -1,
  -1,  0,  0,  1,
   0,  1, -1,  0
};

void IRAM_ATTR encoderISR() {
  uint8_t ab = (digitalRead(ENC_CLK) << 1) | digitalRead(ENC_DT);
  letzterAB = ((letzterAB << 2) | ab) & 0x0F;
  encoderDelta += QUAD_TABELLE[letzterAB];
}

void encoderInit() {
  pinMode(ENC_CLK, INPUT_PULLUP);
  pinMode(ENC_DT,  INPUT_PULLUP);
  pinMode(ENC_SW,  INPUT_PULLUP);

  attachInterrupt(digitalPinToInterrupt(ENC_CLK), encoderISR, CHANGE);
  attachInterrupt(digitalPinToInterrupt(ENC_DT),  encoderISR, CHANGE);
}

void encoderAuswerten() {
  noInterrupts();
  int8_t delta = encoderDelta;
  encoderDelta = 0;
  interrupts();

  // vier Flanken ergeben eine Rastung
  while (delta >= 4) {
    bleKeyboard.write(KEY_MEDIA_VOLUME_UP);
    delta -= 4;
  }
  while (delta <= -4) {
    bleKeyboard.write(KEY_MEDIA_VOLUME_DOWN);
    delta += 4;
  }
}

unsigned long letzterKlick = 0;

void encoderTasteAuswerten() {
  if (digitalRead(ENC_SW) == LOW && millis() - letzterKlick > 300) {
    letzterKlick = millis();
    bleKeyboard.write(KEY_MEDIA_MUTE);
    Serial.println("Mute");
  }
}

Weitere nützliche Media-Konstanten: KEY_MEDIA_PLAY_PAUSE, KEY_MEDIA_NEXT_TRACK, KEY_MEDIA_PREVIOUS_TRACK und KEY_MEDIA_WWW_SEARCH. Wer die Encoder-Grundlagen vertiefen will, findet sie im Artikel zum Rotary Encoder KY-040.

7Layer und OLED-Anzeige

Drei Tasten sind wenig. Mit Layern werden daraus beliebig viele: Die dritte Touchfläche schaltet nicht ein Makro, sondern die Bedeutung der ersten beiden um. Das OLED zeigt jederzeit, wo du gerade bist:

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

Adafruit_SSD1306 oled(128, 64, &Wire, -1);

const char* LAYER_NAMEN[3] = { "TEXT", "MEDIA", "MEETING" };
const char* LAYER_TASTE1[3] = { "Kopieren", "Play/Pause", "Mikro stumm" };
const char* LAYER_TASTE2[3] = { "Einfuegen", "Naechster", "Kamera an/aus" };

uint8_t aktiverLayer = 0;

void zeichneOled(bool verbunden, uint8_t akkuProzent) {
  oled.clearDisplay();
  oled.setTextColor(SSD1306_WHITE);

  // Kopfzeile
  oled.setTextSize(1);
  oled.setCursor(0, 0);
  oled.print(verbunden ? F("BLE verbunden") : F("warte auf Host"));
  oled.setCursor(96, 0);
  oled.printf("%3u%%", akkuProzent);
  oled.drawFastHLine(0, 10, 128, SSD1306_WHITE);

  // Layername gross
  oled.setTextSize(2);
  oled.setCursor(0, 16);
  oled.println(LAYER_NAMEN[aktiverLayer]);

  // Belegung
  oled.setTextSize(1);
  oled.setCursor(0, 40);
  oled.print(F("1: "));
  oled.println(LAYER_TASTE1[aktiverLayer]);
  oled.setCursor(0, 52);
  oled.print(F("2: "));
  oled.println(LAYER_TASTE2[aktiverLayer]);

  oled.display();
}

void layerWeiter() {
  aktiverLayer = (aktiverLayer + 1) % 3;
  Serial.printf("Layer: %s\n", LAYER_NAMEN[aktiverLayer]);
}

void fuehreMakroAus(uint8_t taste) {
  if (aktiverLayer == 0) {                 // TEXT
    bleKeyboard.press(KEY_LEFT_CTRL);
    bleKeyboard.press(taste == 0 ? 'c' : 'v');
    delay(40);
    bleKeyboard.releaseAll();
  }
  else if (aktiverLayer == 1) {            // MEDIA
    bleKeyboard.write(taste == 0 ? KEY_MEDIA_PLAY_PAUSE
                                 : KEY_MEDIA_NEXT_TRACK);
  }
  else {                                   // MEETING
    // Zoom / Teams unter Windows
    bleKeyboard.press(KEY_LEFT_CTRL);
    bleKeyboard.press(KEY_LEFT_SHIFT);
    bleKeyboard.press(taste == 0 ? 'm' : 'o');
    delay(40);
    bleKeyboard.releaseAll();
  }
}

8Akkubetrieb, Batteriestand und Deep Sleep

Ein Makro-Pad am USB-Kabel ist halb so schön. Mit einer 18650-Zelle und einem TP4056-Modul wird es mobil. BLE-HID meldet den Ladestand sogar an das Betriebssystem – unter Windows und macOS siehst du ihn direkt in den Bluetooth-Einstellungen.

Der Akku liefert bis 4,2 V, der ADC des ESP32 verträgt maximal 3,3 V. Ein Spannungsteiler aus zwei gleichen Widerständen (zum Beispiel 100 kΩ) halbiert die Spannung:

#define AKKU_PIN 34            // ADC1, funktioniert auch mit aktivem WLAN/BLE
#define AKKU_LEER  3300        // mV, entspricht 0 %
#define AKKU_VOLL  4200        // mV, entspricht 100 %

uint32_t leseAkkuMillivolt() {
  uint32_t summe = 0;
  for (uint8_t i = 0; i < 16; i++) {
    summe += analogReadMilliVolts(AKKU_PIN);   // kalibrierte Messung
    delay(2);
  }
  return (summe / 16) * 2;     // mal 2 wegen Spannungsteiler
}

uint8_t akkuProzent() {
  int32_t mv = leseAkkuMillivolt();
  int32_t p  = (mv - AKKU_LEER) * 100 / (AKKU_VOLL - AKKU_LEER);
  return constrain(p, 0, 100);
}

// alle 60 Sekunden an den Host melden
unsigned long letzteAkkuMeldung = 0;

void akkuMelden() {
  if (millis() - letzteAkkuMeldung < 60000UL) return;
  letzteAkkuMeldung = millis();

  uint8_t p = akkuProzent();
  bleKeyboard.setBatteryLevel(p);
  Serial.printf("Akku: %u %% (%lu mV)\n", p, leseAkkuMillivolt());
}

Damit die Zelle Wochen statt Tage hält, schickst du den ESP32 nach einigen Minuten Untätigkeit schlafen. Aufwecken lässt er sich über jeden Touch-Sensor:

#define INAKTIV_TIMEOUT 300000UL    // 5 Minuten

unsigned long letzteAktion = 0;

void pruefeSchlaf() {
  if (millis() - letzteAktion < INAKTIV_TIMEOUT) return;

  Serial.println(F("Gehe schlafen - Touch weckt wieder auf"));
  oled.clearDisplay();
  oled.display();
  oled.ssd1306_command(SSD1306_DISPLAYOFF);

  // GPIO4, GPIO5 und GPIO18 als Weckquelle (HIGH = beruehrt)
  esp_sleep_enable_ext1_wakeup(
      (1ULL << 4) | (1ULL << 5) | (1ULL << 18),
      ESP_EXT1_WAKEUP_ANY_HIGH);

  delay(100);
  esp_deep_sleep_start();
}

// In jeder erkannten Tastenaktion aufrufen:
//   letzteAktion = millis();

Praxistipps aus dem Alltag

• Gerätename eindeutig wählen. Hast du mehrere ESP32-Projekte gekoppelt, wird „ESP32“ schnell unübersichtlich. Der Name lässt sich nur beim begin() setzen, nicht später ändern.
• Alte Kopplung löschen. Änderst du den Namen, hat der Host noch die alte Bindung gespeichert und verbindet sich nicht. In den Bluetooth-Einstellungen das Gerät entfernen, dann neu koppeln.
• Nicht mit WLAN kombinieren, wenn es vermeidbar ist. BLE und WLAN teilen sich auf dem WROOM32 eine Antenne. Beides gleichzeitig funktioniert, kostet aber Reaktionszeit und Strom.
• Touchflächen hinter Acryl. Der TTP223 arbeitet durch dünnes Material hindurch. Klebst du ihn von innen an ein Acrylgehäuse, bekommst du ein völlig geschlossenes Pad ohne sichtbare Bauteile.
• Lötpads auf dem TTP223 beachten. Über die Brücken A und B stellst du zwischen Momentkontakt, Umschalter und invertiertem Ausgang um. Für ein Makro-Pad willst du den Werkszustand: HIGH, solange berührt.

Troubleshooting