USB Keyboard And Mouse Bluetooth Adapter (ESP32)

Overview

This project transforms an ESP32 into a Bluetooth adapter that enables wireless connectivity for USB keyboards and mice. It acts as a bridge between traditional USB input devices and Bluetooth-enabled devices, effectively converting your wired peripherals into wireless ones.

Hardware Requirements

🎯 Quick Setup Guide

📱 ESP32-S3-USB-OTG     →  Ready to use!
        OR
🔧 Other ESP32 Board    →  Need USB Host Module

🚨 Important Requirements

Your ESP32 must have USB Host support. Choose your setup:

Option 1: Recommended ⭐

┌──────────────────────┐
│  ESP32-S3-USB-OTG   │
│  ✅ Built-in USB    │
│  ⚡ Full Speed      │
│  📊 12 Mbps        │
└──────────────────────┘

Option 2: Alternative 🔄

┌──────────────────────┐
│    Other ESP32       │──➤  USB Host Module
│  🔌 External USB    │         Required
│  ⚠️ Check Support   │
└──────────────────────┘

💡 Hardware Understanding

• 🎮 Built-in Support: ESP32-S3-USB-OTG has native USB host capabilities
• 🔌 Module Option: Other ESP32s need external USB host module
• ⚡ Speed: Full-speed USB (12 Mbps)
• 📚 Documentation: Official ESP32-S3-USB-OTG Guide

Features

• Supports both USB keyboards and mice simultaneously
• PS/2 trackpad support (works alongside USB devices)
• Bluetooth Low Energy (BLE) connectivity
• Plug-and-play functionality
• Low latency input processing
• Compatible with multiple operating systems (Windows, macOS, Linux, iOS, Android)
• Battery-powered operation possible (with appropriate power supply)

Hardware Requirements

Essential Components

• ESP32-WROOM-32 development board
• USB keyboard (USB HID compliant)
• USB mouse (USB HID compliant)
• Female USB-A ports or breakout boards (for connecting peripherals)
• Jumper wires
• Breadboard (for prototyping)
• 5V power supply

Optional Components

• PS/2 trackpad (any standard PS/2 mouse/trackpad)
• Bi-directional 5V ↔ 3.3V level-shifter module (required for PS/2 trackpad — see wiring section)
• 3D printed case (design files available)
• LiPo battery (for portable use)
• Battery charging module

Software Requirements

Development Environment

• Arduino IDE (2.0 or later recommended)
• ESP32 board support package
• Required Libraries:
  • ESP32-BLE-Keyboard
  • ESP32-BLE-Mouse
  • ESP32-USB-Soft-Host

Dependencies Installation

1. Add ESP32 board manager URL in Arduino IDE preferences:

   https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   

2. Install ESP32 board package via Board Manager
3. Install required libraries through Library Manager

Pin Configuration

USB Port 1 (Keyboard)

• D+ (Data+): GPIO 16 (RX2)
• D- (Data-): GPIO 17 (TX2)
• VCC: 5V (VIN or 5V pin)
• GND: Ground (Any GND pin)

USB Port 2 (Mouse)

• D+ (Data+): GPIO 22 (GPIO22)
• D- (Data-): GPIO 23 (GPIO23)
• VCC: 5V (VIN or 5V pin)
• GND: Ground (Any GND pin)

ESP32 Board Pin Reference

Function	GPIO Pin	Board Label	Notes
Keyboard D+	GPIO 16	RX2	Also labeled as U2RXD
Keyboard D-	GPIO 17	TX2	Also labeled as U2TXD
Mouse D+	GPIO 22	GPIO22	General purpose IO pin
Mouse D-	GPIO 23	GPIO23	General purpose IO pin

Note: The pins used for USB communication (GPIO 16, 17, 22, 23) are multiplexed pins that can serve different functions on the ESP32. In this project, we're using them for USB communication, so they won't be available for their alternative functions while the adapter is operating.

---

PS/2 Trackpad

💡 Inspired by this Hackaday project that turns a PS/2 keyboard into a wireless Bluetooth keyboard.

The firmware includes built-in support for a PS/2 trackpad (or any standard PS/2 mouse). When connected, it transmits movement and button events as BLE HID mouse reports — seamlessly alongside any connected USB devices.

PS/2 Pin Configuration

Function	ESP32 GPIO	PS/2 Mini-DIN Pin	Notes
PS2 Clock	GPIO 32	Pin 5	Via level shifter (5V ↔ 3.3V)
PS2 Data	GPIO 33	Pin 1	Via level shifter (5V ↔ 3.3V)
VCC	—	Pin 4	5V (from VIN / external 5V supply)
GND	GND	Pin 3	Common ground

PS/2 Mini-DIN 6-pin connector pinout (looking into the female socket):

 ┌───────────────┐
 │  6   5   4    │
 │    3   2   1  │
 └───────────────┘
  Pin 1: Data
  Pin 2: Reserved (NC)
  Pin 3: GND
  Pin 4: VCC (+5 V)
  Pin 5: Clock
  Pin 6: Reserved (NC)

⚠️ Voltage Warning — Level Shifting Required

PS/2 operates at 5 V logic levels. The ESP32 is a 3.3 V device. Connecting PS/2 Clock or Data directly to an ESP32 GPIO will damage the ESP32. You must use a bi-directional level-shifter module between the trackpad and the ESP32.

Typical wiring with a 4-channel level shifter (e.g. BSS138-based module):

PS/2 Trackpad          Level Shifter        ESP32
─────────────          ─────────────        ──────
Clock (5V)  ────────►  HV1  ◄──► LV1  ────►  GPIO 32
Data  (5V)  ────────►  HV2  ◄──► LV2  ────►  GPIO 33
VCC   (5V)  ────────►  HV               
GND         ────────►  GND  ─────GND   ────►  GND
                              LV        ────►  3.3 V

Changing the Default GPIO Pins

The default PS/2 pins are GPIO 32 (clock) and GPIO 33 (data). To use different pins, edit the constants in src/PS2Trackpad.h:

#define PS2_CLK_PIN  32   // change to your preferred clock GPIO
#define PS2_DATA_PIN 33   // change to your preferred data GPIO

Or pass them directly when constructing the object in ESP32-USB-TO-BLE.ino:

PS2Trackpad ps2Trackpad(bleDevice, /*clkPin=*/26, /*dataPin=*/27);

How It Works

1. On power-up the firmware sends a PS/2 Reset command (0xFF) to the trackpad.
2. If the trackpad responds with the self-test success code (0xAA), the firmware sends an Enable Data Reporting command (0xF4).
3. The trackpad then streams 3-byte packets on every movement or button event.
4. Each packet is decoded (signed X/Y deltas + button states) and forwarded as a BLE HID mouse report.
5. If no trackpad is detected the firmware continues normally — USB devices are unaffected.

---

Setup Instructions

1. Hardware Assembly

   • Connect USB ports according to the pin configuration
   • Ensure proper power supply connection
   • Double-check all connections before powering on

2. Software Installation

   • Follow the Development Setup instructions below
   • Flash the firmware to ESP32
   • Monitor serial output for debugging

3. Pairing Process

   • Power on the adapter
   • Search for Bluetooth devices on your target device
   • Connect to "ESP32 Keyboard" and "ESP32 Mouse"
   • Test input devices

Development Setup with VSCode

1. Install Visual Studio Code
2. Clone this repository
3. Open the ESP32-USB-TO-BLE.code-workspace file in VSCode
4. Install recommended extensions:
   • PlatformIO IDE
   • C/C++ Extension Pack
   • CMake Tools
   • Git Graph
   • GitLens
   • Serial Monitor
5. Click "Install All" when prompted
6. Wait for PlatformIO to download dependencies
7. Use PlatformIO toolbar for:
   • Building (✓)
   • Uploading (→)
   • Serial monitoring (🔌)

Troubleshooting

Common Issues

1. Device Not Connecting

   • Ensure ESP32 is powered properly
   • Check if device is in pairing mode
   • Verify USB connections

2. Input Lag

   • Reduce distance from adapter
   • Check for interference sources
   • Verify power supply stability

3. Device Not Recognized

   • Confirm USB device compatibility
   • Check physical connections
   • Verify serial monitor output

For additional issues, please open a GitHub issue with:

• Detailed problem description
• Hardware configuration
• Serial monitor output
• Steps to reproduce

Contributing

We welcome contributions! To contribute:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to your branch
5. Open a Pull Request

Please follow our coding standards and include appropriate documentation.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Credits

This project builds upon the excellent work of:

• T-vK for the ESP32-BLE-Keyboard and ESP32-BLE-Mouse libraries
• tobozo for the ESP32-USB-Soft-Host library
• Hackaday for the inspiration to add PS/2 trackpad support

Support

For support:

• Open a GitHub issue
• Join our Discord community
• Check the Wiki for additional documentation

Future Plans

• Add multi-device support
• Implement custom key mapping
• Develop mobile configuration app
• Add macro support