usb 2.17.0 → 3.0.0-alpha.2

package/dist/index.d.ts

@@ -1,22 +1,76 @@
-import { WebUSB } from './webusb';
-import * as usb from './usb';
+import { Emitter } from '../index.js';
+import { EventEmitter } from 'events';
+/**
+ * USB Options
+ */
+interface USBOptions {
+    /**
+     * Optional `device found` callback function to allow the user to select a device
+     */
+    devicesFound?: (devices: USBDevice[]) => Promise<USBDevice | void>;
+    /**
+     * Optional array of preconfigured allowed devices
+     */
+    allowedDevices?: USBDeviceFilter[];
+    /**
+     * Optional flag to automatically allow all devices
+     */
+    allowAllDevices?: boolean;
+    /**
+     * Optional timeout (in milliseconds) to use for the device control transfers
+     */
+    deviceTimeout?: number;
+    /**
+     * Optional flag to enable/disable automatic kernal driver detaching (defaults to true)
+     */
+    autoDetachKernelDriver?: boolean;
+}
+declare class WebUSB implements USB {
+    private options;
+    protected nativeEmitter: Emitter;
+    protected emitter: EventEmitter<any>;
+    protected authorisedDevices: Set<USBDeviceFilter>;
+    protected knownDevices: Map<string, USBDevice>;
+    constructor(options?: USBOptions);
+    private _onconnect;
+    set onconnect(fn: (ev: USBConnectionEvent) => void);
+    private _ondisconnect;
+    set ondisconnect(fn: (ev: USBConnectionEvent) => void);
+    addEventListener(type: 'connect' | 'disconnect', listener: (this: this, ev: USBConnectionEvent) => void): void;
+    addEventListener(type: 'connect' | 'disconnect', listener: EventListener): void;
+    removeEventListener(type: 'connect' | 'disconnect', callback: (this: this, ev: USBConnectionEvent) => void): void;
+    removeEventListener(type: 'connect' | 'disconnect', callback: EventListener): void;
+    dispatchEvent(_event: Event): boolean;
+    /**
+     * Requests a single Web USB device
+     * @param options The options to use when scanning
+     * @returns Promise containing the selected device
+     */
+    requestDevice(options?: USBDeviceRequestOptions): Promise<USBDevice>;
+    /**
+     * Gets all allowed Web USB devices which are connected
+     * @returns Promise containing an array of devices
+     */
+    getDevices(): Promise<USBDevice[]>;
+    private loadDevices;
+    private quickFilter;
+    private filterDevice;
+    private isAuthorisedDevice;
+}
+/**
+ * Convenience method to get an array of all connected devices.
+ */
+declare const getDeviceList: () => Promise<USBDevice[]>;
 /**
  * Convenience method to get the first device with the specified VID and PID, or `undefined` if no such device is present.
  * @param vid
  * @param pid
  */
-declare const findByIds: (vid: number, pid: number) => usb.Device | undefined;
+declare const findByIds: (vid: number, pid: number) => Promise<USBDevice | undefined>;
 /**
  * Convenience method to get the device with the specified serial number, or `undefined` if no such device is present.
  * @param serialNumber
  */
-declare const findBySerialNumber: (serialNumber: string) => Promise<usb.Device | undefined>;
-declare const webusb: WebUSB;
-export { usb, findByIds, findBySerialNumber, webusb };
-export { Device, Transfer, DeviceEvents, getDeviceList, useUsbDkBackend, LibUSBException } from './usb';
-export * from './usb/capability';
-export * from './usb/descriptors';
-export * from './usb/endpoint';
-export * from './usb/interface';
-export * from './webusb';
-export * from './webusb/webusb-device';
+declare const findBySerialNumber: (serialNumber: string) => Promise<USBDevice | undefined>;
+declare const webusb: WebUSB | USB;
+export { webusb, WebUSB, USBOptions, getDeviceList, findByIds, findBySerialNumber, };

package/dist/index.js

@@ -1,32 +1,341 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findBySerialNumber = exports.findByIds = exports.getDeviceList = exports.WebUSB = exports.webusb = void 0;
+const index_js_1 = require("../index.js");
+const events_1 = require("events");
+class NamedError extends Error {
+    constructor(message, name) {
+        super(message);
+        this.name = name;
     }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+}
+const augmentDevice = (device) => {
+    const toUint8Array = (data) => {
+        if (data instanceof ArrayBuffer) {
+            return new Uint8Array(data);
+        }
+        // ArrayBufferView
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    };
+    Object.defineProperty(device, 'controlTransferIn', {
+        enumerable: false,
+        configurable: false,
+        value: async function (setup, length) {
+            const res = await this.nativeControlTransferIn(setup, length);
+            return {
+                data: res ? new DataView(res.buffer) : undefined,
+                status: res ? 'ok' : 'stall',
+            };
+        },
+    });
+    Object.defineProperty(device, 'controlTransferOut', {
+        enumerable: false,
+        configurable: false,
+        value: async function (setup, data) {
+            const res = await this.nativeControlTransferOut(setup, toUint8Array(data));
+            return {
+                bytesWritten: res,
+                status: res >= 0 ? 'ok' : 'stall',
+            };
+        },
+    });
+    Object.defineProperty(device, 'transferIn', {
+        enumerable: false,
+        configurable: false,
+        value: async function (endpointNumber, length) {
+            const res = await this.nativeTransferIn(endpointNumber, length);
+            return {
+                data: res ? new DataView(res.buffer) : undefined,
+                status: res ? 'ok' : 'stall',
+            };
+        },
+    });
+    Object.defineProperty(device, 'transferOut', {
+        enumerable: false,
+        configurable: false,
+        value: async function (endpointNumber, data) {
+            const res = await this.nativeTransferOut(endpointNumber, toUint8Array(data));
+            return {
+                bytesWritten: res,
+                status: res >= 0 ? 'ok' : 'stall',
+            };
+        },
+    });
+    return device;
 };
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LibUSBException = exports.useUsbDkBackend = exports.getDeviceList = exports.Transfer = exports.Device = exports.webusb = exports.findBySerialNumber = exports.findByIds = exports.usb = void 0;
-const util_1 = require("util");
-const webusb_1 = require("./webusb");
-const usb = require("./usb");
-exports.usb = usb;
+class WebUSB {
+    constructor(options = {}) {
+        this.options = options;
+        this.nativeEmitter = new index_js_1.Emitter();
+        this.emitter = new events_1.EventEmitter();
+        this.authorisedDevices = new Set();
+        this.knownDevices = new Map();
+        const deviceConnectCallback = async (device) => {
+            const webDevice = augmentDevice(device);
+            this.knownDevices.set(device.handle, webDevice);
+            // When connected, emit an event if it is an allowed device
+            if (webDevice && this.isAuthorisedDevice(webDevice)) {
+                const event = {
+                    type: 'connect',
+                    device: webDevice
+                };
+                this.emitter.emit('connect', event);
+            }
+        };
+        const deviceDisconnectCallback = async (handle) => {
+            // When disconnected, emit an event if the device was a known allowed device
+            if (this.knownDevices.has(handle)) {
+                const webDevice = this.knownDevices.get(handle);
+                if (webDevice && this.isAuthorisedDevice(webDevice)) {
+                    const event = {
+                        type: 'disconnect',
+                        device: webDevice
+                    };
+                    this.emitter.emit('disconnect', event);
+                }
+                this.knownDevices.delete(handle);
+            }
+        };
+        this.emitter.on('newListener', async (event) => {
+            const listenerCount = this.emitter.listenerCount(event);
+            if (listenerCount !== 0) {
+                return;
+            }
+            if (event === 'connect') {
+                this.nativeEmitter.addAttach(deviceConnectCallback);
+            }
+            else if (event === 'disconnect') {
+                // Ensure we know the current devices
+                this.knownDevices.clear();
+                const devices = await (0, index_js_1.nativeGetDeviceList)();
+                devices.forEach(device => {
+                    this.knownDevices.set(device.handle, augmentDevice(device));
+                });
+                this.nativeEmitter.addDetach(deviceDisconnectCallback);
+            }
+        });
+        this.emitter.on('removeListener', event => {
+            const listenerCount = this.emitter.listenerCount(event);
+            if (listenerCount !== 0) {
+                return;
+            }
+            if (event === 'connect') {
+                this.nativeEmitter.removeAttach(deviceConnectCallback);
+            }
+            else if (event === 'disconnect') {
+                this.knownDevices.clear();
+                this.nativeEmitter.removeDetach(deviceDisconnectCallback);
+            }
+        });
+        this.nativeEmitter.start();
+    }
+    set onconnect(fn) {
+        if (this._onconnect) {
+            this.removeEventListener('connect', this._onconnect);
+            this._onconnect = undefined;
+        }
+        if (fn) {
+            this._onconnect = fn;
+            this.addEventListener('connect', this._onconnect);
+        }
+    }
+    set ondisconnect(fn) {
+        if (this._ondisconnect) {
+            this.removeEventListener('disconnect', this._ondisconnect);
+            this._ondisconnect = undefined;
+        }
+        if (fn) {
+            this._ondisconnect = fn;
+            this.addEventListener('disconnect', this._ondisconnect);
+        }
+    }
+    addEventListener(type, listener) {
+        this.emitter.addListener(type, listener);
+    }
+    removeEventListener(type, callback) {
+        this.emitter.removeListener(type, callback);
+    }
+    dispatchEvent(_event) {
+        // Don't dispatch from here
+        return false;
+    }
+    /**
+     * Requests a single Web USB device
+     * @param options The options to use when scanning
+     * @returns Promise containing the selected device
+     */
+    async requestDevice(options) {
+        // Must have options
+        if (!options) {
+            throw new TypeError('requestDevice error: 1 argument required, but only 0 present');
+        }
+        // Options must be an object
+        if (options.constructor !== {}.constructor) {
+            throw new TypeError('requestDevice error: parameter 1 (options) is not an object');
+        }
+        // Must have a filter
+        if (!options.filters) {
+            throw new TypeError('requestDevice error: required member filters is undefined');
+        }
+        // Filter must be an array
+        if (options.filters.constructor !== [].constructor) {
+            throw new TypeError('requestDevice error: the provided value cannot be converted to a sequence');
+        }
+        // Check filters
+        options.filters.forEach(filter => {
+            // Protocol & Subclass
+            if (filter.protocolCode && !filter.subclassCode) {
+                throw new TypeError('requestDevice error: subclass code is required');
+            }
+            // Subclass & Class
+            if (filter.subclassCode && !filter.classCode) {
+                throw new TypeError('requestDevice error: class code is required');
+            }
+        });
+        let devices = await this.loadDevices(options.filters);
+        devices = devices.filter(device => this.filterDevice(device, options.filters));
+        if (devices.length === 0) {
+            throw new NamedError('Failed to execute \'requestDevice\' on \'USB\': No device selected.', 'NotFoundError');
+        }
+        try {
+            // If no devicesFound function, select the first device found
+            const device = this.options.devicesFound ? await this.options.devicesFound(devices) : devices[0];
+            if (!device) {
+                throw new NamedError('Failed to execute \'requestDevice\' on \'USB\': No device selected.', 'NotFoundError');
+            }
+            this.authorisedDevices.add({
+                vendorId: device.vendorId,
+                productId: device.productId,
+                classCode: device.deviceClass,
+                subclassCode: device.deviceSubclass,
+                protocolCode: device.deviceProtocol,
+                serialNumber: device.serialNumber || undefined
+            });
+            return device;
+        }
+        catch (error) {
+            throw new NamedError('Failed to execute \'requestDevice\' on \'USB\': No device selected.', 'NotFoundError');
+        }
+    }
+    /**
+     * Gets all allowed Web USB devices which are connected
+     * @returns Promise containing an array of devices
+     */
+    async getDevices() {
+        const preFilters = this.options.allowAllDevices ? undefined : this.options.allowedDevices;
+        // Refresh devices and filter for allowed ones
+        const devices = await this.loadDevices(preFilters);
+        return devices.filter(device => this.isAuthorisedDevice(device));
+    }
+    async loadDevices(preFilters) {
+        let devices = await getDeviceList();
+        // Pre-filter devices
+        devices = this.quickFilter(devices, preFilters);
+        return devices;
+    }
+    // Undertake quick filter on devices before creating WebUSB devices if possible
+    quickFilter(devices, preFilters) {
+        if (!preFilters || !preFilters.length) {
+            return devices;
+        }
+        // Just pre-filter on vid/pid
+        return devices.filter(device => preFilters.some(filter => {
+            // Vendor
+            if (filter.vendorId && filter.vendorId !== device.vendorId)
+                return false;
+            // Product
+            if (filter.productId && filter.productId !== device.productId)
+                return false;
+            // Ignore Class, Subclass and Protocol as these need to check interfaces, too
+            // Ignore serial number for node-usb as it requires device connection
+            return true;
+        }));
+    }
+    // Filter WebUSB devices
+    filterDevice(device, filters) {
+        if (!filters || !filters.length) {
+            return true;
+        }
+        return filters.some(filter => {
+            // Vendor
+            if (filter.vendorId && filter.vendorId !== device.vendorId)
+                return false;
+            // Product
+            if (filter.productId && filter.productId !== device.productId)
+                return false;
+            // Class
+            if (filter.classCode) {
+                if (!device.configuration) {
+                    return false;
+                }
+                // Interface Descriptors
+                const match = device.configuration.interfaces.some(iface => {
+                    // Class
+                    if (filter.classCode && filter.classCode !== iface.alternate.interfaceClass)
+                        return false;
+                    // Subclass
+                    if (filter.subclassCode && filter.subclassCode !== iface.alternate.interfaceSubclass)
+                        return false;
+                    // Protocol
+                    if (filter.protocolCode && filter.protocolCode !== iface.alternate.interfaceProtocol)
+                        return false;
+                    return true;
+                });
+                if (match) {
+                    return true;
+                }
+            }
+            // Class
+            if (filter.classCode && filter.classCode !== device.deviceClass)
+                return false;
+            // Subclass
+            if (filter.subclassCode && filter.subclassCode !== device.deviceSubclass)
+                return false;
+            // Protocol
+            if (filter.protocolCode && filter.protocolCode !== device.deviceProtocol)
+                return false;
+            // Serial
+            if (filter.serialNumber && filter.serialNumber !== device.serialNumber)
+                return false;
+            return true;
+        });
+    }
+    // Check whether a device is authorised
+    isAuthorisedDevice(device) {
+        // All devices are authorised
+        if (this.options.allowAllDevices) {
+            return true;
+        }
+        // Check any allowed device filters
+        if (this.options.allowedDevices && this.filterDevice(device, this.options.allowedDevices)) {
+            return true;
+        }
+        // Check authorised devices
+        return [...this.authorisedDevices.values()].some(authorised => authorised.vendorId === device.vendorId
+            && authorised.productId === device.productId
+            && authorised.classCode === device.deviceClass
+            && authorised.subclassCode === device.deviceSubclass
+            && authorised.protocolCode === device.deviceProtocol
+            && authorised.serialNumber === device.serialNumber);
+    }
+}
+exports.WebUSB = WebUSB;
+/**
+ * Convenience method to get an array of all connected devices.
+ */
+const getDeviceList = async () => {
+    const devices = await (0, index_js_1.nativeGetDeviceList)();
+    return devices.map(device => augmentDevice(device));
+};
+exports.getDeviceList = getDeviceList;
 /**
  * Convenience method to get the first device with the specified VID and PID, or `undefined` if no such device is present.
  * @param vid
  * @param pid
  */
-const findByIds = (vid, pid) => {
-    const devices = usb.getDeviceList();
-    return devices.find(item => item.deviceDescriptor.idVendor === vid && item.deviceDescriptor.idProduct === pid);
+const findByIds = async (vid, pid) => {
+    const device = await (0, index_js_1.nativeFindByIds)(vid, pid);
+    return device ? augmentDevice(device) : undefined;
 };
 exports.findByIds = findByIds;
 /**
@@ -34,50 +343,10 @@ exports.findByIds = findByIds;
  * @param serialNumber
  */
 const findBySerialNumber = async (serialNumber) => {
-    const devices = usb.getDeviceList();
-    const opened = (device) => !!device.interfaces;
-    for (const device of devices) {
-        try {
-            if (!opened(device)) {
-                device.open();
-            }
-            const getStringDescriptor = (0, util_1.promisify)(device.getStringDescriptor).bind(device);
-            const buffer = await getStringDescriptor(device.deviceDescriptor.iSerialNumber);
-            if (buffer && buffer.toString() === serialNumber) {
-                return device;
-            }
-        }
-        catch {
-            // Ignore any errors, device may be a system device or inaccessible
-        }
-        finally {
-            try {
-                if (opened(device)) {
-                    device.close();
-                }
-            }
-            catch {
-                // Ignore any errors, device may be a system device or inaccessible
-            }
-        }
-    }
-    return undefined;
+    const device = await (0, index_js_1.nativeFindBySerialNumber)(serialNumber);
+    return device ? augmentDevice(device) : undefined;
 };
 exports.findBySerialNumber = findBySerialNumber;
-const webusb = new webusb_1.WebUSB();
+const webusb = typeof navigator !== 'undefined' && navigator.usb ? navigator.usb : new WebUSB();
 exports.webusb = webusb;
-// Usb types
-var usb_1 = require("./usb");
-Object.defineProperty(exports, "Device", { enumerable: true, get: function () { return usb_1.Device; } });
-Object.defineProperty(exports, "Transfer", { enumerable: true, get: function () { return usb_1.Transfer; } });
-Object.defineProperty(exports, "getDeviceList", { enumerable: true, get: function () { return usb_1.getDeviceList; } });
-Object.defineProperty(exports, "useUsbDkBackend", { enumerable: true, get: function () { return usb_1.useUsbDkBackend; } });
-Object.defineProperty(exports, "LibUSBException", { enumerable: true, get: function () { return usb_1.LibUSBException; } });
-__exportStar(require("./usb/capability"), exports);
-__exportStar(require("./usb/descriptors"), exports);
-__exportStar(require("./usb/endpoint"), exports);
-__exportStar(require("./usb/interface"), exports);
-// WebUSB types
-__exportStar(require("./webusb"), exports);
-__exportStar(require("./webusb/webusb-device"), exports);
 //# sourceMappingURL=index.js.map

package/index.d.ts

@@ -0,0 +1,89 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare class Emitter {
+  constructor()
+  start(): Promise<void>
+  addAttach(callback: ((arg: UsbDevice) => void)): void
+  removeAttach(callback: ((arg: UsbDevice) => void)): void
+  addDetach(callback: ((arg: string) => void)): void
+  removeDetach(callback: ((arg: string) => void)): void
+}
+
+export declare class UsbDevice {
+  vendorId: number
+  productId: number
+  deviceVersionMajor: number
+  deviceVersionMinor: number
+  deviceVersionSubminor: number
+  usbVersionMajor: number
+  usbVersionMinor: number
+  usbVersionSubminor: number
+  deviceClass: number
+  deviceSubclass: number
+  deviceProtocol: number
+  get handle(): string
+  get manufacturerName(): string | null
+  get productName(): string | null
+  get serialNumber(): string | null
+  get opened(): boolean
+  get configuration(): USBConfiguration | null
+  get configurations(): Array<USBConfiguration>
+  open(): Promise<void>
+  close(): Promise<void>
+  forget(): Promise<void>
+  reset(): Promise<void>
+  selectConfiguration(configurationValue: number): Promise<void>
+  claimInterface(interfaceNumber: number): Promise<void>
+  releaseInterface(interfaceNumber: number): Promise<void>
+  selectAlternateInterface(interfaceNumber: number, alternateSetting: number): Promise<void>
+  nativeControlTransferIn(setup: USBControlTransferParameters, length: number): Promise<Uint8Array | null>
+  nativeControlTransferOut(setup: USBControlTransferParameters, data?: Uint8Array | undefined | null): Promise<number>
+  nativeTransferIn(endpointNumber: number, length: number): Promise<Uint8Array | null>
+  nativeTransferOut(endpointNumber: number, data: Uint8Array): Promise<number>
+  isochronousTransferIn(endpointNumber: number, packetLengths: Array<number>): Promise<USBIsochronousInTransferResult>
+  isochronousTransferOut(endpointNumber: number, data: Uint8Array, packetLengths: Array<number>): Promise<USBIsochronousOutTransferResult>
+  clearHalt(direction: USBDirection, endpointNumber: number): Promise<void>
+}
+
+export declare function nativeFindByIds(vendorId: number, productId: number): Promise<UsbDevice>
+
+export declare function nativeFindBySerialNumber(serialNumber: string): Promise<UsbDevice>
+
+export declare function nativeGetDeviceList(): Promise<Array<UsbDevice>>
+
+export interface USBAlternateInterface {
+  alternateSetting: number
+  interfaceClass: number
+  interfaceSubclass: number
+  interfaceProtocol: number
+  interfaceName?: string
+  endpoints: Array<USBEndpoint>
+}
+
+export interface USBConfiguration {
+  configurationValue: number
+  configurationName?: string
+  interfaces: Array<USBInterface>
+}
+
+export interface USBControlTransferParameters {
+  requestType: USBRequestType
+  recipient: USBRecipient
+  request: number
+  value: number
+  index: number
+}
+
+export interface USBEndpoint {
+  endpointNumber: number
+  direction: USBDirection
+  type: USBEndpointType
+  packetSize: number
+}
+
+export interface USBInterface {
+  interfaceNumber: number
+  claimed: boolean
+  alternate: USBAlternateInterface
+  alternates: Array<USBAlternateInterface>
+}