usb 2.0.0-alpha.2 → 2.1.0

package/package.json

@@ -2,14 +2,14 @@
   "name": "usb",
   "description": "Library to access USB devices",
   "license": "MIT",
-  "version": "2.0.0-alpha.2",
+  "version": "2.1.0",
   "main": "dist/index.js",
   "engines": {
-    "node": ">=10"
+    "node": ">=10.16.0"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/tessel/node-usb.git"
+    "url": "https://github.com/node-usb/node-usb.git"
   },
   "contributors": [
     {
@@ -37,22 +37,24 @@
   ],
   "scripts": {
     "prepare": "yarn compile",
-    "install": "prebuild-install --runtime napi --verbose || node-gyp rebuild",
-    "prebuild": "prebuild --runtime napi -t 4 --force --strip --verbose",
+    "install": "node-gyp-build",
     "clean": "git clean -dfx",
     "compile": "tsc && yarn lint && yarn docs",
     "lint": "eslint . --ext .ts",
     "watch": "tsc -w --preserveWatchOutput",
     "test": "mocha --require coffeescript/register --grep Module test/*",
     "full-test": "mocha --require coffeescript/register test/*.coffee",
-    "valgrind": "coffee -c test/usb.coffee; valgrind --leak-check=full --show-possibly-lost=no node --expose-gc --trace-gc node_modules/mocha/bin/_mocha -R spec",
-    "docs": "typedoc"
+    "valgrind": "coffee -c test/*.coffee; valgrind --leak-check=full --show-possibly-lost=no node --expose-gc --trace-gc node_modules/mocha/bin/_mocha -R spec",
+    "docs": "typedoc",
+    "prebuild": "prebuildify --napi --target 10.16.0 --strip",
+    "prebuild-cross": "prebuildify-cross --napi --target 10.16.0 --strip",
+    "prepublishOnly": "prebuildify-ci download",
+    "prebuild-download": "prebuildify-ci download"
   },
   "dependencies": {
     "@types/w3c-web-usb": "^1.0.4",
-    "bindings": "^1.4.0",
-    "node-addon-api": "^3.1.0",
-    "prebuild-install": "^6.1.1"
+    "node-addon-api": "^4.2.0",
+    "node-gyp-build": "^4.3.0"
   },
   "devDependencies": {
     "@types/node": "^14.14.41",
@@ -60,9 +62,12 @@
     "@typescript-eslint/parser": "^4.28.0",
     "coffeescript": "^2.5.1",
     "eslint": "^7.29.0",
-    "mocha": "^8.3.2",
-    "prebuild": "^10.0.1",
-    "typedoc": "^0.20.36",
+    "mocha": "^9.1.3",
+    "node-gyp": "^7.1.2",
+    "prebuildify": "^4.2.1",
+    "prebuildify-ci": "^1.0.5",
+    "prebuildify-cross": "^4.0.1",
+    "typedoc": "^0.22.10",
     "typescript": "~4.2.4"
   },
   "binary": {

package/src/device.cc

@@ -11,7 +11,7 @@
 
 Napi::FunctionReference Device::constructor;
 
-Device::Device(const Napi::CallbackInfo & info) : Napi::ObjectWrap<Device>(info), device_handle(0), refs_(1)
+Device::Device(const Napi::CallbackInfo & info) : Napi::ObjectWrap<Device>(info), device_handle(0), refs_(0)
 #ifndef USE_POLL
 , completionQueue(handleCompletion)
 #endif
@@ -19,18 +19,12 @@ Device::Device(const Napi::CallbackInfo & info) : Napi::ObjectWrap<Device>(info)
 	device = info[0].As<Napi::External<libusb_device>>().Data();
 	libusb_ref_device(device);
 	byPtr.insert(std::make_pair(device, this));
-#ifndef USE_POLL
-	completionQueue.start(info.Env());
-#endif
 	DEBUG_LOG("Created device %p", this);
 	Constructor(info);
 }
 
 Device::~Device(){
 	DEBUG_LOG("Freed device %p", this);
-#ifndef USE_POLL
-	completionQueue.stop();
-#endif
 	byPtr.erase(device);
 	libusb_close(device_handle);
 	libusb_unref_device(device);
@@ -194,6 +188,9 @@ Napi::Value Device::Open(const Napi::CallbackInfo& info) {
 	ENTER_METHOD(Device, 0);
 	if (!self->device_handle){
 		CHECK_USB(libusb_open(self->device, &self->device_handle));
+#ifndef USE_POLL
+		completionQueue.start(info.Env());
+#endif
 	}
 	return env.Undefined();
 }
@@ -203,6 +200,9 @@ Napi::Value Device::Close(const Napi::CallbackInfo& info) {
 	if (self->canClose()){
 		libusb_close(self->device_handle);
 		self->device_handle = NULL;
+#ifndef USE_POLL
+		completionQueue.stop();
+#endif        
 	}else{
 		THROW_ERROR("Can't close device with a pending request");
 	}

package/src/node_usb.cc

@@ -4,8 +4,11 @@
 
 Napi::Value SetDebugLevel(const Napi::CallbackInfo& info);
 Napi::Value GetDeviceList(const Napi::CallbackInfo& info);
+Napi::Value GetLibusbCapability(const Napi::CallbackInfo& info);
 Napi::Value EnableHotplugEvents(const Napi::CallbackInfo& info);
 Napi::Value DisableHotplugEvents(const Napi::CallbackInfo& info);
+Napi::Value RefHotplugEvents(const Napi::CallbackInfo& info);
+Napi::Value UnrefHotplugEvents(const Napi::CallbackInfo& info);
 void initConstants(Napi::Object target);
 
 libusb_context* usb_context;
@@ -16,6 +19,7 @@ struct HotPlug {
 
 #ifdef USE_POLL
 #include <poll.h>
+#include <uv.h>
 #include <sys/time.h>
 
 std::map<int, uv_poll_t*> pollByFD;
@@ -94,8 +98,11 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
 
 	exports.Set("setDebugLevel", Napi::Function::New(env, SetDebugLevel));
 	exports.Set("getDeviceList", Napi::Function::New(env, GetDeviceList));
+	exports.Set("_getLibusbCapability", Napi::Function::New(env, GetLibusbCapability));
 	exports.Set("_enableHotplugEvents", Napi::Function::New(env, EnableHotplugEvents));
 	exports.Set("_disableHotplugEvents", Napi::Function::New(env, DisableHotplugEvents));
+	exports.Set("refHotplugEvents", Napi::Function::New(env, RefHotplugEvents));
+	exports.Set("unrefHotplugEvents", Napi::Function::New(env, UnrefHotplugEvents));
 	return exports;
 }
 
@@ -128,6 +135,17 @@ Napi::Value GetDeviceList(const Napi::CallbackInfo& info) {
 	return arr;
 }
 
+Napi::Value GetLibusbCapability(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+
+	if (info.Length() != 1 || !info[0].IsNumber()) {
+		THROW_BAD_ARGS("Usb::GetLibusbCapability argument is invalid!")
+	}
+
+	int res = libusb_has_capability(info[0].As<Napi::Number>().Int32Value());
+	return Napi::Number::New(env, res);
+}
+
 Napi::ObjectReference hotplugThis;
 
 void handleHotplug(HotPlug* info){
@@ -177,6 +195,7 @@ Napi::Value EnableHotplugEvents(const Napi::CallbackInfo& info) {
 
 	if (!hotplugEnabled) {
 		hotplugThis.Reset(info.This().As<Napi::Object>(), 1);
+		hotplugThis.SuppressDestruct();
 		CHECK_USB(libusb_hotplug_register_callback(usb_context,
 			(libusb_hotplug_event)(LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED | LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT),
 			(libusb_hotplug_flag)0, LIBUSB_HOTPLUG_MATCH_ANY, LIBUSB_HOTPLUG_MATCH_ANY, LIBUSB_HOTPLUG_MATCH_ANY,
@@ -198,10 +217,27 @@ Napi::Value DisableHotplugEvents(const Napi::CallbackInfo& info) {
 	return env.Undefined();
 }
 
+Napi::Value RefHotplugEvents(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	Napi::HandleScope scope(env);
+	if (hotplugEnabled) {
+		hotplugQueue.ref(env);
+	}
+	return env.Undefined();
+}
+
+Napi::Value UnrefHotplugEvents(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	Napi::HandleScope scope(env);
+	if (hotplugEnabled) {
+		hotplugQueue.unref(env);
+	}
+	return env.Undefined();
+}
+
 #define DEFINE_CONSTANT(OBJ, VALUE) \
 	OBJ.DefineProperty(Napi::PropertyDescriptor::Value(#VALUE, Napi::Number::New(OBJ.Env(), VALUE), static_cast<napi_property_attributes>(napi_enumerable | napi_configurable)));
 
-
 void initConstants(Napi::Object target){
 	DEFINE_CONSTANT(target, LIBUSB_CLASS_PER_INTERFACE);
 	DEFINE_CONSTANT(target, LIBUSB_CLASS_AUDIO);
@@ -281,6 +317,12 @@ void initConstants(Napi::Object target){
 	DEFINE_CONSTANT(target, LIBUSB_CONTROL_SETUP_SIZE);
 	DEFINE_CONSTANT(target, LIBUSB_DT_BOS_SIZE);
 
+	// libusb_capability
+	DEFINE_CONSTANT(target, LIBUSB_CAP_HAS_CAPABILITY);
+	DEFINE_CONSTANT(target, LIBUSB_CAP_HAS_HOTPLUG);
+	DEFINE_CONSTANT(target, LIBUSB_CAP_HAS_HID_ACCESS);
+	DEFINE_CONSTANT(target, LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER);
+
 	// libusb_error
 	// Input/output error
 	DEFINE_CONSTANT(target, LIBUSB_ERROR_IO);

package/src/node_usb.h

@@ -10,6 +10,7 @@
 #endif
 #include <libusb.h>
 
+#define NAPI_VERSION 4
 #include <napi.h>
 #include <node_buffer.h>
 

package/src/uv_async_queue.h

@@ -3,31 +3,39 @@
 
 template <class T>
 class UVQueue{
-	public:
-		typedef void (*fptr)(T);
-
-		Napi::ThreadSafeFunction tsfn;
-
-		UVQueue(fptr cb): callback(cb)  {}
-
-		void start(Napi::Env env) {
-			Napi::Function empty_func = Napi::Function::New(env, [](const Napi::CallbackInfo& cb) {});
-			tsfn = Napi::ThreadSafeFunction::New(env, empty_func, "libusb", 0, 1);
-		}
-
-		void stop() {
-    		tsfn.Release();
-		}
-		
-		void post(T value){
-			auto cb = callback;
-			tsfn.BlockingCall( value, [cb](Napi::Env _env, Napi::Function _jsCallback, T val) {
-				cb(val);
-			});
-		}
-
-	private:
-		fptr callback;
+    public:
+        typedef void (*fptr)(T);
+
+        Napi::ThreadSafeFunction tsfn;
+
+        UVQueue(fptr cb): callback(cb)  {}
+
+        void start(Napi::Env env) {
+            Napi::Function empty_func = Napi::Function::New(env, [](const Napi::CallbackInfo& cb) {});
+            tsfn = Napi::ThreadSafeFunction::New(env, empty_func, "libusb", 0, 1);
+        }
+
+        void stop() {
+            tsfn.Release();
+        }
+ 
+        void ref(Napi::Env env) {
+            tsfn.Ref(env);
+        }
+
+        void unref(Napi::Env env) {
+            tsfn.Unref(env);
+        }
+
+        void post(T value){
+            auto cb = callback;
+            tsfn.BlockingCall( value, [cb](Napi::Env _env, Napi::Function _jsCallback, T val) {
+                cb(val);
+            });
+        }
+
+    private:
+        fptr callback;
 };
 
 #endif

package/test/usb.coffee

@@ -3,6 +3,7 @@ util = require('util')
 usb = require('../').usb
 getDeviceList = require('../').getDeviceList
 findByIds = require('../').findByIds
+findBySerialNumber = require('../').findBySerialNumber
 
 if typeof gc is 'function'
 	# running with --expose-gc, do a sweep between tests so valgrind blames the right one
@@ -38,6 +39,11 @@ describe 'findByIds', ->
 		dev = findByIds(0x59e3, 0x0a23)
 		assert.ok(dev, "Demo device is not attached")
 
+describe 'findBySerialNumber', ->
+	it 'should return a single device ', ->
+		dev = findBySerialNumber('TEST_DEVICE')
+		assert.ok(dev, "Demo device is not attached")
+
 describe 'Device', ->
 	device = null
 	before ->

package/tsc/index.ts

@@ -1,8 +1,11 @@
 import { promisify } from 'util';
-import { WebUSB } from './webusb';
+import { WebUSB, getWebUsb } from './webusb';
 import { WebUSBDevice } from './webusb/webusb-device';
 import * as usb from './usb';
 
+const webusb = new WebUSB();
+const getDeviceList = usb.getDeviceList;
+
 /**
  * Convenience method to get the first device with the specified VID and PID, or `undefined` if no such device is present.
  * @param vid
@@ -19,10 +22,13 @@ const findByIds = (vid: number, pid: number): usb.Device | undefined => {
  */
 const findBySerialNumber = async (serialNumber: string): Promise<usb.Device | undefined> => {
     const devices = usb.getDeviceList();
+    const opened = (device: usb.Device): boolean => !!device.interfaces;
 
     for (const device of devices) {
         try {
-            device.open();
+            if (!opened(device)) {
+                device.open();
+            }
 
             const getStringDescriptor = promisify(device.getStringDescriptor).bind(device);
             const buffer = await getStringDescriptor(device.deviceDescriptor.iSerialNumber);
@@ -34,7 +40,9 @@ const findBySerialNumber = async (serialNumber: string): Promise<usb.Device | un
             // Ignore any errors, device may be a system device or inaccessible
         } finally {
             try {
-                device.close();
+                if (opened(device)) {
+                    device.close();
+                }
             } catch {
                 // Ignore any errors, device may be a system device or inaccessible
             }
@@ -44,9 +52,6 @@ const findBySerialNumber = async (serialNumber: string): Promise<usb.Device | un
     return undefined;
 };
 
-const webusb = new WebUSB();
-const getDeviceList = usb.getDeviceList;
-
 export {
     // Core usb object for quick access
     usb,
@@ -55,6 +60,7 @@ export {
     getDeviceList,
     findByIds,
     findBySerialNumber,
+    getWebUsb,
 
     // Default WebUSB object (mimics navigator.usb)
     webusb,
@@ -62,6 +68,6 @@ export {
     // WebUSB class for creating custom webusb instances
     WebUSB,
 
-    // WebUSB Device class for turning a core usb.Device into a webusb device
+    // WebUSB Device class for turning a legacy usb.Device into a webusb device
     WebUSBDevice
 };

package/tsc/usb/bindings.ts

@@ -2,10 +2,11 @@
 //  Eric Brody <https://github.com/underscorebrody>
 //  Rob Moran <https://github.com/thegecko>
 
+import { join } from 'path';
 import type { DeviceDescriptor, ConfigDescriptor, BosDescriptor } from './descriptors';
 
 /* eslint-disable @typescript-eslint/no-var-requires */
-const usb = require('bindings')('usb_bindings');
+const usb = require('node-gyp-build')(join(__dirname, '..', '..'));
 module.exports = usb;
 
 /**
@@ -27,6 +28,17 @@ export declare function setDebugLevel(level: number): void;
 
 export declare function _enableHotplugEvents(): void;
 export declare function _disableHotplugEvents(): void;
+export declare function _getLibusbCapability(capability: number): number;
+
+/**
+ * Restore (re-reference) the hotplug events unreferenced by `unrefHotplugEvents()`
+ */
+export declare function refHotplugEvents(): void;
+
+/**
+ * Unreference the hotplug events from the event loop, allowing the process to exit even when listening for the `attach` and `detach` events
+ */
+export declare function unrefHotplugEvents(): void;
 
 /** Represents a USB transfer */
 export declare class Transfer {
@@ -257,6 +269,12 @@ export declare const LIBUSB_RECIPIENT_OTHER: number;
 export declare const LIBUSB_CONTROL_SETUP_SIZE: number;
 export declare const LIBUSB_DT_BOS_SIZE: number;
 
+// libusb_capability
+export declare const LIBUSB_CAP_HAS_CAPABILITY: number;
+export declare const LIBUSB_CAP_HAS_HOTPLUG: number;
+export declare const LIBUSB_CAP_HAS_HID_ACCESS: number;
+export declare const LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER: number;
+
 // libusb_error
 /** Input/output error */
 export declare const LIBUSB_ERROR_IO: number;

package/tsc/usb/index.ts

@@ -21,32 +21,76 @@ interface EventListeners<T> {
 declare module './bindings' {
 
     /* eslint-disable @typescript-eslint/no-empty-interface */
-	interface Device extends ExtendedDevice {}
-
-	interface DeviceEvents extends EventListeners<DeviceEvents> {
-		attach: Device;
-		detach: Device;
-	}
-
-	function addListener<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
-	function removeListener<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
-	function on<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
-	function off<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
-	function once<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
-	function listeners<K extends keyof DeviceEvents>(event: K): ((arg: DeviceEvents[K]) => void)[];
-	function rawListeners<K extends keyof DeviceEvents>(event: K): ((arg: DeviceEvents[K]) => void)[];
-	function removeAllListeners<K extends keyof DeviceEvents>(event?: K): void;
-	function emit<K extends keyof DeviceEvents>(event: K, arg: DeviceEvents[K]): boolean;
-	function listenerCount<K extends keyof DeviceEvents>(event: K): number;
+    interface Device extends ExtendedDevice { }
+
+    interface DeviceEvents extends EventListeners<DeviceEvents> {
+        attach: Device;
+        detach: Device;
+    }
+
+    function addListener<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
+    function removeListener<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
+    function on<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
+    function off<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
+    function once<K extends keyof DeviceEvents>(event: K, listener: (arg: DeviceEvents[K]) => void): void;
+    function listeners<K extends keyof DeviceEvents>(event: K): ((arg: DeviceEvents[K]) => void)[];
+    function rawListeners<K extends keyof DeviceEvents>(event: K): ((arg: DeviceEvents[K]) => void)[];
+    function removeAllListeners<K extends keyof DeviceEvents>(event?: K): void;
+    function emit<K extends keyof DeviceEvents>(event: K, arg: DeviceEvents[K]): boolean;
+    function listenerCount<K extends keyof DeviceEvents>(event: K): number;
 }
 
+// Polling mechanism for discovering device changes until this is fixed:
+// https://github.com/libusb/libusb/issues/86
+const pollTimeout = 500;
+const hotplugSupported = usb._getLibusbCapability(usb.LIBUSB_CAP_HAS_HOTPLUG) > 0;
+let pollingHotplug = false;
+let pollDevices: usb.Device[] = [];
+
+const pollHotplug = (start = false) => {
+    if (start) {
+        pollingHotplug = true;
+    } else if (!pollingHotplug) {
+        return;
+    }
+
+    const devices = usb.getDeviceList();
+
+    if (!start) {
+        // Find attached devices
+        for (const device of devices) {
+            const found = pollDevices.find(item => item.deviceAddress === device.deviceAddress);
+            if (!found) {
+                usb.emit('attach', device);
+            }
+        }
+
+        // Find detached devices
+        for (const device of pollDevices) {
+            const found = devices.find(item => item.deviceAddress === device.deviceAddress);
+            if (!found) {
+                usb.emit('detach', device);
+            }
+        }
+    }
+
+    pollDevices = devices;
+    setTimeout(() => {
+        pollHotplug();
+    }, pollTimeout);
+};
+
 usb.on('newListener', event => {
     if (event !== 'attach' && event !== 'detach') {
         return;
     }
     const listenerCount = usb.listenerCount('attach') + usb.listenerCount('detach');
     if (listenerCount === 0) {
-        usb._enableHotplugEvents();
+        if (hotplugSupported) {
+            usb._enableHotplugEvents();
+        } else {
+            pollHotplug(true);
+        }
     }
 });
 
@@ -56,7 +100,11 @@ usb.on('removeListener', event => {
     }
     const listenerCount = usb.listenerCount('attach') + usb.listenerCount('detach');
     if (listenerCount === 0) {
-        usb._disableHotplugEvents();
+        if (hotplugSupported) {
+            usb._disableHotplugEvents();
+        } else {
+            pollingHotplug = false;
+        }
     }
 });
 

package/tsc/usb/interface.ts

@@ -28,7 +28,7 @@ export class Interface {
         this.interfaceNumber = this.descriptor.bInterfaceNumber;
         this.endpoints = [];
         const len = this.descriptor.endpoints.length;
-        for (let i=0; i<len; i++){
+        for (let i = 0; i < len; i++) {
             const desc = this.descriptor.endpoints[i];
             const c = (desc.bEndpointAddress & LIBUSB_ENDPOINT_IN) ? InEndpoint : OutEndpoint;
             this.endpoints[i] = new c(this.device, desc);
@@ -145,7 +145,7 @@ export class Interface {
      */
     public setAltSetting(altSetting: number, callback?: (error: LibUSBException | undefined) => void): void {
         this.device.__setInterface(this.id, altSetting, error => {
-            if (!error){
+            if (!error) {
                 this.altSetting = altSetting;
                 this.refresh();
             }