usb

USB Library for Node.JS

Node.JS library for communicating with USB devices.

This is a complete rewrite in rust using @kevinmehall's excellent nusb library and napi-rs.

Prerequisites

Node.js >= v12.22.0, which includes npm.

Windows

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.

You can install one using Zadig.

Linux

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"

Installation

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

License

MIT

Limitations

Does not support:

• Isochronous transfers

Getting Started

Use the following examples to kickstart your development. Once you have a desired device, use the APIs below to interact with it.

APIs

Since v3.0.0, the node-usb library supports the WebUSB API which follows the WebUSB Specification

Convenience methods also exist to easily list or find devices.

Full auto-generated API documentation can be seen here:

https://node-usb.github.io/node-usb-rs/

Electron

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:

• buildDependenciesFromSource: true
• nodeGypRebuild: false
• npmRebuild: false

Convenience Functions

getDeviceList()

Return a list of USB objects for the USB devices attached to the system.

findByIds(vid, pid)

Convenience method to get the first device with the specified VID and PID, or undefined if no such device is present.

findBySerialNumber(serialNumber)

Convenience method to get the device with the specified serial number, or undefined if no such device is present.

WebUSB

Please refer to the WebUSB specification which be found here:

https://wicg.github.io/webusb/

Implementation Status

USB

• getDevices()
• requestDevice()

USBDevice

• usbVersionMajor
• usbVersionMinor
• usbVersionSubminor
• deviceClass
• deviceSubclass
• deviceProtocol
• vendorId
• productId
• deviceVersionMajor
• deviceVersionMinor
• deviceVersionSubminor
• manufacturerName
• productName
• serialNumber
• configuration
• configurations
• opened
• open()
• close()
• selectConfiguration()
• claimInterface()
• releaseInterface()
• selectAlternateInterface()
• controlTransferIn()
• controlTransferOut()
• transferIn()
• transferOut()
• clearHalt()
• reset()
• forget()
• isochronousTransferIn()
• isochronousTransferOut()

Events

• connect
• disconnect

Development

The library is based on native rust bindings wrapping the nusb crate.

Setup

git clone https://github.com/node-usb/node-usb-rs

Building

The package can be built as follows:

npm install
npm run build:all

Testing

To execute the unit tests, Run:

npm run full-test

Some tests require an attached STM32F103 Microprocessor USB device with specific firmware.

Similar packages

Other packages similar to usb

node-hid

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.

usb-detection

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.

webusb

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.