Skip to content

Instantly share code, notes, and snippets.

@manuelbl

manuelbl/README.md

Created August 3, 2019 09:12
Show Gist options
  • Save manuelbl/66f059effc8a7be148adb1f104666467 to your computer and use it in GitHub Desktop.
Save manuelbl/66f059effc8a7be148adb1f104666467 to your computer and use it in GitHub Desktop.
Download ZIP
ESP32 as Bluetooth Keyboard
Raw
README.md

ESP32 as Bluetooth Keyboard

With its built-in Bluetooth capabilities, the ESP32 can act as a Bluetooth keyboard. The below code is a minimal example of how to achieve it. It will generate the key strokes for a message whenever a button attached to the ESP32 is pressed.

For the example setup, a momentary button should be connected to pin 2 and to ground. Pin 2 will be configured as an input with pull-up.

In order to receive the message, add the ESP32 as a Bluetooth keyboard of your computer or mobile phone:

  1. Go to your computers/phones settings
  2. Ensure Bluetooth is turned on
  3. Scan for Bluetooth devices
  4. Connect to the device called "ESP32 Keyboard"
  5. Open an empty document in a text editor
  6. Press the button attached to the ESP32

The code has been written for the Arduino framework. I recommend using PlatformIO for development as it is far superior to the Arduino IDE while still taking full advantage of the Arduino ecosystem (libraries, support etc.)

Raw
main.cpp
/*
* Sample program for ESP32 acting as a Bluetooth keyboard
*
* Copyright (c) 2019 Manuel Bl
*
* Licensed under MIT License
* https://opensource.org/licenses/MIT
*/
//
// This program lets an ESP32 act as a keyboard connected via Bluetooth.
// When a button attached to the ESP32 is pressed, it will generate the key strokes for a message.
//
// For the setup, a momentary button should be connected to pin 2 and to ground.
// Pin 2 will be configured as an input with pull-up.
//
// In order to receive the message, add the ESP32 as a Bluetooth keyboard of your computer
// or mobile phone:
//
// 1. Go to your computers/phones settings
// 2. Ensure Bluetooth is turned on
// 3. Scan for Bluetooth devices
// 4. Connect to the device called "ESP32 Keyboard"
// 5. Open an empty document in a text editor
// 6. Press the button attached to the ESP32
#define US_KEYBOARD 1
#include <Arduino.h>
#include "BLEDevice.h"
#include "BLEHIDDevice.h"
#include "HIDTypes.h"
#include "HIDKeyboardTypes.h"
// Change the below values if desired
#define BUTTON_PIN 2
#define MESSAGE "Hello from ESP32\n"
#define DEVICE_NAME "ESP32 Keyboard"
// Forward declarations
void bluetoothTask(void*);
void typeText(const char* text);
bool isBleConnected = false;
void setup() {
Serial.begin(115200);
// configure pin for button
pinMode(BUTTON_PIN, INPUT_PULLUP);
// start Bluetooth task
xTaskCreate(bluetoothTask, "bluetooth", 20000, NULL, 5, NULL);
}
void loop() {
if (isBleConnected && digitalRead(BUTTON_PIN) == LOW) {
// button has been pressed: type message
Serial.println(MESSAGE);
typeText(MESSAGE);
}
delay(100);
}
// Message (report) sent when a key is pressed or released
struct InputReport {
uint8_t modifiers; // bitmask: CTRL = 1, SHIFT = 2, ALT = 4
uint8_t reserved; // must be 0
uint8_t pressedKeys[6]; // up to six concurrenlty pressed keys
};
// Message (report) received when an LED's state changed
struct OutputReport {
uint8_t leds; // bitmask: num lock = 1, caps lock = 2, scroll lock = 4, compose = 8, kana = 16
};
// The report map describes the HID device (a keyboard in this case) and
// the messages (reports in HID terms) sent and received.
static const uint8_t REPORT_MAP[] = {
USAGE_PAGE(1), 0x01, // Generic Desktop Controls
USAGE(1), 0x06, // Keyboard
COLLECTION(1), 0x01, // Application
REPORT_ID(1), 0x01, // Report ID (1)
USAGE_PAGE(1), 0x07, // Keyboard/Keypad
USAGE_MINIMUM(1), 0xE0, // Keyboard Left Control
USAGE_MAXIMUM(1), 0xE7, // Keyboard Right Control
LOGICAL_MINIMUM(1), 0x00, // Each bit is either 0 or 1
LOGICAL_MAXIMUM(1), 0x01,
REPORT_COUNT(1), 0x08, // 8 bits for the modifier keys
REPORT_SIZE(1), 0x01,
HIDINPUT(1), 0x02, // Data, Var, Abs
REPORT_COUNT(1), 0x01, // 1 byte (unused)
REPORT_SIZE(1), 0x08,
HIDINPUT(1), 0x01, // Const, Array, Abs
REPORT_COUNT(1), 0x06, // 6 bytes (for up to 6 concurrently pressed keys)
REPORT_SIZE(1), 0x08,
LOGICAL_MINIMUM(1), 0x00,
LOGICAL_MAXIMUM(1), 0x65, // 101 keys
USAGE_MINIMUM(1), 0x00,
USAGE_MAXIMUM(1), 0x65,
HIDINPUT(1), 0x00, // Data, Array, Abs
REPORT_COUNT(1), 0x05, // 5 bits (Num lock, Caps lock, Scroll lock, Compose, Kana)
REPORT_SIZE(1), 0x01,
USAGE_PAGE(1), 0x08, // LEDs
USAGE_MINIMUM(1), 0x01, // Num Lock
USAGE_MAXIMUM(1), 0x05, // Kana
LOGICAL_MINIMUM(1), 0x00,
LOGICAL_MAXIMUM(1), 0x01,
HIDOUTPUT(1), 0x02, // Data, Var, Abs
REPORT_COUNT(1), 0x01, // 3 bits (Padding)
REPORT_SIZE(1), 0x03,
HIDOUTPUT(1), 0x01, // Const, Array, Abs
END_COLLECTION(0) // End application collection
};
BLEHIDDevice* hid;
BLECharacteristic* input;
BLECharacteristic* output;
const InputReport NO_KEY_PRESSED = { };
/*
* Callbacks related to BLE connection
*/
class BleKeyboardCallbacks : public BLEServerCallbacks {
void onConnect(BLEServer* server) {
isBleConnected = true;
// Allow notifications for characteristics
BLE2902* cccDesc = (BLE2902*)input->getDescriptorByUUID(BLEUUID((uint16_t)0x2902));
cccDesc->setNotifications(true);
Serial.println("Client has connected");
}
void onDisconnect(BLEServer* server) {
isBleConnected = false;
// Disallow notifications for characteristics
BLE2902* cccDesc = (BLE2902*)input->getDescriptorByUUID(BLEUUID((uint16_t)0x2902));
cccDesc->setNotifications(false);
Serial.println("Client has disconnected");
}
};
/*
* Called when the client (computer, smart phone) wants to turn on or off
* the LEDs in the keyboard.
*
* bit 0 - NUM LOCK
* bit 1 - CAPS LOCK
* bit 2 - SCROLL LOCK
*/
class OutputCallbacks : public BLECharacteristicCallbacks {
void onWrite(BLECharacteristic* characteristic) {
OutputReport* report = (OutputReport*) characteristic->getData();
Serial.print("LED state: ");
Serial.print((int) report->leds);
Serial.println();
}
};
void bluetoothTask(void*) {
// initialize the device
BLEDevice::init(DEVICE_NAME);
BLEServer* server = BLEDevice::createServer();
server->setCallbacks(new BleKeyboardCallbacks());
// create an HID device
hid = new BLEHIDDevice(server);
input = hid->inputReport(1); // report ID
output = hid->outputReport(1); // report ID
output->setCallbacks(new OutputCallbacks());
// set manufacturer name
hid->manufacturer()->setValue("Maker Community");
// set USB vendor and product ID
hid->pnp(0x02, 0xe502, 0xa111, 0x0210);
// information about HID device: device is not localized, device can be connected
hid->hidInfo(0x00, 0x02);
// Security: device requires bonding
BLESecurity* security = new BLESecurity();
security->setAuthenticationMode(ESP_LE_AUTH_BOND);
// set report map
hid->reportMap((uint8_t*)REPORT_MAP, sizeof(REPORT_MAP));
hid->startServices();
// set battery level to 100%
hid->setBatteryLevel(100);
// advertise the services
BLEAdvertising* advertising = server->getAdvertising();
advertising->setAppearance(HID_KEYBOARD);
advertising->addServiceUUID(hid->hidService()->getUUID());
advertising->addServiceUUID(hid->deviceInfo()->getUUID());
advertising->addServiceUUID(hid->batteryService()->getUUID());
advertising->start();
Serial.println("BLE ready");
delay(portMAX_DELAY);
};
void typeText(const char* text) {
int len = strlen(text);
for (int i = 0; i < len; i++) {
// translate character to key combination
uint8_t val = (uint8_t)text[i];
if (val > KEYMAP_SIZE)
continue; // character not available on keyboard - skip
KEYMAP map = keymap[val];
// create input report
InputReport report = {
.modifiers = map.modifier,
.reserved = 0,
.pressedKeys = {
map.usage,
0, 0, 0, 0, 0
}
};
// send the input report
input->setValue((uint8_t*)&report, sizeof(report));
input->notify();
delay(5);
// release all keys between two characters; otherwise two identical
// consecutive characters are treated as just one key press
input->setValue((uint8_t*)&NO_KEY_PRESSED, sizeof(NO_KEY_PRESSED));
input->notify();
delay(5);
}
}
@solilu7
Copy link

solilu7 commented Aug 5, 2024

Hi,
i've a problem with some android devices with some Andorid devices (10 12 and 13 version, all chinese brand, oukitel, ulefone, hugerock)
EP32-C3 boards, i have this behavior:

I connect Esp32 board to smatphone searching a new device, it connects.
Then i switch-off and then switch-on (or simply reboot) Esp32 board, on the smatphone ESP-32 appears on "device cennected" section just for an instant, then disappears (obviusly it is not connected).
if i want reconnect i have to repeat all procedure (searching ecc).

@UsernamePlankalkul
Copy link

Hi . thanks for this Code .
is possible to send Function Keys (FN) from F13 to F24 ?

Thank you

@HubKing
Copy link

HubKing commented Mar 25, 2025

Finally. This worked. I had tested another bluetooth keyboard library, but it had connection errors to begin with, so it did not work at all. The only problem of this Gist is that, the code is too complex because it does not use any library. Isn't there a library to make things simpler? The aforementioned library's example code was very simple (but connection error made the library useless).

@Sfaxihoussem2
Copy link

Sfaxihoussem2 commented Mar 25, 2025 via email

@Marco312-aux
Copy link

Can anyone help me with this snippet?; I was working with an ESP32S3, it's recognized by my devices as a Keyboard. I used the 4 touch functions as inputs for an alternative game pad plus 6 digital buttons. In the Serial Monitor registers all keys, as sent k, s, d, w etc, but none of my devices registers a key on none of the apps. This is my code so far, any suggestion?

#include <Arduino.h>
#include <BleKeyboard.h>
#include <BLEDevice.h>
#include <BLEUtils.h>
#include <BLEServer.h>

BleKeyboard bleKeyboard("ESP32 BLE Keys v2", 100);

// Touch-capable pins for directions
#define TOUCH_UP_PIN 14
#define TOUCH_DOWN_PIN 2
#define TOUCH_LEFT_PIN 3
#define TOUCH_RIGHT_PIN 4

// Digital buttons
#define BUTTON_A_PIN 42
#define BUTTON_B_PIN 41
#define BUTTON_C_PIN 40
#define BUTTON_D_PIN 39
#define BUTTON_START_PIN 17
#define BUTTON_COIN_PIN 18

// Correct threshold for ESP32-S3
#define TOUCH_THRESHOLD 60000

void setup() {
Serial.begin(115200);
delay(1000);
Serial.println("Starting BLE Keyboard...");

bleKeyboard.begin();

// Optional advertising tweaks
BLEAdvertising *pAdvertising = BLEDevice::getAdvertising();
pAdvertising->setMinInterval(0x20);
pAdvertising->setMaxInterval(0x30);
pAdvertising->setMinPreferred(0x06);
pAdvertising->start();

// Setup digital pins
pinMode(BUTTON_A_PIN, INPUT_PULLUP);
pinMode(BUTTON_B_PIN, INPUT_PULLUP);
pinMode(BUTTON_C_PIN, INPUT_PULLUP);
pinMode(BUTTON_D_PIN, INPUT_PULLUP);
pinMode(BUTTON_START_PIN, INPUT_PULLUP);
pinMode(BUTTON_COIN_PIN, INPUT_PULLUP);

Serial.println("BLE Keyboard ready. Waiting for connection...");
}

void loop() {
if (!bleKeyboard.isConnected()) {
Serial.println("Waiting for BLE connection...");
delay(500);
return;
}

// TOUCH INPUTS
int val_up = touchRead(TOUCH_UP_PIN);
int val_down = touchRead(TOUCH_DOWN_PIN);
int val_left = touchRead(TOUCH_LEFT_PIN);
int val_right = touchRead(TOUCH_RIGHT_PIN);

Serial.print("Touch values -> UP: "); Serial.print(val_up);
Serial.print(" | DOWN: "); Serial.print(val_down);
Serial.print(" | LEFT: "); Serial.print(val_left);
Serial.print(" | RIGHT: "); Serial.println(val_right);

if (val_up > TOUCH_THRESHOLD) {
bleKeyboard.write('W'); // Up
Serial.println("Key W sent");
delay(300);
}
if (val_down > TOUCH_THRESHOLD) {
bleKeyboard.write('S'); // Down
Serial.println("Key S sent");
delay(300);
}
if (val_left > TOUCH_THRESHOLD) {
bleKeyboard.write('A'); // Left
Serial.println("Key A sent");
delay(300);
}
if (val_right > TOUCH_THRESHOLD) {
bleKeyboard.write('D'); // Right
Serial.println("Key D sent");
delay(300);
}

// DIGITAL BUTTONS
if (digitalRead(BUTTON_A_PIN) == LOW) {
bleKeyboard.write('J');
Serial.println("Button A = J sent");
delay(300);
}
if (digitalRead(BUTTON_B_PIN) == LOW) {
bleKeyboard.write('K');
Serial.println("Button B = K sent");
delay(300);
}
if (digitalRead(BUTTON_C_PIN) == LOW) {
bleKeyboard.write('L');
Serial.println("Button C = L sent");
delay(300);
}
if (digitalRead(BUTTON_D_PIN) == LOW) {
bleKeyboard.write(';'); // Or any other key
Serial.println("Button D = ; sent");
delay(300);
}
if (digitalRead(BUTTON_START_PIN) == LOW) {
bleKeyboard.write('1'); // Start
Serial.println("START = 1 sent");
delay(300);
}
if (digitalRead(BUTTON_COIN_PIN) == LOW) {
bleKeyboard.write('5'); // Coin/Insert
Serial.println("COIN = 5 sent");
delay(300);
}

delay(10);
}

@wvsbsp
Copy link

wvsbsp commented Jul 21, 2025

touchRead(TOUCH_PIN) results in Values around 100, when NOT touched.
Values get smaller when touched (value=0 when shorted to gnd).

You have to compare if below threshhold and change the thresshold to 20-30.
#define TOUCH_THRESHOLD 25
if (val_up < TOUCH_THRESHOLD)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment