Add Troubleshooting FAQ

[kevinmehall]

Runtime errors

• LIBUSB_ERROR_BUSY
  • Linux: detach_kernel_driver (Example in LIBUSB_ERROR_BUSY Raspberry Pi 3 #174)
• LIBUSB_ERROR_ACCESS
  • macOS: Can't open devices that have a kernel driver, no good workaround. (discussion on LIBUSB_ERROR_ACCESS on OSX as admin user #30)
    • Usually comes up with HID devices -- is there a recommended libhid library?
  • Linux: permissions, udev rules
• LIBUSB_ERROR_NOT_SUPPORTED
  • Windows: Bind WinUSB driver with libwdi / Zadig
    • Mention WCID for custom devices
• LIBUSB_ERROR_NO_DEVICE
  • macOS doesn't configure devices with bDeviceClass=255 "vendor defined" (LIBUSB_ERROR_NOT_FOUND on MacOS when trying to open a device. #61)
    • If it's your firmware, use bDeviceClass=0 "defined at interface level" instead
    • workaround is .open(false), .setConfiguration(1) to tell the kernel to configure the device.

Install errors

• Install fails with gyp WARN EACCES user "root" does not have permission to access the dev dir (Failed at the usb@1.2.0 install script.. #175, user "root" does not have permission to access the dev dir "/home/pi/scanner/node_modules/usb/.node-gyp/8.9.2" #210, npm ERR! Failed at the usb@1.3.1 install script 'node-pre-gyp install --fallback-to-build'. #218)
  • Don't run npm as root. Best way is to install node via nvm, which sets up permissions correctly to run npm -g as your normal user.
  • Or if you really have to, npm install --unsafe-perm usb.
  • Common issue for all NPM packages with native code Warning "root" does not have permission to access the dev dir  nodejs/node-gyp#454 (comment)

[fatso83]

Some mention of how to enable those access rights without requiring sudo would be nice as well.

[mrbar42]

After fighting LIBUSB_ERROR_NOT_FOUND on an OSX Mojave for a while i ended up using node-hid which worked effortlessly.
might serve as a workaround for others with HID devices.

[mcuee]

is there a recommended libhid library?

Yes, libusb project recommends HIDAPI for HID device. It supports both USB and Bluetooth HID and even other types of HID devices. There is a active node binding node-hid as well.

hidapi project:
https://github.com/libusb/hidapi

node-hid:
https://github.com/node-hid/node-hid

[mcuee]

macOS: Can't open devices that have a kernel driver, no good workaround

Please refer to this discussion, libusb-1.0.26 adds the support to detach kernel driver with correct entitlement (which is diffcult to get from Apple) but at least you can run as root.

• How to use the new macOS kernel detach feature for non-root user libusb/libusb#1014

[mcuee]

Please read libusb FAQ here.
https://github.com/libusb/libusb/wiki/FAQ

[fatso83]

Better late than never 😄