Metadata-Version: 2.4
Name: esp32-hid-bridge
Version: 1.0.0
Summary: ESP32 BLE HID Bridge — Control mouse & keyboard via WiFi TCP or Bluetooth SPP through an ESP32
Author: PhaiKub
License: MIT
Project-URL: Homepage, https://github.com/PhaiKub/esp32-hid-bridge
Project-URL: Repository, https://github.com/PhaiKub/esp32-hid-bridge
Project-URL: Issues, https://github.com/PhaiKub/esp32-hid-bridge/issues
Keywords: esp32,ble,hid,mouse,keyboard,bridge,bluetooth,wifi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: bluetooth
Requires-Dist: pyserial>=3.5; extra == "bluetooth"
Dynamic: license-file

# 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

```bash
# 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

```python
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

```python
from esp32_hid_bridge import ESP32Bridge

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

### Context Manager

```python
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

```python
from esp32_hid_bridge import ESP32Bridge

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

### Configuration via Environment Variables

```bash
# 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
```

```python
bridge = ESP32Bridge()  # Reads from env vars
```

### Save/Load Config File

```python
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](https://github.com/blackketter/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
