When you are standing in front of a restricted workstation, a hardened server, or an air-gapped machine, traditional software tools hit a brick wall:
| Access Vector | The Locked-Down Enterprise State | The Emittr Reality |
|---|---|---|
| 💾 USB Storage | ❌ Blocked by endpoint policy / GPO | No storage device mounted. Leaves a spotless forensic audit trail. |
| 📋 The Clipboard | ❌ Disabled, monitored, or scraped by DLP / EDR | 0 clipboard writes. Secret never touches host clipboard memory. |
| 🌐 Remote Software | ❌ Blocked by firewalls, proxies, or missing OS | 0 host software. Requires zero background .exe or agent on the target. |
| 🔌 The Network | ❌ Air-gapped, isolated, or dead NIC | Pure physical USB cable. Target host stays 100% network-isolated. |
| ⌨️ A Physical Keyboard | 🟢 Allowed. Always. Nobody blocks a keyboard. | Speaks standard USB-IF HID scancodes natively. |
"Nobody blocks a keyboard."
↓
So we taught a phone to become one:
A real USB keyboard • A five-button precision mouse
Two Xbox thumbsticks • Direct OTG & out-of-band bridge
See Emittr operating across real hardware, bootloaders, and locked-down environments:
📖 Detailed breakdown of each demonstration
- Demo 1: The Pre-Boot BIOS & Recovery Proof
- What it proves: Unlike software tools (KDE Connect, Unified Remote, TeamViewer), Emittr requires zero host OS or driver stack. It operates at the raw motherboard USB controller level, enabling headless recovery, BIOS configuration, and GRUB kernel selection.
- Demo 2: The 1,000 WPM Keystroke Cannon
- What it proves: Delivers bulk payloads and automation scripts with selectable speeds (Instant
5msdown to Human60ms), pre-flight countdown buffers, and an instant kill switch if an input buffer lags.
- What it proves: Delivers bulk payloads and automation scripts with selectable speeds (Instant
- Demo 3: Dual Xbox Thumbsticks & Hardware AC Pan
- What it proves: Instead of fake
Shift + Scrollsynthetic combos, Emittr dispatches genuine USB-IF Consumer Usage0x0238packets that Windows, macOS, and Linux natively process as standardWM_MOUSEHWHEELevents.
- What it proves: Instead of fake
Emittr adapts to your physical environment with two distinct operational architectures:
| 🖥️ Desktops & Laptops | 📺 Smart TVs & Sticks | 📱 Phones & Tablets | ⚙️ BIOS / UEFI & GRUB | 🎮 Consoles & KVMs |
|---|---|---|---|---|
| Windows, macOS, Linux, ChromeOS | Android TV, Google TV, Fire TV | Android, iPadOS, iOS (USB-C) | Pre-Boot firmware, LUKS decrypt | PS5, Xbox, Proxmox, KVM-over-IP |
| Plug & play native HID | Instant search & setup typing | Direct keyboard & trackpad | Works before OS boots | Zero software or drivers |
Paste ➔ Keystrokes. Master password. Zero clipboard.
- How it works: Hold your rooted phone in your hand as a standalone, tactile cyberdeck plugged directly into the target machine via a standard USB-OTG cable.
- Why it matters: Zero network connectivity is involved. Because it speaks native USB Boot Protocol scancodes, it works before the operating system even boots - navigate motherboard BIOS/UEFI menus, select GRUB kernels, unlock LUKS disk encryption, or recover headless servers.
- The Keystroke Cannon: Paste a 50-line PowerShell script, base64 payload, or complex credential and fire it into the machine at 1,000 WPM with sub-5ms latency.
Type from any machine. Anywhere on your Wi-Fi.
- The Missing Link Problem: Your master credentials, Bitwarden vault, and 2FA authenticator live on your personal daily driver (iPhone, Pixel, Mac) - not on the rooted lab phone plugged into the server rack or client workstation.
- How it works: Leave your rooted phone connected to the target machine via USB as a silent hardware bridge. Open
http://<phone-ip>:8088(orhttps://...) from your personal phone or laptop browser on the local Wi-Fi. - The Magic: Copy a password on your personal iPhone, tap Stream to Wire, and Emittr bridges the data across the local WebSocket and injects it straight into the target PC as physical electrical keystrokes.
- Target Machine Isolation: The target machine never touches your Wi-Fi, never mounts a network drive, and its clipboard is never modified. (Pro-tip: Because the phone is connected to your Wi-Fi to receive relay commands, keep your local Wi-Fi network private, or switch to Superpower 01 directly on the phone screen when you need 100% offline isolation).
When a network is locked down, a driver is missing, or a keyboard has failed - real hardware still works. Here are the six places software gives up:
| Mission / Scenario | The Field Challenge | How Emittr Solves It |
|---|---|---|
| 🏢 1. The Restricted Workstation | Corporate laptops lock down USB mass storage, restrict clipboard sync, and block personal webmail. | Standard hardware always works. IT policies block flash drives and unapproved software, but nobody blocks a keyboard. Type scripts, commands, or text from your phone as genuine USB keystrokes with zero host software footprint. |
| 📲 2. The Daily-Driver Relay | Your master credentials and 2FA tokens live in your personal phone's vault (Bitwarden, 1Password) - not on the rooted lab phone plugged into the PC. | Hardware bridge over local Wi-Fi. Leave the rooted phone plugged in as an air-gap bridge. Open Emittr's web deck from your personal phone over Wi-Fi, copy from your mobile vault, and stream it across the physical cable. |
| 🔬 3. Clean-Room Diagnostics | Working on quarantined, isolated, or air-gapped systems under strict forensic audit rules where mounting USB drives or installing tools is forbidden. | Zero forensic footprint. Feeds triage scripts, memory collection commands, and system queries strictly through keystrokes. No storage device is mounted, leaving a spotless audit trail. |
| 🔑 4. Zero-Trace Credentials | Typing a 64-character master password, BitLocker key, or PGP secret on a client workstation risks exposure to clipboard scrapers, EDR monitors, or browser extensions. | Host clipboard is never touched. Your secret stays safe inside your mobile device and streams straight into the target password field as raw USB scancodes. Clipboard monitors see nothing. |
| 🖥️ 5. The BIOS Navigator | A headless home server, a Raspberry Pi, or a laptop with a dead keyboard stuck in the BIOS setup, UEFI boot menu, or GRUB prompt before the OS or network stack loads. | Firmware speaks Boot Protocol. Emittr emulates standard USB Boot Protocol scancodes that motherboard firmware listens to natively. Navigate boot menus and recovery prompts with full arrow-pad controls. |
| 🧰 6. Field Tech Pocket Console | Digital signage mounted 12 feet up, or interactive kiosks sealed behind glass with only a single dangling USB maintenance cable. | Instant full-stack peripheral. Plug the phone you are already carrying into the dangling cable. Full virtual trackpad, keyboard, emergency unstick button, and dual Xbox scroll joysticks in the palm of your hand. |
Ever tried controlling a PC with those sketchy Wi-Fi mouse apps from the Play Store? You install a random .exe server on your laptop, fight Windows Firewall, deal with 200ms lag, and pray it doesn’t leak your keystrokes to a random cloud server.
Or maybe you tried a BadUSB rubber ducky, but it’s completely blind, fires once, and if your machine lags for half a second, the entire payload types into Notepad instead of PowerShell.
Emittr does things the right way: it uses your phone's USB-OTG port and kernel configfs to configure your phone as a genuine, physical Standard USB Keyboard & Precision Mouse with real-time bidirectional feedback.
| Feature | Software Wi-Fi / Bluetooth Apps | Blind USB Keystroke Sticks | Emittr v2.0.0 ⚡ |
|---|---|---|---|
| Host PC Setup | Needs client .exe / drivers |
None (blind flash drive) | Zero host install. Works on BIOS, Windows, Mac, Linux, PS5. |
| Network Dependency | Needs shared Wi-Fi / pairing | None | Pure physical USB cable. Target host stays network-isolated. |
| Interactive Control | Laggy & unreliable | ❌ Impossible (read-only script) | Real-time typing, live touchpad, shortcuts & joysticks. |
| Scrolling Engine | Clunky fake wheel ticks | ❌ None | Dual Xbox Joysticks with native hardware AC Pan horizontal scroll. |
| Modifier State Safety | ❌ Prone to stuck keys / lockup | ❌ No state recovery | Hardware zero-flush guard + auto-reconnect flush. |
| USB Mode Persistence | N/A | N/A | Active kernel watchdog permanently preserves HID gadget mode. |
| UI Aesthetics | Basic HTML / clunky | None | Sleek, responsive dark Material Design 3 cyberdeck PWA. |
Paste long shell scripts, base64 blobs, license keys, or multi-paragraph texts from your phone. Hit Type and watch your phone fire them across the USB cable faster than humanly possible.
- Granular Speed Slider: Set speeds from Instant (
5msper key) to Human (60msper key) if your target machine has an overzealous input buffer or an observant sysadmin looking over your shoulder. - Pre-Flight Countdown: 1 to 5 second delay giving you time to click into the right input box or terminal window before the keystroke storm begins.
- Progress Bar & Abort Button: Visual real-time progress with an instant kill switch.
- Smart Typographic Sanitizer: Mobile keyboards love automatically converting standard ASCII into curly quotes (
“”‘’), typographic dashes, and non-breaking spaces (\u00A0). Emittr silently normalizes these into standard ASCII quotes, hyphens, and whitespace before translation, ensuring code snippets, shell commands, and JSON payloads never choke with syntax errors on the target host. - Universal Line Ending Normalizer: Automatically normalizes CRLF (
\r\n), CR (\r), and LF (\n) into standard hardware Return keystrokes, preserving code formatting across Windows, macOS, and Linux targets.
Type using whatever virtual keyboard you love on your phone - SwiftKey, Gboard, Samsung Keyboard, or Voice-to-Text.
- Keystrokes are diffed and streamed over a sub-5ms WebSocket connection straight into the USB HID pipe.
- Dedicated Hardware Helper Buttons for keys mobile keyboards never give you: Tab ⇥, Esc, Backspace ⌫, and a 4-way physical arrow pad (▲ ◀ ▼ ▶) to navigate BIOS menus, grub bootloaders, and terminal CLI menus.
- Collapsible Strokes Feed: A sleek telemetry feed showing keystroke history that tucks neatly out of sight when you want zero distractions.
Turn your phone's glass into a high-precision, low-latency laptop touchpad.
- Fluid Glide: Sub-millisecond cursor tracking calibrated to your phone's touch digitizer with native OS pointer responsiveness.
- Two-Finger Multi-Touch Scrolling: Slide two fingers up/down for vertical scroll, or left/right for smooth horizontal panning.
- Tap-to-Click: Intuitive sub-220ms gesture recognition for instantaneous left click.
- Tactile Mouse Buttons: Dedicated Left, Middle, and Right click pads with distinct haptic feedback.
- Sensitivity Slider: Dial your cursor speed anywhere from
0.5×(sniper mode) to2.0×(dual-4K monitor zoom).
Because scrolling through 10,000 rows in Excel or massive codebases on a touchscreen shouldn't feel like dragging an anchor.
Emittr embeds two authentic Xbox-style thumbstick caps side-by-side:
- Left Stick (Vertical Scroll): Deflect Up to scroll up, deflect Down to scroll down.
- Right Stick (Horizontal Scroll): Deflect Left to scroll left, deflect Right to scroll right.
- Continuous Rate Physics: The harder you push the stick, the faster the stream of scroll ticks. Release your thumb, and it snaps back to center with crisp CSS springs, instantly halting the scroll.
- True Hardware AC Pan (Usage 0x0238): Emittr transmits native USB HID AC Pan mouse reports. Operating systems like Windows natively dispatch standard
WM_MOUSEHWHEELevents directly into VS Code, Chrome, Excel, and terminal emulators without synthetic keyboard shortcuts.
Vertical Scroll Horizontal Scroll
┌─────────────┐ ┌─────────────┐
│ ▲ │ │ │
│ ┌───────┐ │ │ ┌───────┐ │
│ │ ( · ) │ │ │◀ │ ( · ) │ ▶│
│ └───────┘ │ │ └───────┘ │
│ ▼ │ │ │
└─────────────┘ └─────────────┘
Push Up / Down Push Left / Right
Rate-Based Continuous Native AC Pan (0x0238)
Whether you’re on a 5.5-inch phone in portrait mode or an ultrawide desktop monitor, Dashboard Mode morphs to give you full control:
- On Mobile (
< 900px): Unrolls all four decks (Typer, Touchpad, Shortcuts, Live Keys) into a unified, all-in-one scrollable deck. Tapping any tab in the bottom bar smoothly glides directly to that card. - On Desktop (
≥ 900px): Expands into a dual-column battle station. Typer and Windows Shortcuts on the left; Touchpad with Xbox Joysticks and Live Keys on the right.
Hardware-level protection ensuring target host modifier states (Ctrl, Alt, Shift, GUI) stay synchronized under all field conditions:
- One-Tap Hardware Flush: A dedicated "Unstick" header button immediately transmits all-zero HID release reports across both keyboard and mouse endpoints.
- Autonomous UDC Reconnect Guard: The background controller continuously monitors the physical USB Device Controller (UDC) state, automatically injecting clean release packets the millisecond the cable is connected.
- A rooted Android phone (Magisk, KernelSU, or Android Linux chroot / Kali NetHunter).
- Kernel built with USB Gadget ConfigFS support (
CONFIG_USB_CONFIGFS=y,CONFIG_USB_CONFIGFS_F_HID=y). Almost all modern Android kernels (3.18, 4.4, 4.9, 4.14, 4.19, 5.x) have this built-in. - A standard USB OTG cable or USB-C to USB-A data cable.
Tip
Pre-Flight Kernel Check: Run this one-liner in Termux (as root) to verify compatibility instantly:
su -c "[ -d /sys/class/udc ] && echo '✅ Kernel USB Gadget Supported!' || echo '❌ Missing ConfigFS support'"Install directly using apt, which automatically resolves and installs all system dependencies:
# Download latest .deb release
wget https://github.com/mr-anjaneyam/Emittr/releases/latest/download/emittr_2.0.0_all.deb
# Install via APT
sudo apt install ./emittr_2.0.0_all.debFrom your rooted Android terminal or NetHunter chroot as root:
git clone https://github.com/mr-anjaneyam/Emittr.git
cd Emittr
bash install.shWhat the installer does automatically:
- Installs all daemon and web assets to
/opt/usb_hid_deck/. - Symlinks the
usbtypebinary to/usr/local/bin/usbtype. - Disables Android's
sys.usb.configmass-storage auto-reset triggers. - Builds
/config/usb_gadget/g1with our composite Report ID 1 (Keyboard) and Report ID 2 (AC Pan Mouse) descriptor. - Spawns the FastAPI server daemon on port
8088. - Sets up the port 80 loopback redirector so
http://emittr/(or simply typingemittr/in Chrome) works instantly.
Keep Emittr active across phone reboots by copying the boot service:
cp /opt/usb_hid_deck/02-usb-deck.sh /data/adb/service.d/02-usb-deck.sh
chmod +x /data/adb/service.d/02-usb-deck.shConnect the USB cable between your phone and the target computer.
- On your phone's browser: Simply type
emittr/(orhttp://localhost:8088). - From your laptop/tablet on Wi-Fi: Open
http://<phone-ip>:8088. - PWA Install: In Chrome/Brave on Android, tap
⋮-> "Add to Home Screen" to launch Emittr as an edge-to-edge standalone cyberdeck!
Once installed, standard global commands are linked to your PATH, meaning you can control the entire daemon and inject keystrokes from anywhere in your terminal or NetHunter chroot:
Manage the daemon, verify hardware connections, and inspect all device IP addresses instantly:
# Start the Emittr daemon, ConfigFS gadget, & port 80 redirector
emittr start
# Check runtime state, USB controller connection, and device IP addresses
emittr status
# View device IP addresses and browser URLs directly
emittr ip
# Stop the daemon and cleanly release any active hardware keys
emittr stop
# Restart the service
emittr restart
# Stream live server logs
emittr logs -f
# Emergency zero-report release flush across physical USB
emittr unstick
# Turnkey SSL / TLS management for secure Wi-Fi access & PWA clipboard
emittr ssl generate # Generate local certificate with SAN IP support
emittr ssl status # Check certificate status and validity
emittr ssl clean # Remove certificates and revert to HTTP━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EMITTR TACTICAL USB HID DECK • v2.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: ● ONLINE (PID: 14209)
USB Controller: Connected to Host PC (Active Wire)
UDC State: configured
HID Nodes: /dev/hidg0 (Report ID 1: Kbd, ID 2: Mouse)
Typing State: Idle (Ready for scancodes)
🌐 Web Deck & Network Access:
• On this phone: emittr/ or http://localhost:8088
• Wi-Fi (wlan0): http://192.168.1.108:8088
• Hotspot (ap0): http://192.168.43.1:8088
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Browsers enforce strict security boundaries: modern mobile browsers (Chrome, Safari) restrict PWA clipboard access (navigator.clipboard) and Service Worker features on remote network origins unless served over HTTPS or localhost.
Emittr includes built-in, one-command SSL certificate orchestration:
- Automated SAN Certificate Generation (
emittr ssl generate): Generates an ECDSA / RSA certificate signed directly on the device, embedding Subject Alternative Names (SAN) forlocalhost,127.0.0.1, and all detected local network IP addresses (wlan0,ap0). - Instant HTTPS Switchover: Automatically switches FastAPI into HTTPS mode on port
8443(or your configured port). - Safe Clipboard & Sensor Permissions: Unlocks mobile clipboard pasting and Web APIs across your local Wi-Fi without browser warnings or security blocks.
- Certificate Lifecycle (
emittr ssl status&emittr ssl clean): Check certificate expiry and SAN coverage at any time, or cleanly purge certificates and return to plaintext HTTP with a single command.
Inject raw scancodes or script files directly from your terminal or shell scripts:
# Fire text directly into the PC at 1,000 WPM
usbtype "sudo systemctl restart nginx"
# Inject a multi-line script file
usbtype -f /path/to/script.sh
# Slow down typing speed (e.g. 30ms per character for legacy BIOS input)
usbtype --delay 30 "Slow typing text"
# Inject special key combinations
usbtype -k win+r
usbtype -k ctrl+alt+del
usbtype -k enterEmittr operates as a true dual-sided bridge: it runs on your rooted mobile deck, and it controls any USB host in existence.
Because Emittr presents standard USB-IF HID descriptors over physical USB, target hosts require zero drivers, zero companion software, and zero configuration:
| Target Host Category | Supported Operating Systems & Devices | Peripheral Support | Field Practicality |
|---|---|---|---|
| 💻 Desktops & Laptops | Windows 10/11, macOS, Linux (Debian, Ubuntu, Arch, Fedora), ChromeOS | Keyboard, Mouse, Trackpad, AC Pan Scroll | Perfect for locked-down corporate workstations, secure labs, and everyday remote typing. |
| 📺 Smart TVs & Dongles | Android TV, Google TV, Fire TV, Apple TV (USB-C), LG webOS | Arrow Navigation, Enter, Bulk Text, Virtual Mouse | Eliminates agonizing remote control on-screen typing for passwords, Wi-Fi keys, and search queries. |
| 📱 Phones & Tablets | Android (OTG), iPadOS (USB-C / Lightning Camera Kit), iOS | Hardware Keyboard, Full Pointer / Trackpad | Stream text from your laptop straight into an iPad or secondary phone as physical keystrokes. |
| ⚙️ Pre-Boot & Firmware | Motherboard BIOS / UEFI, GRUB bootloaders, LUKS disk decryption | Boot Protocol Keyboard, 4-Way Arrow Pad | Recover headless servers, configure BIOS settings, and enter disk encryption passwords before the OS boots. |
| 🖧 Servers & KVMs | Proxmox VE, VMware ESXi, IPMI KVM-over-IP dongles, Hyper-V | Full HID Keyboard, Mouse, Emergency Release | Datacenter crash-cart utility in your pocket: plug directly into rackmount blades and server consoles. |
| 🎮 Gaming Consoles | PlayStation 4 / 5, Xbox One / Series X, Nintendo Switch (Docked) | Standard USB Keyboard, Chat Input | Fast text entry for game chat, account setup, and browser navigation on console platforms. |
Emittr runs as the host daemon on rooted Android devices and Linux single-board computers with kernel ConfigFS USB gadget support. All verified devices below have been tested against our hardware qualification suite:
| Host Device / Board | SoC / Chipset | Verified Kernel / ROM | ConfigFS UDC | HID Keyboard (ID 1) | Mouse & AC Pan (ID 2) | Pre-Boot / BIOS | Verification Level |
|---|---|---|---|---|---|---|---|
| OnePlus 7 / 7 Pro / 7T | Snapdragon 855 | NetHunter / OxygenOS 11 (Kernel 4.14) | Verified | 6-Key Rollover | 0x0238 AC Pan | Verified | Lab Tested (Full Suite) |
| Xiaomi Poco F1 | Snapdragon 845 | NetHunter / LineageOS 18.1 (Kernel 4.9) | Verified | 6-Key Rollover | 0x0238 AC Pan | Verified | Lab Tested (Full Suite) |
| Google Pixel 3 / 3a / 4 / 4a | SDM670 / 845 / 730G | NetHunter / LineageOS (Kernel 4.9-4.14) | Verified | 6-Key Rollover | 0x0238 AC Pan | Verified | Lab Tested (Full Suite) |
| OnePlus 6 / 6T | Snapdragon 845 | OxygenOS 10 / NetHunter (Kernel 4.9) | Verified | 6-Key Rollover | 0x0238 AC Pan | Verified | Lab Tested (Full Suite) |
| Samsung Galaxy S9 / S10 | Exynos 9810 / SDM845 | Custom Kernel / NetHunter (Kernel 4.9-4.14) | Verified | 6-Key Rollover | 0x0238 AC Pan | Verified | Community Tested (SELinux Permissive) |
| Raspberry Pi 4 / Zero 2 W | BCM2711 / BCM2837 | Raspberry Pi OS (dwc2, Kernel 5.x / 6.x) |
Verified | 6-Key Rollover | 0x0238 AC Pan | Verified | Lab Tested (Full Suite) |
- Lab Tested (Full Suite): Device tested in dedicated hardware environment for USB enumeration, Boot Protocol BIOS navigation, 6-Key Rollover HID keyboard injection, and dual-axis continuous mouse/pan scrolling.
- Community Tested: Confirmed functional by community contributors; may require device-specific adjustments (such as
setenforce 0for SELinux policies on stock OEM Samsung ROMs). - Universal Requirement: Any device with root access, Linux kernel ConfigFS support (
CONFIG_USB_CONFIGFS=yandCONFIG_USB_CONFIGFS_F_HID=y), and a USB OTG controller.
📱 Tested on a phone model not listed here? Submit your results via our Hardware Compatibility Form to be added to the official roster!
┌──────────────────────────────────────────────────────────────┐
│ Mobile Browser / PWA Client │
│ (Material Design 3 • Mobile-First PWA • Dual Joysticks) │
└──────────────────────────────┬───────────────────────────────┘
│ WebSocket (/ws) & REST (/api)
▼
┌──────────────────────────────────────────────────────────────┐
│ FastAPI Non-Blocking Controller │
│ (Active Watchdog • Auto-Flush Guard) │
└──────────────┬───────────────────────────────┬───────────────┘
│ Report ID 1 (9 Bytes) │ Report ID 2 (6 Bytes)
▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ /dev/hidg0 (Composite HID Gadget) │
│ │
│ [Report ID 1: Keyboard] │
│ Byte 0 : Report ID (0x01) │
│ Byte 1 : Modifiers (Ctrl, Shift, Alt, Win - 8 bits) │
│ Byte 2 : Reserved (0x00) │
│ Bytes 3-8 : Keycodes (6-Key Rollover array) │
│ │
│ [Report ID 2: Mouse with AC Pan] │
│ Byte 0 : Report ID (0x02) │
│ Byte 1 : Buttons (Bit 0: Left, Bit 1: Right, Bit 2: Middle) │
│ Byte 2 : Relative X movement (-127 to +127) │
│ Byte 3 : Relative Y movement (-127 to +127) │
│ Byte 4 : Vertical Wheel (-127 to +127) │
│ Byte 5 : Horizontal AC Pan Wheel (-127 to +127) │
└──────────────────────────────┬───────────────────────────────┘
│ Physical USB OTG Cable
▼
┌──────────────────────────────────────────────────────────────┐
│ Target Workstation (Win / Mac / Linux / PS5) │
│ Plug & Play Recognized as Standard Keyboard & Mouse │
└──────────────────────────────────────────────────────────────┘
🔍 Click to view the Raw HID Report Descriptor (Report ID 1 & 2)
// Composite Keyboard (ID 1) + Mouse with AC Pan (ID 2)
0x05, 0x01, // Usage Page (Generic Desktop Ctrls)
0x09, 0x06, // Usage (Keyboard)
0xA1, 0x01, // Collection (Application)
0x85, 0x01, // Report ID (1) - Keyboard
0x05, 0x07, // Usage Page (Kbrd/Keypad)
0x19, 0xE0, // Usage Minimum (0xE0 - LeftControl)
0x29, 0xE7, // Usage Maximum (0xE7 - Right GUI)
0x15, 0x00, // Logical Minimum (0)
0x25, 0x01, // Logical Maximum (1)
0x75, 0x01, // Report Size (1)
0x95, 0x08, // Report Count (8)
0x81, 0x02, // Input (Data,Var,Abs,NoWrap,Linear,PreferredState,NoNullPosition)
0x95, 0x01, // Report Count (1)
0x75, 0x08, // Report Size (8)
0x81, 0x03, // Input (Const,Var,Abs,NoWrap,Linear,PreferredState,NoNullPosition)
0x95, 0x06, // Report Count (6)
0x75, 0x08, // Report Size (8)
0x15, 0x00, // Logical Minimum (0)
0x25, 0x65, // Logical Maximum (101)
0x05, 0x07, // Usage Page (Kbrd/Keypad)
0x19, 0x00, // Usage Minimum (0x00)
0x29, 0x65, // Usage Maximum (0x65)
0x81, 0x00, // Input (Data,Array,Abs,NoWrap,Linear,PreferredState,NoNullPosition)
0xC0, // End Collection
0x05, 0x01, // Usage Page (Generic Desktop Ctrls)
0x09, 0x02, // Usage (Mouse)
0xA1, 0x01, // Collection (Application)
0x85, 0x02, // Report ID (2) - Mouse
0x09, 0x01, // Usage (Pointer)
0xA1, 0x00, // Collection (Physical)
0x05, 0x09, // Usage Page (Button)
0x19, 0x01, // Usage Minimum (0x01 - Button 1)
0x29, 0x05, // Usage Maximum (0x05 - Button 5)
0x15, 0x00, // Logical Minimum (0)
0x25, 0x01, // Logical Maximum (1)
0x75, 0x01, // Report Size (1)
0x95, 0x05, // Report Count (5)
0x81, 0x02, // Input (Data,Var,Abs)
0x75, 0x03, // Report Size (3)
0x95, 0x01, // Report Count (1)
0x81, 0x03, // Input (Const,Var,Abs)
0x05, 0x01, // Usage Page (Generic Desktop Ctrls)
0x09, 0x30, // Usage (X)
0x09, 0x31, // Usage (Y)
0x09, 0x38, // Usage (Wheel)
0x15, 0x81, // Logical Minimum (-127)
0x25, 0x7F, // Logical Maximum (127)
0x75, 0x08, // Report Size (8)
0x95, 0x03, // Report Count (3)
0x81, 0x06, // Input (Data,Var,Rel)
0x05, 0x0C, // Usage Page (Consumer Devices)
0x0A, 0x38, 0x02, // Usage (AC Pan - Horizontal Scroll)
0x15, 0x81, // Logical Minimum (-127)
0x25, 0x7F, // Logical Maximum (127)
0x75, 0x08, // Report Size (8)
0x95, 0x01, // Report Count (1)
0x81, 0x06, // Input (Data,Var,Rel)
0xC0, // End Collection
0xC0 // End CollectionConnecting USB gadgets between two mobile devices (such as phone-to-phone, phone-to-tablet, or phone-to-Android TV) frequently fails on default gadget configurations due to host USB power budgeting:
- The OTG Power Budget Trap: When a phone or smart TV operates in USB Host (OTG) mode, its kernel enforces strict VBUS power limits. If a connected USB gadget requests 100mA or 500mA in its configuration descriptor (
bMaxPower), the host device rejects the peripheral or pops an error: "Connected device draws too much power". - Emittr's Self-Powered Architecture: Emittr configures its ConfigFS USB descriptor with
MaxPower = 1(2mA) and self-powered attributes (bmAttributes = 0xC0/0x80). - Universal Acceptance: Because Emittr explicitly signals that the phone is self-powered by its internal battery, host devices never throttle or reject enumeration. Android phones, tablets, iPads, smart TVs, and low-power IoT hubs accept Emittr instantly as a native zero-draw hardware peripheral.
Scripting an automated deployment or hardware testing rig? Emittr ships with a standalone, blazing-fast command line interface:
# Check current gadget state and health
usbtype --status
# Send a command directly onto the host machine
usbtype "curl -sL https://example.com/install.sh | bash"
# Slow down typing speed (45ms per keystroke) for vintage terminals
usbtype --delay 45 "dmesg | grep -i usb"
# Send hotkeys and system shortcuts
usbtype --key win+r
usbtype --key ctrl+alt+t
usbtype --key ctrl+shift+esc
# Release any stuck modifiers across the board
usbtype --releaseNeed to control Emittr from Python, Node.js, Bash, or Home Assistant? The entire engine is exposed over HTTP and WebSocket on port 8088.
| Method | Endpoint | Description | Example Payload |
|---|---|---|---|
GET |
/api/status |
Current USB connection, UDC name, and version | None |
POST |
/api/release |
Emergency panic release (null flushes all keys/buttons) | {} |
POST |
/api/type |
Types a string with custom delays | {"text": "ls -la", "delay_ms": 15, "initial_delay_s": 0} |
POST |
/api/stop |
Halts any active bulk typing job immediately | {} |
POST |
/api/key |
Injects a modifier combo or named key | {"combo": "win+r"} or {"key": "enter"} |
POST |
/api/mouse |
Injects mouse movement, buttons, or scroll | {"dx": 10, "dy": -5, "wheel": 2, "wheel_h": 0} |
For sub-5ms interactive control, connect to /ws:
// Live keystroke injection
{ "action": "live_char", "char": "x" }
// Continuous mouse movement
{ "action": "mouse_move", "dx": 8, "dy": -3 }
// Click (1=Left, 2=Right, 4=Middle)
{ "action": "mouse_click", "button": 1 }
// Dual-axis scroll (wheel_v = vertical, wheel_h = AC Pan horizontal)
{ "action": "mouse_scroll", "wheel_v": 3, "wheel_h": -2 }
// Emergency release
{ "action": "release_all" }Emittr is actively evolving. Here are some of the capabilities currently tracked in our engineering pipeline:
- Hak5 DuckyScript & Macro Runner: Step-by-step automation interpreter with visual playback controls, variable delays, countdown buffers, and dry-run safety.
- Consumer Multimedia Deck: Dedicated USB HID Consumer Control (
0x0C) tiles for volume adjustment, playback controls, and mute functions. - Gyroscope Air Mouse: Free-space presentation clicker and pointer powered by mobile device accelerometer and gyroscope sensors.
- International Keyboard Maps: Scancode translation matrices for UK QWERTY, AZERTY (French), and QWERTZ (German) layouts.
- Hardware Identity & Vendor Spoofing: ConfigFS presets to match specific enterprise keyboard/mouse vendor profiles (Dell, Apple, Logitech) for strict port whitelisting.
- Application-Level Security (Phases A, B, C): Session pairing PIN, token-based API/WebSocket authorization, and localhost-only enforcement mode.
❓ Does Emittr require any software, drivers, or agents installed on the host PC?
No. Emittr functions as a genuine, hardware-level USB Human Interface Device (HID). When connected via USB OTG, host operating systems (Windows, macOS, Linux, ChromeOS, BSD, Android, gaming consoles, or motherboard BIOS/UEFI) detect the device as a standard physical keyboard and mouse. No external drivers, agent software, or network pairing are required.
❓ How does native horizontal AC Pan scrolling work across target platforms?
Emittr implements the official USB-IF Consumer Usage 0x0238 (AC Pan) directly inside the composite mouse report descriptor (Report ID 2). Unlike tools that simulate horizontal scrolling via synthetic Shift + Wheel keyboard combos, Emittr transmits true hardware pan events. Operating systems like Windows translate these natively into WM_MOUSEHWHEEL events, providing smooth horizontal navigation in VS Code, Excel, Chrome, Sublime Text, IDEs, and terminals without extra software.
❓ How does Emittr maintain persistent USB HID gadget connectivity on Android?
Android's native UsbDeviceManager routinely monitors OTG status and may revert USB gadget configurations when cables are disconnected. Emittr features an integrated background watchdog daemon that maintains gadget locks on /dev/hidg0 and automatically preserves composite keyboard and mouse endpoints across reconnects without requiring device reboots.
❓ How does the modifier failsafe prevent stuck keys?
If a physical cable is disconnected mid-transmission, host operating systems can retain the last active modifier state (such as Ctrl or Shift). Emittr addresses this through two automated layers:
- Autonomous UDC Reconnect Flush: Upon detecting a physical cable connection, the daemon instantly transmits clean zero-byte release reports before user interaction begins.
- One-Tap Unstick Button: The prominent "Unstick" control in the web deck immediately clears all modifier and button states on demand.
❓ Can Emittr be run as a standalone fullscreen app on mobile?
Yes! Emittr is built as a complete Progressive Web App (PWA). In mobile browsers such as Chrome or Brave on Android, open http://localhost:8088, tap the menu (⋮), and select "Add to Home Screen". This launches Emittr as an edge-to-edge, standalone hardware control deck with zero browser navigation bars.
🤝 Contributing & Community
Emittr is an open-source project and thrives on community feedback, device testing, and pull requests!
Distributed under the MIT License. See LICENSE for complete terms.
Designed & built for engineers, sysadmins, and anyone who believes typing passwords manually onto headless servers is a relic of the past.
