# nrf-ble-usb > List USB/serialport devices based on traits and conflate them by serial number Latest version **2.5.6** (published 2021-08-03) · SEE LICENSE IN LICENSE license · 0 weekly downloads ## Install ```sh npm install nrf-ble-usb pnpm add nrf-ble-usb yarn add nrf-ble-usb bun add nrf-ble-usb ``` Provides the command `nrf-device-lister`. ## Health **Score 20/100 (F)** — status: abandoned. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 2.5.6 | | Published | 2021-08-03 | | First published | 2021-08-02 | | Weekly downloads | 0 | | License | SEE LICENSE IN LICENSE | | TypeScript types | none | | Module format | ESM + CommonJS | | Dependencies | 5 | | Unpacked size | 128.4 KB | | Known vulnerabilities | 0 (+1 in 1 direct dependencies) | | Install scripts | no | | Author | Nordic Semiconductor ASA | | Maintainers | yongle_work | ## Links - npm: https://www.npmjs.com/package/nrf-ble-usb - npm.io page: https://npm.io/package/nrf-ble-usb ## Dependencies (5) - [usb](https://npm.io/package/usb.md) ~1.7.1 - [debug](https://npm.io/package/debug.md) ~4.1.1 - [commander](https://npm.io/package/commander.md) ~2.20.0 - [serialport](https://npm.io/package/serialport.md) ~9.2.0 - [await-semaphore](https://npm.io/package/await-semaphore.md) ~0.1.3 ## Recent versions - 2.5.6 (latest) — 2021-08-03 - 2.5.5 — 2021-08-02 - 2.5.4 — 2021-08-02 ## README # nrf-device-lister [![Build Status](https://dev.azure.com/NordicSemiconductor/Wayland/_apis/build/status/nrf-device-lister-js?branchName=master)](https://dev.azure.com/NordicSemiconductor/Wayland/_build/latest?definitionId=13&branchName=master) [![License](https://img.shields.io/badge/license-Modified%20BSD%20License-blue.svg)](LICENSE) List USB/serialport devices based on traits and conflate them by serial number This is part of [Nordic Semiconductor](http://www.nordicsemi.com/)'s javascript tools to interface with nRF SoCs and development kits. ## Building prerequisites Node.js 8 or newer ## Usage as a command Do a `npm install nrf-device-lister` or `yarn add nrf-device-lister`, then run in a console: `node node_modules/.bin/nrf-device-lister --help` All options are displayed there. ## Usage as a library ```js // Import / require var DeviceLister = require('nrf-device-lister'); // Create an instance, specifying which kind of traits to look for, // as booleans. var lister = new DeviceLister({ usb: true, nordicUsb: false, // Like 'usb', but filters by VendorId seggerUsb: false, // Like 'usb', but filters by VendorId nordicDfu: false, // Like 'nordicUsb', but also looks for the Nordic DFU trigger interface serialport: true, }); // When started, the lister will two three kinds of events: // The 'conflated' event fires whenever there is a new conflated list of // devices (i.e. after each reenumeration). This list is an instance of Map, // with the serial number of each device as the keys. // Each device has a list of the traits that devices shows. // USB devices have a minimal data structure containing a Device instance, // as per the 'usb' module. Serial port devices have the metadata structure // returned by the 'list()' function of the 'serialport' module. J-link probes // only have the trait. lister.on('conflated', function(deviceMap){ // Loop through map, etc // Each item in the Map will look like this: /* { traits: ['serialport', 'usb', 'seggerUsb' ], serialNumber: '00012345678', usb: { serialNumber: '00012345678', manufacturer: 'SEGGER', product: 'J-Link', device: (Instance of Device as per 'usb' module) } serialport: { manufacturer: 'SEGGER', serialNumber: '00012345678', pnpId: 'usb-SEGGER_J-Link_00012345678-if00', locationId: undefined, vendorId: '1366', productId: '1015', path: '/dev/ttyACM1' } } */ }); // The 'error' event fires whenever a serial number could not be // fetched, or when enumeration failed. // There are some specific cases where this will happen: no permissions // to open a USB device through libusb, an error in serial ports without a serial number // (e.g. those built into the motherboard). // The recommendation is to raise all errors related to devices with any USB trait only if their Product ID/Vendor ID // (as listed in the usb Device) are of interest to your application. // Errors that happen on consecutive enumerations are throttled down: only // the first one is emitted. lister.on('error', function(err){ // `err` is an instance of Error console.error(err.message+ ' (error code: '+err.errorCode+')'); // Optionally, if the error originated from a USB device, there will // be an `usb` property with an instance of `usb`'s `Device`: if (err.usb) { console.error('Error originated from USB device ' + 'VID: ' + err.usb.deviceDescriptor.idVendor + ' ' + 'PID: ' + err.usb.deviceDescriptor.idProduct ); } // Optionally, if the error originated from a serial port, there will // be an `serialport` property with the serial port metadata: if (err.serialport) { console.error('Error originated from serial port device at ' + err.serialport.path ); } }); // Ask for *one* enumeration of devices. Result is a Promise for a map of devices, // just like the parameter for the handler of the `conflated` event. // Note that calling reenumerate() will also trigger *one* `conflated` event. lister.reenumerate().then(function(deviceMap){ // ...iterate through deviceMap and do something... }); // Start listening to hardware changes (in connected/disconnected USB devices). lister.start(); // When all is done (or after some time, etc), stop listening to hardware changes // (in connected/disconnected USB devices) setTimeout(function(){ lister.stop(); }, 5000); ``` ## Development ### Build The project is using `rollup.js`, so the following command is needed to run the build: npm run rollup ### Test #### Equipments The project comes with automated integration tests in the `test` directory. In order to run the basic tests, the following devices must be connected to the PC: * Nordic USB devices In order to run the full tests, e.g. on the build server, the following device must be connected to the PC together with environment variables set (see below): * a nRF52840 development kit attached to the PC on CDC ACM port #### Environment Variables The following environment variables need to be set to specify certain devices for the tests. * NRF52840_DK_USB_SERIAL_NUMBER To run the tests: npm test ## Error Codes Error codes are accessed from `DeviceLister.ErrorCodes`. Error message |Constant | Error code ----------------------------------------------------------------|----------------------------------|------------- Cannot instantiate AbstractBackend. |CANNOT_INSTANTIATE_ABSTRACTBACKEND| 0 Reenumerate must be implemented in _constructorName_ |REENUMERATE_NOT_IMPLEMENTED | 1 Received neither serial number nor error! |RECEIVED_NEITHER_SNO_NOR_ERROR | 2 Could not fetch serial number for serial port at _comName_ |COULD_NOT_FETCH_SNO_FOR_PORT | 3 LIBUSB_SUCCESS |LIBUSB_SUCCESS | 100 LIBUSB_ERROR_IO |LIBUSB_ERROR_IO | 101 LIBUSB_ERROR_INVALID_PARAM |LIBUSB_ERROR_INVALID_PARAM | 102 LIBUSB_ERROR_ACCESS |LIBUSB_ERROR_ACCESS | 103 LIBUSB_ERROR_NO_DEVICE |LIBUSB_ERROR_NO_DEVICE | 104 LIBUSB_ERROR_NOT_FOUND |LIBUSB_ERROR_NOT_FOUND | 105 LIBUSB_ERROR_BUSY |LIBUSB_ERROR_BUSY | 106 LIBUSB_ERROR_TIMEOUT |LIBUSB_ERROR_TIMEOUT | 107 LIBUSB_ERROR_OVERFLOW |LIBUSB_ERROR_OVERFLOW | 108 LIBUSB_ERROR_PIPE |LIBUSB_ERROR_PIPE | 109 LIBUSB_ERROR_INTERRUPTED |LIBUSB_ERROR_INTERRUPTED | 110 LIBUSB_ERROR_NO_MEM |LIBUSB_ERROR_NO_MEM | 111 LIBUSB_ERROR_NOT_SUPPORTED |LIBUSB_ERROR_NOT_SUPPORTED | 112 LIBUSB_ERROR_OTHER |LIBUSB_ERROR_OTHER | 113 --- _Source: https://npm.io/package/nrf-ble-usb · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._