From 7387afd6f2190e0238dca925bb7f8aaf3c2f8e1c Mon Sep 17 00:00:00 2001 From: Pawel Osmolski Date: Mon, 12 Oct 2026 12:14:35 +0100 Subject: [PATCH] Organize backend documentation and consolidate release history --- CHANGELOG.md | 73 +++++ README.md | 273 ++---------------- docs/api/overview.md | 88 +++--- docs/api/xboxone-exact-removal.md | 173 ----------- ...d-transport-direction-review-2026-09-02.md | 3 + .../controller-platform-audit-2026-08-29.md | 3 + ...ntroller-platform-checkpoint-2026-09-06.md | 3 + ...r-platform-provenance-ledger-2026-08-29.md | 3 + ...ntroller-platform-validation-2026-08-29.md | 3 + ...ntroller-platform-validation-2026-08-30.md | 3 + ...ntroller-platform-validation-2026-08-31.md | 3 + ...ntroller-platform-validation-2026-09-01.md | 3 + ...ntroller-platform-validation-2026-09-02.md | 5 +- ...ntroller-platform-validation-2026-09-03.md | 3 + ...ntroller-platform-validation-2026-09-04.md | 4 +- ...-primary-identity-retirement-2026-09-06.md | 3 + ...resentation-decision-package-2026-08-29.md | 3 + ...andidate-release-preparation-2026-09-08.md | 3 + ...iper-tray-startup-validation-2026-09-08.md | 3 + ...ical-downstream-packet-batch-2026-08-31.md | 3 + ...horized-retained-composition-2026-08-31.md | 3 + ...-one-dormant-duplex-boundary-2026-08-30.md | 3 + ...rmant-external-identity-gate-2026-08-31.md | 3 + ...interrupt-out-packet-adapter-2026-08-31.md | 3 + ...dormant-receive-framing-gate-2026-08-31.md | 3 + ...ormant-retained-ep0-capacity-2026-08-31.md | 3 + ...xbox-one-usbip-adapter-audit-2026-08-29.md | 3 + docs/cli/codegen.md | 8 +- docs/cli/configuration.md | 18 +- docs/cli/overview.md | 12 +- docs/cli/server.md | 34 ++- docs/clients/cpp.md | 12 +- docs/clients/csharp.md | 8 +- docs/clients/go.md | 24 +- docs/clients/rust.md | 16 +- docs/clients/typescript.md | 10 +- docs/development.md | 41 +++ docs/devices/overview.md | 18 ++ docs/getting-started/installation.md | 266 ++++------------- docs/getting-started/quickstart.md | 30 +- docs/getting-started/usbip.md | 30 +- docs/index.md | 192 +++--------- docs/libviiper/overview.md | 16 +- docs/misc/support.md | 33 +-- docs/mkdocs-readme.md | 61 ++-- docs/reference.md | 47 +++ docs/release-notes-v0.1.6-rc4.6.4.md | 19 -- docs/release-notes-v0.1.7-rc4.6.5.md | 13 - docs/release-notes-v0.1.9-rc4.6.6.md | 12 - mkdocs.yml | 18 +- 50 files changed, 590 insertions(+), 1027 deletions(-) create mode 100644 CHANGELOG.md delete mode 100644 docs/api/xboxone-exact-removal.md create mode 100644 docs/development.md create mode 100644 docs/devices/overview.md create mode 100644 docs/reference.md delete mode 100644 docs/release-notes-v0.1.6-rc4.6.4.md delete mode 100644 docs/release-notes-v0.1.7-rc4.6.5.md delete mode 100644 docs/release-notes-v0.1.9-rc4.6.6.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..b384514e --- /dev/null +++ b/CHANGELOG.md @@ -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. + + + +### 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! + + + +### 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! + + + +### 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! diff --git a/README.md b/README.md index a8e04454..daff2a4f 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/api/overview.md b/docs/api/overview.md index ff23a435..0751a48a 100644 --- a/docs/api/overview.md +++ b/docs/api/overview.md @@ -53,11 +53,11 @@ })(); -VIIPER provides a lightweight TCP API for managing and controlling virtual buses/devices. +VIIPER provides a lightweight TCP API for managing and controlling virtual buses/devices.\ It's designed to be trivial to drive from any language that can open a TCP socket and send null-byte-terminated payloads. !!! tip "Client Libraries Available" - Client libraries are available that abstract away any protocol details described below. + Client libraries are available that abstract away any protocol details described below.\ For most use cases, you should use one of the provided client libraries rather than implementing the raw protocol yourself: - [Go Client](../clients/go.md): Reference implementation included in the repository @@ -67,13 +67,13 @@ It's designed to be trivial to drive from any language that can open a TCP socke - [TypeScript Client Library](../clients/typescript.md): Generated Node.js library with EventEmitter streams - [Rust Client Library](../clients/rust.md): Generated Rust library with sync/async support - + The documentation below is provided for reference and for implementing clients in languages not supported officially. ## Protocol overview -The TCP API is inspired by the ubiquitous HTTP REST style, but is more lightweight. -If you ever worked with HTTP APIs before, you'll feel right at home. +The TCP API is inspired by the ubiquitous HTTP REST style, but is more lightweight.\ +If you ever worked with HTTP APIs before, you'll feel right at home.\ The exception to this are the device-control and feedback streams, which are raw binary streams specific to each device type. - **Transport**: TCP with optional encryption (ChaCha20-Poly1305) @@ -81,9 +81,9 @@ The exception to this are the device-control and feedback streams, which are raw - **Authentication**: Required for remote connections, optional for localhost (password-based with HMAC validation) - **Encryption**: Automatic for authenticated connections (ChaCha20-Poly1305 with unique session keys) - **Request format**: a single ASCII/UTF‑8 line terminated by `\0` -- **Routing**: path followed by optional payload separated by whitespace +- **Routing**: path followed by optional payload separated by whitespace\ (e.g., `bus/list\0` or `bus/create 5\0`) -- **Payload**: optional string that can be a JSON object, numeric value, or plain string depending on the endpoint. +- **Payload**: optional string that can be a JSON object, numeric value, or plain string depending on the endpoint.\ The payload may contain newlines (e.g., pretty-printed JSON) as only the null byte terminates the request. - **Success response**: a single line containing a JSON payload (or an empty line for commands that have no payload), terminated by connection close - **Error response**: a single line JSON object following RFC 7807 Problem Details format with a `status` field (HTTP-style status code) and other error details, terminated by connection close @@ -95,31 +95,31 @@ The exception to this are the device-control and feedback streams, which are raw After you add a device with `bus/{id}/add`, you must connect to its streaming endpoint within the configured `DeviceHandlerConnectTimeout` (default: 5s). If no stream connection is established in time, the device is automatically removed. Likewise, when a stream disconnects, a reconnection timer with the same timeout starts; if the client doesn’t reconnect before it expires, the device is removed. !!! warning "Authentication Required for Remote Connections" - **VIIPER requires authentication for all non-localhost connections.** + **VIIPER requires authentication for all non-localhost connections.**\ - **Localhost clients** (`127.0.0.1`, `::1`, `localhost`): Authentication is **optional** (but supported) by default - **Remote clients**: Authentication is **required** and enforced - + On first start, VIIPER generates a random password - and saves it to `/viiper.key.txt`. - Windows: `%APPDATA%\VIIPER\viiper.key.txt` - Linux (user): `~/.config/github.com/Alia5/viiper/viiper.key.txt` + and saves it to `/viiper.key.txt`.\ + Windows: `%APPDATA%\VIIPER\viiper.key.txt`\ + Linux (user): `~/.config/github.com/Alia5/viiper/viiper.key.txt`\ Linux (root/systemd): `/etc/viiper/viiper.key.txt` - Remote clients must provide this password to establish a connection. + Remote clients must provide this password to establish a connection.\ See the [Configuration](../cli/configuration.md) documentation for details on password management and the `--api.require-localhost-auth` option. ## Endpoints !!! info "null byte excluded" - The `\0` (null byte) terminator is excluded from all examples below for readability. + The `\0` (null byte) terminator is excluded from all examples below for readability.\ All requests must be terminated with a null byte (unless otherwise noted).
- **Bus Management** - + --- Create, list, and remove virtual buses @@ -127,7 +127,7 @@ The exception to this are the device-control and feedback streams, which are raw [Jump to section](#bus-management) - **Device Management** - + --- Add, list, and remove devices on a bus @@ -135,7 +135,7 @@ The exception to this are the device-control and feedback streams, which are raw [Jump to section](#device-management) - **Device Control / Feedback** - + --- Real-time input and feedback streams for devices @@ -143,7 +143,7 @@ The exception to this are the device-control and feedback streams, which are raw [Jump to section](#device-control--feedback) - **Error Handling** - + --- Error response format and common error codes @@ -173,9 +173,9 @@ The exception to this are the device-control and feedback streams, which are raw ??? info "bus/create - Create a new bus" **Request:** `bus/create` or `bus/create 5` - **Payload:** Optional numeric bus ID (e.g., `5`) + **Payload:** Optional numeric bus ID (e.g., `5`)\ If provided, VIIPER attempts to create the bus with that id; otherwise it picks the next free id. - + **Response:** `{ "busId": }` #### `bus/remove ` {.toc-anchor} @@ -184,7 +184,7 @@ The exception to this are the device-control and feedback streams, which are raw **Request:** `bus/remove 1` **Payload:** Numeric bus ID (e.g., `1`) - + **Response:** `{ "busId": }` ### Device Management {#device-management} @@ -194,7 +194,7 @@ The exception to this are the device-control and feedback streams, which are raw ??? info "bus/{id}/list - List devices on a bus" **Request:** `bus/1/list` - **Response:** + **Response:** ```json { "devices": [ @@ -226,12 +226,12 @@ The exception to this are the device-control and feedback streams, which are raw "deviceSpecific": } ``` - + **Examples:** - `{"type":"xbox360"}` - `{"type":"keyboard","idVendor":1234,"idProduct":5678}` - `{"type":"xbox360", "deviceSpecific": {"subType": 7}}` - + **Response:** ```json { @@ -245,12 +245,12 @@ The exception to this are the device-control and feedback streams, which are raw } } ``` - + !!! warning "Connection timeout" After add, the server starts a connect timer (default `5s`). You must open a device stream before the timeout expires, otherwise the device is auto-removed. - + !!! info "Auto-attach" - If [auto-attach](../cli/server.md#api.auto-attach-local-client) is enabled (default), the server automatically attaches the new device to a local USBIP client on the same host (localhost only). Failures are logged but do not affect the API response. + If [auto-attach](../cli/server.md#option-auto-attach-local-client) is enabled (default), the server automatically attaches the new device to a local USBIP client on the same host (localhost only). Failures are logged but do not affect the API response. #### `bus/{id}/remove ` {.toc-anchor} @@ -258,7 +258,7 @@ The exception to this are the device-control and feedback streams, which are raw **Request:** `bus/1/remove 1` **Payload:** Numeric device ID (e.g., `1` for device 1-1 on the bus) - + **Response:** `{ "busId": , "devId": "" }` ### Device Control / Feedback {#device-control--feedback} @@ -268,19 +268,19 @@ Device Control and Feedback requires an initial "handshake" request, afterwards !!! info "Establish control/feedback connection/stream" **Path:** `bus/{busId}/{deviceId}` - **Handshake:** Send the path followed by `\0` (null byte) + **Handshake:** Send the path followed by `\0` (null byte)\ Example: `bus/1/1\0` - + **Type:** Long-lived TCP connection - - **Purpose:** Device-specific, bidirectional stream. - + + **Purpose:** Device-specific, bidirectional stream.\ + !!! warning "Timeout behavior" - When a stream ends, a reconnect timer is started. + When a stream ends, a reconnect timer is started.\ If the client doesn't reconnect in time, the device is removed. -Device control and feedback is **device-specific**. -Each device type defines it's own packet formats. +Device control and feedback is **device-specific**.\ +Each device type defines it's own packet formats.\ **In general** the client (your code) sends sends binary input state packets to the VIIPER server and possibly receives binary feedback packets (rumble, keyboard leds, etc.) back. @@ -288,8 +288,8 @@ Refer to the individual [device documentation](../devices/overview.md) for detai ### Error Handling {#error-handling} -All errors are inspired by HTTP REST APIs and are returned as single-line JSON objects in the style of [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807). -The connection closes immediately after the error response. +All errors are inspired by HTTP REST APIs and are returned as single-line JSON objects in the style of [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807).\ +The connection closes immediately after the error response.\ If you have ever worked with HTTP APIs, the errors and status codes will feel familiar. @@ -360,9 +360,9 @@ Error codes are basically HTTP carbon copies: printf "bus/1/list\0" | nc localhost 3242 ``` -Then, open a second TCP connection for device control to `bus/1/1` (the API port, not the USBIP port). -First send the "handshake" `bus/1/1\0`, -then you'll write device-specific input packets and read device-specific feedback packets. +Then, open a second TCP connection for device control to `bus/1/1` (the API port, not the USBIP port).\ +First send the "handshake" `bus/1/1\0`,\ +then you'll write device-specific input packets and read device-specific feedback packets.\ Any language with raw TCP support works. ### Go snippet (raw TCP Socket) @@ -379,10 +379,10 @@ import ( func main() { conn, _ := net.Dial("tcp", "localhost:3242") defer conn.Close() - + // Send request with null terminator fmt.Fprint(conn, "bus/create\x00") - + // Read entire response until connection closes resp, _ := io.ReadAll(conn) fmt.Println(string(resp)) // {"busId":1}\n @@ -393,7 +393,7 @@ For a higher-level experience, see the Go client in `/apiclient/`. ## How this relates to USBIP -The VIIPER API controls which virtual devices exist and exposes a device stream for live input/feedback. +The VIIPER API controls which virtual devices exist and exposes a device stream for live input/feedback.\ Separately, the USBIP server (default `127.0.0.1:3241`) makes these devices attachable from a local USBIP client. USB/IP is not covered by API authentication; remote exposure requires an explicitly configured address and diff --git a/docs/api/xboxone-exact-removal.md b/docs/api/xboxone-exact-removal.md deleted file mode 100644 index 66539cf4..00000000 --- a/docs/api/xboxone-exact-removal.md +++ /dev/null @@ -1,173 +0,0 @@ -# Exact production Xbox One removal - -The authenticated `bus/{id}/add-authorized-xboxone` response includes a -top-level `removalToken`. It is a fresh 256-bit `crypto/rand` nonce encoded as -exactly 64 lowercase hexadecimal characters. This is a creation-only secret: -it is not in ordinary device listings, descriptors, device-specific arguments, -input, feedback, or API diagnostics. - -The same creation receipt includes `usbipBusId`, an independent public -per-registration export alias, and `removalTimeoutMilliseconds`, the actual -normal server close budget rounded upward. The timeout is a positive integer -at most 300000; unsupported configurations are rejected before production -creation rather than clamped. The normal CLI default is 90000 milliseconds -(three times its 30-second connection timeout). - -`usbipBusId` is `x1-` followed by 26 canonical lowercase unpadded base32 -characters from 16 independent cryptographically random bytes (29 ASCII -bytes total). Its final character is one of `a/e/i/m/q/u/y/4`. It is not -derived from the secret removal token. The immutable alias is installed before -registration publication, including descriptor admission; aliases already -reserved by unpublished registrations also fail the collision check. - -USB/IP DEVLIST, IMPORT reply, native Windows attach, and Linux/Windows CLI -attach all preserve this exact export identity. Protected production imports -accept no numeric bus-device fallback. Stale aliases therefore cannot select a -different controller after numeric address reuse, bus reuse, or server restart. -Numeric USB/IP bus/device fields and the resulting URB transfer device ID are -unchanged. Generic and explicitly dormant/test registrations remain numeric. - -The production registry binds the nonce once to the unique lifetime channel -of the successful `VirtualBus.Add`. Neither numeric address reuse, bus-number -reuse, server restart, nor re-adding the same device pointer transfers that -authority. No predictable local counter is used as the secret. - -Send the following over an authenticated API session: - -```text -bus/{busId}/{devId}/remove-authorized-xboxone {"version":1,"removalToken":""} -``` - -The same closed capability payload is required for -`bus/{busId}/{devId}/stream-authorized-xboxone` and -`bus/{busId}/{devId}/activate-authorized-xboxone`. The former is a NUL-terminated -stream command followed by unchanged X1BR v1 framing; the latter returns -`version:1`, the exact public `usbipBusId`, a positive `usbipPort`, and -`usbipOwnerSerial` (empty for pinned native 0.9.7.7). Legacy address-only broker -opening is rejected for Xbox. Duplicate authorized streams cannot displace the -consumer; activation revalidates both registration and consumer after native -I/O. Registration leases cover only synchronous lifecycle transitions, never -network/native I/O or acquisition of the stream-coordinator mutex. - -The request schema is closed and bounded to 256 bytes. Both fields are required; -unknown fields, duplicate fields, case-folded names, wrong types, unsupported -versions, noncanonical tokens, and trailing JSON are rejected. Authentication -is checked before parsing or lookup. The route never echoes token material in -an error. - -Responses are `{"version":1,"removed":true}` or -`{"version":1,"removed":false}`. A missing/already-gone target or a validly -formed token which does not authorize the captured incarnation returns false -without touching any successor. False is not a new proof of neutralization. - -For a matching live incarnation, the server fences further retained stream -registration for that exact Add, captures and cancels only its existing USB -streams, and joins their existing retained lifecycle. The feedback consumer -must remain alive during this request so `DisconnectNeutral` can receive its -exact canonical Stop acknowledgement. Only after successful joining does -the operation complete exact registration removal. A concurrent safe one-shot -retirement may already have removed that same registration; this still counts -as true for the closer which captured it live. Concurrent callers may join -the result or observe that the registration is already gone. - -Rejected/ambiguous feedback, drain or transport failures, and incomplete joins -return a conflict instead of claiming success. Quarantined owner/admission -proofs stay with their existing lifecycle owners. The exact close fence cannot -be reopened by a late stream completion. Normal registration cancellation -cleans up idle close bookkeeping, including when this API was never called. - -The join budget is the server's existing retained close deadline: normally -three times `ConnectionTimeout`, using a five-second lifecycle fallback when -unset (15 seconds total), or an already-established server shutdown deadline. -Clients need a compatible bounded response timeout; a client timeout is not -permission to attempt numeric device, bus, or port cleanup. - -This API does **not** prove that a Windows USB/IP port has been permanently -detached or that saved-location auto-reattach has been canceled. In pinned -usbip-win2 0.9.7.7, receiver socket loss can schedule another attach by the -saved export location. The independent export alias makes such an old retry -fail lookup instead of selecting a numeric-address successor. No client-side -numeric port detach is authorized by this behavior. Token-bound broker stream -and activation admission remain necessary alongside alias-safe USB selection; -an export alias is public routing identity, not API authentication. - -### Native activation retry policy (September 5 source follow-up) - -Windows native production Xbox activation now uses pinned 0.9.7.7's -`PLUGIN_HARDWARE_ONCE`. The request/response layout, exact export alias and -positive-port validation are unchanged. If the initial native call fails, -it must not also schedule a background import after the creation transaction -has reported failure and rolled back. Legacy numeric exports keep ordinary -`PLUGIN_HARDWARE`; no global driver retry setting is changed. - -This operation does **not** cancel reattachment after a successful import later -loses its broker connection. Source review confirms that receiver teardown -schedules those requests separately. Exact stale-location retry cancellation -remains an open cleanup gate; neither a fixed delay nor a saved numeric port -proves the driver has finished creating its retry work. In particular, calling -the location-based `STOP_ATTACH_ATTEMPTS` before that work exists can return -zero and still be followed by a retry. Do not report such a zero as permanent -retirement, or use global Stop/Detach All to conceal this gap. - -The five new fake-native call-boundary tests and `go test ./...` pass. No -hardware operation is performed by these tests, and the running portable b56 -broker has not been replaced with this source follow-up. - -### Native activation cancellation (September 5 source follow-up) - -Native attach now opens an overlapped driver handle and owns one manual-reset -completion event, pinned payload and `OVERLAPPED` structure. Cancellation uses -`CancelIoEx` with that exact non-null structure; neither all-handle cancellation -nor port-number detach is used. The helper observes the operation's actual -completion and joins any cancellation callback before releasing its event, -buffer or outer driver handle. Pending/incomplete observations cannot retire -that storage. A success which wins cancellation retains its returned port as -evidence; cancellation is not falsely reported as native removal. - -This follows Microsoft's [CancelIoEx contract](https://learn.microsoft.com/en-us/windows/win32/api/ioapiset/nf-ioapiset-cancelioex) -and [GetOverlappedResult completion rules](https://learn.microsoft.com/en-us/windows/win32/api/ioapiset/nf-ioapiset-getoverlappedresult). -The configured API `ConnectionTimeout` (30-second fallback when unset/nonpositive) -requests activation cancellation; it is **not a hard native completion bound**. -A driver which delays or cannot complete cancellation can still retain the -in-flight operation. Request/registration cancellation and the deadline prevent -that operation from subsequently committing a successful activation response. -The existing API request context does not independently observe a peer closing -its management socket while the handler is executing; that event alone is not -claimed as an immediate cancellation source. - -Before native submission, activation rejects an already-canceled request without -consuming the ready owner. Once reserved, the operation retains its reservation -through actual native completion and cancellation cleanup. Cancellation removes -only the captured registration through the existing retained stream drain/Stop -ACK lifecycle. A reused numeric address cannot select a successor. Incomplete -cleanup returns conflict and remains fenced, not successful removal. Commit -revalidates context, exact registration and feedback-consumer readiness. Normal -non-cancellation attach errors retain the prior same-owner retry policy. - -Six new native-operation tests and five new handler tests cover pending abort, -late success/ERROR_NOT_FOUND, callback/storage lifetime, malformed responses, -pre-cancellation, deadline propagation, duplicate activation while cancellation -is pending, and exact-registration replacement. The prior ABI tests now exercise -the same production helper; the obsolete synchronous helper was removed. -`go test ./... -count=1`, `go vet ./...`, and ten race-enabled repetitions of -native/activation regressions pass. These tests use fake native calls and real -loopback authenticated broker streams, not the installed driver. - -Successful-retired-import retry cleanup is still a distinct open gate. Pinned -0.9.7.7 handles imported-device queries and retry cancellation on a parallel -queue, separately from detach/retry creation. Cancellation matches a 32-bit -location hash (zero selects all), not an opaque native attachment identity. -Neither observing absence nor canceling zero current retries establishes that -future retry work cannot appear. No speculative native cleanup operation was -added. This source is not in the running portable b56 payload. - -When a positive `BusCleanupTimeout` is configured, creating an initially empty -bus schedules the same exact bus/empty-incarnation cleanup used after device -removal. A rejected factory therefore does not require numeric bus deletion by -the client. Initial zero-timeout embedding behavior remains unchanged. - -Source-backed in-process coverage includes real production broker/retained USB -Stop ACK success, rejection, wrong correlation, socket loss, late import -registration, close timeout, duplicate-import Busy isolation, registration -cleanup, stale address/bus reuse, token isolation, schema validation, and -concurrent idempotent removal. These tests do not access physical hardware. diff --git a/docs/architecture/authenticated-transport-direction-review-2026-09-02.md b/docs/architecture/authenticated-transport-direction-review-2026-09-02.md index 5eb8a49b..f51210bd 100644 --- a/docs/architecture/authenticated-transport-direction-review-2026-09-02.md +++ b/docs/architecture/authenticated-transport-direction-review-2026-09-02.md @@ -1,5 +1,8 @@ # Authenticated transport direction review, 2026-09-02 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Status: **original v1 defect confirmed; coordinated v2 source repair implemented on September 3, with deployment/SDK acceptance still open**. This is not an exploitation claim, a hardware result, or an explanation for the isolated b48 probe failure. No live credentials or raw diff --git a/docs/architecture/controller-platform-audit-2026-08-29.md b/docs/architecture/controller-platform-audit-2026-08-29.md index 8db1cde2..13844c44 100644 --- a/docs/architecture/controller-platform-audit-2026-08-29.md +++ b/docs/architecture/controller-platform-audit-2026-08-29.md @@ -1,5 +1,8 @@ # Controller platform audit, 2026-08-29 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Status: the pinned PadForge/HIDMaestro, Switch2Connect, mandatory Microsoft, and xow source audits are complete enough to select the current offline Phase 1/2 work. This is not a completed full-platform audit: Windows binding, diff --git a/docs/architecture/controller-platform-checkpoint-2026-09-06.md b/docs/architecture/controller-platform-checkpoint-2026-09-06.md index 397a7c7f..ccb322a2 100644 --- a/docs/architecture/controller-platform-checkpoint-2026-09-06.md +++ b/docs/architecture/controller-platform-checkpoint-2026-09-06.md @@ -1,5 +1,8 @@ # Controller platform source checkpoint, 2026-09-06 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + This is a source-preservation checkpoint on `feature/native-udecx-landing-zone`, not a release tag or a claim that the remaining hardware/game acceptance matrix is complete. It collects the accumulated Xbox One retained-USB, authentication, diff --git a/docs/architecture/controller-platform-provenance-ledger-2026-08-29.md b/docs/architecture/controller-platform-provenance-ledger-2026-08-29.md index ec3fffe8..d9eb6851 100644 --- a/docs/architecture/controller-platform-provenance-ledger-2026-08-29.md +++ b/docs/architecture/controller-platform-provenance-ledger-2026-08-29.md @@ -1,5 +1,8 @@ # Controller platform provenance ledger, 2026-08-29 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + This ledger applies to the Xbox One/Series and physical Switch 2 work. A fact may be independently implemented only when its destination license and the source's grant permit it, or when it is a protocol fact recovered through a diff --git a/docs/architecture/controller-platform-validation-2026-08-29.md b/docs/architecture/controller-platform-validation-2026-08-29.md index 45ae1b45..7c8c24e4 100644 --- a/docs/architecture/controller-platform-validation-2026-08-29.md +++ b/docs/architecture/controller-platform-validation-2026-08-29.md @@ -1,5 +1,8 @@ # Controller platform validation status, 2026-08-29 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + This is an evidence/status snapshot for the in-progress DS4Windows + VIIPER controller-platform work. It is not a release note and does not claim product completion, Windows Xbox One/Series visibility, live Switch 2 support, latency diff --git a/docs/architecture/controller-platform-validation-2026-08-30.md b/docs/architecture/controller-platform-validation-2026-08-30.md index cae9b7e8..441ce507 100644 --- a/docs/architecture/controller-platform-validation-2026-08-30.md +++ b/docs/architecture/controller-platform-validation-2026-08-30.md @@ -1,5 +1,8 @@ # Controller platform validation status, 2026-08-30 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + This is the current evidence snapshot for the in-progress DS4Windows + VIIPER Xbox One/Series and physical Switch 2 work. It is not a release note. It does not claim a registered Xbox One/Series device, live Switch 2 product support, diff --git a/docs/architecture/controller-platform-validation-2026-08-31.md b/docs/architecture/controller-platform-validation-2026-08-31.md index 6ad9ae8d..32323bc9 100644 --- a/docs/architecture/controller-platform-validation-2026-08-31.md +++ b/docs/architecture/controller-platform-validation-2026-08-31.md @@ -1,5 +1,8 @@ # Controller platform validation status, 2026-08-31 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + This is a dated evidence snapshot for the in-progress DS4Windows + VIIPER Xbox One/Series output and physical Switch 2 work. It is not a release note. It does not claim a production-registered Xbox One/Series persona, live diff --git a/docs/architecture/controller-platform-validation-2026-09-01.md b/docs/architecture/controller-platform-validation-2026-09-01.md index 4aabf2a9..ac49b808 100644 --- a/docs/architecture/controller-platform-validation-2026-09-01.md +++ b/docs/architecture/controller-platform-validation-2026-09-01.md @@ -1,5 +1,8 @@ # Controller platform validation status, 2026-09-01 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + This is the current dirty-working-tree evidence ledger for the DS4Windows + VIIPER Xbox One/Series output and physical Switch 2 work. It supersedes the implementation-status portions of diff --git a/docs/architecture/controller-platform-validation-2026-09-02.md b/docs/architecture/controller-platform-validation-2026-09-02.md index 81b4e87c..06e06eac 100644 --- a/docs/architecture/controller-platform-validation-2026-09-02.md +++ b/docs/architecture/controller-platform-validation-2026-09-02.md @@ -1,5 +1,8 @@ # Controller platform validation status, 2026-09-02 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + For the later coordinated auth v2 repair and current acceptance gaps, see the [September 3 continuation](controller-platform-validation-2026-09-03.md). @@ -1431,7 +1434,7 @@ Switch2Connect `61ac6642ce12fe7217e38a860b14863b18ca7e28` (GPL-3.0-or-later). XML defaults, absent-key migration, reset and view-model properties are covered. This reuses the existing DS4Windows translators and sole physical writers; no donor transport, bundled binary or PadForge code was copied. See -[`switch2-dualsense-conversion-policy.md`](../../../DS4Windows/docs/protocols/switch2-dualsense-conversion-policy.md). +[`switch2-dualsense-conversion-policy.md`](https://github.com/hbashton/DS4Windows/blob/main/docs/protocols/switch2-dualsense-conversion-policy.md). Live edits retain ordinary body rumble and any still-enabled component within the original absolute expiry, without resurrecting removed media on re-enable. diff --git a/docs/architecture/controller-platform-validation-2026-09-03.md b/docs/architecture/controller-platform-validation-2026-09-03.md index 9e6039e0..63a4d48a 100644 --- a/docs/architecture/controller-platform-validation-2026-09-03.md +++ b/docs/architecture/controller-platform-validation-2026-09-03.md @@ -1,5 +1,8 @@ # Controller platform validation status, 2026-09-03 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Continuation: [September 4 evidence](controller-platform-validation-2026-09-04.md) establishes and repairs the recurring USB counter disconnect, records actual Go↔DS4Windows auth interoperability, and stages the matched portable b50 pair. diff --git a/docs/architecture/controller-platform-validation-2026-09-04.md b/docs/architecture/controller-platform-validation-2026-09-04.md index 993c2292..e0c3a9dd 100644 --- a/docs/architecture/controller-platform-validation-2026-09-04.md +++ b/docs/architecture/controller-platform-validation-2026-09-04.md @@ -1,5 +1,8 @@ # Controller platform validation status, 2026-09-04 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Current working order: [itemized execution checklist](controller-platform-execution-checklist.md). The user redirected prioritization on September 4: core USB/Xbox/Bluetooth play and measured failures take precedence over continuing the profile-picker pathway. @@ -1243,7 +1246,6 @@ that event alone is not claimed as an immediate cancellation trigger. Pinned usbip-win2 parallel query/Stop queues and hash-based retry selection still do not supply a permanent exact retry-removal barrier after successful imports. That separate cleanup remains open; no Stop All/numeric-port detach is added. -See [the API lifecycle contract](../api/xboxone-exact-removal.md) for details and Microsoft references. No app, broker, controller, pairing or output action was performed during this source follow-up; installed binaries remain untouched. diff --git a/docs/architecture/gip-primary-identity-retirement-2026-09-06.md b/docs/architecture/gip-primary-identity-retirement-2026-09-06.md index 67daf08d..5dad190c 100644 --- a/docs/architecture/gip-primary-identity-retirement-2026-09-06.md +++ b/docs/architecture/gip-primary-identity-retirement-2026-09-06.md @@ -1,5 +1,8 @@ # Primary GIP identity must survive asynchronous native retirement +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + The primary GIP Hello DeviceID is an OS lookup key, not a model identifier. Changing only the USB serial or retained import lease ID does not make two primary GIP devices distinct. Local Windows dump evidence from September 6 diff --git a/docs/architecture/native-presentation-decision-package-2026-08-29.md b/docs/architecture/native-presentation-decision-package-2026-08-29.md index 56d1ed91..f88821c5 100644 --- a/docs/architecture/native-presentation-decision-package-2026-08-29.md +++ b/docs/architecture/native-presentation-decision-package-2026-08-29.md @@ -1,5 +1,8 @@ # Native presentation decision package, 2026-08-29 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Decision: do not implement, merge, install, or package the native driver in the current Xbox/Switch 2 task. Preserve ABI 1.14 and the current `inputpresentation.Source` seam so a separately authorized backend can be diff --git a/docs/architecture/rc4.5-candidate-release-preparation-2026-09-08.md b/docs/architecture/rc4.5-candidate-release-preparation-2026-09-08.md index 3321e92d..4149307f 100644 --- a/docs/architecture/rc4.5-candidate-release-preparation-2026-09-08.md +++ b/docs/architecture/rc4.5-candidate-release-preparation-2026-09-08.md @@ -1,5 +1,8 @@ # RC4.5 candidate release preparation, 2026-09-08 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + This source checkpoint prepares VIIPER `v0.1.3-rc4.5` for the DS4Windows `5.0.5.0-VIIPERRC4.5` tester package. It is not a GitHub release, signed binary, live hardware acceptance, driver replacement, or permission to change the diff --git a/docs/architecture/viiper-tray-startup-validation-2026-09-08.md b/docs/architecture/viiper-tray-startup-validation-2026-09-08.md index c4c784d5..e7a0ca01 100644 --- a/docs/architecture/viiper-tray-startup-validation-2026-09-08.md +++ b/docs/architecture/viiper-tray-startup-validation-2026-09-08.md @@ -1,5 +1,8 @@ # VIIPER tray startup recovery validation — 2026-09-08 +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + ## Scope and confidence Source-level repair for [DS4Windows #69](https://github.com/hbashton/DS4Windows/issues/69), diff --git a/docs/architecture/xbox-one-canonical-downstream-packet-batch-2026-08-31.md b/docs/architecture/xbox-one-canonical-downstream-packet-batch-2026-08-31.md index a6187f5b..0e600e74 100644 --- a/docs/architecture/xbox-one-canonical-downstream-packet-batch-2026-08-31.md +++ b/docs/architecture/xbox-one-canonical-downstream-packet-batch-2026-08-31.md @@ -1,5 +1,8 @@ # Xbox One canonical downstream packet batch (dormant) +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Audit and implementation date: 2026-08-31. ## Outcome diff --git a/docs/architecture/xbox-one-dormant-authorized-retained-composition-2026-08-31.md b/docs/architecture/xbox-one-dormant-authorized-retained-composition-2026-08-31.md index 168f5c78..c1b4d455 100644 --- a/docs/architecture/xbox-one-dormant-authorized-retained-composition-2026-08-31.md +++ b/docs/architecture/xbox-one-dormant-authorized-retained-composition-2026-08-31.md @@ -1,5 +1,8 @@ # Dormant authorized Xbox retained-USB composition (2026-08-31) +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + ## Scope and status `NewAuthorizedDormantRetainedUSBAdapter` remains the private-engine diff --git a/docs/architecture/xbox-one-dormant-duplex-boundary-2026-08-30.md b/docs/architecture/xbox-one-dormant-duplex-boundary-2026-08-30.md index c8d144a8..f2500fe8 100644 --- a/docs/architecture/xbox-one-dormant-duplex-boundary-2026-08-30.md +++ b/docs/architecture/xbox-one-dormant-duplex-boundary-2026-08-30.md @@ -1,5 +1,8 @@ # Xbox One dormant duplex boundary audit +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Audit date: 2026-08-30. Status: the semantic input contract, persona-local feedback translation, and diff --git a/docs/architecture/xbox-one-dormant-external-identity-gate-2026-08-31.md b/docs/architecture/xbox-one-dormant-external-identity-gate-2026-08-31.md index 31086ef4..8940407b 100644 --- a/docs/architecture/xbox-one-dormant-external-identity-gate-2026-08-31.md +++ b/docs/architecture/xbox-one-dormant-external-identity-gate-2026-08-31.md @@ -1,5 +1,8 @@ # Dormant Xbox external-identity gate +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Date: 2026-08-31 Status: offline prerequisite only; no registry, CLI, USB/IP, device, Windows, or hardware activation diff --git a/docs/architecture/xbox-one-dormant-interrupt-out-packet-adapter-2026-08-31.md b/docs/architecture/xbox-one-dormant-interrupt-out-packet-adapter-2026-08-31.md index 6cb89e3e..bd4a93fc 100644 --- a/docs/architecture/xbox-one-dormant-interrupt-out-packet-adapter-2026-08-31.md +++ b/docs/architecture/xbox-one-dormant-interrupt-out-packet-adapter-2026-08-31.md @@ -1,5 +1,8 @@ # Xbox One dormant interrupt-OUT packet adapter +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Audit and implementation date: 2026-08-31. ## Outcome diff --git a/docs/architecture/xbox-one-dormant-receive-framing-gate-2026-08-31.md b/docs/architecture/xbox-one-dormant-receive-framing-gate-2026-08-31.md index c3d31115..7761fbd6 100644 --- a/docs/architecture/xbox-one-dormant-receive-framing-gate-2026-08-31.md +++ b/docs/architecture/xbox-one-dormant-receive-framing-gate-2026-08-31.md @@ -1,5 +1,8 @@ # Xbox One dormant receive-framing gate +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Audit and implementation date: 2026-08-31. ## Outcome diff --git a/docs/architecture/xbox-one-dormant-retained-ep0-capacity-2026-08-31.md b/docs/architecture/xbox-one-dormant-retained-ep0-capacity-2026-08-31.md index 23791887..a58894fc 100644 --- a/docs/architecture/xbox-one-dormant-retained-ep0-capacity-2026-08-31.md +++ b/docs/architecture/xbox-one-dormant-retained-ep0-capacity-2026-08-31.md @@ -1,5 +1,8 @@ # Dormant Xbox retained EP0 254-byte response capacity (2026-08-31) +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Status update (2026-09-01): still unregistered, but now transport-routed behind the explicit retained-device/authority opt-in. Product creation, Windows binding, and hardware validation remain absent. diff --git a/docs/architecture/xbox-one-usbip-adapter-audit-2026-08-29.md b/docs/architecture/xbox-one-usbip-adapter-audit-2026-08-29.md index 17bb7cd2..fa3ddf8d 100644 --- a/docs/architecture/xbox-one-usbip-adapter-audit-2026-08-29.md +++ b/docs/architecture/xbox-one-usbip-adapter-audit-2026-08-29.md @@ -1,5 +1,8 @@ # Xbox One/Series offline persona to USB/IP adapter audit +> **Historical record.** This preserves the source, tests and limitations recorded at the time; it is not current setup guidance. See the [documentation index](../index.md). + + Status: generic transactional EP0, prepared interrupt-IN, transactional interrupt-OUT, late RET_SUBMIT serialization, and a narrow three-lane Xbox retained owner are implemented and dormant. A separately typed exact reset diff --git a/docs/cli/codegen.md b/docs/cli/codegen.md index 01b271ab..747c1b89 100644 --- a/docs/cli/codegen.md +++ b/docs/cli/codegen.md @@ -33,15 +33,15 @@ viiper codegen [flags] Output directory for generated client libraries (relative to repository root). -**Default:** `clients` +**Default:** `clients`\ **Environment Variable:** `VIIPER_CODEGEN_OUTPUT` ### `--lang` Target language to generate. -**Values:** `csharp`, `typescript`, `all` -**Default:** `all` +**Values:** `csharp`, `typescript`, `all`\ +**Default:** `all`\ **Environment Variable:** `VIIPER_CODEGEN_LANG` ## Examples @@ -71,5 +71,5 @@ Run codegen when any of these change: ## See Also - [Generator Documentation](../clients/generator.md): Detailed explanation of tagging system and code generation flow -- [API and Client Reference](../../api/overview.md): API endpoints and data structures +- [API and Client Reference](../api/overview.md): API endpoints and data structures - [Configuration](configuration.md): Global configuration options diff --git a/docs/cli/configuration.md b/docs/cli/configuration.md index ec9a66e6..c1a05e79 100644 --- a/docs/cli/configuration.md +++ b/docs/cli/configuration.md @@ -46,7 +46,7 @@ The tray's normal startup-registration and Quit actions are unchanged. ## Configuration Files -VIIPER supports JSON, YAML, and TOML configuration files. +VIIPER supports JSON, YAML, and TOML configuration files.\ Generate a starter file (default configuration) with: ```bash @@ -101,13 +101,13 @@ authenticated network boundary. The password file is _intentionally_ separated from the main configuration -**Password File:** `viiper.key.txt` +**Password File:** `viiper.key.txt`\ -- **Location:** - - **Windows:** `%APPDATA%\VIIPER\` - - **Linux/macOS (user):** `~/.config/github.com/Alia5/viiper/` - - **Linux (root/systemd):** `/etc/viiper/` -- **Auto-generation:** If the file doesn't exist, +- **Location:**\ + - **Windows:** `%APPDATA%\VIIPER\`\ + - **Linux/macOS (user):** `~/.config/github.com/Alia5/viiper/`\ + - **Linux (root/systemd):** `/etc/viiper/`\ +- **Auto-generation:** If the file doesn't exist,\ VIIPER generates a random 16-character password on first start and displays it in the console - **Custom passwords:** You can edit `viiper.key.txt` and replace it with any password of any length - **Encryption:** All authenticated connections use fast ChaCha20-Poly1305 encryption with unique session keys @@ -117,12 +117,12 @@ file without reading or writing the default password location. Explicit invalid, unreadable, or empty key files fail closed; only a missing file is generated, using exclusive creation so an existing key cannot be overwritten. This does not isolate other configuration, logging, or tray-startup behavior. -See [the server key-file option](server.md#--key-file) for a local lab example and +See [the server key-file option](server.md#option-key-file) for a local lab example and the limits of `--config` and `--config-only`. ### Localhost Exemption -By default, clients connecting from `localhost`, `127.0.0.1`, or `::1` do NOT require authentication (they can optionally provide it). +By default, clients connecting from `localhost`, `127.0.0.1`, or `::1` do NOT require authentication (they can optionally provide it).\ To require authentication even for localhost connections, use `--api.require-local-host-auth=true`. ### Remote Connections diff --git a/docs/cli/overview.md b/docs/cli/overview.md index c73e8780..0a8d5bc5 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -6,8 +6,8 @@ VIIPER provides a command-line interface for running the USBIP server and proxy. - [`server`](server.md) - Start the VIIPER USBIP server - [`proxy`](proxy.md) - Start the VIIPER USBIP proxy -- `install` - Configure VIIPER to start automatically on system boot (see [Installation](../getting-started/installation.md#system-startup-configuration)) -- `uninstall` - Remove VIIPER from system startup configuration +- `install` - Developer-only standalone startup registration (see [Standalone development](../getting-started/installation.md#standalone-development)); DS4Windows manages its own backend startup +- `uninstall` - Remove standalone startup registration; use DS4Windows setup/repair for managed installations - [`codegen`](codegen.md) - Generate client libraries from source code annotations ## Global Options @@ -20,8 +20,8 @@ VIIPER supports flexible logging configuration via global flags or environment v Set the logging level. -**Values:** `trace`, `debug`, `info`, `warn`, `error` -**Default:** `info` +**Values:** `trace`, `debug`, `info`, `warn`, `error`\ +**Default:** `info`\ **Environment Variable:** `VIIPER_LOG_LEVEL` **Example:** @@ -34,7 +34,7 @@ viiper server --log.level=debug Log to a file in addition to console output. -**Default:** (none - logs only to console) +**Default:** (none - logs only to console)\ **Environment Variable:** `VIIPER_LOG_FILE` **Example:** @@ -47,7 +47,7 @@ viiper server --log.file=/var/log/viiper.log Log raw USB packet data to a file for debugging and reverse engineering. -**Default:** (none) +**Default:** (none)\ **Environment Variable:** `VIIPER_LOG_RAW_FILE` **Example:** diff --git a/docs/cli/server.md b/docs/cli/server.md index 4a4667db..2c444719 100644 --- a/docs/cli/server.md +++ b/docs/cli/server.md @@ -1,6 +1,6 @@ # Server Command -Start the VIIPER daemon/server to expose virtual devices. +Start the VIIPER daemon/server to expose virtual devices.\ This is the default command you should run when you want to create virtual USB devices using VIIPER. ## Usage @@ -19,26 +19,28 @@ The server exposes two interfaces: 2. **VIIPER API Server** - Management API for device/bus control !!! warning "Authentication Required for Remote Connections" - VIIPER requires **authentication for all remote (non-localhost) connections** to prevent unauthorized device creation. + VIIPER requires **authentication for all remote (non-localhost) connections** to prevent unauthorized device creation.\ On first start, VIIPER generates a random password - and saves it to `/viiper.key.txt`. - Windows: `%APPDATA%\VIIPER\viiper.key.txt` - Linux (user): `~/.config/github.com/Alia5/viiper/viiper.key.txt` + and saves it to `/viiper.key.txt`.\ + Windows: `%APPDATA%\VIIPER\viiper.key.txt`\ + Linux (user): `~/.config/github.com/Alia5/viiper/viiper.key.txt`\ Linux (root/systemd): `/etc/viiper/viiper.key.txt` - + - **Localhost clients** (`127.0.0.1`, `::1`): Authentication is optional by default - **Remote clients**: Authentication is required and enforced - All authenticated connections use **ChaCha20-Poly1305 encryption** - + See the `--api.require-local-host-auth` option below to require authentication for localhost connections. !!! info "Automatic Local Attachment" - By default, VIIPER automatically attaches newly created devices to the local USBIP client (localhost only). - This means when you create a device via the API, it will be immediately available on the same machine without manual `usbip attach` commands. + By default, VIIPER automatically attaches newly created devices to the local USBIP client (localhost only).\ + This means when you create a device via the API, it will be immediately available on the same machine without manual `usbip attach` commands.\ This behavior can be disabled with `--api.auto-attach-local-client=false` if you prefer manual control or are running on a remote server. ## Options + + ### `--key-file` @@ -88,23 +90,25 @@ authentication does not authenticate the separate USB/IP port. API server listen address. -**Default:** `:3242` +**Default:** `:3242`\ **Environment Variable:** `VIIPER_API_ADDR` ### `--api.device-handler-timeout` Time before auto-cleanup occurs when a device handler has no active connection. -**Default:** `5s` +**Default:** `5s`\ **Environment Variable:** `VIIPER_API_DEVICE_HANDLER_TIMEOUT` + + ### `--api.auto-attach-local-client` Automatically attach newly added devices to a local USBIP client on the same host (localhost only). This is a convenience feature; attachment failures (tool not found, error exit) are logged but do not abort device creation. VIIPER expects the USBIP command-line tool to be in the PATH (should be by default) (`usbip` on Linux, `usbip.exe` on Windows). If it is missing, auto-attach will simply log an error. -**Default:** `true` +**Default:** `true`\ **Environment Variable:** `VIIPER_API_AUTO_ATTACH_LOCAL_CLIENT` Disable example: @@ -117,10 +121,10 @@ viiper server --api.auto-attach-local-client=false Require authentication even for clients connecting from localhost (`127.0.0.1`, `::1`, `localhost`). -By default, localhost clients are exempt from authentication for convenience during local development. +By default, localhost clients are exempt from authentication for convenience during local development.\ Enable this option if you want to enforce authentication for all connections regardless of origin. -**Default:** `false` +**Default:** `false`\ **Environment Variable:** `VIIPER_API_REQUIRE_LOCALHOST_AUTH` Enable example: @@ -133,7 +137,7 @@ viiper server --api.require-local-host-auth=true Connection operation timeout for both USBIP and API servers. -**Default:** `30s` +**Default:** `30s`\ **Environment Variable:** `VIIPER_CONNECTION_TIMEOUT` ## Examples diff --git a/docs/clients/cpp.md b/docs/clients/cpp.md index 15ab4a0f..9e3cb864 100644 --- a/docs/clients/cpp.md +++ b/docs/clients/cpp.md @@ -17,11 +17,11 @@ The C++ client library features: **Recommended**: [nlohmann/json](https://github.com/nlohmann/json) - a header-only JSON library that can be easily integrated. !!! warning "OpenSSL Required" - The C++ client library requires OpenSSL for encrypted connections to VIIPER servers with authentication enabled. + The C++ client library requires OpenSSL for encrypted connections to VIIPER servers with authentication enabled.\ Ensure OpenSSL is installed and linked in your project. !!! note "License" - The C++ client library is licensed under the **MIT License**, providing maximum flexibility for integration into your projects. + The C++ client library is licensed under the **MIT License**, providing maximum flexibility for integration into your projects.\ The core VIIPER server remains under its original license. ## Installation @@ -234,7 +234,7 @@ stream->on_output(viiper::keyboard::OUTPUT_SIZE, [](const std::uint8_t* data, st if (len < viiper::keyboard::OUTPUT_SIZE) return; auto result = viiper::keyboard::Output::from_bytes(data, len); if (result.is_error()) return; - + auto& leds = result.value(); bool num_lock = (leds.leds & viiper::keyboard::LEDNumLock) != 0; bool caps_lock = (leds.leds & viiper::keyboard::LEDCapsLock) != 0; @@ -249,7 +249,7 @@ stream->on_output(viiper::xbox360::OUTPUT_SIZE, [](const std::uint8_t* data, std if (len < viiper::xbox360::OUTPUT_SIZE) return; auto result = viiper::xbox360::Output::from_bytes(data, len); if (result.is_error()) return; - + auto& rumble = result.value(); std::cout << "Rumble: Left=" << static_cast(rumble.left) << ", Right=" << static_cast(rumble.right) << "\n"; @@ -382,7 +382,7 @@ Full working examples are available in the repository: - **Virtual Keyboard**: `examples/cpp/virtual_keyboard.cpp` - Types "Hello!" every 5 seconds using generated maps - Displays LED feedback in console - + - **Virtual Mouse**: `examples/cpp/virtual_mouse.cpp` - Moves cursor in a circle pattern - Demonstrates button clicks @@ -445,4 +445,4 @@ viiper server --api-addr localhost:3242 - [C# Client Library Documentation](csharp.md): .NET client library - [TypeScript Client Library Documentation](typescript.md): Node.js client library - [API Overview](../api/overview.md): Management API reference -- [Device Documentation](../devices/): Wire formats and device-specific details +- [Device Documentation](../devices/overview.md): Wire formats and device-specific details diff --git a/docs/clients/csharp.md b/docs/clients/csharp.md index 574d5573..8e9aff5b 100644 --- a/docs/clients/csharp.md +++ b/docs/clients/csharp.md @@ -11,7 +11,7 @@ The C# client library features: - **Zero external dependencies**: Uses only built-in .NET libraries !!! note "License" - The C# client library is licensed under the **MIT License**, providing maximum flexibility for integration into your projects. + The C# client library is licensed under the **MIT License**, providing maximum flexibility for integration into your projects.\ The core VIIPER server remains under its original license. ## Installation @@ -151,7 +151,7 @@ device.OnOutput += data => { if (data.Length < 1) return; byte leds = data[0]; - + Console.WriteLine($"LEDs: " + $"Num={(leds & (byte)LED.NumLock) != 0} " + $"Caps={(leds & (byte)LED.CapsLock) != 0} " + @@ -315,7 +315,7 @@ Full working examples are available in the repository: - **Virtual Keyboard**: `examples/csharp/virtual_keyboard/Program.cs` - Types "Hello!" every 5 seconds using generated maps - Displays LED feedback in console - + - **Virtual Mouse**: `examples/csharp/virtual_mouse/Program.cs` - Moves cursor in a circle pattern - Demonstrates button clicks and scroll wheel @@ -359,4 +359,4 @@ The generated code uses nullable annotations. You may see warnings like CS8601/C - [TypeScript Client Library Documentation](typescript.md): Node.js client library - [C++ Client Library Documentation](cpp.md): Header-only C++ client library - [API Overview](../api/overview.md): Management API reference -- [Device Documentation](../devices/): Wire formats and device-specific details +- [Device Documentation](../devices/overview.md): Wire formats and device-specific details diff --git a/docs/clients/go.md b/docs/clients/go.md index 082dddd9..8f73b235 100644 --- a/docs/clients/go.md +++ b/docs/clients/go.md @@ -29,13 +29,13 @@ func main() { // Create new Viiper client client := viiperclient.New("127.0.0.1:3242") ctx := context.Background() - + // Create or find a bus buses, err := client.BusList() if err != nil { log.Fatal(err) } - + var busID uint32 if len(buses) > 0 { busID = buses[0] @@ -46,7 +46,7 @@ func main() { } busID = resp.BusID } - + // Add device and connect (optional CreateOptions parameter for VID/PID) // Pass nil to use default VID/PID for the device type. stream, resp, err := client.AddDeviceAndConnect(ctx, busID, "keyboard", nil) @@ -54,21 +54,21 @@ func main() { log.Fatal(err) } defer stream.Close() - + log.Printf("Connected to device %s", resp.ID) - + // Send keyboard input input := &keyboard.InputState{ Modifiers: keyboard.ModLeftShift, } input.SetKey(keyboard.KeyH, true) - + if err := stream.WriteBinary(input); err != nil { log.Fatal(err) } - + time.Sleep(100 * time.Millisecond) - + // Release input = &keyboard.InputState{} stream.WriteBinary(input) @@ -94,8 +94,8 @@ log.Printf("Connected to device %s", resp.ID) ### Sending Input -Device input is sent using structs that implement `encoding.BinaryMarshaler`. -Every device package (e.g. `device/xbox360`) provides type-safe input state structs. +Device input is sent using structs that implement `encoding.BinaryMarshaler`.\ +Every device package (e.g. `device/xbox360`) provides type-safe input state structs.\ ```go import "github.com/Alia5/VIIPER/device/xbox360" @@ -155,8 +155,8 @@ The VIIPER server automatically removes the device when the stream is closed aft ## Device-Specific Notes -Each device type has specific wire formats and helper methods. -For wire format details and usage patterns, see the [Devices](../devices/) section of the documentation. +Each device type has specific wire formats and helper methods.\ +For wire format details and usage patterns, see the [Devices](../devices/overview.md) section of the documentation. The Go client provides device packages under `/device/` with type-safe structs and constants (e.g., `keyboard.InputState`, `keyboard.KeyA`, `mouse.Btn_Left`). diff --git a/docs/clients/rust.md b/docs/clients/rust.md index fc1e2aab..35c8d0fe 100644 --- a/docs/clients/rust.md +++ b/docs/clients/rust.md @@ -11,7 +11,7 @@ The Rust client library features: - **Tokio-based async**: Optional `async` feature for async/await support with Tokio runtime !!! note "License" - The Rust client library is licensed under the **MIT License**, providing maximum flexibility for integration into your projects. + The Rust client library is licensed under the **MIT License**, providing maximum flexibility for integration into your projects.\ The core VIIPER server remains under its original license. ## Installation @@ -224,11 +224,11 @@ For devices that send feedback (rumble, LEDs), register a callback with `on_outp let mut buf = [0u8; OUTPUT_SIZE]; reader.read_exact(&mut buf)?; let leds = buf[0]; - + let num_lock = (leds & 0x01) != 0; let caps_lock = (leds & 0x02) != 0; let scroll_lock = (leds & 0x04) != 0; - + println!("LEDs: Num={} Caps={} Scroll={}", num_lock, caps_lock, scroll_lock); Ok(()) }).expect("Failed to register callback"); @@ -258,11 +258,11 @@ For devices that send feedback (rumble, LEDs), register a callback with `on_outp let mut guard = stream.lock().await; guard.read_exact(&mut buf).await?; drop(guard); - + let leds = buf[0]; let num_lock = (leds & 0x01) != 0; let caps_lock = (leds & 0x02) != 0; - + println!("LEDs: Num={} Caps={}", num_lock, caps_lock); Ok(()) }).expect("Failed to register callback"); @@ -361,7 +361,7 @@ match client.bus_list() { } ``` -The server returns errors as RFC 7807 Problem inspired JSON. +The server returns errors as RFC 7807 Problem inspired JSON.\ The client parses these into `ProblemJson`: ```rust @@ -397,7 +397,7 @@ Full working examples are available in the repository: - **Virtual Keyboard (sync)**: `examples/rust/sync/virtual_keyboard/` - Types "Hello!" every 5 seconds using generated maps - Displays LED feedback in console - + - **Virtual Keyboard (async)**: `examples/rust/async/virtual_keyboard/` - Async version using Tokio runtime @@ -417,4 +417,4 @@ Full working examples are available in the repository: - [TypeScript Client Library Documentation](typescript.md): Node.js client library - [C++ Client Library Documentation](cpp.md): Header-only C++ client library - [API Overview](../api/overview.md): Management API reference -- [Device Documentation](../devices/): Wire formats and device-specific details +- [Device Documentation](../devices/overview.md): Wire formats and device-specific details diff --git a/docs/clients/typescript.md b/docs/clients/typescript.md index dec3d7c4..f9afe4fa 100644 --- a/docs/clients/typescript.md +++ b/docs/clients/typescript.md @@ -9,7 +9,7 @@ The TypeScript client library features: - **Zero external dependencies**: Uses only built-in Node.js libraries !!! note "License" - The TypeScript client library is licensed under the **MIT License**, providing maximum flexibility for integration into your projects. + The TypeScript client library is licensed under the **MIT License**, providing maximum flexibility for integration into your projects.\ The core VIIPER server remains under its original license. ## Installation @@ -154,7 +154,7 @@ const { LED } = Keyboard; device.on("output", (data: Buffer) => { if (data.length < 1) return; const leds = data.readUInt8(0); - + console.log(`LEDs: ` + `Num=${(leds & LED.NumLock) !== 0} ` + `Caps=${(leds & LED.CapsLock) !== 0} ` + @@ -203,7 +203,7 @@ For long-running applications with intervals or timers, stop them before cleanup let running = true; const interval = setInterval(async () => { if (!running) return; - + try { await device.send(input); } catch (err) { @@ -342,7 +342,7 @@ Full working examples are available in the repository: - **Virtual Keyboard**: `examples/typescript/virtual_keyboard.ts` - Types "Hello!" every 5 seconds using generated maps - Displays LED feedback in console - + - **Virtual Mouse**: `examples/typescript/virtual_mouse.ts` - Moves cursor diagonally - Demonstrates button clicks and scroll wheel @@ -369,4 +369,4 @@ node dist/virtual_keyboard.js localhost:3242 - [Rust Client Library Documentation](rust.md): Rust client library with sync/async support - [C++ Client Library Documentation](cpp.md): Header-only C++ client library - [API Overview](../api/overview.md): Management API reference -- [Device Documentation](../devices/): Wire formats and device-specific details +- [Device Documentation](../devices/overview.md): Wire formats and device-specific details diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..80df0f44 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,41 @@ +# VIIPER development + +[Documentation index](index.md) · [Installation](getting-started/installation.md) + +Use the Go toolchain required by `go.mod` (currently 1.26.2 or a compatible newer +version). `just` provides the repository's build recipes. From the repository root: + +```powershell +go test ./... +just build Release +go run ./cmd/viiper codegen +``` + +Build the generated client examples after changing public state or feedback +contracts. The module path remains `github.com/Alia5/VIIPER`; fork repository +ownership does not change Go imports or on-disk configuration namespaces. + +The default server output is `dist/viiper.exe` on Windows or `dist/viiper` on +Linux. libVIIPER requires CGO and a compatible C toolchain. See `justfile` and +[the shared-library guide](libviiper/overview.md). + +## Tests and hardware + +Unit tests and client interoperability checks do not prove game or hardware +compatibility. Record the source commit, device model, connection, feeder, +driver and procedure for live tests. Use the documented opt-in test tools; +keep authentication and backend ownership intact during experiments. + +- [Latency testing](testing/e2e_latency.md) +- [DualSense end-to-end testing](https://github.com/hbashton/VIIPER/blob/main/_testing/e2e/DUALSENSE_V5.md) +- [Startup diagnostics](startup-diagnostics.md) +- [Technical records](reference.md) + +## Documentation + +Use [the MkDocs guide](mkdocs-readme.md) to preview and build the site. The docs +deployment workflow publishes main/tag versions automatically; do not manually +publish unrelated development content to GitHub Pages. + +Keep README concise, release notes in CHANGELOG.md, and dated investigations +clearly identified as evidence. Retain licensing notices and attribution. diff --git a/docs/devices/overview.md b/docs/devices/overview.md new file mode 100644 index 00000000..c0697083 --- /dev/null +++ b/docs/devices/overview.md @@ -0,0 +1,18 @@ +# Device protocols + +[Documentation index](../index.md) · [API overview](../api/overview.md) + +Device pages describe the feeder's wire format and supported virtual USB +behaviour. Use the matching server/client contract; do not treat one device's +binary input as interchangeable with another's. + +- [Xbox 360](xbox360.md) +- [DualShock 4](dualshock4.md) +- [DualSense and DualSense Edge](dualsense.md) +- [Switch 2 Pro](ns2pro.md) +- [Keyboard](keyboard.md) +- [Mouse](mouse.md) +- [Xbox One/Series source specification](https://github.com/hbashton/VIIPER/blob/main/device/xboxone/SPEC.md) + +Audio, adaptive triggers, motion and microphone behaviour depend on the device +type and matching feeder. For DS4Windows, use the backend bundled with the app. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 459f5b3d..2933d461 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1,204 +1,66 @@ # Installation -VIIPER comes in two distinct flavors: - -- **VIIPER Server** -A self-contained, portable, standalone executable providing a lightweight TCP-based API for feeder application development. All client libraries are MIT licensed. -- **libVIIPER** - a single shared library that lets you emulate devices using USBIP directly from within your application. Requires your application to be GPL-3.0 licensed. - -Regardless of the flavour you choose, VIIPER requires USBIP. - -## Requirements - -### USBIP - -VIIPER relies on USBIP. -You must have a USBIP-Client implementation available on your system to use VIIPER's virtual devices. - -=== "Windows" - - VIIPER for DS4Windows requires the signed - [usbip-win2 0.9.7.7 x64 release](https://github.com/vadimgrn/usbip-win2/releases/tag/v.0.9.7.7). - Use the DS4Windows **Install / Repair VIIPER** action whenever possible; its - package contains this exact verified installer. - - !!! danger "Do not substitute another USBIP build" - This release is ABI-pinned to **0.9.7.7**. Version 0.9.7.8 reproduced - kernel pool corruption during controller attachment and is explicitly - rejected. The installer verifies the version and live ABI before - allowing VIIPER to start. - - !!! warning "USBIP-Win2 signing certificate" - The upstream 0.9.7.7 installer may add the publicly available USBIP - test-signing CA to **Trusted Root Certification Authorities**. After - installation, you may remove the certificate named **USBIP** with - `certlm.msc` (run as administrator). Do not replace 0.9.7.7 with a - newer or OSSign build: VIIPER validates this exact userspace/driver ABI. - -=== "Linux" - - #### Ubuntu/Debian - - ```bash - sudo apt install linux-tools-generic - ``` - - [Ubuntu USBIP Manual](https://manpages.ubuntu.com/manpages/noble/man8/usbip.8.html) - - #### Arch Linux - - ```bash - sudo pacman -S usbip - ``` - - [Arch Wiki: USBIP](https://wiki.archlinux.org/title/USB/IP) - - ### Linux Kernel Module Setup - - !!! info "USBIP Client Requirement" - USBIP requires the `vhci-hcd` (Virtual Host Controller Interface) kernel module on Linux for client operations. This includes VIIPER's auto-attach feature and manual device attachment. - - Most Linux distributions include this module but do not load it automatically. - - #### One-Time Setup - - To load the module automatically on boot: - - ```bash - echo "vhci-hcd" | sudo tee /etc/modules-load.d/vhci-hcd.conf - sudo modprobe vhci-hcd - ``` - - #### Manual Loading - - To load the module for the current session only: - - ```bash - sudo modprobe vhci-hcd - ``` - - #### Verification - - ```bash - lsmod | grep vhci_hcd - ``` - ---- - -=== "VIIPER Server" - - A standalone executable that exposes an API over TCP. - - ## Installing VIIPER - - VIIPER does not require system-wide installation. - The `viiper` executable is completely self-contained (fully portable, no dependencies except USBIP) and can be: - - - Placed in any directory - - Shipped alongside your application - - Run directly without installation - - Bundled with your application's distribution - - !!! warning "Daemon/Service Conflicts" - If VIIPER is already running as a system service or daemon on the target machine, be aware of potential port conflicts. Applications should: - - Check if VIIPER is already running before starting their own instance - - Use the `ping` API endpoint to check for VIIPER presence and version - - Connect to the existing VIIPER instance (if accessible) - - Use a custom port via `--api.addr` flag to run a separate instance - - !!! info "Linux Permissions" - On Linux, attaching devices via USBIP requires root permissions. - You can run VIIPER with `sudo`, or configure appropriate udev rules to allow non-root users to attach devices. - - ### Pre-built Binaries - - Download the latest release from the [hbashton/VIIPER Releases](https://github.com/hbashton/VIIPER/releases) page. Pre-built binaries are available for: - - - Windows (x64, ARM64) - - Linux (x64, ARM64) - - ### Automated Install Script - - The following scripts will download a VIIPER release, install it to a system location and configure it to start automatically on boot. - - !!! info "For Application Developers" - The installation scripts are intended for **end-users** setting up a permanent VIIPER service on their system. - - If you are developing an application that uses VIIPER, I **strongly** encourage you to **not** install a permanent VIIPER service on your users' machines. - - Instead, bundle the (no dependencies, portable) VIIPER binary with your application and start/stop the server directly from your application as needed. - You may need to check for existing VIIPER instances or use a custom port via `--api.addr` to avoid conflicts. - - !!! info "USBIP installed by scripts" - The install scripts install and configure USBIP for you: - - - **Windows:** installs the usbip-win2 driver (admin prompt) and prompts for a reboot when drivers were added. - - **Linux:** installs USBIP via the distro package manager (when available), loads `vhci_hcd` and configures it to autoload. - - If the automated USBIP setup fails, follow the [USBIP guide](usbip.md) to finish manually. - - === "Windows" - - ```powershell - irm https://raw.githubusercontent.com/hbashton/VIIPER/main/scripts/install.ps1 | iex - ``` - - Installs to: `%LOCALAPPDATA%\VIIPER\viiper.exe` - - The scripts will: - - 1. Download the specified VIIPER binary version - 2. Install it to the system location - 3. Install and configure USBIP (driver on Windows; packages/modules on Linux) - 4. Configure automatic startup (Registry RunKey on Windows, systemd service on Linux) - 5. Start/restart the VIIPER service - - === "Linux" - - ```bash - curl -fsSL https://raw.githubusercontent.com/hbashton/VIIPER/main/scripts/install.sh | sh - ``` - - Installs to: `/usr/local/bin/viiper` - - The scripts will: - - 1. Download the specified VIIPER binary version - 2. Install it to the system location - 3. Attempt to install and configure USBIP - 4. Load the `vhci_hcd` kernel module and configure it to autoload on boot - 5. Configure and run a systemd service - -=== "libVIIPER" - - libVIIPER is a shared library (`libVIIPER.dll` on Windows, `libVIIPER.so` on Linux) that you link against directly from your application, eliminating the need for a separate VIIPER server process. - - !!! warning "License" - Linking against libVIIPER requires your application to be licensed under the **GPL-3.0** (or a compatible license). - If you cannot comply with the GPL-3.0, use the standalone executable and the [TCP API](../api/overview.md) instead. All client libraries are **MIT licensed**. - - ## Pre-built Binaries - - Download the latest `libVIIPER` release artifact from the [hbashton/VIIPER Releases](https://github.com/hbashton/VIIPER/releases) page. - The archive contains: - - - `libVIIPER.dll` / `libVIIPER.so`: the shared library - - `libVIIPER.h`: the C header - - `libVIIPER.def`: Windows import definition (for generating `.lib`/`.dll.a` import libraries) - - ## Building from Source - - ```bash - git clone https://github.com/hbashton/VIIPER.git - cd VIIPER - just build-libVIIPER - ``` - - The output will be in `dist/libVIIPER/`. - - !!! info "CGO Required" - Building libVIIPER requires CGO (`CGO_ENABLED=1`) and a C compiler (GCC / MSVC / Clang) in `PATH`. - On Windows, [mingw-w64](https://www.mingw-w64.org/) or MSVC is required. - - See [libVIIPER documentation](../libviiper/overview.md) for integration guides and examples. +[Documentation index](../index.md) · [USB/IP prerequisites](usbip.md) + +## DS4Windows on Windows x64 + +Use [hbashton/DS4Windows Releases](https://github.com/hbashton/DS4Windows/releases) +and follow [the app setup guide](https://github.com/hbashton/DS4Windows/blob/main/docs/getting-started.md). +The Setup EXE includes the matching backend and driver; portable users extract +the whole package and retain its backend files. Use Settings > Install / Repair +VIIPER when requested. Restart Windows if setup asks. + +Installed copies use `%ProgramFiles%\DS4Windows\VIIPER`; portable copies keep +their backend beside DS4Windows. The app verifies the expected executable, +USB/IP files, ABI and API readiness. Avoid a separate standalone service that +competes with this ownership. + +The current upstream controller package pins usbip-win2 **0.9.7.7 x64**. Update the app, backend and driver together when a new compatible package is released. Do not replace it with another +userspace/driver version. See [USB/IP](usbip.md) for the prerequisite details +and [startup diagnostics](../startup-diagnostics.md) for failed checks. +Consult the app release notes for signing status; driver +signing and app signing are separate properties. + +## Standalone development + +The VIIPER server is a userspace executable, but Windows virtual attachment +still needs the matching kernel driver. Check +[this project's releases](https://github.com/hbashton/VIIPER/releases) for actual +available assets, or [build from source](#building-from-source). +Do not assume every operating system/architecture has a published binary. + +The legacy Windows install script is gated for deliberate standalone developer +use. Inspect `scripts/install.ps1` in your checkout before using it; it requires +`VIIPER_DEVELOPER_STANDALONE=1` and `-DeveloperStandalone`. It is not a supported +DS4Windows installation path. Ordinary users should use the app's setup/repair +controls. This checkout has no maintained `scripts/install.sh`; the former +download-and-execute instructions for that file are obsolete. + +For Linux development, use the distribution's USB/IP client and `vhci-hcd`. +See [USB/IP](usbip.md); package names, permissions and kernel availability depend +on the distribution. Run the server using [CLI configuration](../cli/configuration.md). + +## Building from source + +Use the Go version required by `go.mod` (currently **1.26.2** or a compatible +newer toolchain), and optionally `just`: + +```powershell +git clone https://github.com/hbashton/VIIPER.git +cd VIIPER +just build Release +``` + +By default, the executable is `dist/viiper.exe` on Windows or `dist/viiper` on +Linux; cross-build recipes can choose other output names. See +[Development](../development.md) for testing and generated clients. + +## libVIIPER + +libVIIPER embeds emulation in a shared library rather than a separate server. +Build it with `just build-libVIIPER Release`; this requires CGO and a compatible +C toolchain. Output is under `dist/libVIIPER/`. Do not assume the fork release +contains prebuilt shared libraries; inspect its actual assets. + +The core/library licensing differs from generated TCP clients. See +[libVIIPER](../libviiper/overview.md) and the repository licenses before embedding. diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 47937a37..8bef9aef 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -4,8 +4,8 @@ Ensure you have: -1. **USBIP installed** on your system (see [Installation](installation.md#requirements)) -2. **VIIPER binary** downloaded from [hbashton/VIIPER Releases](https://github.com/hbashton/VIIPER/releases) or [built from source](installation.md#building-from-source) +1. **USBIP installed** on your system (see [Installation](usbip.md)) +2. **VIIPER binary** downloaded from [this project's releases](https://github.com/hbashton/VIIPER/releases) or [built from source](installation.md#building-from-source) ## Starting the Server @@ -22,16 +22,16 @@ This starts two services: !!! warning "Authentication for Remote Connections" On first start, VIIPER generates a random password - and saves it to `/viiper.key.txt`. - Windows: `%APPDATA%\VIIPER\viiper.key.txt` - Linux (user): `~/.config/github.com/Alia5/viiper/viiper.key.txt` + and saves it to `/viiper.key.txt`.\ + Windows: `%APPDATA%\VIIPER\viiper.key.txt`\ + Linux (user): `~/.config/github.com/Alia5/viiper/viiper.key.txt`\ Linux (root/systemd): `/etc/viiper/viiper.key.txt` - **Localhost clients** (`127.0.0.1`, `::1`): Authentication is **optional** (but supported) - **Remote clients**: Authentication is **required** - provide the password using your client library - + All authenticated connections use **ChaCha20-Poly1305 encryption** to protect against man-in-the-middle attacks. - + You can change the password at any time by editing `viiper.key.txt`. !!! warning "USB/IP is local-only by default" @@ -41,7 +41,7 @@ This starts two services: tunnel, host firewall, or equivalent authenticated network boundary. !!! tip "Auto-attach Feature" - By default, VIIPER automatically attaches newly created devices to the local machine. You can disable this with `--api.auto-attach-local-client=false`. + By default, VIIPER automatically attaches newly created devices to the local machine. You can disable this with `--api.auto-attach-local-client=false`.\ **Linux users:** Auto-attach requires running VIIPER with `sudo` as USBIP attach operations need elevated permissions. !!! info "Custom Ports" @@ -55,7 +55,7 @@ This starts two services: ## 🎮 Creating Your First Virtual Device -VIIPER provides multiple ways to interact with the API. +VIIPER provides multiple ways to interact with the API.\ Choose the method that works best for you. ### Option 1: Using Client Libraries (Recommended) @@ -74,9 +74,9 @@ Full working examples for all device types are available in the `examples/` dire ### Example -For a minimal example, we'll be using TypeScript (as there are more Javascript devs than Insects on this planet), but you can checkout any of the examples provided in the [API Reference](../../api/overview.md) +The minimal example below uses TypeScript. Other client examples are linked from the [API Reference](../api/overview.md). -This minimal example creates a virtual Xbox 360 controller and sends an input state to press the "A" button, left bumper, half-press the left trigger, and push the left analog-stick to the right. +This minimal example creates a virtual Xbox 360 controller and sends an input state to press the "A" button, left bumper, half-press the left trigger, and push the left analog-stick to the right.\ Error handling is omitted for brevity. @@ -107,7 +107,7 @@ device.send(new Xbox360Input({ ### Option 2: Using Raw TCP -VIIPER provides a lightweight TCP API for direct interaction. +VIIPER provides a lightweight TCP API for direct interaction.\ See: [API Reference](../api/overview.md) for complete documentation. For quick testing you can use `netcat` on Linux or the provided PowerShell helper script on Windows. @@ -191,7 +191,7 @@ If auto-attach is disabled or you're connecting from a remote machine: VIIPER supports multiple virtual device types including keyboards, mice, and game controllers. Each device type has its own protocol and capabilities. -For a complete list of supported devices, their specifications, and wire protocols, see the [Devices](../devices/) documentation. +For a complete list of supported devices, their specifications, and wire protocols, see the [Devices](../devices/overview.md) documentation. ## ➡️ Next Steps @@ -243,7 +243,7 @@ sudo modprobe vhci-hcd # Or configure persistent loading (see Installation guide) ``` -See [Linux Kernel Module Setup](installation.md#linux-kernel-module-setup-for-auto-attach) for detailed setup instructions. +See [Linux Kernel Module Setup](usbip.md) for detailed setup instructions. **Windows - USBIP tool not found:** @@ -256,7 +256,7 @@ checks the live ABI before starting. **USBIP tool not found:** -Make sure USBIP is installed and in your PATH (see [Installation requirements](installation.md#requirements)). +Make sure USBIP is installed and in your PATH (see [Installation requirements](usbip.md)). **Connection refused:** diff --git a/docs/getting-started/usbip.md b/docs/getting-started/usbip.md index 6f90393e..a35a986f 100644 --- a/docs/getting-started/usbip.md +++ b/docs/getting-started/usbip.md @@ -3,16 +3,32 @@ === "Windows" VIIPER for DS4Windows requires the signed - [usbip-win2 0.9.7.7 x64 release](https://github.com/vadimgrn/usbip-win2/releases/tag/v.0.9.7.7). + [usbip-win2 0.9.7.7 x64 release](https://github.com/vadimgrn/usbip-win2/releases/tag/v.0.9.7.7) + with the matching DS4Windows-managed backend. Prefer the DS4Windows **Install / Repair VIIPER** action because it bundles - and verifies this exact package. Do not install 0.9.7.8 or substitute a + and verifies this exact package. Older DS4Windows packages require their + original dependency; update the complete DS4Windows package together. + Do not substitute a different userspace/driver build; VIIPER rejects an incompatible ABI. - !!! warning "USBIP-Win2 signing certificate" - The 0.9.7.7 installer may add the publicly available USBIP test-signing - CA as a trusted root. After installation, you may remove the certificate - named **USBIP** with `certlm.msc` (run as administrator). Keep the - 0.9.7.7 driver and userspace files installed together. + ### Replacing a different driver version + + Close games and controller tools, then use the matching DS4Windows + installer or **Install / Repair**. A driver replacement first removes the + previous package, then requires a Windows restart before installing the + new package. Run setup again after restarting. If the new driver requests + another restart, complete it before using VIIPER. + + The 0.9.7.7 x64 installer and command-line executable have a valid Cloudyne + Systems Authenticode signature. Both bundled driver binaries are signed by + Microsoft Windows Hardware Compatibility Publisher. This upgrade does not + require enabling test-signing mode or adding a test certificate. + + Windows attachments use upstream's `low-latency` WSK receive mode for + frequent controller reports. Linux attachments keep the Linux usbip tools. + The published 0.9.7.7 serial override has a known upstream bug; VIIPER leaves + it empty and retains exact endpoint/export identity checks. See the + [upstream release](https://github.com/vadimgrn/usbip-win2/releases/tag/v.0.9.7.7). === "Linux" diff --git a/docs/index.md b/docs/index.md index 6b38f70b..ce447f01 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,153 +1,39 @@ - -
- -# VIIPER 🐍 - -**Virtual** **I**nput over **IP** **E**mulato**R** - -A **cross-platform virtual USB input framework** for creating virtual USB input devices (game controllers, keyboards, mice and more) -that are indistinguishable from real hardware to the operating system and applications. - -## Quick Links - -- [Installation (VIIPER Server)](getting-started/installation.md) - - [CLI Reference](cli/overview.md) - - [API Reference](api/overview.md) -- [libVIIPER](libviiper/overview.md) -- [GitHub Repository](https://github.com/hbashton/VIIPER) - -## What is VIIPER? - -VIIPER lets developers create and programmatically control virtual USB input devices (using USBIP under the hood), -enabling seamless integration for gaming, automation, testing and remote control scenarios. - -These virtual devices are indistinguishable from real hardware to the operating system and applications. - -- Runs on Linux and Windows. -- _(Optional)_ network support built in: control devices over a network with lower overhead than raw USBIP alone. -- VIIPER abstracts away all USB / USBIP details. -- VIIPER is portable and runs entirely in userspace. - - Utilizes a generic USBIP kernel mode driver - (built into Linux; on Windows [usbip-win2](https://github.com/vadimgrn/usbip-win2) provides a signed kernel mode driver) - New device types never require touching kernel code. -- After installing USBIP once, VIIPER can run without additional dependencies or system-wide installation. - -VIIPER comes in two distinct flavors: - -- **VIIPER server** - a self-contained, (no dependencies, statically linked) portable, standalone executable - - exposing a lightweight TCP-API - - control devices from any language or machine on the network -- **libVIIPER** - a single shared library to embed device emulation directly into your application - See Examples for C and C# [here](./examples/libVIIPER) - or the [libVIIPER documentation](libviiper/overview.md) for details and examples. - -For why you should pick one over the other see the [FAQ](#why-choose-the-the-standalone-executable-and-interfacing-via-tcp-over-and-the-shared-object-libviiper-library) - -Beyond device emulation, VIIPER can proxy real USB devices for traffic inspection and reverse engineering. - -## Emulatable devices - -- Xbox 360 controller emulation; see [Devices › Xbox 360 Controller](devices/xbox360.md) -- HID Keyboard with N-key rollover and LED feedback; see [Devices › Keyboard](devices/keyboard.md) -- HID Mouse with 5 buttons and horizontal/vertical wheel; see [Devices › Mouse](devices/mouse.md) -- PS4 controller emulation; see [Devices › DualShock 4 Controller](devices/dualshock4.md) -- PS5 DualSense controller emulation (including Edge variant); see [Devices › DualSense Controller](devices/dualsense.md) -- Nintendo Switch 2 Pro Controller emulation; see [Devices › Switch 2 Pro Controller](devices/ns2pro.md) - ---- - -## 🥫 Feeder application development - -You have two options for developing feeder applications that control the virtual devices created by VIIPER: - -- Use the standalone VIIPER server and interface via the exposed TCP-API (preferably using one of the available client libraries) -- Integrate libVIIPER directly into your application. - See [libVIIPER documentation](libviiper/overview.md) for details and examples. - -### 🔌 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. - -!!! tip "Client Libraries Available" - Most of the time, you don't need to implement that raw protocol yourself, as client libraries are available. - See [Client Libraries Available](api/overview.md). - -- 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](https://datatracker.ietf.org/doc/html/rfc7807) - 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. - -!!! info "Security: Authentication & Encryption" - VIIPER **requires authentication for remote connections** - to prevent unauthorized device creation. - All authenticated connections use fast **ChaCha20-Poly1305 encryption** - to protect against man-in-the-middle attacks. - Localhost connections are exempt from authentication by default for convenience. - -See the [API documentation](api/overview) for details - ---- - -## ❓ 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 choose the standalone executable and interfacing via TCP over, and the (shared-object) libVIIPER library - -- 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 - - Allows users to idenpendently update VIIPER to receive updates and bugfixes without affecting other components or having to recompile applications themselves. - This also takes away maintenance burdens for feeder-application developers (likely you) - -### Can I use VIIPER for gaming? - -Yes! VIIPER can create virtual input devices that appear as real hardware to games and applications. - -This works with Steam, native Windows games and any other application that supports the emulated device types. - -### How is VIIPER different from other controller emulators? - -Many controller emulation approaches require writing a custom kernel driver for every device type you want to support. -VIIPER uses USBIP to handle the USB protocol layer, so device emulation code lives entirely in userspace. - -USBIP itself does require a kernel driver. -On Linux, the USBIP driver is built into the kernel. -On Windows, [usbip-win2](https://github.com/vadimgrn/usbip-win2) provides a signed kernel mode driver. -That driver is generic and does not need to know anything about specific device types. -All device-type logic stays in userspace. - -This makes VIIPER portable, easier to extend and simpler to bundle with applications. -Adding a new device type never requires touching kernel code. - -### Can I add support for other device types? - -Yes! VIIPER's architecture is designed to be extensible. - -### 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 is 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](testing/e2e_latency.md). -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. +# VIIPER documentation + +VIIPER is the USB/IP backend used by +[hbashton/DS4Windows](https://github.com/hbashton/DS4Windows). +This project continues hbashton's integration and the original Alia5 framework. + +## DS4Windows users + +Use the [matching DS4Windows package](https://github.com/hbashton/DS4Windows/releases) +and its setup/repair controls. See [Installation](getting-started/installation.md) +and [Startup diagnostics](startup-diagnostics.md). The app owns backend launch, +credentials and compatibility checks. Portable packages keep the matching +backend beside the app; installed copies use the managed installation. + +## Feeder and backend developers + +| Reference | Contents | +| --- | --- | +| [Quick start](getting-started/quickstart.md) | Standalone server and client examples | +| [Development](development.md) | Source build, tests, code generation and documentation | +| [CLI](cli/overview.md) | Server, proxy, codegen and configuration | +| [API](api/overview.md) | Bus/device management and streams | +| [Clients](clients/generator.md) | Go, C++, C#, Rust and TypeScript bindings | +| [libVIIPER](libviiper/overview.md) | Embedding device emulation | +| [Devices](devices/overview.md) | Device protocols and limits | +| [USB/IP](getting-started/usbip.md) | Driver/client prerequisites | +| [Technical records](reference.md) | Scheduling, architecture and dated validation | +| [Support](misc/support.md) | Where to report bugs and request help | + +The standalone TCP server provides management requests and per-device binary +streams. DS4Windows supplies physical input and forwards compatible feedback; +VIIPER presents virtual USB devices to the operating system. Remote connections +use the implemented authentication/encryption contract; consult the API and +configuration reference before deploying beyond localhost. + +Release history is maintained in +[CHANGELOG.md](https://github.com/hbashton/VIIPER/blob/main/CHANGELOG.md). +Dated records preserve evidence for their recorded source and hardware. They +are not current compatibility promises or instructions to install an old build. diff --git a/docs/libviiper/overview.md b/docs/libviiper/overview.md index c296fa65..bb04b64a 100644 --- a/docs/libviiper/overview.md +++ b/docs/libviiper/overview.md @@ -4,23 +4,23 @@ libVIIPER is a shared library (`libVIIPER.dll` on Windows, `libVIIPER.so` on Lin - Single shared library (`libVIIPER.dll` / `libVIIPER.so`) - Pure C API callable from any language with C FFI support -- In-process + threadsafe +- In-process + threadsafe\ the USBIP server runs in a background thread inside your application - Optional auto-attach to the local USBIP client on the same machine !!! warning "License" - libVIIPER is licensed under **GPL-3.0**. - Linking against it **requires your application to be GPL-3.0 compatible**. + libVIIPER is licensed under **GPL-3.0**.\ + Linking against it **requires your application to be GPL-3.0 compatible**.\ If your project cannot comply with the GPL-3.0, use the standalone VIIPER executable and the [TCP API](../api/overview.md) instead. All TCP client libraries are **MIT licensed**. !!! info "USBIP Required" - libVIIPER uses USBIP internally. A USBIP client must be installed on the target machine. - See [Installation › Requirements](../getting-started/installation.md#usbip) for setup instructions. + libVIIPER uses USBIP internally. A USBIP client must be installed on the target machine.\ + See [Installation › Requirements](../getting-started/usbip.md) for setup instructions. ## API Overview -The libVIIPER C API is declared in `libVIIPER.h`. -All functions return `bool` (`true` on success, `false` on failure). +The libVIIPER C API is declared in `libVIIPER.h`.\ +All functions return `bool` (`true` on success, `false` on failure).\ Handles (`USBServerHandle`, `Xbox360DeviceHandle`, …) are opaque `uintptr_t` values. ### Server lifecycle @@ -109,7 +109,7 @@ Full working examples are in [`examples/libVIIPER/`](https://github.com/hbashton ### Logging -Pass a `VIIPERLogCallback` to `NewUSBServer` to receive log messages from the library. +Pass a `VIIPERLogCallback` to `NewUSBServer` to receive log messages from the library.\ Pass `NULL` to discard all log output. ```c diff --git a/docs/misc/support.md b/docs/misc/support.md index eaca0430..ea5c74a1 100644 --- a/docs/misc/support.md +++ b/docs/misc/support.md @@ -1,23 +1,22 @@ -# Cummonity & Support +# Support and bug reports -Still stuck after reading the documentation? -No worries, there are several ways to get help from the community +[Documentation index](../index.md) · [Startup diagnostics](../startup-diagnostics.md) -## Discord +For installation, controller mapping and app UI questions, start with +[DS4Windows documentation](https://github.com/hbashton/DS4Windows/blob/main/docs/README.md). +Report app issues to [hbashton/DS4Windows](https://github.com/hbashton/DS4Windows/issues). -[![Discord](https://img.shields.io/discord/368823110817808384?logo=discord&logoColor=white&label=Discord&color=%23535fe5 -)](https://discord.gg/hs34MtcHJY) +For reproducible backend bugs, use +[hbashton/VIIPER Issues](https://github.com/hbashton/VIIPER/issues). +Search existing reports and include: -Feel free to joind the Discord server to ask for help, or a general chat and hangout with other users and the developers +- VIIPER and feeder/app version, plus source commit for development builds. +- OS and architecture, driver version, device type and physical connection. +- Reproduction steps, expected behaviour and actual result. +- Relevant diagnostics, checked for personal data and credentials. -## GitHub Discussions +Describe which hardware was tested. Keep virtual device behaviour separate from +physical-controller feedback when isolating a fault. -The repository has [Discussions](https://github.com/hbashton/VIIPER/discussions) enabled; browse existing topics or open your own. -if your search didn't bring up satisfying results - -## GitHub Issues - -Please respect that the GitHub issue tracker is a collaboration platform mainly intended for developers. -Please do not use it to ask for general support or help. -If you are absolutely sure you found a bug, you may go ahead with detailed steps on how to reproduce. -Otherwise, please use GitHub Discussions or Discord for general support. +The [DS4Windows community](https://www.reddit.com/r/DS4Windows/) can help with +general usage. This project does not claim ownership of upstream community channels. diff --git a/docs/mkdocs-readme.md b/docs/mkdocs-readme.md index c776c048..7706f424 100644 --- a/docs/mkdocs-readme.md +++ b/docs/mkdocs-readme.md @@ -1,51 +1,28 @@ -# MkDocs Documentation +# Build and preview the documentation -This directory contains the MkDocs-based documentation for VIIPER. +[Documentation index](index.md) -## Setup +Run commands from the **repository root**, where `mkdocs.yml` is located. +Use a Python virtual environment with `mkdocs-material` and `mike` installed: -Install MkDocs with Material theme: - -```bash -pip install mkdocs-material -``` - -## Development - -Run the documentation server locally: - -```bash -cd doc -mkdocs serve -``` - -Then open http://127.0.0.1:8000/ in your browser. - -## Building - -Build the static documentation site: - -```bash -cd doc -mkdocs build +```powershell +python -m venv .venv +.\.venv\Scripts\python -m pip install mkdocs-material mike +.\.venv\Scripts\python -m mkdocs serve ``` -The built site will be in the `site/` directory. - -## Deployment - -Deploy to GitHub Pages: +Open the local address printed by MkDocs. On Linux, use `.venv/bin/python`. -```bash -cd doc -mkdocs gh-deploy +```powershell +.\.venv\Scripts\python -m mkdocs build ``` -## Documentation Structure +The generated site is written to `site/`; do not commit it as source. Review +build warnings and check new navigation targets. `docs/` holds the maintained +pages; `mkdocs.yml` controls navigation. Repository-level licenses, source tools +and CHANGELOG.md are linked on GitHub where appropriate. -- `mkdocs.yml` - MkDocs configuration -- `docs/` - Documentation source files (Markdown) - - `index.md` - Home page - - `getting-started/` - Installation and quick start - - `cli/` - CLI reference - - `api/` - API reference +The Deploy Documentation workflow publishes versioned main/tag pages using +`mike`. It also generates commit changelogs for those versions. Those generated +commit lists are distinct from the curated release history in CHANGELOG.md. +Do not run a manual deployment as part of an ordinary documentation edit. diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 00000000..927242b7 --- /dev/null +++ b/docs/reference.md @@ -0,0 +1,47 @@ +# Technical records + +[Documentation index](index.md) + +Architecture documents describe contracts, research decisions and dated validation. +Records marked historical retain their original source/hardware evidence and limits. +Do not infer current platform qualification from an older experiment. + +## Architecture + +- [Authenticated transport direction review, 2026-09-02](architecture/authenticated-transport-direction-review-2026-09-02.md) +- [Controller platform audit, 2026-08-29](architecture/controller-platform-audit-2026-08-29.md) +- [Controller platform source checkpoint, 2026-09-06](architecture/controller-platform-checkpoint-2026-09-06.md) +- [Controller platform execution checklist](architecture/controller-platform-execution-checklist.md) +- [Controller platform provenance ledger, 2026-08-29](architecture/controller-platform-provenance-ledger-2026-08-29.md) +- [Controller platform validation status, 2026-08-29](architecture/controller-platform-validation-2026-08-29.md) +- [Controller platform validation status, 2026-08-30](architecture/controller-platform-validation-2026-08-30.md) +- [Controller platform validation status, 2026-08-31](architecture/controller-platform-validation-2026-08-31.md) +- [Controller platform validation status, 2026-09-01](architecture/controller-platform-validation-2026-09-01.md) +- [Controller platform validation status, 2026-09-02](architecture/controller-platform-validation-2026-09-02.md) +- [Controller platform validation status, 2026-09-03](architecture/controller-platform-validation-2026-09-03.md) +- [Controller platform validation status, 2026-09-04](architecture/controller-platform-validation-2026-09-04.md) +- [Primary GIP identity must survive asynchronous native retirement](architecture/gip-primary-identity-retirement-2026-09-06.md) +- [Native presentation decision package, 2026-08-29](architecture/native-presentation-decision-package-2026-08-29.md) +- [Native UdeCx ABI landing zone](architecture/native-udecx-abi.md) +- [RC4.5 candidate release preparation, 2026-09-08](architecture/rc4.5-candidate-release-preparation-2026-09-08.md) +- [Dormant Stage-B retained USB submission boundary](architecture/retained-usb-submission-stage-b-design.md) +- [VIIPER tray startup recovery validation — 2026-09-08](architecture/viiper-tray-startup-validation-2026-09-08.md) +- [Xbox One canonical downstream packet batch (dormant)](architecture/xbox-one-canonical-downstream-packet-batch-2026-08-31.md) +- [Dormant authorized Xbox retained-USB composition (2026-08-31)](architecture/xbox-one-dormant-authorized-retained-composition-2026-08-31.md) +- [Xbox One dormant duplex boundary audit](architecture/xbox-one-dormant-duplex-boundary-2026-08-30.md) +- [Dormant Xbox external-identity gate](architecture/xbox-one-dormant-external-identity-gate-2026-08-31.md) +- [Xbox One dormant interrupt-OUT packet adapter](architecture/xbox-one-dormant-interrupt-out-packet-adapter-2026-08-31.md) +- [Xbox One dormant receive-framing gate](architecture/xbox-one-dormant-receive-framing-gate-2026-08-31.md) +- [Dormant Xbox retained EP0 254-byte response capacity (2026-08-31)](architecture/xbox-one-dormant-retained-ep0-capacity-2026-08-31.md) +- [Xbox persona late-admission transport coordinator](architecture/xbox-one-persona-transport-coordinator.md) +- [Xbox One/Series offline persona to USB/IP adapter audit](architecture/xbox-one-usbip-adapter-audit-2026-08-29.md) +- [Xbox One/Series presentation through USB/IP: feasibility decision](architecture/xbox-one-usbip-feasibility.md) + +## Scheduling and provenance + +- [USB scheduling](https://github.com/hbashton/VIIPER/blob/main/internal/server/usb/SCHEDULING.md) +- [DualSense scheduling](https://github.com/hbashton/VIIPER/blob/main/device/dualsense/SCHEDULING.md) +- [DualSense rear resampler](dualsense-rear-resampler.md) +- [Xbox One specification](https://github.com/hbashton/VIIPER/blob/main/device/xboxone/SPEC.md) +- [Xbox One provenance](https://github.com/hbashton/VIIPER/blob/main/device/xboxone/PROVENANCE.md) +- [Tray component notice](https://github.com/hbashton/VIIPER/blob/main/internal/tray/systray/README.viiper.md) diff --git a/docs/release-notes-v0.1.6-rc4.6.4.md b/docs/release-notes-v0.1.6-rc4.6.4.md deleted file mode 100644 index 0bd6ebc6..00000000 --- a/docs/release-notes-v0.1.6-rc4.6.4.md +++ /dev/null @@ -1,19 +0,0 @@ -# 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! diff --git a/docs/release-notes-v0.1.7-rc4.6.5.md b/docs/release-notes-v0.1.7-rc4.6.5.md deleted file mode 100644 index 8e9f590b..00000000 --- a/docs/release-notes-v0.1.7-rc4.6.5.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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! diff --git a/docs/release-notes-v0.1.9-rc4.6.6.md b/docs/release-notes-v0.1.9-rc4.6.6.md deleted file mode 100644 index b48d5b3a..00000000 --- a/docs/release-notes-v0.1.9-rc4.6.6.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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! diff --git a/mkdocs.yml b/mkdocs.yml index 04efcea0..591c1b9d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,6 +60,8 @@ nav: - Getting Started: - Installation: getting-started/installation.md - Quick Start: getting-started/quickstart.md + - USB/IP Prerequisites: getting-started/usbip.md + - Startup Diagnostics: startup-diagnostics.md - CLI Reference: - Overview: cli/overview.md - Server Command: cli/server.md @@ -74,20 +76,18 @@ nav: - Rust Client Library: clients/rust.md - TypeScript Client Library: clients/typescript.md - Generator Documentation: clients/generator.md -- libVIIPER: - - Overview: libviiper/overview.md - - Xbox 360 Controller: devices/xbox360.md - - DualShock 4: devices/dualshock4.md - - DualSense: devices/dualsense.md - - Switch 2 Pro Controller: devices/ns2pro.md - - Keyboard: devices/keyboard.md - - Mouse: devices/mouse.md +- libVIIPER: libviiper/overview.md - Devices: + - Overview: devices/overview.md - Xbox 360 Controller: devices/xbox360.md - DualShock 4 Controller: devices/dualshock4.md - DualSense Controller: devices/dualsense.md - Switch 2 Pro Controller: devices/ns2pro.md - Keyboard: devices/keyboard.md - Mouse: devices/mouse.md +- Development: + - Build and Test: development.md + - Documentation Site: mkdocs-readme.md +- Technical Records: reference.md - Community & Support: misc/support.md -- Changelog: changelog/ +- Release History: https://github.com/hbashton/VIIPER/blob/main/CHANGELOG.md