HIDMaestro

https://hidmaestro.org/docs
Admin
HIDMaestro is a C# SDK and UMDF2 driver for Windows that enables applications to create, emulate,...
Tokens:159,707
Snippets:1,023
Trust Score:3.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize Virtual Controller

Source: https://hidmaestro.org/docs/start/installation

A minimal example to load profiles, install the driver, and create a virtual controller. The controller is automatically removed when the scope ends.

```csharp
using var ctx = new HMContext();
ctx.LoadDefaultProfiles();
ctx.InstallDriver();
using var ctrl = ctx.CreateController(ctx.GetProfile("xbox-360-wired")!);
ctrl.SubmitState(new HMGamepadState
{
    Axes = HMGamepadStateHelpers.StandardAxes(ctrl.Profile, leftStickX: 1.0f),
});
```

--------------------------------

### Check and install USB/IP backend

Source: https://hidmaestro.org/docs/sdk/usb-audio-composite

Two optional APIs: check if the transport is already installed via HMContext.IsUsbipBackendAvailable, and perform the one-time install with progress reporting via HMContext.InstallUsbipBackend. Both are idempotent and not required for CreateController.

```csharp
// Informational: has this machine already got the transport?
bool ready = HMContext.IsUsbipBackendAvailable;

// Do the one-time install now (onboarding step, settings toggle) instead
// of on the first composite create. Idempotent.
HMContext.InstallUsbipBackend(status => Console.WriteLine(status));

```

--------------------------------

### Create a composite persona with HMContext

Source: https://hidmaestro.org/docs/sdk/usb-audio-composite

Shows the minimal setup to create a composite controller: load default profiles, install the driver, and create the controller using the 'dualsense-composite' profile. Requires elevation for InstallDriver.

```csharp
using var ctx = new HMContext();
ctx.LoadDefaultProfiles();
ctx.InstallDriver();

using var ctrl = ctx.CreateController(ctx.GetProfile("dualsense-composite")!);

```

--------------------------------

### Cold-start flow process and timing

Source: https://hidmaestro.org/docs/reference/driver-install-and-signing

A breakdown of the HIDMaestro installation pipeline steps and their approximate execution times on a clean development machine.

```text
Process A:                                           Time
─────────────────────────────────────────────       ────
1.  using var ctx = new HMContext();                ~10 ms
       Background prewarm tasks fire-and-forget
2.  ctx.LoadDefaultProfiles();                      ~100 ms
       Parse 228 embedded JSONs
3.  ctx.InstallDriver();                            ~1.7 s on a clean machine
       3a. RemoveAllVirtualControllers (no-op)        ~50 ms
       3b. Compute hash, IsDriverInstalled? no       <50 ms
       3c. Extract embedded payload to %TEMP%         ~20 ms
       3d. Remove any prior package (idempotent)     ~100 ms
       3e. Generate self-signed cert (first-ever)    ~500 ms (one-time per machine)
       3f. Install cert to Root + TrustedPublisher    ~50 ms (one-time per machine)
       3g. Sign DLLs + INFs (signtool, batched)      ~130 ms
       3h. Generate .cat catalogs (Inf2Cat, batched) ~840 ms (largest single step, AV-sensitive)
       3i. pnputil /add-driver, both INFs            ~580 ms total
       3j. Delete %TEMP% extraction                   <50 ms
       3k. Write marker file                          <1 ms
4.  ctx.CreateController(profile);                  ~200-700 ms
       SetupController for one Xbox 360 Wired
─────────────────────────────────────────────       ────
                                            Total: ~2.5-3 s on a clean dev machine
                                                   ~5-20 s on a corporate workstation
                                                       (PnP tree depth scales pnputil)
```

--------------------------------

### Run SDK consumer and test application

Source: https://hidmaestro.org/docs/start/installation

Commands to run the SDK consumer example and the full test application for emulation.

```batch
:: Smallest possible SDK consumer (5 seconds)
dotnet run --project example\SdkDemo

:: Full test app (admin required for create; cleans up on exit)
dotnet build test
test\bin\Release\net10.0-windows10.0.26100.0\win-x64\HIDMaestroTest.exe emulate xbox-360-wired
```

--------------------------------

### Populating HMGamepadState Axes

Source: https://hidmaestro.org/docs/sdk/sdk-reference

Example of populating the Axes dictionary for a HOTAS setup. Values are normalized to [0.0, 1.0].

```csharp
// HOTAS with stick + slider + rudder + throttle, all in one dict
state.Axes = new Dictionary<HMAxis, float>
{
    [HMAxis.X]        = 0.55f,   // stick X, slightly right of center
    [HMAxis.Y]        = 0.35f,   // stick Y, slightly below center
    [HMAxis.Slider]   = 0.75f,   // throttle slider
    [HMAxis.Rudder]   = 0.25f,   // rudder pedal
    [HMAxis.Throttle] = 1.00f,   // secondary throttle full
};
```

--------------------------------

### CreateController(HMProfile profile)

Source: https://hidmaestro.org/docs/sdk/sdk-reference

Creates a new HMController with the next free index, runs the full setup orchestration, and returns a live controller. Requires admin.

```APIDOC
## CreateController(HMProfile profile)

### Description
Allocates the next free controller index, runs the per-archetype setup orchestration, and returns a live HMController ready to receive input. Requires admin.

### Method
CreateController

### Parameters
- **profile** (HMProfile) - Required - The profile to use for the controller. Must not be null and must have a descriptor.

### Return Value
- **HMController** - A live controller instance.

### Exceptions
- **ArgumentNullException** - If `profile` is null.
- **ArgumentException** - If the profile has no descriptor (not deployable).
- **InvalidOperationException** - If device-node creation fails or the driver install fails.

### Remarks
The returned controller is live. Dispose it to remove the device, or dispose the entire context to remove all controllers it owns.
```

--------------------------------

### HID Maestro Suffix Mapping Example

Source: https://hidmaestro.org/docs/reference/swdevice-and-pnp

An example showing the naming convention for HID Maestro virtual devices, including controller index, device type, and sequence numbers.

```text
SWD\HIDMAESTRO\A7B40001_0000   ← controller 0 (Xbox 360 Wired companion), seq=1
SWD\HIDMAESTRO\A7B40002_0001   ← controller 1 (Xbox Series BT main HID), seq=2
SWD\HIDMAESTRO_VID_045E_PID_0B13&IG_00\A7B40002_0001    ← (xinputhid path uses different enumerator)
SWD\HIDMAESTRO\A7B40003_0002   ← controller 2 (DualSense), if it had a companion (it doesn't)
...
```

--------------------------------

### FullDeploy steps

Source: https://hidmaestro.org/docs/reference/driver-install-and-signing

Numbered list of steps performed by FullDeploy. Idempotent: if payload hash matches installed, returns immediately. Requires admin; otherwise UnauthorizedAccessException.

```text
1. Compute payload hash (SHA-256 of every embedded resource)
2. IsDriverInstalled? → check DriverStore for matching hash → if yes, return
3. EnsureExtracted: extract embedded resources to %TEMP%\HIDMaestro\<hash>\
4. Generate self-signed certificate if not in Cert:\LocalMachine\Root
5. Install certificate to Cert:\LocalMachine\Root and \TrustedPublisher
6. Generate .cat catalogs via Inf2Cat for both INFs
7. Sign HIDMaestro.dll, HMXInput.dll, hmswd.exe, both .cat files
8. pnputil /add-driver hidmaestro.inf /install
9. pnputil /add-driver hidmaestro_xusb.inf /install
10. Delete %TEMP%\HIDMaestro\<hash>\ (leave nothing behind)

```

--------------------------------

### HMContext.InstallDriver

Source: https://hidmaestro.org/docs/sdk/sdk-reference

Installs the embedded driver files, generating and installing a self-signed code-signing certificate, signing the binaries, and registering them with pnputil. Requires admin.

```APIDOC
## HMContext.InstallDriver

### Description
Extracts the embedded driver files to %TEMP%, generates/installs a self-signed code-signing certificate, signs the binaries, and registers them with pnputil. Idempotent — if the same hash is already installed, returns immediately. The temp extraction is deleted on success. Requires admin.

### Method
Method

### Endpoint
`public void InstallDriver()`

### Parameters
None.

### Throws
- **UnauthorizedAccessException** - If the process is not elevated.
- **InvalidOperationException** - If any signing or pnputil step fails.

### Remarks
- Always runs `RemoveAllVirtualControllers` first as a self-heal so a stale INF can't pin the install.
```

--------------------------------

### Install drivers with pnputil /add-driver

Source: https://hidmaestro.org/docs/reference/driver-install-and-signing

Adds and installs HIDMaestro INF drivers to the DriverStore. The /install flag makes the driver boot-critical and loadable; without it the driver is only staged. Requires admin and returns exit code 0 on success, non-zero on failure. A partial match with an existing package can trigger integrity verification errors that the self-heal sweep prevents.

```batch
pnputil /add-driver hidmaestro.inf /install
pnputil /add-driver hidmaestro_xusb.inf /install

```

--------------------------------

### Driver Lifecycle Methods

Source: https://hidmaestro.org/docs/sdk/sdk-reference

Methods for checking driver status, installing the driver (requires admin), and removing all virtual controllers from the system.

```csharp
public bool IsDriverInstalled { get; }
public void InstallDriver();
public static void RemoveAllVirtualControllers();
```

--------------------------------

### ActiveControllers

Source: https://hidmaestro.org/docs/sdk/sdk-reference

Gets a snapshot of all live controllers owned by this context, in creation order.

```APIDOC
## ActiveControllers

### Description
Returns a snapshot of every live controller this context owns, in creation order.

### Property Type
- **IReadOnlyCollection<HMController>** - A read-only collection of live controllers.
```

--------------------------------

### XInput slot-1-skip output example

Source: https://hidmaestro.org/docs/reference/swdevice-and-pnp

Shows the observed output when the slot-1-skip bug occurs: slot 0 is empty while slots 1-3 are assigned. This is the reported behavior from consumers.

```text
Slot 0: NOT CONNECTED
Slot 1: HM-CTL-0001 (Xbox 360 Wired)
Slot 2: NOT CONNECTED
Slot 3: NOT CONNECTED

```

--------------------------------

### HMVR.SteamVRPath

Source: https://hidmaestro.org/docs/sdk/vr-controllers

Gets the file system path to the SteamVR installation.

```APIDOC
## HMVR.SteamVRPath

### Description
Gets the file system path to the SteamVR installation.

### Property
`public static string? SteamVRPath { get; }`

### Returns
- **string?** - The path to the SteamVR installation, or `null` if not available.
```

--------------------------------

### Run the SDK Demo

Source: https://hidmaestro.org/docs/start/quickstart

Execute the minimal SDK consumer to verify virtual controller creation and rumble capture.

```bash
dotnet run --project example\SdkDemo
```

--------------------------------

### HMVR.IsSteamVRInstalled

Source: https://hidmaestro.org/docs/sdk/vr-controllers

Gets a value indicating whether SteamVR is installed.

```APIDOC
## HMVR.IsSteamVRInstalled

### Description
Gets a value indicating whether SteamVR is installed.

### Property
`public static bool IsSteamVRInstalled { get; }`

### Returns
- **bool** - `true` if SteamVR is installed; otherwise, `false`.
```

--------------------------------

### Non-sentinel pContainerId for SwDeviceCreate

Source: https://hidmaestro.org/docs/reference/swdevice-and-pnp

The GUID format passed as pContainerId to SwDeviceCreate to fix the bug. The base GUID decodes to ASCII 'HIDMAESTRO' plus a 16-bit big-endian controller index appended, so each controller gets a unique non-sentinel ID.

```text
{48494430-4D41-4553-5452-4F0000000000}    // base
                              ^^^^ ← 16-bit controller index appended

```

--------------------------------

### Force-kill recovery self-heal example

Source: https://hidmaestro.org/docs/reference/lifecycle-and-teardown

Shows the self-heal sequence when a new process starts after a crash. The HMContext constructor does not sweep, but InstallDriver triggers RemoveAllVirtualControllers to clean up orphaned controllers from the previous process.

```csharp
// Process A creates 3 controllers, then crashes
// Process B starts:
using var ctx = new HMContext();   // constructor doesn't sweep yet
ctx.InstallDriver();   // ← RemoveAllVirtualControllers runs here, sweeps process A's orphans
ctrl0 = ctx.CreateController(...);   // fresh state
```

--------------------------------

### Build phases overview

Source: https://hidmaestro.org/docs/reference/build-and-release

A breakdown of the four phases executed by build_all.cmd, including native compilation, INF stamping, and SDK resource packaging.

```text
Phase 1: Native driver
  scripts\build.cmd
  → cl.exe driver.c, companion.c, hmswd.c
  → link.exe → build\HIDMaestro.dll, build\HMXInput.dll, build\hmswd.exe
  → scripts\stamp_inf.ps1 hidmaestro.inf → build\hidmaestro.inf
  → scripts\stamp_inf.ps1 hidmaestro_xusb.inf → build\hidmaestro_xusb.inf

Phase 2: Native companion (separate build script for parallelism)
  scripts\build_companion.cmd
  → cl.exe companion.c → build\HMXInput.dll
  (Note: build.cmd builds the main + hmswd; build_companion.cmd builds only HMXInput)

Phase 3: SDK build #1 — populates Resources/ from build/
  dotnet build sdk\HIDMaestro.Core\HIDMaestro.Core.csproj
  → PackResources MSBuild target copies build/* into sdk/HIDMaestro.Core/Resources/
  → embedded resource glob picks them up
  → output: sdk\HIDMaestro.Core\bin\Release\net10.0-windows10.0.26100.0\HIDMaestro.Core.dll

Phase 4: SDK build #2 — embeds fresh driver bytes
  dotnet build sdk\HIDMaestro.Core\HIDMaestro.Core.csproj
  → PackResources rebuilds Resources/ (idempotent)
  → embedded resource glob has fresh content
  → output: HIDMaestro.Core.dll with current driver bytes embedded
```

--------------------------------

### Configure Target Framework and Platform

Source: https://hidmaestro.org/docs/start/installation

Set the target framework and platform in your csproj file. Note that only x64 is supported.

```xml
<PropertyGroup>
  <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>
  <Platforms>x64</Platforms>
</PropertyGroup>
```

--------------------------------

### Create a custom HOTAS device profile

Source: https://hidmaestro.org/docs/sdk/hid-descriptor-builder

This example demonstrates how to use HidDescriptorBuilder to define device capabilities and HMProfileBuilder to create a profile, followed by initializing the controller and handling FFB output.

```csharp
var desc = new HidDescriptorBuilder()
    .Joystick()                       // Joystick TLC for FFB compatibility
    .AddStick("Left", 16)             // primary X/Y
    .AddTrigger("Left", 8)             // throttle
    .AddTrigger("Right", 8)            // brake
    .AddButtons(20)                    // 20 buttons (rounded up to 24)
    .AddHat(positions: 16)             // 22.5° hat
    .AddPidFfbBlock();                 // full PID FFB

var profile = new HMProfileBuilder()
    .Id("custom-hotas-stick")
    .Name("Custom HOTAS Stick")
    .Vendor("MyCo")
    .Vid(0x0483).Pid(0x5740)
    .ProductString("Custom HOTAS")
    .Type("hotas")
    .Connection("usb")
    .FromDescriptorBuilder(desc)       // descriptor bytes + correct InputReportSize
    .Build();

using var ctx = new HMContext();
ctx.LoadDefaultProfiles();
ctx.InstallDriver();
using var ctrl = ctx.CreateController(profile);

// FFB now works: declare pool, drive any DirectInput game with this virtual
ctrl.PublishPidPool(ramPoolSize: 0x0400,
                    simultaneousEffectsMax: 16,
                    deviceManagedPool: false,
                    sharedParameterBlocks: false);

// Wire output to your physical HOTAS
ctrl.OutputReceived += (sender, packet) => RouteFFBToHardware(packet);

// 16-position hat at full descriptor resolution
ctrl.SubmitState(new HMGamepadState { HatDegrees = 22.5f });
```

--------------------------------

### Run one-shot build

Source: https://hidmaestro.org/docs/reference/build-and-release

Execute the build_all.cmd script from the HIDMaestro directory to trigger the full build process.

```batch
cd HIDMaestro
scripts\build_all.cmd
```

--------------------------------

### Install the HIDMaestro driver

Source: https://hidmaestro.org/docs/start/quickstart

Installs the driver idempotently. Requires elevated privileges and throws UnauthorizedAccessException if not elevated, or InvalidOperationException if signing or pnputil steps fail.

```csharp
ctx.InstallDriver();
```

--------------------------------

### Example usage of DisposeControllersInParallel

Source: https://hidmaestro.org/docs/reference/lifecycle-and-teardown

Example call to DisposeControllersInParallel with four controllers and a callback that logs each controller's profile ID and disposal time in milliseconds.

```csharp
ctx.DisposeControllersInParallel(
    new[] { ctrl0, ctrl1, ctrl2, ctrl3 },
    perControllerCallback: (c, ms) => Logger.Info($"  {c.Profile.Id}: {ms} ms"));
```

--------------------------------

### Install SteamVR without Steam client using steamcmd

Source: https://hidmaestro.org/docs/sdk/vr-controllers

Commands to install SteamVR on a machine without the Steam client, using Valve's command-line tool with no account needed. The first command downloads steamcmd.zip, the second installs SteamVR (app ID 250820) to C:\SteamVR anonymously.

```bash
curl -L -o steamcmd.zip https://steamcdn-a.akamaihd.net/client/installer/steamcmd.zip
steamcmd +force_install_dir "C:\SteamVR" +login anonymous +app_update 250820 validate +quit
```

--------------------------------

### Loading and Enumerating Profiles

Source: https://hidmaestro.org/docs/profiles/profile-system

Demonstrates how to load default or custom profiles into the context and how to enumerate the loaded catalog.

```csharp
// Embedded catalog (228 profiles)
ctx.LoadDefaultProfiles();

// Custom directory of JSON profiles
ctx.LoadProfilesFromDirectory(@"C:\my-profiles");

// Mix both — embedded first, then custom (custom IDs win on collision)
ctx.LoadDefaultProfiles();
ctx.LoadProfilesFromDirectory(@"C:\my-overrides");

// Lookup
HMProfile? p = ctx.GetProfile("xbox-360-wired");

// Enumerate
foreach (var profile in ctx.AllProfiles)
    Console.WriteLine($"{profile.Id} — {profile.Name}");
```

--------------------------------

### Initialize Shared Memory Sections in SetupController

Source: https://hidmaestro.org/docs/reference/shared-memory-protocol

The SDK consumer initializes input and output mappings in the SetupController before binding the driver. The PID state section is created lazily upon the first call to PublishPidPool.

```csharp
// In DeviceOrchestrator.SetupController
SharedMemoryIO.EnsureInputMapping(controllerIndex);    // creates Global\HIDMaestroInput<N> + Event
SharedMemoryIO.EnsureOutputMapping(controllerIndex);   // creates Global\HIDMaestroOutput<N>
// PID state section is lazy — only created on first HMController.PublishPidPool call
```

--------------------------------

### CRC32 scope JSON example

Source: https://hidmaestro.org/docs/profiles/profile-system

Example JSON for the CRC32 scope field, specifying the prefix bytes and the byte range covered by the CRC. Used in extendedReport fields of type crc32-le.

```json
"scope": {
  "prefix": [161, 49],   // two bytes for Sony BT input: [0xA1, 0x31]
  "from": 1,             // first byte covered (after report ID)
  "to":   73             // last byte covered (before CRC field)
}

```
Tokens:
Raw