VIIPER

VIIPER 🐍

Virtual Input over IP EmulatoR

VIIPER lets developers create virtual USB input devices (like game controllers, keyboards, and mice) that can be controlled programmatically (even over a network!) (using USBIP under the hood).
These virtual devices are indistinguishable from real hardware to the operating system and applications, enabling seamless integration for testing, automation, and remote control scenarios.

• VIIPER abstracts away all USB / USBIP details.
• Device emulation happens in userspace code instead of kernel drivers, so no kernel programming is required to add new device types.
• Users need USBIP installed once (built into Linux, usbip-win2 for Windows), after that VIIPER can run without additional dependencies or system-wide installation.

VIIPER currently comes in a single flavor:

• a self-contained, (no dependencies) portable, standalone executable.
  providing a lightweight TCP based API for feeder application development.
• There will eventually be a library version (libVIIPER) that you can link against directly from your application.
  For more information, see FAQ

Beyond device emulation, VIIPER can proxy real USB devices for traffic inspection and reverse engineering.

✨🛣️ Features / Roadmap

• ✅ Virtual input device emulation over IP using USBIP
  • ✅ Xbox 360 controller emulation; see Devices › Xbox 360 Controller
  • ✅ HID Keyboard with N-key rollover and LED feedback; see Devices › Keyboard
  • ✅ HID Mouse with 5 buttons and horizontal/vertical wheel; see Devices › Mouse
  • 🔜 Xbox One / Series(?) controller emulation
  • 🔜 PS4 controller emulation
  • 🔜 ???
    🔜 Future plugin system allows for more device types (other gamepads, specialized HID)
• ✅ Automatic local attachment: automatically controls usbip client on localhost to attach devices (enabled by default)
• ✅ Proxy mode: forward real USB devices and inspect/record traffic (for reversing)
• ✅ Cross-platform: works on Linux and Windows, 0 dependencies portable binary
• ✅ Flexible logging (including raw USB packet logs)
• ✅ Multiple client libraries for easy integration; see Client Libraries
  MIT Licensed
• 🔜 libVIIPER to link against, directly incoporating VIIPER into your feeder application.

🔌 Requirements

Linux:

• Arch Linux:

  • Install: sudo pacman -S usbip
  • Docs: Arch Wiki: USBIP

• Ubuntu:

  • Install: sudo apt install linux-tools-generic
  • Docs: Ubuntu USBIP Manual

Windows:

• usbip-win2 is by far the most complete implementation of USBIP for Windows (comes with a SIGNED kernel mode driver).

🥫 Feeder application development

VIIPER currently comes in a single flavor:

• a standalone executable that exposes an API over TCP.
• There will eventually be a library version (libVIIPER) that you can link against directly from your application.
  For more information, see FAQ

🔌 API

VIIPER includes a lightweight TCP based API for device and bus management, as well as streaming device control.
It's designed to be trivial to drive from any language that can open a TCP socket and send null-byte-terminated commands.

⚠️ Most of the time, you don't need to implement that raw protocol yourself, as client libraries are available.
See Client Libraries Available.

• The TCP API uses a string-based request/response protocol terminated by null bytes (\0) for device and bus management.
  • Requests have a "path" and optional payload (sometimes JSON).
    eg. bus/{id}/add {"type": "keyboard", "idVendor": "0x6969"}\0
  • Responses are often JSON as well!
  • Errors are reported using JSON objectes similar to RFC 7807 Problem Details
    ^{The use of JSON allows for future extenability without breaking compatibility ;)}
• For controlling, or feeding, a device a long lived TCP stream is used, with a wire-protocol specific to each device type.
  After an initial "handshake" (bus/{busId}/{deviceId}\0) a device-specific binary protocol is used to send input reports and receive output reports (e.g., rumble commands).

VIIPER takes care of all USBIP protocol details, so you can focus on implementing the device logic only.
On localhost VIIPER also automatically attached the USBIP client, so you don't have to worry about USBIP details at all.

See the API documentation for details

🛠️ VIIPER development

🧰 Prerequisites

• Go 1.25 or newer
• USBIP installed
• (Optional) Make
  • Linux/macOS: Usually pre-installed
  • Windows: winget install ezwinports.make

🔄 Building from Source

git clone https://github.com/Alia5/VIIPER.git
cd VIIPER
make build

The binary will be in dist/viiper (or dist/viiper.exe on Windows).

For more build options:

make help              # Show all available targets
make test              # Run tests

🤝 Contributing

Contributions are welcome!
Please open issues or pull requests on GitHub.
See the issues page for bugs and feature requests.

❓ FAQ

What is USBIP and why does VIIPER use it?

USBIP is a protocol that allows USB devices to be shared over a network.
VIIPER uses it because it's already built into Linux and available for Windows, making virtual device emulation possible without writing custom kernel drivers yourself.

Why is this a standalone executable that I have to interface via TCP, and not a (shared-object) library in itself

• Flexibility
  • allows one to use VIIPER as a service on the same host as the USBIP-Client and use the feeder on a different, remote machine.
  • allows for software written utilizing VIIPER to not be licensed under the terms of the GPLv3
  • future versions: Users can enhance VIIPER with device plugins, sharing a common wire-protocol, which can be dynamically incorporated.
• That said, there will be a libVIIPER that you can link against, eleminating multi-process and potential firewall issues.
  Note that this will require your application to be licensed under the terms of the GPLv3 (or comptible license)

Can I use VIIPER for gaming?

Yes! VIIPER can create virtual controllers (currently only Xbox360) that appear as real hardware to games and applications. This works with Steam, native Windows games, and any other application supporting controllers.

How is VIIPER different from other controller emulators?

Most controller emulators require custom kernel drivers for each device type.
VIIPER uses USBIP to handle the USB protocol layer, allowing device emulation in userspace without kernel drivers.
This makes VIIPER portable, easier to extend, and simpler to bundle with applications.

Can I add support for other device types?

Yes! VIIPER's architecture is designed to be extensible.
Check the xbox360 device implementation as a reference for creating new device types.
In the future there will be a plugin system to load and expose device types dynamically.

What about the proxy mode?

Proxy mode sits between a USBIP client and a USBIP server (like a Linux machine sharing real USB devices).
VIIPER intercepts and logs all USB traffic passing through, without handling the devices directly.
Useful for reverse engineering USB protocols and understanding how devices communicate.

What about TCP overhead or input latency performance?

End-to-end input latency for virtual devices created with VIIPER could be typically well below 1 millisecond on a modern desktop (e.g. Windows / Ryzen 3900X test machine).
Detailed methodology and sample runs can be found in E2E Latency Benchmarks.
However, to not stress the CPU excessively, reports get batched and sent every millisecond. So the best you will achive is a 1000Hz update rate, which is more than enough and more than what most real hardware devices provide.
Note: Actual device polling rates may be lower depending on the device type and configuration.

📄 License

VIIPER - Virtual Input over IP EmulatoR

Copyright (C) 2025 Peter Repukat

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Credits / Inspiration

• REDACTED-Bus aka ViGEmBus
  (Retired, but still widely used) Windows kernel-mode driver emulating well-known USB game controllers
  Shoutout and thank you to @nefarius for paving the way and always being a super decent guy!
• Valve Software
  For creating the OG Steam Controller (2015) and Steam Input (and the way it, understandably, works...)
  that sent me down this rabbit hole in the first place
  ^{I kinda hate you guys... in good way(?) ;)}
• USBIP without VIIPER would not be possible.
  • USBIP
  • USBIP-Win2
• SDL
  For their excellent work on input device handling, reducing reversing efforts to a minimum.