Skip to content

Windows: opt into the libusb UsbDk backend at init (parity with libfreenect2)#701

Open
Le-Syl21 wants to merge 1 commit intoOpenKinect:masterfrom
Le-Syl21:windows-usbdk-opt-in
Open

Windows: opt into the libusb UsbDk backend at init (parity with libfreenect2)#701
Le-Syl21 wants to merge 1 commit intoOpenKinect:masterfrom
Le-Syl21:windows-usbdk-opt-in

Conversation

@Le-Syl21
Copy link
Copy Markdown

@Le-Syl21 Le-Syl21 commented May 8, 2026

Summary

Mirror libfreenect2's Windows init behaviour by calling
libusb_set_option(ctx, LIBUSB_OPTION_USE_USBDK) immediately after
libusb_init in fnusb_init, guarded by #ifdef _WIN32. This is the
exact same one-line opt-in libfreenect2 already does in
libfreenect2.cpp:

```c
#if defined(WIN32) || defined (WIN32) || defined(WINDOWS)
(void)libusb_set_option(usb_context
, LIBUSB_OPTION_USE_USBDK);
#endif
```

Why

Without the opt-in, libusb on Windows uses the WinUSB backend by
default. WinUSB can only attach to devices whose function driver is
WinUSB / libusbK / libusb-win32. On a typical user setup, the Kinect
v1 sub-devices (`Xbox NUI Motor`, `Xbox NUI Audio`, `Xbox NUI
Camera`) are either:

  • bound to no driver (Windows shows them as Unknown device) → libusb
    cannot enumerate them at all, or
  • bound to the Microsoft Kinect SDK driver → libusb enumerates them
    but `libusb_open` returns `LIBUSB_ERROR_NOT_SUPPORTED` (-12).

Today the README's only documented fix for this is "run Zadig, pick
each of the three sub-devices, replace their driver with libusbK"
.
That works but is invasive: it removes the Microsoft SDK driver, has
to be redone if the user later reinstalls the SDK, and requires three
manual Zadig replacements per Kinect.

UsbDk solves the same problem in a much friendlier way — it's a filter
driver
shipped as a signed MSI by Daynix that slots above the existing
function driver and gives userspace tools libusb-compatible access to
any USB device. libfreenect2 already takes advantage of it via the
opt-in above; this PR brings libfreenect to parity.

After this patch, a Windows user can install
UsbDk once and have
libfreenect open the Kinect regardless of whether the Microsoft Kinect
SDK driver is installed — no per-device Zadig steps, no driver
replacement.

Verified

  • Identical guard pattern to libfreenect2 (`_WIN32 || WIN32 ||
    WINDOWS`).
  • Return value cast to `(void)` exactly like libfreenect2 — the call
    only ever fails on non-Windows platforms (where it's compiled out).
  • Zero behaviour change on Linux and macOS (preprocessor-gated).
  • `LIBUSB_OPTION_USE_USBDK` was added in libusb 1.0.22 (Aug 2018).
    libfreenect's README already recommends libusb ≥ 1.0.22 for native
    libusbK isochronous transfers on Windows, so no new minimum-version
    requirement is introduced for users actually building the Windows
    target.

Test plan

  • Builds cleanly on Linux (no Windows code path touched).
  • Behavioural test on Windows with UsbDk installed and the
    Microsoft Kinect SDK driver attached — `freenect_open_device`
    should now succeed where it previously returned -12.

Mirror libfreenect2's behaviour (libfreenect2.cpp): on Windows, after
libusb_init, call libusb_set_option(LIBUSB_OPTION_USE_USBDK).

Without this opt-in, libusb on Windows uses the WinUSB backend, which
can only reach devices that already have a libusb-compatible driver
attached (WinUSB / libusbK / libusb-win32). On Kinect v1 hardware whose
sub-devices are bound to the Microsoft Kinect SDK driver — or to no
driver at all — libusb_open returns LIBUSB_ERROR_NOT_SUPPORTED (-12),
forcing users to run Zadig and replace each sub-device's driver with
libusbK before the device can be opened.

libfreenect2 already addresses this with a one-line opt-in. Extending
the same opt-in to libfreenect lets a Windows user install UsbDk's
filter driver (a single signed MSI from Daynix) and have the Kinect
work, without per-device Zadig steps and without giving up the
Microsoft Kinect SDK driver if they want to keep it.

The call is wrapped in (void) to swallow the return value, matching
libfreenect2's pattern, since LIBUSB_OPTION_USE_USBDK only fails on
non-Windows platforms (where this code is compiled out anyway). No
behaviour change on Linux or macOS.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant