# dorssel/usbipd-win architecture

> Architecture diagram of the GitHub repository dorssel/usbipd-win, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dorssel/usbipd-win
- Repository: https://github.com/dorssel/usbipd-win

## Overview

##### Project Type and Purpose
- This is a Windows system service (daemon) that enables USB device sharing from a Windows host (including Hyper-V and WSL 2 setups) to remote clients (such as Linux systems).
- Its purpose is to allow locally connected USB devices to be shared and used on other machines using standard USB/IP protocols.
- The README confirms that the system is installed as a Windows service (usbipd) along with a CLI tool, integrated PowerShell module support, and installation of device drivers.

##### Analysing the File Structure
- Notice directories like “Drivers” (with platform-specific folders for x64 and ARM64) that contain the low-level drivers (e.g., VBoxUSB.sys, VBoxUSBMon.sys). This indicates that the service interacts directly with Windows kernel drivers.
- The “Installer” folder contains WiX project files and WXS source files, which means the system deploys a robust installation package—installing the service, drivers, and additional components.
- The “Usbipd” directory (and its subprojects “Usbipd.Automation” and “Usbipd.PowerShell”) contains the core business logic, command handling, and integration for CLI and PowerShell interfaces used for device sharing.
- The “UnitTests” folder shows comprehensive testing on many aspects (binding, USB device operations, parsing, etc.), supporting the core functionalities.
- Build and configuration files (like Directory.Build.props, .editorconfig, GitHub workflows, etc.) indicate that this project is structured as a .NET application with continuous integration.

To represent the overall architecture accurately, consider the following components and their interactions:

A. Main Components:
- Windows Service (usbipd):
– Core daemon that listens for device sharing commands and manages USB device binding.
– Implements the backend logic for communication with external clients via TCP port (default 3240).
- USB Device Drivers:
– Include the x64 and ARM64 drivers stored in the Drivers directory.
– Provide low-level interaction with the USB hardware.
- Command-Line Interface (CLI) Tool:
– The “usbipd” command tool, which users invoke (with administrator privileges or not, depending on the operation) to list, bind, or attach devices.
- PowerShell Module:
– Located in Usbipd.PowerShell, offering additional scripting and automation capabilities, especially for configuration and installation management.
- Installer Package:
– Built with WiX (located in the Installer directory), the installer handles deployment of the service, drivers, firewall rules, and CLI tool.
- External USBIP Client(s):
– These are devices (for example, Linux systems or other operating systems) that use the USB/IP client protocol to attach to the host’s shared devices.
- WSL 2 Integration:
– Special support (via an internal WSL folder and accompanying scripts) allowing seamless USB device sharing into Microsoft’s Windows Subsystem for Linux.

B. Relationships and Data Flow:
- The Installer deploys the service, drivers, CLI tool, and configures firewall rules.
- The Windows Service (usbipd) runs in the background and interacts directly with the USB device drivers to make connected devices available.
- The CLI and PowerShell interfaces are used by local administrators to control the binding, listing, and attaching of USB devices (i.e., making changes that the service then enacts).
- External clients communicate with the service via network (TCP port 3240) to request attached USB devices.
- There is a feedback loop where the service notifies the client (or manages the state) based on device actions (bind, attach, detach, etc.).

C. Architectural Patterns and Technologies:
- Layered Architecture: Separates the installer/deployment, service (backend logic), and user interfaces (CLI/PowerShell) from the driver level.
- Client-Server Communication: Demonstrated by the TCP-based protocol handling remote USB device attachments.
- Use of .NET for service and tooling implementation.
- WiX Toolset for installer creation.
- Cross-platform considerations (touching on ARM64, x64, and even WSL interactions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Deployment"
        I("Installer (WiX)"):::installer
    end

    subgraph "Drivers Layer"
        D1("USB Device Drivers (x64)"):::driver
        D2("USB Device Drivers (ARM64)"):::driver
    end

    subgraph "Windows Host Components"
        WS("Windows Service (usbipd)"):::service
        CLI("CLI Tool (usbipd)"):::cli
        PS("PowerShell Module"):::powershell
        WSL("WSL 2 Integration"):::wsl
    end

    E("External USB/IP Client"):::external

    %% Relationships
    I -->|"deploys"| WS
    I -->|"deploys"| D1
    I -->|"deploys"| D2
    I -->|"deploys"| WSL

    CLI -->|"controls"| WS
    PS -->|"controls"| WS

    WS -->|"manages"| D1
    WS -->|"manages"| D2

    WSL -->|"integrates"| WS

    E -->|"TCP:3240_request"| WS
    WS -->|"status_updates"| E

    %% Click Events
    click WS "https://github.com/dorssel/usbipd-win/blob/master/Usbipd/Program.cs"
    click D1 "https://github.com/dorssel/usbipd-win/tree/master/Drivers/x64"
    click D2 "https://github.com/dorssel/usbipd-win/tree/master/Drivers/arm64"
    click CLI "https://github.com/dorssel/usbipd-win/blob/master/Usbipd/CommandHandlersCli.cs"
    click PS "https://github.com/dorssel/usbipd-win/blob/master/Usbipd.PowerShell/GetUsbipdDevice.cs"
    click I "https://github.com/dorssel/usbipd-win/blob/master/Installer/Installer.wixproj"
    click WSL "https://github.com/dorssel/usbipd-win/blob/master/Usbipd/WSL/auto-attach.sh"

    %% Styles
    classDef installer fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef service fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef cli fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef powershell fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef driver fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef external fill:#FF6347,stroke:#333,stroke-width:2px;
    classDef wsl fill:#40E0D0,stroke:#333,stroke-width:2px;
```
