usb 1.9.2 → 2.0.2

package/tsc/usb/interface.ts

@@ -0,0 +1,172 @@
+import { LibUSBException, LIBUSB_ENDPOINT_IN, Device } from './bindings';
+import { InterfaceDescriptor } from './descriptors';
+import { Endpoint, InEndpoint, OutEndpoint } from './endpoint';
+
+export class Interface {
+    /** Integer interface number. */
+    public interfaceNumber!: number;
+
+    /** Integer alternate setting number. */
+    public altSetting = 0;
+
+    /** Object with fields from the interface descriptor -- see libusb documentation or USB spec. */
+    public descriptor!: InterfaceDescriptor;
+
+    /** List of endpoints on this interface: InEndpoint and OutEndpoint objects. */
+    public endpoints!: Endpoint[];
+
+    constructor(protected device: Device, protected id: number) {
+        this.refresh();
+    }
+
+    protected refresh(): void {
+        if (!this.device.configDescriptor) {
+            return;
+        }
+
+        this.descriptor = this.device.configDescriptor.interfaces[this.id][this.altSetting];
+        this.interfaceNumber = this.descriptor.bInterfaceNumber;
+        this.endpoints = [];
+        const len = this.descriptor.endpoints.length;
+        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);
+        }
+    }
+
+    /**
+     * Claims the interface. This method must be called before using any endpoints of this interface.
+     *
+     * The device must be open to use this method.
+     */
+    public claim(): void {
+        this.device.__claimInterface(this.id);
+    }
+
+    /**
+     * Releases the interface and resets the alternate setting. Calls callback when complete.
+     *
+     * It is an error to release an interface with pending transfers.
+     *
+     * The device must be open to use this method.
+     * @param callback
+     */
+    public release(callback?: (error?: LibUSBException) => void): void;
+
+    /**
+     * Releases the interface and resets the alternate setting. Calls callback when complete.
+     *
+     * It is an error to release an interface with pending transfers. If the optional closeEndpoints
+     * parameter is true, any active endpoint streams are stopped (see `Endpoint.stopStream`),
+     * and the interface is released after the stream transfers are cancelled. Transfers submitted
+     * individually with `Endpoint.transfer` are not affected by this parameter.
+     *
+     * The device must be open to use this method.
+     * @param closeEndpoints
+     * @param callback
+     */
+    public release(closeEndpoints?: boolean, callback?: (error?: LibUSBException) => void): void;
+    public release(closeEndpointsOrCallback?: boolean | ((error?: LibUSBException) => void), callback?: (error: LibUSBException | undefined) => void): void {
+
+        let closeEndpoints = false;
+        if (typeof closeEndpointsOrCallback === 'boolean') {
+            closeEndpoints = closeEndpointsOrCallback;
+        } else {
+            callback = closeEndpointsOrCallback;
+        }
+
+        const next = () => {
+            this.device.__releaseInterface(this.id, error => {
+                if (!error) {
+                    this.altSetting = 0;
+                    this.refresh();
+                }
+                if (callback) {
+                    callback.call(this, error);
+                }
+            });
+        };
+
+        if (!closeEndpoints || this.endpoints.length === 0) {
+            next();
+        } else {
+            let n = this.endpoints.length;
+            this.endpoints.forEach(ep => {
+                if (ep.direction === 'in' && (ep as InEndpoint).pollActive) {
+                    ep.once('end', () => {
+                        if (--n === 0) {
+                            next();
+                        }
+                    });
+                    (ep as InEndpoint).stopPoll();
+                } else {
+                    if (--n === 0) {
+                        next();
+                    }
+                }
+            });
+        }
+    }
+
+    /**
+     * Returns `false` if a kernel driver is not active; `true` if active.
+     *
+     * The device must be open to use this method.
+     */
+    public isKernelDriverActive(): boolean {
+        return this.device.__isKernelDriverActive(this.id);
+    }
+
+    /**
+     * Detaches the kernel driver from the interface.
+     *
+     * The device must be open to use this method.
+     */
+    public detachKernelDriver(): void {
+        return this.device.__detachKernelDriver(this.id);
+    }
+
+    /**
+     * Re-attaches the kernel driver for the interface.
+     *
+     * The device must be open to use this method.
+     */
+    public attachKernelDriver(): void {
+        return this.device.__attachKernelDriver(this.id);
+    }
+
+    /**
+     * Sets the alternate setting. It updates the `interface.endpoints` array to reflect the endpoints found in the alternate setting.
+     *
+     * The device must be open to use this method.
+     * @param altSetting
+     * @param callback
+     */
+    public setAltSetting(altSetting: number, callback?: (error: LibUSBException | undefined) => void): void {
+        this.device.__setInterface(this.id, altSetting, error => {
+            if (!error) {
+                this.altSetting = altSetting;
+                this.refresh();
+            }
+            if (callback) {
+                callback.call(this, error);
+            }
+        });
+    }
+
+    /**
+     * Return the InEndpoint or OutEndpoint with the specified address.
+     *
+     * The device must be open to use this method.
+     * @param addr
+     */
+    public endpoint(addr: number): Endpoint {
+        const endpoint = this.endpoints.find(item => item.address === addr);
+        if (!endpoint) {
+            throw new Error(`Endpoint not found for address: ${addr}`);
+        }
+
+        return endpoint;
+    }
+}

package/tsc/webusb/index.ts

@@ -0,0 +1,363 @@
+import * as usb from '../usb';
+import { EventEmitter } from 'events';
+import { WebUSBDevice } from './webusb-device';
+
+/**
+ * USB Options
+ */
+export 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;
+}
+
+export class WebUSB implements USB {
+
+    protected emitter = new EventEmitter();
+    protected knownDevices: Map<string, USBDevice> = new Map();
+    protected allowedDevices: USBDeviceFilter[];
+
+    constructor(private options: USBOptions = {}) {
+        this.allowedDevices = options.allowedDevices || [];
+
+        const deviceConnectCallback = async (device: usb.Device) => {
+            const webDevice = await WebUSBDevice.createInstance(device);
+
+            // When connected, emit an event if it is an allowed device
+            if (webDevice && this.isAllowedDevice(webDevice)) {
+                const deviceId = this.getDeviceId(device);
+                if (deviceId) {
+                    this.knownDevices.set(deviceId, webDevice);
+                }
+
+                const event = {
+                    type: 'connect',
+                    device: webDevice
+                };
+
+                this.emitter.emit('connect', event);
+            }
+        };
+
+        const deviceDisconnectCallback = async (device: usb.Device) => {
+            const deviceId = this.getDeviceId(device);
+
+            // When disconnected, emit an event if the device was a known allowed device
+            if (deviceId !== undefined && this.knownDevices.has(deviceId)) {
+                const webDevice = this.knownDevices.get(deviceId);
+
+                if (webDevice && this.isAllowedDevice(webDevice)) {
+                    const event = {
+                        type: 'disconnect',
+                        device: webDevice
+                    };
+
+                    this.emitter.emit('disconnect', event);
+                }
+            }
+        };
+
+        this.emitter.on('newListener', event => {
+            const listenerCount = this.emitter.listenerCount(event);
+
+            if (listenerCount !== 0) {
+                return;
+            }
+
+            if (event === 'connect') {
+                usb.addListener('attach', deviceConnectCallback);
+            } else if (event === 'disconnect') {
+                usb.addListener('detach', deviceDisconnectCallback);
+            }
+        });
+
+        this.emitter.on('removeListener', event => {
+            const listenerCount = this.emitter.listenerCount(event);
+
+            if (listenerCount !== 0) {
+                return;
+            }
+
+            if (event === 'connect') {
+                usb.removeListener('attach', deviceConnectCallback);
+            } else if (event === 'disconnect') {
+                usb.removeListener('detach', deviceDisconnectCallback);
+            }
+        });
+    }
+
+    private _onconnect: ((ev: USBConnectionEvent) => void) | undefined;
+    public set onconnect(fn: (ev: USBConnectionEvent) => void) {
+        if (this._onconnect) {
+            this.removeEventListener('connect', this._onconnect);
+            this._onconnect = undefined;
+        }
+
+        if (fn) {
+            this._onconnect = fn;
+            this.addEventListener('connect', this._onconnect);
+        }
+    }
+
+    private _ondisconnect: ((ev: USBConnectionEvent) => void) | undefined;
+    public set ondisconnect(fn: (ev: USBConnectionEvent) => void) {
+        if (this._ondisconnect) {
+            this.removeEventListener('disconnect', this._ondisconnect);
+            this._ondisconnect = undefined;
+        }
+
+        if (fn) {
+            this._ondisconnect = fn;
+            this.addEventListener('disconnect', this._ondisconnect);
+        }
+    }
+
+    public addEventListener(type: 'connect' | 'disconnect', listener: (this: this, ev: USBConnectionEvent) => void): void;
+    public addEventListener(type: 'connect' | 'disconnect', listener: EventListener): void;
+    public addEventListener(type: string, listener: (ev: USBConnectionEvent) => void): void {
+        this.emitter.addListener(type, listener);
+    }
+
+    public removeEventListener(type: 'connect' | 'disconnect', callback: (this: this, ev: USBConnectionEvent) => void): void;
+    public removeEventListener(type: 'connect' | 'disconnect', callback: EventListener): void;
+    public removeEventListener(type: string, callback: (this: this, ev: USBConnectionEvent) => void): void {
+        this.emitter.removeListener(type, callback);
+    }
+
+    public dispatchEvent(_event: Event): boolean {
+        // 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
+     */
+    public async requestDevice(options?: USBDeviceRequestOptions): Promise<USBDevice> {
+        // 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(options, device));
+
+        if (devices.length === 0) {
+            throw new Error('requestDevice error: no devices found');
+        }
+
+        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 Error('selected device not found');
+            }
+
+            if (!this.isAllowedDevice(device)) {
+                this.allowedDevices.push({
+                    vendorId: device.vendorId,
+                    productId: device.productId,
+                    serialNumber: device.serialNumber
+                });
+            }
+
+            return device;
+        } catch (error) {
+            throw new Error(`requestDevice error: ${error}`);
+        }
+    }
+
+    /**
+     * Gets all allowed Web USB devices which are connected
+     * @returns Promise containing an array of devices
+     */
+    public async getDevices(): Promise<USBDevice[]> {
+        let preFilters: USBDeviceFilter[] | undefined;
+
+        if (!this.options.allowAllDevices) {
+            // Create pre-filters
+            preFilters = this.allowedDevices.map(device => ({
+                vendorId: device.vendorId || undefined,
+                productId: device.productId || undefined,
+                serialNumber: device.serialNumber || undefined
+            }));
+        }
+
+        // Refresh devices and filter for allowed ones
+        const devices = await this.loadDevices(preFilters);
+        return devices.filter(device => this.isAllowedDevice(device));
+    }
+
+    private async loadDevices(preFilters?: USBDeviceFilter[]): Promise<USBDevice[]> {
+        let devices = usb.getDeviceList();
+
+        // Pre-filter devices
+        devices = this.preFilterDevices(devices, preFilters);
+
+        const webDevices: USBDevice[] = [];
+
+        for (const device of devices) {
+            if (this.options.deviceTimeout) {
+                device.timeout = this.options.deviceTimeout;
+            }
+
+            const webDevice = await WebUSBDevice.createInstance(device);
+            if (webDevice) {
+                webDevices.push(webDevice);
+
+                const deviceId = this.getDeviceId(device);
+                if (deviceId) {
+                    this.knownDevices.set(deviceId, webDevice);
+                }
+            }
+        }
+
+        return webDevices;
+    }
+
+    private preFilterDevices(devices: usb.Device[], preFilters?: USBDeviceFilter[]): usb.Device[] {
+        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.deviceDescriptor.idVendor) return false;
+
+            // Product
+            if (filter.productId && filter.productId !== device.deviceDescriptor.idProduct) return false;
+
+            // Ignore serial number for node-usb as it requires device connection
+            return true;
+        }));
+    }
+
+    private filterDevice(options: USBDeviceRequestOptions, device: USBDevice): boolean {
+        if (!options.filters || !options.filters.length) {
+            return true;
+        }
+
+        return options.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;
+        });
+    }
+
+    private getDeviceId(device: usb.Device): string | undefined {
+        if (device.busNumber === undefined || device.deviceAddress === undefined) {
+            return undefined;
+        }
+
+        return `${device.busNumber}.${device.deviceAddress}`;
+    }
+
+    private isAllowedDevice(device: USBDeviceFilter): boolean {
+        if (this.options.allowAllDevices) {
+            return true;
+        }
+
+        const isSameDevice = (device1: USBDeviceFilter, device2: USBDeviceFilter): boolean => {
+            return (device1.productId === device2.productId
+                && device1.vendorId === device2.vendorId
+                && device1.serialNumber === device2.serialNumber);
+        };
+
+        for (const i in this.allowedDevices) {
+            if (isSameDevice(device, this.allowedDevices[i])) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}

package/tsc/webusb/mutex.ts

@@ -0,0 +1,38 @@
+/**
+ * A mutex implementation that can be used to lock access between concurrent async functions
+ */
+export class Mutex {
+    private locked: boolean;
+
+    /**
+     * Create a new Mutex
+     */
+    constructor() {
+        this.locked = false;
+    }
+
+    /**
+     *  Yield the current execution context, effectively moving it to the back of the promise queue
+     */
+    private async sleep(): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, 1));
+    }
+
+    /**
+     * Wait until the Mutex is available and claim it
+     */
+    public async lock(): Promise<void> {
+        while (this.locked) {
+            await this.sleep();
+        }
+
+        this.locked = true;
+    }
+
+    /**
+     * Unlock the Mutex
+     */
+    public unlock(): void {
+        this.locked = false;
+    }
+}