WireHID

Turn your everyday laptop into a wireless keyboard, mouse and clipboard for another PC — over an ESP32‑S3 USB dongle.

WireHID is a small USB dongle (based on an ESP32‑S3) that plugs into the computer you want to control. That computer sees a perfectly ordinary USB keyboard + mouse — no drivers, no software to install on it. From your own laptop you run the WireHID host app, arm a monitor, and your keystrokes, mouse movement and clipboard are streamed to the dongle over Bluetooth Low Energy (primary) or Wi‑Fi/TCP (fallback).

Built by Marak123 with the help of AI tooling (Claude Code — Opus 4.6 and Fable 5).

🇵🇱 Polska wersja: README.pl.md

---

Why?

I did not want to carry a keyboard around the workshop just to type on the machines I service. My laptop is always next to me, so WireHID lets it act as a portable keyboard/mouse for any host — and paste text straight from my laptop's clipboard into that host.

Features

• 🖱️ Keyboard + mouse over the air — the target PC sees a native USB HID device, no software needed on it.
• 📶 BLE‑first transport with automatic Wi‑Fi/TCP fallback (dongle runs its own SoftAP).
• 📋 Clipboard → target as a safe "typed paste" (ASCII‑first).
• 🖥️ Per‑monitor capture — input is routed only while your cursor is on the armed monitor; a full‑screen overlay makes the state obvious.
• ⌨️ Global hotkeys — Ctrl+Alt+F12 to arm/disarm, Ctrl+Shift+V to send the clipboard, Esc to bail out.
• 🛡️ Safety guards — heartbeat, session timeout and automatic release‑all‑keys so nothing gets stuck on the target.
• 🧪 Client tester — exercise the whole host pipeline on a single PC, without a dongle.
• 🔌 Optional ADB Wireless Bridge firmware mode (see the note below — work in progress).

⚠️ ADB Wireless Bridge — experimental / work in progress

What it is: ADB (Android Debug Bridge) is the standard tool for talking to Android devices from a PC — adb shell, adb push/pull, adb logcat, installing APKs, etc. Normally it needs a USB cable. The ADB Bridge mode reflashes the dongle's role so the ESP32‑S3 becomes a USB Host: you plug the Android phone into the dongle by USB, the dongle exposes a TCP tunnel over Wi‑Fi, and the host app presents a local adb connect endpoint. The goal is fully wireless adb without a cable tying you to your desk.

Status: this mode is NOT finished and is under active development. Basic connection and the USB‑to‑TCP tunnel work, but the handshake/framing is still being stabilized and it is not reliable for everyday use yet. Treat it as a preview. The default firmware image does not include it — you have to flash the separate HID+ADB image on purpose. If you only need a wireless keyboard/mouse, use the plain HID image and ignore ADB entirely.

---

Hardware

Firmware targets the ESP32‑S3 and is developed on the LilyGO T‑Dongle‑S3 (sold in various listings as "Pocket‑Dongle‑S3 0.96""):

Part	Detail
MCU	ESP32‑S3 (native USB OTG, BLE 5, Wi‑Fi)
Display	ST7735 0.96" 80×160 TFT
Storage	microSD slot (SD_MMC) — runtime logs & config.json
Button	single BOOT button (GPIO0)
USB	USB‑A male (plugs directly into the target PC)

Why ESP32‑S3: it has a native USB device controller, so it can emulate a composite HID keyboard+mouse directly, and in ADB mode it can switch the same port to USB Host. See docs/HARDWARE.md for the full pinout (LCD, microSD, BOOT).

The T‑Dongle‑S3 vendor resources live in LilyGO's own repo: https://github.com/Xinyuan-LilyGO/T-Dongle-S3.

---

Repository layout

WirelessHID/
├─ firmware/      ESP‑IDF v6.0 firmware for the ESP32‑S3 dongle (C)
├─ host-app/      Windows host app (Python + native WinAPI hook DLL) + client tester
├─ scripts/       One‑click .bat wrappers for build / flash / run
├─ docs/          Specification, roadmap, hardware pinout, ADB bridge notes
└─ README.md

Component READMEs: firmware/README.md · host-app/README.md.

---

Quick start

1. Flash the dongle

Install ESP‑IDF v6.0, then from an ESP‑IDF PowerShell:

cd firmware
.\build_firmware.ps1                 # HID image (keyboard + mouse, default)
.\flash_firmware.ps1 -Port COM5      # flash it (use your dongle's COM port)

Prefer the ADB preview instead? Use .\build_firmware_adb.ps1 + .\flash_firmware_adb.ps1. No local IDF profile? Copy IDF_Powershell_Profile.example.ps1 → IDF_Powershell_Profile.ps1 and point it at your install, or just run the scripts from an ESP‑IDF PowerShell. See firmware/README.md.

2. Run the host app (Windows)

Requires Python 3.12+ and a C toolchain (cmake + gcc + ninja/mingw32-make) to build the tiny native hook DLL.

cd host-app
pip install -r requirements.txt
python build_native.py
python run_host.py

Or grab a prebuilt WireHIDHost.exe from the Releases page — it bundles the native DLL and needs no Python/toolchain.

3. Use it

1. Plug the dongle into the PC you want to control.
2. In the host app pick your monitor and transport (auto is fine), then Connect.
3. Press Ctrl+Alt+F12 to arm. Move your cursor onto the armed monitor — a red overlay shows capture is live and your input now goes to the target.
4. Copy something on your laptop, press Ctrl+Shift+V to paste it into the target.
5. Press Ctrl+Alt+F12 (or Esc) to disarm and return control to your laptop.

No dongle yet? Run python run_client_tester.py to try the host pipeline against a local loopback target.

---

How it works

┌───────────────────────────┐   BLE (primary) / Wi‑Fi TCP (fallback)   ┌──────────────────────────────┐
│ Your laptop (host app)    │  ─────────────────────────────────────►  │ ESP32‑S3 dongle (firmware)   │
│ • WinAPI keyboard/mouse   │   WireHID line protocol (K/m/b/w/P/R)    │ • TinyUSB HID keyboard+mouse │
│   hooks (native DLL)      │                                          │ • BLE GATT (Nordic UART)     │
│ • per‑monitor overlay     │                                          │ • Wi‑Fi SoftAP + TCP server  │
│ • clipboard → typed paste │                                          │ • ST7735 status screen       │
└───────────────────────────┘                                          └──────────────┬───────────────┘
                                                                                      │ USB HID
                                                                                      ▼
                                                                          ┌─────────────────────────┐
                                                                          │ Target PC (no software) │
                                                                          └─────────────────────────┘

The host captures input with low‑level Windows hooks, encodes each event as a compact line (m,dx,dy for mouse, K,down,usage,mod for keys, …), batches them and streams them to the dongle, which replays them as USB HID reports. Details and the message table are in docs/PROTOCOL.md.

---

Documentation

Doc	What's inside
docs/HARDWARE.md	Board, pinout (LCD / microSD / BOOT), power notes
docs/PROTOCOL.md	WireHID line protocol, BLE GATT UUIDs, transports
docs/ADB_BRIDGE.md	What the ADB mode is, how to try it, current limitations
docs/MVP_SPEC.md	Original product specification
docs/ROADMAP.md	Planned work
CHANGELOG.md	Release history
CONTRIBUTING.md	How to build, test and contribute

---

Limitations

• Host app is Windows‑only (uses Win32 hooks + tray). Firmware and protocol are OS‑agnostic; a Linux/macOS host would be a nice contribution.
• Clipboard is ASCII‑first typed paste, not a true shared clipboard; non‑ASCII is transliterated.
• ESP32‑S3 supports BLE, not Bluetooth Classic SPP.
• ADB Bridge mode is experimental — see the note above.

Contributing

Issues and PRs are welcome — see CONTRIBUTING.md. This project was built with heavy use of AI pair‑programming (Claude Code, Opus 4.6 & Fable 5); that context is documented rather than hidden.

License

MIT © 2026 Marak123