- node-hid - Access USB HID devices from Node.js
- Platform Support
- Installation
- Examples
- Usage
- Complete API
- devices = HID.devices()
- HID.setDriverType(type)
- device = new HID.HID(path)
- device = new HID.HID(vid,pid)
- device.on('data', function(data) {} )
- device.on('error, function(error) {} )
- device.write(data)
- device.close()
- device.pause()
- device.resume()
- device.read(callback)
- device.readSync()
- device.readTimeout(time_out)
- device.sendFeatureReport(data)
- device.getFeatureReport(report_id, report_length)
- device.setNonBlocking(no_block)
- General notes:
- Mac notes
- Windows notes
- Linux notes
- Compiling from source
- Electron projects using node-hid
- NW.js projects using node-hid
- Support
node-hid
supports Node.js v6 and upwards. For versions before that,
you will need to build from source. The platforms, architectures and node versions node-hid
supports are the following.
In general we try to provide pre-built native library binaries for the most common platforms, Node and Electron versions.
We strive to make node-hid
cross-platform so there's a good chance any
combination not listed here will compile and work.
- Windows x86 (32-bit) (¹)
- Windows x64 (64-bit)
- Mac OSX 10.9+
- Linux x64 (²)
- Linux x86 (¹)
- Linux ARM / Raspberry Pi (¹)
- Linux MIPSel (¹)
- Linux PPC64 (¹)
¹ prebuilt-binaries not provided for these platforms
² prebuilt binary built on Ubuntu 18.04 x64
- Node v8 to
- Node v14
- Electron v3 to
- Electron v11
Native modules like node-hid
require upstream dependencies to be updated to work with newer Node and Electron versions. Unless you need the features in the most recent Electron or Node, use a supported version.
For most "standard" use cases (node v4.x on mac, linux, windows on a x86 or x64 processor), node-hid
will install like a standard npm package:
npm install node-hid
If you install globally, the test program src/show-devices.js
is installed as hid-showdevices
. On Linux you can use it to try the difference between hidraw
and libusb
driverTypes:
$ npm install -g node-hid
$ hid-showdevices libusb
$ hid-showdevices hidraw
We are using prebuild to compile and post binaries of the library for most common use cases (Linux, MacOS, Windows on standard processor platforms). If a prebuild is not available, node-hid
will work, but npm install node-hid
will compile the binary when you install. For more details on compiler setup, see 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 Buttontest-teensyrawhid.js
- Read/write Teensy running RawHID "Basic" Arduino sketch
To try them out, run them with node src/showdevices.js
from within 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: 10168,
productId: 493,
path: 'IOService:/AppleACPIPl...HIDDevice@14210000,0',
serialNumber: '20002E8C',
manufacturer: 'ThingM',
product: 'blink(1) mk2',
release: 2,
interface: -1,
usagePage: 65280,
usage: 1 },
{ vendorId: 1452,
productId: 610,
path: 'IOService:/AppleACPIPl...Keyboard@14400000,0',
serialNumber: '',
manufacturer: 'Apple Inc.',
product: 'Apple Internal Keyboard / Trackpad',
release: 549,
interface: -1,
usagePage: 1,
usage: 6 },
<and more>
Both HID.devices()
and new HID.HID()
are relatively costly, each causing a USB (and potentially Bluetooth) enumeration. This takes time and OS resources. Doing either can slow down the read/write that you do in parallel with a device, and cause other USB devices to slow down too. This is how USB works.
If you are polling HID.devices()
or doing repeated new HID.HID(vid,pid)
to detect device plug / unplug, consider instead using node-usb-detection. node-usb-detection
uses OS-specific, non-bus enumeration ways to detect device plug / unplug.
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
.
While it shares some method names and usage patterns with
Readable
and Writable
streams, it is not a stream and the semantics vary.
For example, device.write
does not take encoding or callback args and
device.pause
does not do the same thing as readable.pause
.
There is also no pipe
method.
If you need to filter down the HID.devices()
list, you can use
standard Javascript array techniques:
var devices = HID.devices();
var deviceInfo = devices.find( function(d) {
var isTeensy = d.vendorId===0x16C0 && d.productId===0x0486;
return isTeensy && d.usagePage===0xFFAB && d.usage===0x200;
});
if( deviceInfo ) {
var device = new HID.HID( deviceInfo.path );
// ... use device
}
To receive FEATURE reports, use device.getFeatureReport()
.
To receive INPUT reports, use device.on("data",...)
.
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) {});
For FEATURE reports:
var buf = device.getFeatureReport(reportId, reportLength)
Notes:
- Reads via
device.on("data")
are asynchronous - Reads via
device.getFeatureReport()
are synchronous - To remove an event handler, close the device with
device.close()
- When there is not yet a data handler or no data handler exists, data is not read at all -- there is no buffer.
To send FEATURE reports, use device.sendFeatureReport()
.
To send OUTPUT reports, use device.write()
.
All writing is synchronous.
The ReportId is the first byte of the array sent to device.sendFeatureReport()
or device.write()
, meaning the array should be one byte bigger than your report.
If your device does NOT use numbered reports, set the first byte of the 0x00.
device.write([0x00, 0x01, 0x01, 0x05, 0xff, 0xff]);
device.sendFeatureReport( [0x01, 'c', 0, 0xff,0x33,0x00, 70,0, 0] );
Notes:
- You must send the exact number of bytes for your chosen OUTPUT or FEATURE report.
- Both
device.write()
anddevice.sendFeatureReport()
return number of bytes written + 1. - For devices using Report Ids, the first byte of the array to
write()
orsendFeatureReport()
must be the Report Id.
- Return array listing all connected HID devices
- Linux only
- Sets underlying HID driver type
type
can be"hidraw"
or"libusb"
, defaults to"hidraw"
- Open a HID device at the specified platform-specific path
- Open first HID device with specific VendorId and ProductId
data
- Buffer - the data read from the device
error
- The error Object emitted
data
- the data to be synchronously written to the device, first byte is Report Id or 0x00 if not using numbered reports.- Returns number of bytes actually written
- Closes the device. Subsequent reads will raise an error.
- Pauses reading and the emission of
data
events.
This means the underlying device is silenced until resumption -- it is not like pausing a stream, where data continues to accumulate.
-
This method will cause the HID device to resume emmitting
data
events. If no listeners are registered for thedata
event, data will be lost. -
When a
data
event is registered for this HID device, this method will be automatically called.
- Low-level function call to initiate an asynchronous read from the device.
callback
is of the formcallback(err, data)
- Return an array of numbers data. If an error occurs, an exception will be thrown.
time_out
- timeout in milliseconds- Return an array of numbers data. If an error occurs, an exception will be thrown.
data
- data of HID feature report, with 0th byte being report_id ([report_id,...]
)- Returns number of bytes actually written
report_id
- HID feature report id to getreport_length
- length of report
no_block
- boolean. Set totrue
to enable non-blocking reads- exactly mirrors
hid_set_nonblocking()
inhidapi
In general node-hid
is not thread-safe because the underlying C-library it wraps (hidapi
) is not thread-safe.
However, node-hid
is now reporting as minimally Context Aware to allow use in Electron v9+.
Until node-hid
(or hidapi
) is rewritten to be thread-safe, please constrain all accesses to it via a single thread.
The following devices are unavailable to node-hid
because the OS owns them:
- Keyboards
- Mice
- Barcode readers (in USB HID keyboard mode)
- RFID scanners (in USB HID keyboard mode)
- Postage Scales (in USB HID keyboard mode)
Most OSes will prevent USB HID keyboards or mice, or devices that appear as a keyboard to the OS. This includes many RFID scanners, barcode readers, USB HID scales, and many other devices. This is a security precaution. Otherwise, it would be trivial to build keyloggers.
Some keyboard-pretending devices like barcode or RFID readers can be configured to be in
"HID data" mode or "Serial / UART" mode. If in "HID Data" mode then node-hid
can access them,
if in "Serial / UART" mode, you should use node-serialport
instead.
See General notes above Keyboards
See General notes above about Keyboards
For reasons similar to mice & keyboards it appears you can't access this controller on Windows 10.
See General notes above about Keyboards
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 text file placed in /etc/udev/rules.d
.
For an example HID device (say a blink(1) light with vendorId = 0x27b8 and productId = 0x01ed,
the rules file to support both hidraw
and libusb
would look like:
SUBSYSTEM=="input", GROUP="input", MODE="0666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="27b8", ATTRS{idProduct}=="01ed", MODE:="666", GROUP="plugdev"
KERNEL=="hidraw*", ATTRS{idVendor}=="27b8", ATTRS{idProduct}=="01ed", MODE="0666", GROUP="plugdev"
Note that the values for idVendor and idProduct must be in hex and lower-case.
Save this file as /etc/udev/rules.d/51-blink1.rules
, unplug the HID device,
and reload the rules with:
sudo udevadm control --reload-rules
For a complete example, see the blink1 udev rules.
By default as of [email protected]
, the hidraw driver is used to talk to HID devices. Before [email protected]
, the more older but less capable libusb driver was used. With hidraw
Linux apps can now see usage
and usagePage
attributes of devices.
If you would still like to use the libusb
driver, then you can do either:
During runtime, you can use HID.setDriverType('libusb')
immediately after require()-ing node-hid
:
var HID = require('node-hid');
HID.setDriverType('libusb');
If you must have the libusb version and cannot use setDriverType()
,
you can install older node-hid or build from source:
npm install [email protected]
or:
npm install node-hid --build-from-source --driver=libusb
To compile & develop locally or if prebuild
cannot download a pre-built
binary for you, you will need the following compiler tools and libraries:
- Compilation tools:
apt install build-essential git
- gcc-4.8+:
apt install gcc-4.8 g++-4.8 && export CXX=g++-4.8
- libusb-1.0-0 w/headers:
apt install libusb-1.0-0 libusb-1.0-0-dev
- libudev-dev:
apt install libudev-dev
(Debian/Ubuntu) /yum install libusbx-devel
(Fedora)
- Compilation tools:
pkg install git gcc gmake libiconv node npm
- Visual C++ compiler and Python 2.7
- either:
npm install --global windows-build-tools
- add
%USERPROFILE%\.windows-build-tools\python27
toPATH
, like PowerShell:$env:Path += ";$env:USERPROFILE\.windows-build-tools\python27"
- or:
- either:
npm install node-hid --build-from-source
- check out a copy of this repo
- change into its directory
- update the submodules
- build the node package
For example:
git clone https://github.com/node-hid/node-hid.git
cd node-hid # must change into node-hid directory
npm install -g rimraf # just so it doesn't get 'clean'ed
npm run prepublishOnly # get the needed hidapi submodule
npm install --build-from-source # rebuilds the module with C code
npm run showdevices # list connected HID devices
node ./src/show-devices.js # same as above
You may see some warnings from the C compiler as it compiles
hidapi (the underlying C library node-hid
uses).
This is expected.
For ease of development, there are also the scripts:
npm run gypclean # "node-gyp clean" clean gyp build directory
npm run gypconfigure # "node-gyp configure" configure makefiles
npm run gypbuild # "node-gyp build" build native code
When cross-compiling you need to override node-hid
's normal behavior
of using Linux pkg-config
to determine CLFAGS and LDFLAGS for libusb
.
To do this, you can use the node-gyp
variable node_hid_no_pkg_config
and then invoke a node-hid
rebuild with either:
node-gyp rebuild --node_hid_no_pkg_config=1
or
npm gyprebuild --node_hid_no_pkg_config=1
In your electron project, add electron-rebuild
to your devDependencies
.
Then in your package.json scripts
add:
"postinstall": "electron-rebuild"
This will cause npm
to rebuild node-hid
for the version of Node that is in Electron.
If you get an error similar to The module "HID.node" was compiled against a different version of Node.js
then electron-rebuild
hasn't been run and Electron is trying to use node-hid
compiled for Node.js and not for Electron.
If using node-hid
with webpack
or similar bundler, you may need to exclude
node-hid
and other libraries with native code. In webpack, you say which
externals
you have in your webpack-config.js
:
externals: {
"node-hid": 'commonjs node-hid'
}
Examples of node-hid
in Electron:
- electron-hid-test - Simple example of using
node-hid
, should track latest Electron release - electron-hid-toy - Simple example of using
node-hid
, showing packaging and signing - Blink1Control2 - a complete application, using webpack (e.g. see its webpack-config.js)
Without knowing much about NW.js, a quick hacky solution that works is:
cd my-nwjs-app
npm install node-hid --save
npm install -g nw-gyp
cd node_modules/node-hid
nw-gyp rebuild --target=0.42.3 --arch=x64 // or whatever NW.js version you have
cd ../..
nwjs .
Please use the node-hid github issues page for support questions and issues.