esp32-hid-bridge 1.0.0

ESP32 BLE HID Bridge — Control mouse & keyboard via WiFi TCP or Bluetooth SPP through an ESP32

ESP32 HID Bridge

Control mouse & keyboard input through an ESP32 acting as a BLE HID device. Communicate with the ESP32 over WiFi TCP or Bluetooth SPP from Python.

Features

• Mouse: move, click, press/release, scroll
• Keyboard: press, release, tap, multi-key combos (shortcuts)
• Dual Mode: WiFi TCP (~1-5ms) or Bluetooth SPP (~10-50ms)
• Auto-detect: Finds ESP32 Bluetooth COM port automatically
• Context manager: Use with with statement for auto-cleanup

Installation

# WiFi only (no extra dependencies)
pip install esp32-hid-bridge

# WiFi + Bluetooth SPP support
pip install esp32-hid-bridge[bluetooth]

Quick Start

WiFi TCP Mode

from esp32_hid_bridge import ESP32Bridge

# Connect via WiFi
bridge = ESP32Bridge(host="192.168.1.100")

# Mouse
bridge.mouse_move_relative(100, 50)
bridge.mouse_click()
bridge.mouse_click("right")
bridge.mouse_scroll(3)

# Keyboard
bridge.key_tap("a")
bridge.key_multi_press(["ctrl", "c"])  # Ctrl+C

bridge.close()

Bluetooth SPP Mode

from esp32_hid_bridge import ESP32Bridge

# Connect via Bluetooth
bridge = ESP32Bridge(port="COM8")
bridge.mouse_click()
bridge.close()

Context Manager

from esp32_hid_bridge import ESP32Bridge

with ESP32Bridge(host="192.168.1.100") as bridge:
    bridge.mouse_click()
    bridge.key_tap("enter")
# Connection is closed automatically

Auto-detect Bluetooth

from esp32_hid_bridge import ESP32Bridge

# Scans all COM ports for an ESP32 with PONG response
bridge = ESP32Bridge()

Configuration via Environment Variables

# Set once, no need to pass host= every time
set ESP32_HOST=192.168.1.100
set ESP32_TCP_PORT=8266     # optional, default 8266
set ESP32_PORT=COM8          # for Bluetooth mode

bridge = ESP32Bridge()  # Reads from env vars

Save/Load Config File

from esp32_hid_bridge import ESP32Bridge
from esp32_hid_bridge.bridge import save_config, load_config

# Save host to config file
save_config("esp32_config.json", ESP32_HOST="192.168.1.100")

# Load and connect
bridge = ESP32Bridge(config_path="esp32_config.json")

API Reference

ESP32Bridge

Method	Description
mouse_move_relative(dx, dy)	Move cursor by (dx, dy) pixels
mouse_click(button="left")	Click a button (left, right, middle)
mouse_press(button="left")	Press and hold a button
mouse_release(button="left")	Release a button
mouse_scroll(wheel)	Scroll (positive=up, negative=down)
key_press(key)	Press and hold a key
key_release_all()	Release all pressed keys
key_tap(key, delay_ms=35)	Tap a key (press + delay + release)
key_multi_press(keys)	Press multiple keys then release
ping()	Ping ESP32, returns True if alive
close()	Close the connection
is_open()	Check if connected
mode	Current mode: "wifi", "bluetooth", or None

Supported Keys

All standard keys including: a-z, 0-9, enter, esc, tab, space, backspace, delete, insert, home, end, pageup, pagedown, arrow keys (up, down, left, right), f1-f12, modifiers (ctrl, shift, alt, win), and common symbols.

ESP32 Firmware

Flash the included Arduino firmware (examples/firmware/esp32_bt_hid.ino) to your ESP32. Requirements:

• Board: ESP32 Dev Module
• Partition: Huge APP (3MB)
• Library: ESP32-BLE-Combo by blackketter

Setup

1. Open esp32_bt_hid.ino in Arduino IDE
2. Change WIFI_SSID and WIFI_PASS to your WiFi credentials
3. Flash to ESP32
4. Find the IP address from Serial Monitor or your router

License

MIT