add deviceId filter for requestDevice

Author: hugomontero

README.md

@@ -95,6 +95,17 @@ button.addEventListener('click', async () => {
 });
 ```
 
+Pass an `id` to scope the picker to a single device. The picker lists that device in whichever mode it
+is currently in, and updates live as it enumerates, which is useful to grant access to a device that is
+about to enter DFU mode (the browser keeps a separate grant for the DFU mode of a device):
+
+```js
+button.addEventListener('click', async () => {
+  const device = await usb.requestDevice({ id: '0123456789abcdef01234567' });
+  await device.open();
+});
+```
+
 All three must be called from a user gesture, such as a click handler. Outside of one the browser
 refuses to show the picker, so you only get back devices that were already granted access.
 

src/device-base.js

@@ -815,16 +815,17 @@ async function openNativeUsbDevice(nativeUsbDevice, options = null) {
 	return dev;
 }
 
-async function requestDevice({ types = [], includeDfu = true } = {}) {
+async function requestDevice({ types = [], includeDfu = true, id } = {}) {
 	types = types.map(type => type.toLowerCase());
 	const filters = [];
+	const addFilter = (usbIds) => filters.push(id ? Object.assign({ serialNumber: id }, usbIds) : usbIds);
 	PLATFORMS.forEach((platform) => {
 		if (types.length === 0 || types.includes(platform.name)) {
 			if (platform && platform.usb && platform.usb.vendorId) {
-				filters.push(platform.usb);
+				addFilter(platform.usb);
 			}
 			if (includeDfu && platform && platform.dfu && platform.dfu.vendorId) {
-				filters.push(platform.dfu);
+				addFilter(platform.dfu);
 			}
 		}
 	});

src/device-base.test.js

@@ -5,6 +5,12 @@ const proxyquire = require('proxyquire');
 const { getDevices, openDeviceById, openNativeUsbDevice, PollingPolicy } = proxyquire('../src/device-base', {
 	'./usb-device-node': fakeUsb
 });
+// requestDevice() is browser-only, so the node implementation always throws. Stub it out to inspect
+// the filters the library passes down to WebUSB.
+const requestUsbDeviceStub = sinon.stub();
+const { requestDevice } = proxyquire('../src/device-base', {
+	'./usb-device-node': Object.assign({}, fakeUsb, { requestUsbDevice: requestUsbDeviceStub })
+});
 const usbImpl = require('./usb-device-node');
 const proto = require('./usb-protocol');
 const error = require('./error');
@@ -195,6 +201,65 @@ describe('device-base', () => {
 		});
 	});
 
+	describe('requestDevice()', () => {
+		beforeEach(() => {
+			requestUsbDeviceStub.reset();
+		});
+
+		it('does not filter by serial number by default', async () => {
+			const photon = fakeUsb.addPhoton();
+			requestUsbDeviceStub.resolves(photon);
+			const dev = await requestDevice();
+			expect(dev.usbDevice).to.equal(photon);
+			const filters = requestUsbDeviceStub.firstCall.args[0];
+			expect(filters).to.not.be.empty;
+			expect(filters.every(f => f.serialNumber === undefined)).to.be.true;
+		});
+
+		it('filters by serial number when an ID is specified', async () => {
+			const photon = fakeUsb.addPhoton({ id: '111111111111111111111111' });
+			requestUsbDeviceStub.resolves(photon);
+			const dev = await requestDevice({ id: '111111111111111111111111' });
+			expect(dev.usbDevice).to.equal(photon);
+			const filters = requestUsbDeviceStub.firstCall.args[0];
+			expect(filters).to.not.be.empty;
+			expect(filters.every(f => f.serialNumber === '111111111111111111111111')).to.be.true;
+			// The ID applies to both the regular and the DFU USB IDs of each platform
+			expect(filters).to.containSubset([{
+				serialNumber: '111111111111111111111111',
+				vendorId: photon.vendorId,
+				productId: photon.productId
+			}]);
+		});
+
+		it('filters by serial number for the requested device types only', async () => {
+			const photon = fakeUsb.addPhoton({ id: '111111111111111111111111' });
+			requestUsbDeviceStub.resolves(photon);
+			await requestDevice({ types: ['photon'], includeDfu: false, id: '111111111111111111111111' });
+			const filters = requestUsbDeviceStub.firstCall.args[0];
+			expect(filters).to.have.lengthOf(1);
+			expect(filters).to.containSubset([{
+				serialNumber: '111111111111111111111111',
+				vendorId: photon.vendorId,
+				productId: photon.productId
+			}]);
+		});
+
+		it('does not modify the platform USB IDs', async () => {
+			const photon = fakeUsb.addPhoton({ id: '111111111111111111111111' });
+			requestUsbDeviceStub.resolves(photon);
+			await requestDevice({ id: '111111111111111111111111' });
+			await requestDevice();
+			const filters = requestUsbDeviceStub.secondCall.args[0];
+			expect(filters.every(f => f.serialNumber === undefined)).to.be.true;
+		});
+
+		it('fails if no device type matches the requested types', async () => {
+			await expect(requestDevice({ types: ['nonexistent'] })).to.be.rejectedWith(RangeError);
+			expect(requestUsbDeviceStub).to.have.not.been.called;
+		});
+	});
+
 	describe('openNativeUsbDevice()', () => {
 		it('opens a native usb device', async () => {
 			const fakeNativeDevice = {

src/particle-usb.js

@@ -54,6 +54,8 @@ function openNativeUsbDevice(nativeUsbDevice, options) {
  * @param {Array<String>} [options.types] Device types (photon, boron, tracker, etc). By default,
  *        the user can pick a device of any platform supported by the library.
  * @param {Boolean} [options.includeDfu=true] Whether to include devices in DFU mode.
+ * @param {String} [options.id] Device ID. If specified, the picker only lists the device with that ID,
+ *        in whichever mode it is currently in. By default, the user can pick any matching device.
  * @return {Promise<Device>} The device the user has selected.
  * @throws {NotFoundError} The user dismissed the prompt without selecting a device.
  * @throws {NotAllowedError} Called outside of a browser environment.