sportident.js 1.0.0

package/src/SiDevice/WebUsbSiDeviceDriver.ts

@@ -0,0 +1,343 @@
+import * as utils from '../utils';
+import { DeviceClosedError, SiDeviceState } from '../SiDevice/ISiDevice';
+import type { ISiDevice, ISiDeviceDriverData } from '../SiDevice/ISiDevice';
+import { SiDeviceAddEvent, SiDeviceRemoveEvent } from '../SiDevice/ISiDeviceDriver';
+import type { ISiDeviceDriver, ISiDeviceDriverWithAutodetection, ISiDeviceDriverWithDetection, SiDeviceDriverWithAutodetectionEvents } from '../SiDevice/ISiDeviceDriver';
+import { SiDevice } from '../SiDevice/SiDevice';
+import type * as nav from './INavigatorWebUsb';
+
+const siConfiguration = 1;
+const siAlternate = 0;
+const siPacketSize = 64;
+const siUsbClassCode = 255;
+const siDeviceFilters = [{ vendorId: 0x10c4, productId: 0x800a }];
+const matchesSiDeviceFilters = (vendorId: number, productId: number) => siDeviceFilters.some((filter) => vendorId === filter.vendorId && productId === filter.productId);
+
+const getIdent = (device: nav.WebUsbDevice) => `${device.serialNumber}`;
+
+function findEndpoint(iface: USBInterface, direction: USBDirection): USBEndpoint {
+	const alternate = iface.alternates[0];
+	for (const endpoint of alternate.endpoints) {
+		if (endpoint.direction == direction) {
+			return endpoint;
+		}
+	}
+	throw new TypeError(`Interface ${iface.interfaceNumber} does not have an ` + `${direction} endpoint.`);
+}
+function findInterface(device: nav.WebUsbDevice): USBInterface {
+	const configuration = device.configurations[0];
+	for (const iface of configuration.interfaces) {
+		const alternate = iface.alternates[0];
+		if (alternate.interfaceClass === siUsbClassCode) {
+			return iface;
+		}
+	}
+	throw new TypeError(`Unable to find interface with class ${siUsbClassCode}.`);
+}
+export interface WebUsbSiDeviceDriverData extends ISiDeviceDriverData<WebUsbSiDeviceDriver> {
+	driver: WebUsbSiDeviceDriver;
+	device: nav.WebUsbDevice;
+}
+
+interface WebUsbAutodetectionCallbacks {
+	onConnect: utils.EventCallback<nav.WebUsbConnectEvent>;
+	onDisconnect: utils.EventCallback<nav.WebUsbDisconnectEvent>;
+}
+
+export type IWebUsbSiDevice = ISiDevice<WebUsbSiDeviceDriverData>;
+export type WebUsbSiDevice = SiDevice<WebUsbSiDeviceDriverData>;
+
+class WebUsbSiDeviceDriver
+	implements ISiDeviceDriver<WebUsbSiDeviceDriverData>, ISiDeviceDriverWithDetection<WebUsbSiDeviceDriverData, []>, ISiDeviceDriverWithAutodetection<WebUsbSiDeviceDriverData>
+{
+	public name = 'WebUSB';
+
+	private siDeviceByIdent: { [ident: string]: WebUsbSiDevice } = {};
+
+	private autodetectedSiDevices: { [ident: string]: WebUsbSiDevice } = {};
+
+	private autodetectionCallbacks?: WebUsbAutodetectionCallbacks;
+
+	constructor(private navigatorUsb: nav.WebUsb) {}
+
+	detect(): Promise<WebUsbSiDevice> {
+		return this.navigatorUsb
+			.requestDevice({
+				filters: siDeviceFilters
+			})
+			.catch((e) => {
+				return Promise.reject(new Error('Failed to get access to USB device! ' + e.toString()));
+			})
+			.then((navigatorWebUsbDevice: nav.WebUsbDevice) => this.autodetectSiDevice(navigatorWebUsbDevice))
+			.catch((e) => {
+				return Promise.reject(new Error('Failed to initialize Si Device! ' + e.toString()));
+			});
+	}
+
+	getSiDevice(navigatorWebUsbDevice: nav.WebUsbDevice): WebUsbSiDevice {
+		const ident = getIdent(navigatorWebUsbDevice);
+		if (this.siDeviceByIdent[ident] !== undefined) {
+			return this.siDeviceByIdent[ident];
+		}
+		const newSiDeviceData: WebUsbSiDeviceDriverData = {
+			driver: this,
+			device: navigatorWebUsbDevice
+		};
+		const newSiDevice = new SiDevice(ident, newSiDeviceData);
+		this.siDeviceByIdent[ident] = newSiDevice;
+		return newSiDevice;
+	}
+
+	forgetSiDevice(siDevice: IWebUsbSiDevice) {
+		const navigatorWebUsbDevice = siDevice.data.device;
+		const ident = getIdent(navigatorWebUsbDevice);
+		delete this.siDeviceByIdent[ident];
+		if (this.autodetectedSiDevices[ident] !== undefined) {
+			this.dispatchEvent('remove', new SiDeviceRemoveEvent(siDevice));
+		}
+		delete this.autodetectedSiDevices[ident];
+	}
+
+	startAutoDetection(): Promise<IWebUsbSiDevice[]> {
+		this.registerAutodetectionCallbacks();
+		return this.getAutodetectedDevices();
+	}
+
+	getAutodetectedDevices(): Promise<WebUsbSiDevice[]> {
+		return this.navigatorUsb.getDevices().then((navigatorWebUsbDevices: nav.WebUsbDevice[]) => this.autodetectSiDevices(navigatorWebUsbDevices));
+	}
+
+	autodetectSiDevices(navigatorWebUsbDevices: nav.WebUsbDevice[]): Promise<WebUsbSiDevice[]> {
+		// TODO: Make this easier when Promise.allSettled polyfill is available
+		return new Promise((resolve) => {
+			let numSettled = 0;
+			const devices: WebUsbSiDevice[] = [];
+			const onSettled = () => {
+				numSettled += 1;
+				if (numSettled === navigatorWebUsbDevices.length) {
+					resolve(devices);
+				}
+			};
+			navigatorWebUsbDevices.forEach((navigatorWebUsbDevice: nav.WebUsbDevice) =>
+				this.autodetectSiDevice(navigatorWebUsbDevice)
+					.then((siDevice: WebUsbSiDevice) => {
+						devices.push(siDevice);
+						onSettled();
+					})
+					.catch(() => onSettled())
+			);
+		});
+	}
+
+	autodetectSiDevice(navigatorWebUsbDevice: nav.WebUsbDevice): Promise<WebUsbSiDevice> {
+		if (!matchesSiDeviceFilters(navigatorWebUsbDevice.vendorId, navigatorWebUsbDevice.productId)) {
+			return Promise.reject(new Error('Not a SI device'));
+		}
+		const ident = getIdent(navigatorWebUsbDevice);
+		if (this.autodetectedSiDevices[ident] !== undefined) {
+			return Promise.reject(new Error('Duplicate SI device'));
+		}
+		const siDevice = this.getSiDevice(navigatorWebUsbDevice);
+		this.autodetectedSiDevices[ident] = siDevice;
+		return siDevice.open();
+	}
+
+	registerAutodetectionCallbacks(): void {
+		if (this.autodetectionCallbacks !== undefined) {
+			return;
+		}
+		const onConnectCallback = (event: nav.WebUsbConnectEvent) => {
+			const navigatorWebUsbDevice = event.device;
+			this.autodetectSiDevice(navigatorWebUsbDevice)
+			.then((openedDevice: WebUsbSiDevice) => {
+				this.dispatchEvent('add', new SiDeviceAddEvent(openedDevice));
+			})
+		};
+		this.navigatorUsb.addEventListener('connect', onConnectCallback);
+		const onDisconnectCallback = (event: nav.WebUsbDisconnectEvent) => {
+			const navigatorWebUsbDevice = event.device;
+			const ident = getIdent(navigatorWebUsbDevice);
+			const siDevice = this.siDeviceByIdent[ident];
+			if (siDevice === undefined) {
+				return;
+			}
+			this.forgetSiDevice(siDevice);
+		};
+		this.navigatorUsb.addEventListener('disconnect', onDisconnectCallback);
+		this.autodetectionCallbacks = {
+			onConnect: onConnectCallback,
+			onDisconnect: onDisconnectCallback
+		};
+	}
+
+	stopAutoDetection(): Promise<void> {
+		this.deregisterAutodetectionCallbacks();
+		return this.closeAutoOpened();
+	}
+
+	deregisterAutodetectionCallbacks(): void {
+		if (this.autodetectionCallbacks === undefined) {
+			return;
+		}
+		this.navigatorUsb.removeEventListener('connect', this.autodetectionCallbacks.onConnect);
+		this.navigatorUsb.removeEventListener('disconnect', this.autodetectionCallbacks.onDisconnect);
+		this.autodetectionCallbacks = undefined;
+	}
+
+	closeAutoOpened(): Promise<void> {
+		return Promise.all(Object.values(this.autodetectedSiDevices).map((autoOpenedDevice) => autoOpenedDevice.close())).then(() => {
+			this.autodetectedSiDevices = {};
+		});
+	}
+
+	open(device: IWebUsbSiDevice): Promise<void> {
+		console.debug('Opening...');
+		const navigatorDevice = device.data.device;
+		return navigatorDevice
+			.open()
+			.then(() => {
+				try {
+					console.debug('Resetting...');
+					return navigatorDevice.reset();
+				} catch (e) {
+					console.error('Failed resetting web usb device:', e);
+				}
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to reset usb device'));
+			})
+			.then(() => {
+				try {
+					console.debug('Selecting Configuration...');
+					return navigatorDevice.selectConfiguration(siConfiguration);
+				} catch (e) {
+					console.error('Failed selecting configuration of web usb device:', e);
+				}
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to select configuration of usb device'));
+			})
+			.then(() => {
+				try {
+					console.debug('Claiming Interface...');
+					return navigatorDevice.claimInterface(findInterface(navigatorDevice).interfaceNumber);
+				} catch (e) {
+					console.error('Failed claiming web usb device interface:', e);
+				}
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to claim usb device interface'));
+			})
+			.then(() => {
+				try {
+					console.debug('Selection Alternate Interface...');
+					return navigatorDevice.selectAlternateInterface(findInterface(navigatorDevice).interfaceNumber, siAlternate);
+				} catch (e) {
+					console.error('Failed selecting alternate interface web usb device:', e);
+				}
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to select alternate interface of usb device'));
+			})
+			.then(() => {
+				try {
+					console.debug('Enabling Serial...');
+					return navigatorDevice.controlTransferOut({
+						requestType: 'vendor',
+						recipient: 'interface',
+						request: 0x00,
+						value: 0x01,
+						index: findInterface(navigatorDevice).interfaceNumber
+					});
+				} catch (e) {
+					console.error('Failed enabling serial on web usb device:', e);
+				}
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to enable serial on usb device'));
+			})
+			.then(() => {
+				try {
+					console.debug('Setting Baudrate...');
+					return navigatorDevice.controlTransferOut(
+						{
+							requestType: 'vendor',
+							recipient: 'interface',
+							request: 0x1e,
+							value: 0x00,
+							index: findInterface(navigatorDevice).interfaceNumber
+						},
+						new Uint8Array([0x00, 0x96, 0x00, 0x00]).buffer
+					);
+				} catch (e) {
+					console.error('Failed setting baudrate on web usb device:', e);
+				}
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to set baudrate on usb device'));
+			});
+	}
+
+	async close(device: IWebUsbSiDevice): Promise<void> {
+		console.debug('Disabling Serial...');
+		const navigatorDevice = device.data.device;
+		navigatorDevice
+			.controlTransferOut({
+				requestType: 'vendor',
+				recipient: 'interface',
+				request: 0x00,
+				value: 0x00,
+				index: findInterface(navigatorDevice).interfaceNumber
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to shutdown usb device'));
+			})
+			.then(() => {
+				console.debug('Releasing Interface...');
+				return navigatorDevice.releaseInterface(findInterface(navigatorDevice).interfaceNumber);
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to release claimed usb device interface'));
+			})
+			.then(() => {
+				console.debug('Closing Device...');
+				return navigatorDevice.close();
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to close usb device'));
+			})
+			.then(() => {
+				return this.forgetSiDevice(device);
+			})
+			.catch((_e) => {
+				return Promise.reject(new Error('Failed to forget usb device'));
+			})
+	}
+
+	receive(device: IWebUsbSiDevice): Promise<number[]> {
+		const navigatorDevice = device.data.device;
+		if (navigatorDevice.opened !== true) {
+			console.warn('Device has been closed. Stopping receive loop.');
+			device.setState(SiDeviceState.Closed);
+			throw new DeviceClosedError();
+		}
+		return navigatorDevice.transferIn(findEndpoint(findInterface(navigatorDevice), 'in').endpointNumber, siPacketSize).then((response) => {
+			if (!response.data) {
+				return [];
+			}
+			const uint8Data = new Uint8Array(response.data.buffer);
+			return [...uint8Data];
+		});
+	}
+
+	async send(device: IWebUsbSiDevice, uint8Data: number[]): Promise<void> {
+		const navigatorDevice = device.data.device;
+		const buffer = new Uint8Array(uint8Data);
+		navigatorDevice.transferOut(findEndpoint(findInterface(navigatorDevice), 'out').endpointNumber, buffer).then(() => true);
+	}
+}
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface WebUsbSiDeviceDriver extends utils.EventTarget<SiDeviceDriverWithAutodetectionEvents<WebUsbSiDeviceDriverData>> {}
+utils.applyMixins(WebUsbSiDeviceDriver, [utils.EventTarget]);
+
+export const getWebUsbSiDeviceDriver = (navigatorWebUsb: USB): WebUsbSiDeviceDriver => new WebUsbSiDeviceDriver(<nav.WebUsb>(<unknown>navigatorWebUsb));

package/src/SiDevice/index.ts

@@ -0,0 +1,3 @@
+export { SiDevice } from './SiDevice';
+export type { ISiDevice } from './ISiDevice';
+export type { ISiDeviceDriver } from './ISiDeviceDriver';

package/src/SiDevice/testUtils/index.ts

@@ -0,0 +1,2 @@
+export { testISiDeviceDriver } from './testISiDeviceDriver';
+export { testISiDeviceDriverWithAutodetection } from './testISiDeviceDriverWithAutodetection';

package/src/SiDevice/testUtils/testISiDeviceDriver.ts

@@ -0,0 +1,63 @@
+import { expect, test } from '@jest/globals';
+import * as testUtils from '../../testUtils';
+import type { ISiDevice, ISiDeviceDriverData } from '../ISiDevice';
+import type { ISiDeviceDriver } from '../ISiDeviceDriver';
+
+export interface TestISiDeviceDriverOptions {
+	numTicks: number;
+	waitFor: number;
+}
+
+export const testISiDeviceDriver = <T extends ISiDeviceDriverData<ISiDeviceDriver<T>>>(
+	siDeviceDriverData: T,
+	options: TestISiDeviceDriverOptions = {
+		numTicks: 10,
+		waitFor: 1
+	}
+): (() => void) => {
+	const testFunction = () => {
+		const advanceTime = () => testUtils.advanceTimersByTime(options.waitFor);
+		const waitForDriver = () => testUtils.nTimesAsync(options.numTicks, advanceTime);
+		test('driver has a name', () => {
+			expect(siDeviceDriverData.driver.name).not.toBe('');
+		});
+		test('driver can open-receive-send-close', () => {
+			const asyncCall = async () => {
+				const siDevice = {
+					data: siDeviceDriverData
+				} as ISiDevice<T>;
+
+				let openSuccessful = false;
+				siDeviceDriverData.driver.open(siDevice).then(() => {
+					openSuccessful = true;
+				});
+				await waitForDriver();
+				expect(openSuccessful).toBe(true);
+
+				let successfullyReceived: number[] | undefined = undefined;
+				siDeviceDriverData.driver.receive(siDevice).then((received: number[]) => {
+					successfullyReceived = received;
+				});
+				await waitForDriver();
+				expect(successfullyReceived).toEqual([0x01, 0x02, 0x03]);
+
+				let sendSuccessful = false;
+				siDeviceDriverData.driver.send(siDevice, [0x03, 0x02, 0x01]).then(() => {
+					sendSuccessful = true;
+				});
+				await waitForDriver();
+				expect(sendSuccessful).toBe(true);
+
+				let closeSuccessful = false;
+				siDeviceDriverData.driver.close(siDevice).then(() => {
+					closeSuccessful = true;
+				});
+				await waitForDriver();
+				expect(closeSuccessful).toBe(true);
+			};
+
+			asyncCall();
+		});
+	};
+	return testFunction;
+};

package/src/SiDevice/testUtils/testISiDeviceDriverWithAutodetection.ts

@@ -0,0 +1,72 @@
+import { expect, test } from '@jest/globals';
+import * as testUtils from '../../testUtils';
+import { type ISiDeviceDriverData, SiDeviceState } from '../ISiDevice';
+import type { ISiDeviceDriver, ISiDeviceDriverWithAutodetection } from '../ISiDeviceDriver';
+
+export interface TestISiDeviceDriverWithAutodetectionOptions {
+	numTicks: number;
+	waitFor: number;
+}
+
+export const testISiDeviceDriverWithAutodetection = <T extends ISiDeviceDriverData<ISiDeviceDriver<T> & ISiDeviceDriverWithAutodetection<T>>>(
+	siDeviceDriverData: T,
+	nonSiDeviceDriverData: T,
+	simulateConnect: (data: T) => void,
+	simulateDisconnect: (data: T) => void,
+	options: TestISiDeviceDriverWithAutodetectionOptions = {
+		numTicks: 50,
+		waitFor: 1
+	}
+): (() => void) => {
+	const testFunction = () => {
+		const advanceTime = () => testUtils.advanceTimersByTime(options.waitFor);
+		const waitForDriver = () => testUtils.nTimesAsync(options.numTicks, advanceTime);
+		test('driver can startAutoDetection-connect-disconnect-stopAutodetection', async () => {
+			const driver = siDeviceDriverData.driver;
+
+			let numAddCalled = 0;
+			let numRemoveCalled = 0;
+			driver.addEventListener('add', () => numAddCalled++);
+			driver.addEventListener('remove', () => numRemoveCalled++);
+
+			simulateConnect(siDeviceDriverData);
+			await waitForDriver();
+			expect([numAddCalled, numRemoveCalled]).toEqual([0, 0]);
+
+			simulateDisconnect(siDeviceDriverData);
+			await waitForDriver();
+			expect([numAddCalled, numRemoveCalled]).toEqual([0, 0]);
+
+			const initialDevices = await driver.startAutoDetection();
+			expect(initialDevices.length).toBe(1);
+			expect(initialDevices[0].state).toBe(SiDeviceState.Opened);
+
+			simulateConnect(siDeviceDriverData);
+			await waitForDriver();
+			expect([numAddCalled, numRemoveCalled]).toEqual([1, 0]);
+
+			simulateDisconnect(siDeviceDriverData);
+			await waitForDriver();
+			expect([numAddCalled, numRemoveCalled]).toEqual([1, 1]);
+
+			simulateConnect(nonSiDeviceDriverData);
+			await waitForDriver();
+			expect([numAddCalled, numRemoveCalled]).toEqual([1, 1]);
+
+			simulateDisconnect(nonSiDeviceDriverData);
+			await waitForDriver();
+			expect([numAddCalled, numRemoveCalled]).toEqual([1, 1]);
+
+			simulateConnect(siDeviceDriverData);
+			await waitForDriver();
+			expect([numAddCalled, numRemoveCalled]).toEqual([2, 1]);
+
+			simulateDisconnect(siDeviceDriverData);
+			await waitForDriver();
+			expect([numAddCalled, numRemoveCalled]).toEqual([2, 2]);
+
+			await driver.stopAutoDetection();
+		});
+	};
+	return testFunction;
+};