DOCSEARCHbyAlgolia
Submit Docs

DsHidMini Documentation

repository·master·Indexed 22 days ago

https://github.com/nefarius/dshidmini

A user-mode (UMDF) driver for Windows 10 and 11 that enables Sony DualShock 3 controllers to function as configurable HID devices. It supports various emulation modes including XInput, DualShock 4, and Sixaxis over USB and Bluetooth (via BthPS3). The project includes a ControlApp for managing device settings, profiles, and LEDs, as well as a portable Control Utility (DSHMC) and an XInput Bridge.

Tokens
19.2K
Snippets
31
Records
74
Agent score
80%

What's inside DsHidMini

  1. Overview of DsHidMini

    master

    DsHidMini is a user-mode (UMDF) driver for Windows 10/11 that allows Sony DualShock 3 controllers to be used as configurable, standard-compliant HID devices. It supports both USB and Bluetooth (when used with BthPS3).

    Key capabilities include:

    • HID Modes: Supports single Gamepad (with pressure-sensitive buttons), split/multi-device, Sony sixaxis emulation, DualShock 4 emulation (for use with DS4Windows), and Xbox/XInput emulation.
    • Input APIs: Controllers can be accessed via DirectInput, Raw Input, the HID API, or XInput (using the optional XInput Bridge).
    • Features: Rumble is exposed as Force Feedback, and LEDs indicate battery status (1–4).
    • Compatibility: Works with PCSX2, RPCS3, DS4Windows (v2.2.10+), RetroArch, x360ce, Dolphin, and DuckStation.

  2. Overview of DsHidMini Control Utility (DSHMC)

    master
    DsHidMini Control Utility (DSHMC) is a portable, single-executable .NET Framework 4.6 application designed to read and alter DsHidMini driver properties. It serves as a management interface for the DsHidMini driver.

  3. What is XInput Bridge and how to use it

    master

    XInput Bridge is a drop-in XInput proxy DLL designed for use with DsHidMini. It functions by replacing XInput1_3.dll in a game or application directory.

    How it works:

    • DsHidMini DS3 pads (in SXS mode): The bridge intercepts these devices via HIDAPI, maps them to standard XInput state/rumble, and optionally exposes extended pressure-sensitive data.
    • Real Xbox/XInput devices: The bridge transparently forwards these calls to the system's actual C:\Windows\System32\XInput1_3.dll.

    Deployment: To use it, deploy the compiled XInput1_3.dll next to a game executable or use a loader like x360ce to ensure the application loads the bridge instead of the system DLL.

  4. Overview of the DsHidMini Driver

    master

    DsHidMini is a user-mode filter driver for Sony DualShock 3 controllers. It functions as a kernel component that presents the controller as various configurable HID devices, including GamePad, Joystick, Sixaxis, DS4, and XInput modes, over both USB and Bluetooth.

    Key Technical Details

    • Framework: Uses the UMDF (User-Mode Driver Framework).
    • Core HID Handling: Utilizes DMF Virtual Hid Mini for virtual HID report handling.
    • Transports: Supports USB via DsUsb and Bluetooth via DsBth (which requires BthPS3).
    • Configuration: Managed via a JSON configuration file and IPC (memory-mapped file) used by the configuration application.

  6. Ensure thread safety when using DsHidMiniInterop

    master

    The IPC mechanism is single-threaded. Only one thread may perform an IPC operation at a time. If multiple threads attempt to call methods like SetHostAddress or GetRawInputReport concurrently, the SDK will throw a DsHidMiniInteropConcurrencyException.

    Best Practice: Serialize all calls to the DsHidMiniInterop instance. Use a dedicated background thread for all IPC operations or wrap calls in a synchronization primitive like a lock.

  7. Understand device indexing and discovery

    master

    The SDK uses a one-based device index (range 1 to 255) representing the driver's IPC slot (SlotIndex).

    Important Discovery Notes:

    • Do not assume that the order of devices returned by SetupAPI or CM_Get_Device_Interface_List matches the slot order.
    • If a device in the middle of a sequence disconnects, remaining devices may occupy non-contiguous slots (e.g., slots 1 and 3).
    • To find the correct index, query the read-only device property DsHidMiniDriver.IpcSlotIndexProperty (DEVPROP_TYPE_UINT32) for each PnPDevice interface.
    • If the property is missing (older drivers), you must use your own mapping logic.

  8. How to integrate PID descriptor sections

    master

    The Physical Interface Device (PID) implementation is split into multiple logically grouped header files to manage the complexity of large HID Report Descriptors. These files contain raw byte arrays and comments designed to be included directly into an existing HID Report Descriptor structure.

    Key Integration Rules:

    • Include Order: The numeric prefixes in the filenames (e.g., 01_..., 02_...) indicate the required order of inclusion, not the Report IDs.
    • No Include Guards: The header files do not contain include guards because they are intended to be embedded as raw data within a larger descriptor structure.
    • Data Format: Files contain raw byte arrays formatted for direct inclusion.

  9. Build DsHidMini from source

    master

    To build the project from the repository root, you can use the provided batch script or open the solution file in Visual Studio:

    build.cmd

    Or open dshidmini.sln in Visual Studio.

    Note that specific build steps for the driver and the XInput Bridge are located in their respective directories:

    • Driver build details: driver/README.md
    • XInput Bridge build details: XInputBridge/README.md

  10. Create a production release for DsHidMini

    master

    To generate a production release, follow these steps from the solution root directory:

    1. Build via CI: Tag a release to trigger the "Build" GitHub Actions workflow.
    2. Download Artifacts: Authenticate with the GitHub CLI (gh auth login with repo scope) and use the Nuke build system to download the tagged release artifacts using the workflow run ID:
      nuke download-ci-artifacts -buildversion "<workflow-run-id>"
    3. Signing:
      • Submit the *.cab files to the MS Partner Portal for signing.
      • Place the signed files in the .\artifacts\drivers directory.
      • Apply EV signatures to binaries using Nuke:
        nuke sign-production-binaries
    4. Build MSI: Build and sign the MSI package with a specific version:
      nuke build-setup -setupversion "3.6.0"
    5. Publish: Create a public GitHub release and tag the setup with the format setup-v<version> (e.g., setup-v3.6.0).
    nuke download-ci-artifacts -buildversion "<workflow-run-id>"
nuke sign-production-binaries
nuke build-setup -setupversion "3.6.0"

  11. Install the Nefarius.DsHidMini.IPC SDK

    master

    Install the SDK via NuGet to connect your .NET 8 Windows application to the DsHidMini driver using shared memory and named synchronization objects.

    Requirements:

    • .NET: .NET 8.0 (target net8.0-windows)
    • OS: Windows
    • Driver: DsHidMini driver must be installed and at least one compatible controller must be connected.

    Note: Elevation is not required for normal use.

    dotnet add package Nefarius.DsHidMini.IPC

  12. Build DsHidMini ControlApp

    master

    You can build the application using the dotnet CLI. Run these commands from the ControlApp folder or the repository root.

    Standard Build:

    dotnet build

    Release Build:

    dotnet build -c Release

    Solution Build (from repo root):

    dotnet build ControlAppSolution.sln