Skip to content

Organize backend documentation and consolidate release history #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Pav-Osmolski wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Organize backend documentation and consolidate release history #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Changelog

Historical upstream release descriptions. Current downloads are on [Releases](https://github.com/hbashton/VIIPER/releases).

## Inherited release records

The following records preserve the original release descriptions and their
limitations. They are historical context, not current setup instructions.

<a id="inherited-release-notes-v016-rc464"></a>

### release-notes-v0.1.6-rc4.6.4

Original record: `docs/release-notes-v0.1.6-rc4.6.4.md`. Instructions and validation claims apply to that release.

### VIIPER 0.1.6-rc4.6.4 — Smoother Controller Feedback

This update accompanies DS4Windows RC4.6.4 and improves the consistency and detail of supported controller feedback.

#### Improvements

- Improved conversion of advanced game haptics for DualSense and DualSense Edge over Bluetooth when used with the matching DS4Windows update.
- More consistent controller-audio delivery through brief timing variations, helping prevent interrupted haptic effects.
- Backward-compatible operation with clients that do not request the updated conversion.

#### Install or update

**DS4Windows users:** install the matching **DS4Windows RC4.6.4 all-in-one installer**, or extract its complete portable ZIP. Both include the matching VIIPER build; a separate installation is not necessary.

Close your games, exit DS4Windows, and quit VIIPER before updating. Keep **USB/IP 0.9.7.7** when using DS4Windows.

Standalone users should select the archive for their operating system and architecture from the assets below. This is a release candidate.

Thanks for using VIIPER!

<a id="inherited-release-notes-v017-rc465"></a>

### release-notes-v0.1.7-rc4.6.5

Original record: `docs/release-notes-v0.1.7-rc4.6.5.md`. Instructions and validation claims apply to that release.

### VIIPER 0.1.7-rc4.6.5 — Updates Made Simple

VIIPER updates now come with DS4Windows. There are no separate VIIPER update pop-ups or automatic downloads.

Your existing settings remain compatible. Controller support and feedback are unchanged in this update.

#### How to update

**DS4Windows users:** use the matching DS4Windows RC4.6.5 installer or complete portable ZIP. Both include VIIPER, so you do not need a separate download.

Standalone users can download the archive for their operating system below. Close VIIPER before replacing its files.

This is a release candidate. Thanks for your feedback!

<a id="inherited-release-notes-v019-rc466"></a>

### release-notes-v0.1.9-rc4.6.6

Original record: `docs/release-notes-v0.1.9-rc4.6.6.md`. Instructions and validation claims apply to that release.

### VIIPER 0.1.9-rc4.6.6 — Reliable Startup & Better Edge Support

- Improved startup and shutdown cleanup so failed or canceled attempts can be retried more reliably.
- Added clearer startup failure information for DS4Windows.
- Improved virtual DualSense Edge reports and compatibility with the shared DualSense feedback path.
- Unsupported Edge onboard-profile commands now fail clearly instead of appearing to succeed.

**DS4Windows users:** use the matching RC4.6.6 installer or complete portable ZIP. Both include the correct VIIPER, so no separate update is needed.

Standalone users can download the archive for their operating system below. Close VIIPER before replacing its files.

This is a release candidate. Virtual Edge onboard-profile editing is not supported. Thanks for your feedback!
273 changes: 31 additions & 242 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,257 +3,46 @@
# VIIPER

[![Build](https://github.com/hbashton/VIIPER/actions/workflows/snapshots.yml/badge.svg)](https://github.com/hbashton/VIIPER/actions)
[![Release](https://img.shields.io/github/v/release/hbashton/VIIPER?include_prereleases&sort=semver)](https://github.com/hbashton/VIIPER/releases)
[![License](https://img.shields.io/github/license/hbashton/VIIPER)](LICENSE.txt)

**Virtual Input over IP EmulatoR**
**Virtual Input over IP EmulatoR** — a userspace virtual USB device framework
built on USB/IP, used as the controller backend for
[hbashton/DS4Windows](https://github.com/hbashton/DS4Windows).

VIIPER is a userspace virtual USB device framework built on USBIP. This
hbashton fork is the backend used by the hbashton DS4Windows project for native
virtual controller output, including the ongoing DualSense audio, haptics, and
microphone work.
This project builds on [Alia5/VIIPER](https://github.com/Alia5/VIIPER).

This repository is forked from [Alia5/VIIPER](https://github.com/Alia5/VIIPER).
The hbashton release channel contains the protocol and USB-audio changes needed
by [hbashton/DS4Windows](https://github.com/hbashton/DS4Windows). Install links
in this README download hbashton builds.
## Use with DS4Windows

> **Windows releases from this fork are x64 only.** x86 Windows and x86
> DS4Windows builds are not compatible with VIIPER. Use 64-bit Windows and the
> x64 DS4Windows package.
Download the matching x64 package from
[DS4Windows Releases](https://github.com/hbashton/DS4Windows/releases).
The Setup EXE includes VIIPER and the pinned USB/IP driver. Portable packages
include their matching backend; extract the complete archive. Use
**Settings > Install / Repair VIIPER** if the app requests repair, and restart
Windows when setup asks. Do not independently substitute another backend or driver.

## Install for DS4Windows
Windows controller releases require Windows 10 or 11 x64. Consult DS4Windows release notes for signing status and package requirements.

The simplest and recommended path is through a VIIPER-capable DS4Windows build:
## Features

1. Download the newest VIIPER pre-release from
[hbashton/DS4Windows Releases](https://github.com/hbashton/DS4Windows/releases).
2. Open **DS4Windows > Settings**.
3. Under **VIIPER Virtual Controller Support**, click **Install / Repair VIIPER**.
4. Accept the administrator prompt and restart Windows if `usbip-win2` was installed or updated.
5. In a profile, choose an output such as **DualSense**.
- Virtual Xbox 360, Xbox One/Series, DualShock 4, DualSense/Edge and Switch 2 Pro controller paths.
- Native controller feedback, adaptive triggers, audio and microphone transport
where supported by the device, matching feeder and physical connection.
- Generic keyboard and mouse devices for feeder applications.
- TCP management and binary device streams, plus generated client libraries.

DS4Windows installs the exact bundled VIIPER build to
`%ProgramFiles%\DS4Windows\VIIPER\viiper.exe`, installs or safely replaces the
pinned USB-IP package when necessary, registers startup, and verifies the
binary hash, driver files, USB-IP ABI, and local VIIPER API before reporting
Ready. Portable DS4Windows uses this same protected backend.
VIIPER presents USB devices; DS4Windows maps and forwards physical-controller
input and feedback. Virtual emulation does not guarantee every game or hardware feature.

## Standalone Windows setup is developer-only
## Develop

The former PowerShell installer created a separate LocalAppData/HKCU owner that
could disagree with DS4Windows about VIIPER, USB-IP, startup, and reboot state.
It is therefore fail-closed by default. End users should use the signed
DS4Windows installer or its built-in **Install / Repair VIIPER** action.
See [Documentation](docs/index.md) for installation, API, device protocols,
build instructions and historical validation. [CHANGELOG.md](CHANGELOG.md)
contains release history. Standalone deployment is a developer path and must
not compete with DS4Windows-managed startup and ownership.

Developers deliberately testing VIIPER outside the managed DS4Windows contract
must download the repository, inspect the script, set
`VIIPER_DEVELOPER_STANDALONE=1`, and pass `-DeveloperStandalone`. That mode is
not a supported DS4Windows installation path.
Report backend bugs in [backend issues](https://github.com/hbashton/VIIPER/issues).
Report app UI or mapping bugs in [DS4Windows issues](https://github.com/hbashton/DS4Windows/issues).

You can also download `viiper.exe` manually from the
[latest hbashton release](https://github.com/hbashton/VIIPER/releases/latest).
VIIPER itself is portable, but virtual devices on Windows still require the
[`usbip-win2`](https://github.com/vadimgrn/usbip-win2) kernel driver.

## What the hbashton fork adds

### DS4Windows controller backends

VIIPER can expose the following virtual USB devices for DS4Windows:

- Xbox 360 controller
- DualShock 4
- DualSense
- DualSense Edge
- Nintendo Switch 2 Pro Controller

The generic VIIPER keyboard and mouse devices remain available to other feeder
applications.

### Native DualSense input

The virtual DualSense and DualSense Edge paths carry:

- Face, shoulder, system, and mute buttons
- Sticks and analog triggers
- Touchpad click and two-finger coordinates
- Gyroscope and accelerometer reports
- DualSense Edge Fn buttons and back paddles
- Battery and controller metadata used by the USB identity

### Output reports and adaptive triggers

VIIPER returns host output to DS4Windows instead of reducing every command to
generic rumble. Extended DualSense streams preserve:

- The native USB HID output report `0x02`
- Lightbar, player LED, mute LED, and rumble state
- Native-spaced left and right adaptive-trigger effect blocks
- Optional Bluetooth haptics report `0x32`
- Combined Bluetooth state, haptics, and speaker report `0x36`

This lets DS4Windows forward game-authored adaptive-trigger commands and other
DualSense output to a compatible physical controller.

### Advanced haptics and speaker audio

The virtual DualSense includes the USB Audio Class interfaces expected by games.
The hbashton fork implements USBIP isochronous packet descriptors, completion
pacing, and audio-interface state so those endpoints can carry real data.

With the matching DS4Windows bridge:

- A game can open the virtual DualSense playback endpoint.
- DualSense haptics samples are converted into the Bluetooth haptics lane.
- Speaker samples can be forwarded to the physical controller speaker over Bluetooth.
- Haptics and speaker data share the combined Bluetooth report without one path starving the other.

### Microphone input

The microphone-capable DualSense, DualSense Edge, and DualShock 4 device types
expose virtual Windows recording endpoints. The framed feeder protocol accepts
PCM microphone frames separately from controller input state, and the USBIP
ISO-IN path supplies them to Windows.

In the DS4Windows integration, microphone audio follows this path:

1. The physical Bluetooth DualSense or DualShock 4 supplies its encoded
microphone frames.
2. DS4Windows decodes and conditions the signal.
3. DS4Windows converts the PCM to the emulated controller's native format and
sends it to VIIPER.
4. VIIPER presents that PCM through the selected virtual controller's recording
endpoint.

Transport framing and microphone data are deliberately isolated from HID input
reports. This prevents audio bytes from being interpreted as controller buttons,
keyboard commands, or mouse movement.

## Architecture

```text
Physical controller
|
| HID input, audio, and feedback
v
DS4Windows feeder
|
| local framed TCP API
v
VIIPER userspace USB device
|
| USBIP
v
usbip-win2 virtual host controller
|
v
Windows, games, and audio services
```

VIIPER does not emulate a Bluetooth radio and does not make the virtual device
appear wirelessly paired. The game sees a native-style USB controller. DS4Windows
is responsible for translating and forwarding supported feedback between that
virtual USB device and the physical USB or Bluetooth controller.

## Requirements

### Windows

- Windows 10 or Windows 11 x64
- [`usbip-win2`](https://github.com/vadimgrn/usbip-win2)
- The hbashton VIIPER executable for the protocol used by your DS4Windows build
- Administrator approval for driver installation and startup registration

The current hbashton release channel prioritizes Windows x64 and DS4Windows.
The underlying VIIPER project remains cross-platform, but binaries and features
available from this fork may differ from upstream.

### Linux development

Linux uses the kernel USBIP client and `vhci-hcd` module. Package names vary by
distribution; common starting points are `linux-tools-generic` on Ubuntu and
`usbip` on Arch Linux.

## Server and API

The standalone `viiper` executable exposes a lightweight TCP API for bus and
device management. Management requests are null-terminated path/payload messages,
while active devices use persistent binary streams for low-latency input and
feedback.

Localhost feeder applications can create a bus, add a device, open its stream,
send input state, and receive output feedback. VIIPER handles USB descriptors,
USBIP requests, and device attachment.

See:

- [API overview](docs/api/overview.md)
- [DualSense protocol](docs/devices/dualsense.md)
- [DualShock 4 protocol](docs/devices/dualshock4.md)
- [Xbox 360 protocol](docs/devices/xbox360.md)
- [Switch 2 Pro protocol](docs/devices/ns2pro.md)
- [libVIIPER overview](docs/libviiper/overview.md)

## Build from source

### Prerequisites

- [Go](https://go.dev/) 1.26 or newer
- [just](https://github.com/casey/just), recommended
- USBIP support for the target operating system
- A C compiler only when building `libVIIPER`

### Build

```powershell
git clone https://github.com/hbashton/VIIPER.git
cd VIIPER
just build Release
```

The Windows executable is written to `dist/viiper-windows-amd64.exe`. Useful
development commands include:

```powershell
just test
go test ./...
go run ./cmd/viiper codegen
```

Client bindings are generated for TypeScript, C#, C++, and Rust. Run code
generation whenever a public device-state or feedback contract changes, then
build the client examples before publishing the change.

## Troubleshooting

- **DS4Windows says VIIPER is unavailable:** run **Install / Repair VIIPER** and
restart Windows if `usbip-win2` was just installed.
- **No virtual controller appears:** confirm `viiper.exe server` is running and
that the USBIP driver is installed.
- **Several stale controllers appear:** stop DS4Windows and VIIPER, start VIIPER
once, then start DS4Windows. Report repeatable lifecycle bugs with both logs.
- **DualSense audio or microphone endpoints are missing:** use matching
hbashton DS4Windows and VIIPER releases; older upstream VIIPER builds do not
contain the same extended device types.
- **Input becomes corrupted while the microphone is active:** stop the test and
report the DS4Windows log plus the VIIPER log. Microphone-capable streams must
use the framed protocol and should never pass audio transport bytes into HID state.

Report backend issues at
[hbashton/VIIPER Issues](https://github.com/hbashton/VIIPER/issues). Report
controller mapping or DS4Windows UI issues at
[hbashton/DS4Windows Issues](https://github.com/hbashton/DS4Windows/issues).

## License

The VIIPER server and core are licensed under GPL-3.0-or-later. Generated client
libraries retain their documented MIT licensing. See [`LICENSE.txt`](LICENSE.txt)
and the individual client packages for details.

## Credits

VIIPER was created by Peter Repukat and the Alia5/VIIPER contributors. This fork
builds on that architecture for DS4Windows. It also depends on the USBIP project,
`usbip-win2`, and controller/audio protocol research shared by SDL, SAxense,
DualSense reverse-engineering projects, and the wider open-source community.
The server/core are GPL-3.0-or-later; generated client libraries retain their
documented MIT licensing. See [LICENSE.txt](LICENSE.txt) and component notices.
Credits include Peter Repukat, Alia5 contributors, hbashton, USB/IP, usbip-win2,
and the controller/audio research community.
Loading