PIOKMbox — USB HID Passthrough & KMBox Serial Interface

A high-performance dual-role USB HID firmware for Raspberry Pi Pico that creates a transparent USB passthrough device while providing KMBox-compatible serial control for mouse and keyboard automation.

What It Does

USB Passthrough: Connects between your mouse/keyboard and PC, transparently forwarding all input while mirroring the connected device's identity (VID/PID, manufacturer, product name).

Serial Control: Accepts KMBox-compatible commands over UART/USB to inject precise mouse movements, clicks, and keyboard input alongside your physical devices.

Advanced Features: Humanized movement injection with anti-detection capabilities, smooth velocity matching, and optional RP2350 bridge support for computer vision applications.

Key Features

• Transparent USB Passthrough: Your PC sees the original device, not the Pico
• KMBox Serial Compatibility: Works with existing KMBox scripts and tools
• Dual-Core Architecture: Dedicated cores for USB host and device operations
• Movement Humanization: Anti-detection algorithms with configurable modes
• Hardware Watchdog: Automatic recovery from USB stack failures
• Visual Status: RGB LED feedback for all operational states
• Minimal Wiring: Just 2 wires for basic operation

Hardware Requirements

Target Hardware

Primary Target: Adafruit Feather RP2040 USB Host

• Built-in USB-A host port eliminates external wiring
• USB-C device port for PC connection
• Onboard LED and WS2812 NeoPixel support
• Standard Feather pinout for expansion

Alternative Boards:

• Any RP2040 or RP2350 board with external USB host wiring
• Minimum 264KB RAM required for dual USB stacks

Basic Wiring

Adafruit Feather RP2040 USB Host (zero external wiring):

• USB-A port → Mouse/keyboard
• USB-C port → PC

Standard RP2040/RP2350 Boards (USB host connection):

• GPIO 16 → USB D+ (typically green wire)
• GPIO 17 → USB D- (typically white wire)
• 5V → VBUS (red wire)
• GND → Ground (black wire)

Optional Peripherals

Component	Pin	Purpose
WS2812 LED	GPIO 21	RGB status indicator
Button	GPIO 7 (pull-up)	Mode switching, USB reset
Debug UART TX	GPIO 0	Serial debug output
Debug UART RX	GPIO 1	Serial debug input
External UART TX	GPIO 5	KMBox command alternative
External UART RX	GPIO 6	KMBox command alternative

Note: Debug UART and external UART both operate at 115200 baud.

Power Requirements

• USB bus powered (5V)
• Typical consumption: 100-200mA
• No external power supply required

Quick Start

1. Build Firmware

git clone https://github.com/ramseymcgrath/RaspberryKMBox.git
cd RaspberryKMBox
./build.sh          # Main KMBox firmware
./build.sh bridge   # Optional: RP2350 bridge autopilot

2. Flash Firmware

• Hold BOOTSEL on your Pico while connecting USB
• Drag PIOKMbox.uf2 to the mounted RPI-RP2 drive
• Device reboots automatically

3. Connect Devices

1. Mouse/Keyboard → Pico USB host port (USB-A on Feather)
2. Pico → PC (USB-C on Feather)
3. Optional: Serial connection for KMBox commands

4. Verify Operation

• LED Status: Should show connected device state
• Mouse/Keyboard: Works normally through PC
• Serial: Connect to new COM port for KMBox commands

Using KMBox Commands

Serial Connection

• Baud Rate: 115200, 8N1
• Interface: USB CDC (appears as COM port) or external UART
• Protocol: KMBox-compatible text and binary commands

Basic Commands

km.move(100, 50)      # Move mouse relative
km.left(1)            # Press left button  
km.left(0)            # Release left button
km.click(0)           # Left click
km.wheel(5)           # Scroll up
km.lock_mx(1)         # Lock X axis

Fast Binary Protocol (Ultra-Low Latency)

# 8-byte binary packet for <50µs latency
packet = bytes([0x01, x_lo, x_hi, y_lo, y_hi, buttons, wheel, 0x00])
serial.write(packet)

KMBox Compatibility

Fully Compatible with KMBox B+, Net, Ferrum, and Macku devices:

✅ Mouse Control: Movement, all buttons, scroll wheel
✅ Axis Locking: X/Y movement and button masking
✅ Monitor Mode: Real-time button state queries
✅ Fast Binary Protocol: <50µs latency for automation
✅ Smooth Injection: Velocity matching and timing control
✅ Movement Humanization: Anti-detection with Bezier easing

Compatible Devices: Works with 95%+ of existing KMBox scripts and tools.

Performance:

• Text commands: ~1-2ms latency, 100 cmd/s
• Binary protocol: <50µs latency, 2000 cmd/s

Status Indicators

LED Feedback

• Fast blink: Device connected/active
• Slow blink: Device suspended or error
• Solid: Normal operation

NeoPixel Colors (if connected)

• Blue: Starting up
• Green: USB device only
• Orange: USB host only
• Cyan: Both USB stacks active
• Magenta: Mouse connected
• Yellow: Keyboard connected
• Pink: Mouse + keyboard connected
• Red: Error state
• Purple: Suspended

Humanization Mode Colors (button press)

• Red: OFF (no humanization)
• Yellow: LOW (minimal)
• Green: MEDIUM (default)
• Cyan: HIGH (maximum)

Controls

Button (GPIO 7)

• Short press (< 3 sec): Cycle humanization modes
• Long press (≥ 3 sec): Reset USB stacks

Movement Humanization

Built-in anti-detection system with 4 modes selectable via button:

Mode	Description	Use Case
OFF	Linear movement	Testing, maximum precision
LOW	Minimal variation	Competitive gaming
MEDIUM	Balanced (default)	General use, recommended
HIGH	Maximum stealth	Anti-detection priority

Features: Bezier easing curves, micro-jitter injection, overshoot simulation, randomized timing Security: Resists statistical analysis, velocity profiling, and ML detection Performance: <10 cycles overhead, no latency impact

Conclusion

This implementation provides full KMBox compatibility for the most commonly used features:

✅ Mouse control (movement, buttons, wheel)
✅ Axis locking and button masking
✅ Monitor mode with button queries
✅ Fast binary protocol for minimal latency
✅ Smooth injection and advanced timing

Missing features are primarily:

• Text-based keyboard commands (use binary protocol instead)
• Advanced movement patterns (recoil, auto-movement)
• Network-specific commands (not applicable)

For 95% of KMBox use cases, this is a complete replacement. make -j4 # or: ninja

### Build outputs

**Main KMBox firmware:**
- `PIOKMbox.uf2` — UF2 firmware for drag-and-drop flashing
- `PIOKMbox.elf` — ELF for debugging
- `PIOKMbox.bin`, `PIOKMbox.hex` — alternative images

**Bridge firmware:**
- `bridge/build/kmbox_bridge.uf2` — RP2350 bridge firmware

### Flashing

- Automatic (if picotool is installed): run `./build.sh`
- Manual UF2: hold BOOTSEL while plugging USB, mount RPI-RP2, copy `PIOKMbox.uf2`

Note: To target a different board, set `PICO_BOARD` via CMake cache or edit `CMakeLists.txt` (default is `adafruit_feather_rp2040_usb_host`).

## How it works

1. Core 1 runs TinyUSB host on PIO-USB to talk to your keyboard/mouse.
2. The firmware reads the HID report descriptor and caches VID/PID and strings from the attached device.
3. Core 0 exposes a TinyUSB HID device to the PC and mirrors the attached device’s identity and report behavior.
4. When VID/PID changes, the device disconnects and re-enumerates to reflect the new identity. String descriptors are mirrored when available.
5. Physical HID input and KMBox serial commands are combined so scripted actions and real input can coexist (with axis locks and timing).

Fallbacks: If no device is attached or descriptors aren’t available, defaults are used — VID:PID `0x9981:0x4001`, Manufacturer `"Hurricane"`, Product `"PIOKM Box"`, and a serial derived from the Pico’s unique ID.

## Using KMBox serial

- Capabilities: movement injection, button press/release, timed clicks, wheel, axis locks, monitor mode

### Basic Commands

```text
km.move(100, 50)      # Move mouse relative
km.left(1)            # Press left button
km.left(0)            # Release left button
km.click(0)           # Left click (button 0)
km.wheel(5)           # Scroll up
km.lock_mx(1)         # Lock X axis
km.lock_my(1)         # Lock Y axis

Monitor Mode (Polling Button States)

Monitor mode enables polling-based button state queries:

km.monitor(1)         # Enable monitoring
km.isdown_left()      # Query left button (returns 0 or 1)
km.isdown_right()     # Query right button
km.isdown_middle()    # Query middle button
km.isdown_side1()     # Query side button 1
km.isdown_side2()     # Query side button 2
km.monitor(0)         # Disable monitoring

See MONITOR_COMMANDS.md for detailed monitor mode documentation.

Fast Binary Protocol

For ultra-low latency (<100µs), use 8-byte binary packets:

# Fast mouse move (0x01 command)
packet = bytes([0x01, x_lo, x_hi, y_lo, y_hi, buttons, wheel, 0x00])
serial.write(packet)

Binary protocol bypasses text parsing for minimal latency at 2 Mbps (approx. ~40µs per 8-byte packet).

Movement Humanization

Overview

Enhanced mouse movement injection that resists statistical analysis and ML-based detection by simulating natural human input patterns. All humanization features are enabled by default and automatically adapt to movement characteristics.

Button Control (Pin 7)

Quick Press (< 3 seconds)

Cycles through humanization modes with LED color feedback:

Mode	LED Color	Description	Use Case
OFF	🔴 Red	No humanization, linear movement	Maximum precision, testing
LOW	🟡 Yellow	Minimal jitter (±0.5px), 5% overshoot	Competitive gaming
MEDIUM	🟢 Green	Balanced (±1px), 15% overshoot	Default - Recommended
HIGH	🔵 Cyan	Maximum variation (±2px), 25% overshoot	Maximum stealth

Long Press (≥ 3 seconds)

Triggers USB reset (existing functionality)

Features

Bezier Easing Curves

• Cubic Ease-In-Out: Natural acceleration/deceleration for large movements
• Quadratic Ease-Out: Quick corrections with smooth deceleration
• Automatic Selection: Chooses appropriate curve based on movement size

Micro-Jitter Injection

• Hand Tremor Simulation: ±1-2 pixels of natural variation
• Context-Aware: More jitter during mid-movement (when hand is active)
• Probabilistic: 40% chance per frame (not constant)
• Excluded from MICRO mode: Precision adjustments remain accurate

Variable Thresholds & Parameters

• Per-Session Randomization: Base parameters vary on initialization
• Per-Injection Variation: ±1 pixel variation per movement
• Frame Count Jitter: ±1 frame for movements >3 frames

Overshoot & Correction

• Realistic Patterns: 15% chance to overshoot target by 1-2 pixels
• Natural Correction: Smooth correction over 2-4 frames
• Only Large Movements: Triggered for moves >30 pixels

Security Improvements

Resistant To:

• ✅ Statistical Analysis: No fixed patterns or distributions
• ✅ Velocity Profiling: Non-linear curves with natural variation
• ✅ Tremor Detection: Includes realistic hand micro-movements
• ✅ Timing Analysis: Randomized frame counts and thresholds
• ✅ Fingerprinting: Per-session parameter randomization

Detection Risk Level: Low (requires extensive data collection + advanced ML)

KMBox Bridge - Advanced Autopilot

An optional companion autopilot firmware that runs on a separate Adafruit Feather RP2350 with color-based target tracking.

Architecture

┌─────────────┐   USB CDC    ┌──────────────────┐   PIO UART   ┌───────────────┐
│   PC Tool   │  (RGB frames) │ Feather RP2350   │  (115200)    │ KMBox Pico    │
│  (capture)  │◄────────────►│   (Tracker)      │────────────►│ (USB Host)    │
└─────────────┘               └──────────────────┘              └───────────────┘

Key Features

• USB CDC Interface: Receives RGB frame data from PC capture tool
• Color Tracking: Hardware-accelerated blob detection and centroid calculation
• PIO UART TX: Sends mouse movement commands to main KMBox at 115200 baud
• One-way Communication: Bridge → KMBox (TX only, no RX needed)

Quick Setup

1. Build: ./build.sh bridge or ./build.sh all
2. Wire: Connect RP2350 GPIO0 (TX) → KMBox RX pin, plus GND
3. Flash: Hold BOOTSEL, copy bridge/build/kmbox_bridge.uf2 to drive
4. Use: Connect via USB CDC for direct KMBox serial passthrough

Status LEDs

• Onboard LED: Heartbeat (500ms blink)
• NeoPixel: RED=idle, GREEN=tracking, YELLOW=disabled, BLUE=activity

For detailed documentation, wiring diagrams, and Python client examples, see bridge/README.md.

Status Indicators

LED Feedback

• Fast blink: Device connected/active
• Slow blink: Device suspended or error
• Solid: Normal operation

NeoPixel Colors (if connected)

• Blue: Starting up
• Green: USB device only
• Orange: USB host only
• Cyan: Both USB stacks active
• Magenta: Mouse connected
• Yellow: Keyboard connected
• Pink: Mouse + keyboard connected
• Red: Error state
• Purple: Suspended

Humanization Mode Colors (button press)

• Red: OFF (no humanization)
• Yellow: LOW (minimal)
• Green: MEDIUM (default)
• Cyan: HIGH (maximum)

Button behavior

• Short press (< 3 seconds): Cycle through humanization modes (OFF → LOW → MEDIUM → HIGH → OFF...) with visual LED feedback
• Long press (≥ 3 seconds): Reset USB stacks (with cooldown to avoid loops)

Development notes

Project layout

PIOKMbox/
├── PIOKMbox.c               # Main firmware (core orchestration)
├── usb_hid.*                # HID device/host, VID/PID & string mirroring
├── led_control.*            # LED & WS2812 control
├── watchdog.*               # HW/SW watchdog + inter-core heartbeats
├── init_state_machine.*     # Startup/initialization sequencing
├── state_management.*       # Shared system state
├── kmbox_serial_handler.*   # KMBox UART integration
├── ws2812.pio               # PIO program for NeoPixel
├── defines.h, timing_config.h, config.h
├── lib/
│   ├── Pico-PIO-USB/        # PIO USB library
│   └── kmbox-commands/      # KMBox command parser
└── CMakeLists.txt, build.sh

Configuration

• Build configuration presets (see defines.h):
  • BUILD_CONFIG_DEVELOPMENT (default)
  • BUILD_CONFIG_PRODUCTION
  • BUILD_CONFIG_TESTING
  • BUILD_CONFIG_DEBUG
• Pins, LED timings, watchdog intervals, and colors are centralized in defines.h.
• CPU clock and USB timing are tuned for PIO-USB (RP2040 default 240 MHz).

Troubleshooting

1. Ensure Pico SDK is installed and PICO_SDK_PATH is set.
2. For USB host, verify 5V power and DP/DM wiring to GPIO 16/17.
3. If passthrough seems inactive, open the debug UART (GPIO 0/1 @ 115200) for logs.
4. If re-enumeration loops occur, check that the attached device is stable; the firmware only re-enumerates when VID/PID changes.
5. Some devices present 16-bit mouse deltas; these are scaled to 8-bit—adjust sensitivity in code if needed.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Test on hardware
4. Submit a pull request

License

Libraries under lib/ retain their respective licenses. Main project files follow standard open source practices.