The 'usb' npm package provides a way to interact with USB devices in Node.js. It allows you to list, read from, and write to USB devices, making it useful for applications that need to communicate with hardware peripherals.
Listing USB Devices
This feature allows you to list all USB devices connected to the system. The code sample demonstrates how to use the 'usb' package to retrieve and print the list of connected USB devices.
const usb = require('usb');
const devices = usb.getDeviceList();
console.log(devices);Opening a USB Device
This feature allows you to open a connection to a specific USB device using its vendor and product IDs. The code sample shows how to find and open a USB device.
const usb = require('usb');
const device = usb.findByIds(vendorId, productId);
device.open();Reading from a USB Device
This feature allows you to read data from a USB device. The code sample demonstrates how to open a device, access its endpoint, and read data from it.
const usb = require('usb');
const device = usb.findByIds(vendorId, productId);
device.open();
const endpoint = device.interfaces[0].endpoints[0];
endpoint.transfer(64, (error, data) => {
if (error) {
console.error(error);
} else {
console.log(data);
}
});Writing to a USB Device
This feature allows you to write data to a USB device. The code sample shows how to open a device, access its endpoint, and send data to it.
const usb = require('usb');
const device = usb.findByIds(vendorId, productId);
device.open();
const endpoint = device.interfaces[0].endpoints[1];
const data = Buffer.from('Hello USB');
endpoint.transfer(data, (error) => {
if (error) {
console.error(error);
} else {
console.log('Data sent');
}
});The 'node-hid' package provides access to HID (Human Interface Devices) such as keyboards, mice, and game controllers. It is similar to 'usb' but is specifically designed for HID devices, offering a higher-level API for these types of peripherals.
The 'usb-detection' package allows you to detect when USB devices are added or removed from the system. While it does not provide direct access to USB device communication like 'usb', it is useful for monitoring USB device connections and disconnections.
The 'webusb' package is a polyfill for the WebUSB API, allowing web applications to communicate with USB devices. It is more focused on web environments and provides a different approach compared to the 'usb' package, which is designed for Node.js applications.
Node.JS library for communicating with USB devices.
This is a refactoring / rewrite of Christopher Klein's node-usb.
Node.js >= v10.20.0, which includes npm.
On Windows, if you get LIBUSB_ERROR_NOT_SUPPORTED when attempting to open your device, it's possible your device doesn't have a WinUSB driver for libusb to use.
You can install one using Zadig or another approach is to use the UsbDK Backend of libusb by immediately calling usb.useUsbDkBackend().
Note that you cannot use multiple drivers on Windows as they get exclusive access to the device. So if you want to switch between drivers (e.g. using a printer with this software or the system), you will need to uninstall/install drivers as required.
For further info, check How to use libusb on Windows in the libusb's wiki.
On Linux, you'll need libudev to build libusb if a prebuild is not available. On Ubuntu/Debian:
sudo apt-get install build-essential libudev-dev
You may need to modify your udev and permission rules in order to access your desired device. Along the lines of:
SUBSYSTEM=="usb", ATTR{idVendor}=="USB-VENDOR-ID", ATTR{idProduct}=="USB-PRODUCT-ID", MODE="0660", GROUP="GROUP-YOUR-USER-IS-IN"
For libusb issues, please refer to the FAQ at https://github.com/libusb/libusb/wiki/FAQ
Native modules are bundled using prebuildify, so installation should be as simple as installing the package.
With npm:
npm install usb
With yarn:
yarn add usb
Note: the library is now written in TypeScript, so a separate types file is not longer required to be installed (e.g. don't install @types/usb).
Note that the compiled Node extension includes libusb, and is thus subject to the LGPL.
Does not support:
Use the following examples to kickstart your development. Once you have a desired device, use the APIs below to interact with it.
v2.0.0The legacy API exists on an object called usb on the main import and the convenience functions exist as top level objects.
To use v2.0.0 simply update your import statements and the function calls;
// import * as usb from 'usb';
// const devices: usb.Device[] = usb.getDeviceList();
import { usb, getDeviceList } from 'usb';
const devices: usb.Device[] = getDeviceList();
import { getDeviceList } from 'usb';
const devices = getDeviceList();
for (const device of devices) {
console.log(device); // Legacy device
}
import { findByIds } from 'usb';
const device = findByIds(0x59e3, 0x0a23);
if (device) {
console.log(device); // Legacy device
}
import { findBySerialNumber } from 'usb';
(async () => {
// Uses a blocking call, so is async
const device = await findBySerialNumber('TEST_DEVICE');
if (device) {
console.log(device); // Legacy device
}
})();
import { findBySerialNumber, WebUSBDevice } from 'usb';
(async () => {
// Uses a blocking call, so is async
const device = await findBySerialNumber('TEST_DEVICE');
// Uses blocking calls, so is async
const webDevice = await WebUSBDevice.createInstance(device);
if (webDevice) {
console.log(webDevice); // WebUSB device
}
})();
import { webusb } from 'usb';
(async () => {
// Returns first matching device
const device = await webusb.requestDevice({
filters: [{}]
})
console.log(device); // WebUSB device
})();
import { WebUSB } from 'usb';
(async () => {
const customWebUSB = new WebUSB({
// This function can return a promise which allows a UI to be displayed if required
devicesFound: devices => devices.find(device => device.serialNumber === 'TEST_DEVICE')
});
// Returns device based on injected 'devicesFound' function
const device = await customWebUSB.requestDevice({
filters: [{}]
})
console.log(device); // WebUSB device
})();
import { webusb } from 'usb';
(async () => {
// The default webusb instance follows the WebUSB spec and only returns authorised devices
const devices = await webusb.getDevices();
for (const device of devices) {
console.log(device); // WebUSB device
}
})();
import { WebUSB } from 'usb';
(async () => {
const customWebUSB = new WebUSB({
// Bypass checking for authorised devices
allowAllDevices: true
});
// Uses blocking calls, so is async
const devices = await customWebUSB.getDevices();
for (const device of devices) {
console.log(device); // WebUSB device
}
})();
Please refer to the maintained example for using node-usb in electron:
https://github.com/node-usb/node-usb-example-electron
If using a packaging system for electron, ensure the node-usb library does not get recompiled as the correct binaries are already shipped with the package. For example, for electron-builder, use these settings:
Since v2.0.0, the node-usb library supports two APIs:
WebUSB which follows the WebUSB Specification (recommended)Legacy API which retains the previous 'non-blocking' APIConvenience methods also exist to easily list or find devices as well as convert between a legacy usb.Device device and WebUSB device.
Full auto-generated API documentation can be seen here:
https://node-usb.github.io/node-usb/
Return a list of legacy Device objects for the USB devices attached to the system.
Convenience method to get the first legacy device with the specified VID and PID, or undefined if no such device is present.
Convenience method to get a promise of the legacy device with the specified serial number, or undefined if no such device is present.
Return the navigator.usb instance if it exists, otherwise a webusb instance.
WebUSB Device class for wrapping a legacy Device into a WebUSB device
Convenience method to return a promise of a WebUSB device based on a legacy device
Please refer to the WebUSB specification which be found here:
https://wicg.github.io/webusb/
bytesWritten always equals the initial buffer lengthbytesWritten always equals the initial buffer lengthLegacy usb object.
Constant properties from libusb
Return a list of legacy Device objects for the USB devices attached to the system.
Force polling loop for hotplug events.
Set the libusb debug level (between 0 and 4)
On Windows, use the USBDK backend of libusb instead of WinUSB
Represents a USB device.
Integer USB device number
Integer USB device address
Array containing the USB device port numbers, or undefined if not supported on this platform.
Object with properties for the fields of the device descriptor:
Object with properties for the fields of the configuration descriptor:
Contains all config descriptors of the device (same structure as .configDescriptor above)
Contains the parent of the device, such as a hub. If there is no parent this property is set to null.
Open the device. All methods below require the device to be open before use.
Close the device.
Perform a control transfer with libusb_control_transfer.
Parameter data_or_length can be a integer length for an IN transfer, or a Buffer for an out transfer. The type must match the direction specified in the MSB of bmRequestType.
The data parameter of the callback is always undefined for OUT transfers, or will be passed a Buffer for IN transfers.
A package is available to calculate bmRequestType if needed.
Set the device configuration to something other than the default (0). To use this, first call .open(false) (which tells it not to auto configure), then before claiming an interface, call this method.
Perform a control transfer to retrieve a string descriptor
Perform a control transfer to retrieve an object with properties for the fields of the Binary Object Store descriptor:
Retrieve a list of Capability objects for the Binary Object Store capabilities of the device.
Return the interface with the specified interface number.
List of Interface objects for the interfaces of the default configuration of the device.
Timeout in milliseconds to use for control transfers.
Performs a reset of the device. Callback is called when complete.
Enable/disable libusb's automatic kernel driver detachment (defaults to true in the WebUSB API)
Return the InEndpoint or OutEndpoint with the specified address.
List of endpoints on this interface: InEndpoint and OutEndpoint objects.
Integer interface number.
Integer alternate setting number.
Sets the alternate setting. It updates the interface.endpoints array to reflect the endpoints found in the alternate setting.
Claims the interface. This method must be called before using any endpoints of this interface.
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.
Returns false if a kernel driver is not active; true if active.
Detaches the kernel driver from the interface.
If a LIBUSB_ERROR_ACCESS error is raised, you may need to execute this with elevated privileges.
Re-attaches the kernel driver for the interface.
Object with fields from the interface descriptor -- see libusb documentation or USB spec.
Integer capability type.
Buffer capability data.
Object with fields from the capability descriptor -- see libusb documentation or USB spec.
Common base for InEndpoint and OutEndpoint, see below.
Endpoint direction: "in" or "out".
Endpoint type: usb.LIBUSB_TRANSFER_TYPE_BULK, usb.LIBUSB_TRANSFER_TYPE_INTERRUPT, or usb.LIBUSB_TRANSFER_TYPE_ISOCHRONOUS.
Object with fields from the endpoint descriptor -- see libusb documentation or USB spec.
Sets the timeout in milliseconds for transfers on this endpoint. The default, 0, is infinite timeout.
Clear the halt/stall condition for this endpoint.
Endpoints in the IN direction (device->PC) have this type.
Perform a transfer to read data from the endpoint.
If length is greater than maxPacketSize, libusb will automatically split the transfer in multiple packets, and you will receive one callback with all data once all packets are complete.
this in the callback is the InEndpoint object.
Start polling the endpoint.
The library will keep nTransfers transfers of size transferSize pending in
the kernel at all times to ensure continuous data flow. This is handled by the
libusb event thread, so it continues even if the Node v8 thread is busy. The
data and error events are emitted as transfers complete.
Stop polling.
Further data may still be received. The end event is emitted and the callback
is called once all transfers have completed or canceled.
Emitted with data received by the polling transfers
Emitted when polling encounters an error. All in flight transfers will be automatically canceled and no further polling will be done. You have to wait for the end event before you can start polling again.
Emitted when polling has been canceled
Endpoints in the OUT direction (PC->device) have this type.
Perform a transfer to write data to the endpoint.
If length is greater than maxPacketSize, libusb will automatically split the transfer in multiple packets, and you will receive one callback once all packets are complete.
this in the callback is the OutEndpoint object.
Emitted when the stream encounters an error.
Emitted when the stream has been stopped and all pending requests have been completed.
Attaches a callback to plugging in a device.
Attaches a callback to unplugging a device.
Restore (re-reference) the hotplug events unreferenced by unrefHotplugEvents()
Listening to events will prevent the process to exit. By calling this function, hotplug events will be unreferenced by the event loop, allowing the process to exit even when listening for the attach and detach events.
If you have been referred here by node-usb-detection, the following may be helpful for you to update your existing code.
There is no direct equivalent to these methods. This is handled automatically for you when you add and remove event listeners.
You may find usb.unrefHotplugEvents() useful as it is intended to help with exit conditions.
You can instead use usb.getDeviceList(). Be aware that this will do an enumeration to find all of the devices, and not look at a cache of the known devices. If you call it too often it may have a performance impact.
To find a specific device by vid and pid, call usb.findByIds. e.g. usb.findByIds(0x12, 0x34).
These should be changed to usb.on('attach', function(device) { ... }).
There is no equivalent to filter based on the vid or pid, instead you should do a check inside the callback you provide.
The contents of the device object has also changed.
These should be changed to usb.on('detach', function(device) { ... }).
There is no equivalent to filter based on the vid or pid, instead you should do a check inside the callback you provide.
The contents of the device object has also changed.
There is no direct equivalent to this. Instead you can listen to both attach and detach to get the same behaviour.
The library is based on native bindings wrapping the libusb library.
Libusb is included as a submodule, clone this repository and then the submodule as follows:
git clone https://github.com/node-usb/node-usb
cd node-usb
git submodule update --init
Alternatively, if you want to build this library against your system libusb set the use_system_libusb variable to true in the binding.gyp and libusb.gypi files.
The package uses prebuildify to generate the native binaries using an install script and TypeScript for the binding code using the compile script. The package can be built as follows:
yarn
yarn compile
The native binaries can be rebuilt with:
yarn rebuild
Note: On Linux, you'll need libudev to build libusb. On Ubuntu/Debian:
sudo apt-get install build-essential libudev-dev
To execute the unit tests, Run:
yarn test
Some tests require an attached STM32F103 Microprocessor USB device with specific firmware.
yarn full-test
yarn valgrind
Please refer to the Wiki for release instructions.
FAQs
Library to access USB devices
The npm package usb receives a total of 135,811 weekly downloads. As such, usb popularity was classified as popular.
We found that usb demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
The Socket Research Team has discovered six new malicious npm packages linked to North Korea’s Lazarus Group, designed to steal credentials and deploy backdoors.
Security News
Socket CEO Feross Aboukhadijeh discusses the open web, open source security, and how Socket tackles software supply chain attacks on The Pair Program podcast.
Security News
Opengrep continues building momentum with the alpha release of its Playground tool, demonstrating the project's rapid evolution just two months after its initial launch.