node-hid supports Node.js v4 and upwards. For versions 0.10 and 0.12,
you will need to build from source. The platforms, architectures and node versions node-hid supports are the following;
| Platform / Arch | Node v4.x | Node v6.x | Node v7.x |
|---|---|---|---|
| Windows / x86 | ☑ | ☑ | ☑ |
| Windows / x64 | ☑ | ☑ | ☑ |
| Mac OSX / x64 | ☑ | ☑ | ☑ |
| Linux / x64 | ☑ | ☑ | ☑ |
| Linux / ia32 | ☐ | ☐ | ☐ |
| Linux / ARM v6¹ | ☐ | ☐ | ☐ |
| Linux / ARM v7¹ | ☐ | ☐ | ☐ |
| Linux / ARM v8¹ | ☐ | ☐ | ☐ |
| Linux / MIPSel¹ | ☐ | ☐ | ☐ |
| Linux / PPC64¹ | ☐ | ☐ | ☐ |
¹ ia32, ARM, MIPSel and PPC64 platforms are known to work but are not currently part of our test or build matrix. ARM v4 and v5 was dropped from Node.js after Node v0.10.
For most "standard" use cases (node v4.x on mac, linux, windows on a x86 or x64 processor), node-hid will install nice and easy with a standard:
npm install node-hid
We are using prebuild to compile and post binaries of the library for most common use cases (linux, mac, windows on standard processor platforms). If you are on a special case, node-hid will work, but it will compile the binary when you install.
If node-hid doesn't have a pre-built binary for your system
(e.g. Linux on Raspberry Pi),
node-gyp is used to compile node-hid locally. It will need the pre-requisites
listed in Compling from source below.
In the src/ directory, various JavaScript programs can be found
that talk to specific devices in some way. Some interesting ones:
show-devices.js - display all HID devices in the systemtest-ps3-rumbleled.js - Read PS3 joystick and control its LED & rumblerstest-powermate.js - Read Griffin PowerMate knob and change its LEDtest-blink1.js - Fade colors on blink(1) RGB LEDtest-bigredbutton.js - Read Dreamcheeky Big Red ButtonTo try them out, call them like node src/showdevices.js from the node-hid directory.
var HID = require('node-hid');
var devices = HID.devices();
devices will contain an array of objects, one for each HID device
available. Of particular interest are the vendorId and
productId, as they uniquely identify a device, and the
path, which is needed to open a particular device.
Sample output:
HID.devices();
[ { vendorId: 1452,
productId: 595,
path: 'USB_05ac_0253_0x100a148e0',
serialNumber: '',
manufacturer: 'Apple Inc.',
product: 'Apple Internal Keyboard / Trackpad',
release: 280,
interface: -1 },
{ vendorId: 1452,
productId: 595,
path: 'USB_05ac_0253_0x100a14e20',
serialNumber: '',
manufacturer: 'Apple Inc.',
product: 'Apple Internal Keyboard / Trackpad',
release: 280,
interface: -1 },
<and more>
Before a device can be read from or written to, it must be opened.
The path can be determined by a prior HID.devices() call.
Use either the path from the list returned by a prior call to HID.devices():
var device = new HID.HID(path);
or open the first device matching a VID/PID pair:
var device = new HID.HID(vid,pid);
The device variable will contain a handle to the device.
If an error occurs opening the device, an exception will be thrown.
A node-hid device is an EventEmitter.
Reading from a device is performed by registering a "data" event handler:
device.on("data", function(data) {});
You can also listen for errors like this:
device.on("error", function(err) {});
Notes:
data event receives INPUT reports. To receive Feature reports,
see the readFeatureReport() method below.device.close()Writing to a device is performed using the write call in a device handle. All writing is synchronous.
device.write([0x00, 0x01, 0x01, 0x05, 0xff, 0xff]);
Notes:
write() method sends OUTPUT reports. To send Feature reports,
see the sendFeatureReport() method below.write() should be the reportId.write() is 0x00, you may need to prepend an extra 0x00 due to a bug in hidapi (see issue #187)devices = HID.devices()device = new HID.HID(path)device = new HID.HID(vid,pid)device.on('data', function(data) {} )data - Buffer - the data read from the devicedevice.on('error, function(error) {} )error - The error Object emitteddevice.write(data)data - the data to be synchronously written to the devicedevice.close()Closes the device. Subsequent reads will raise an error.
device.pause()Pauses reading and the emission of data events.
device.resume()This method will cause the HID device to resume emmitting data events.
If no listeners are registered for the data event, data will be lost.
When a data event is registered for this HID device, this method will
be automatically called.
device.read(callback)Low-level function call to initiate an asynchronous read from the device.
callback is of the form callback(err, data)
device.readSync()Return an array of numbers data. If an error occurs, an exception will be thrown.
device.readTimeout(time_out)time_out - timeout in milliseconds
Return an array of numbers data. If an error occurs, an exception will be thrown.device.sendFeatureReport(data)data - data of HID feature report, with 0th byte being report_id ([report_id,...])device.getFeatureReport(report_id, report_length)report_id - HID feature report id to getreport_length - length of reportusage and usagePage device info fieldsThese are not available on Linux, only Mac and Windows. For reason why, and to ask for its addition, see: https://github.com/signal11/hidapi/pull/6
To install node-hid with the hidraw driver instead of the default libusb one,
install the "libudev-dev" package and rebuild the library with:
npm install node-hid --driver=hidraw
Most Linux distros use udev to manage access to physical devices,
and USB HID devices are normally owned by the root user.
To allow non-root access, you must create a udev rule for the device,
based on the devices vendorId and productId.
This rule is a file, placed in /etc/udev/rules.d, with the lines:
SUBSYSTEM=="input", GROUP="input", MODE="0666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="27b8", ATTRS{idProduct}=="01ed", MODE:="666", GROUP="plugdev"
(the above is for vendorId = 27b8, productId = 01ed)
Then the udev service is reloaded with: sudo udevadm control --reload-rules
For an example, see the
blink1 udev rules.
To compile & develop locally or if prebuild cannot download a pre-built
binary for you, you will need the following tools:
All OSes:
node-gyp installed globally: npm install -g node-gypLinux (kernel 2.6+) : install examples shown for Ubuntu
apt install build-essential gitapt install gcc-4.8 g++-4.8 && export CXX=g++-4.8sudo apt install libusb-1.0-0 libusb-1.0-0-devyum install libusbx-develMac OS X 10.8+
Windows XP, 7, 8, 10
npm install --global windows-build-tools%USERPROFILE%\.windows-build-tools\python27 to PATH,
like PowerShell: $env:Path += ";$env:USERPROFILE\.windows-build-tools\python27"node-hid from source for your project:npm install node-hid --build-from-source
node-hid for development:For example:
git clone https://github.com/node-hid/node-hid.git
cd node-hid # must change into node-hid directory
npm install --build-from-source # rebuilds the module with C code
node ./src/show-devices.js
You will likely see some warnings from the C compiler as it compiles
hidapi (the underlying C library node-hid uses).
This is expected.
node-hid in Electron projectsIn your electron project, add electron-rebuild and electron-prebuilt to your devDependencies.
Then in your package.json scripts add:
"postinstall": "electron-rebuild --force"
If you want a specific version of electron, do something like:
electron-rebuild -v 0.36.5 --force -m . -w node-hid
node-hid in NW.js projects(TBD)
Please use the node-hid github issues page for support questions and issues.
FAQs
USB HID device access library
The npm package node-hid receives a total of 73,782 weekly downloads. As such, node-hid popularity was classified as popular.
We found that node-hid demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 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.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.