Node.JS library for communicating with USB devices.
This is a complete rewrite in rust using @kevinmehall's excellent nusb library and napi-rs.
Node.js >= v12.22.0, which includes npm.
On Windows, if you get a NOT_SUPPORTED error when attempting to open your device, it's possible your device doesn't have a WinUSB driver to use.
If you are a device vendor, consider implementing WCID to get WinUSB driver support automatically. Otherwise, you can install a WinUSB driver using Zadig.
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"
Native modules are bundled as separate optional packages, so installation should be as simple as installing the package.
With npm:
npm install usb
With yarn:
yarn add usb
Use the following examples to kickstart your development. Once you have a desired device, use the APIs below to interact with it.
import { usb } from 'usb';
const devices = await usb.getDevices();
for (const device of devices) {
console.log(device); // WebUSB device
}
import { usb } from 'usb';
const device = await usb.findDeviceByIds(0x59e3, 0x0a23);
if (device) {
console.log(device); // WebUSB device
}
import { usb } from 'usb';
const device = await usb.findDeviceBySerial('TEST_DEVICE');
if (device) {
console.log(device); // WebUSB device
}
import { usb } from 'usb';
usb.addEventListener('connect', (event) => {
console.log('Device connected:', event.device.serialNumber);
});
usb.addEventListener('disconnect', (event) => {
console.log('Device disconnected:', event.device.serialNumber);
});
import { webusb } from 'usb';
// Returns first matching device
const device = await webusb.requestDevice({
filters: [{}]
})
console.log(device); // WebUSB device
import { WebUSB } from 'usb';
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
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 v3.0.0, the node-usb API follows the WebUSB specification which can be found here:
https://wicg.github.io/webusb/
Two versions of the WebUSB API exist by default:
usb - which exposes all functionality in an unrestricted manner (e.g. without needing to requestDevice() first)webusb - which follows the WebUSB specification exactly and requires the user to authorise devices via requestDevice() first.You may also construct your own WebUSB (e.g. to specify a requestDevice() callback) using the exported WebUSB class.
Full auto-generated API documentation can be seen here:
https://node-usb.github.io/node-usb-rs/
This library extends the WebUSB specification to add further functionality and convenience
Convenience method to get the first device with the specified VID and PID, or undefined if no such device is present.
Convenience method to get the device with the specified serial number, or undefined if no such device is present.
Detaches the kernel driver from the interface. You may need to execute this with elevated privileges.
Re-attaches the kernel driver for the interface.
The library is based on native rust bindings wrapping the nusb crate.
Ensure you have a working rust environment, instructions for setting this up are avalable at https://rust-lang.org/tools/install/
git clone https://github.com/node-usb/node-usb-rs
The package can be built as follows:
npm install
npm run build:all
To execute the unit tests, Run:
npm run full-test
Some tests require an attached STM32F103 Microprocessor USB device with specific firmware.
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.
FAQs
Library to access USB devices
The npm package usb receives a total of 290,981 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
Malicious Chrome and Firefox extensions posed as free VPNs while stealing clipboard data through later extension updates.
Research
/Security News
Miasma Mini Shai-Hulud hits @immobiliarelabs Backstage plugins, targeting GitLab and LDAP auth packages on npm.
Security News
Rolldown paused Rust React Compiler integration after a 5MB binary size increase raised concerns about shipping React-specific code to all Vite users.