Windows: opt into the libusb UsbDk backend at init (parity with libfreenect2)#701
Open
Le-Syl21 wants to merge 1 commit intoOpenKinect:masterfrom
Open
Windows: opt into the libusb UsbDk backend at init (parity with libfreenect2)#701Le-Syl21 wants to merge 1 commit intoOpenKinect:masterfrom
Le-Syl21 wants to merge 1 commit intoOpenKinect:masterfrom
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Mirror libfreenect2's Windows init behaviour by calling
libusb_set_option(ctx, LIBUSB_OPTION_USE_USBDK)immediately afterlibusb_initinfnusb_init, guarded by#ifdef _WIN32. This is theexact 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:
cannot enumerate them at all, or
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
WINDOWS`).
only ever fails on non-Windows platforms (where it's compiled out).
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
Microsoft Kinect SDK driver attached — `freenect_open_device`
should now succeed where it previously returned -12.