/node-hid

Access USB HID devices through Node.JS

Primary LanguageJavaScript

node-hid - Access USB HID devices from Node.js

npm Build Status Build status

Platform Support

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. Those with checks we provide pre-built binaries, for the others you will need to compile.

  • ☑ = full-support with pre-built binaries
  • ☐ = source-support only

We strive to make node-hid cross-platform so there's a good chance any combination not listed here will compile and work.

Supported Node versions

Platform / Arch Node v4.x Node v6.x Node v7.x Node v8.x Node v9.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.

Supported Electron versions

Platform / Arch v1.0 v1.2 v1.3 v1.4 v1.5 v1.6 v1.7 v1.8²
Windows / x86 ☑ ☑ ☑ ☑ ☑ ☑ ☑ ☑
Windows / x64 ☑ ☑ ☑ ☑ ☑ ☑ ☑ ☑
Mac OSX / x64 ☑ ☑ ☑ ☑ ☑ ☑ ☑ ☑
Linux / x64 ☑ ☑ ☑ ☑ ☑ ☑ ☑ ☑
Linux / ia32¹ ☐ ☐ ☐ ☐ ☐ ☐ ☐ ☐
Linux / ARM v6¹ ☐ ☐ ☐ ☐ ☐ ☐ ☐ ☐
Linux / ARM v7¹ ☐ ☐ ☐ ☐ ☐ ☐ ☐ ☐
Linux / ARM v8¹ ☐ ☐ ☐ ☐ ☐ ☐ ☐ ☐
Linux / MIPSel¹ ☐ ☐ ☐ ☐ ☐ ☐ ☐ ☐
Linux / PPC64¹ ☐ ☐ ☐ ☐ ☐ ☐ ☐ ☐

² Electron v1.8 currently has issues but prebuilt binaries are provided.

Installation

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

Installation Special Cases

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.

Examples

In the src/ directory, various JavaScript programs can be found that talk to specific devices in some way. Some interesting ones:

To try them out, run them like node src/showdevices.js from within the node-hid directory.

Usage

List all HID devices connected

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>

Opening a device

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.

Picking a device from the device list

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
}

Reading from a 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()

Writing to a device

To send FEATURE reports, use device.sendFeatureReport(). To send OUTPUT reports, use device.write(). All writing is synchronous.

device.write([0x00, 0x01, 0x01, 0x05, 0xff, 0xff]);
device.sendFeatureReport( [0x01, 'c', 0, 0xff,0x33,0x00, 70,0, 0] );

Notes:

  • Both device.write() and device.sendFeatureReport() return number of bytes written
  • Some devices use reportIds for OUTPUT reports. In that case, the first byte of the array to write() should be the reportId.
  • BUG: Windows requires the prepend of an extra byte due to a bug in hidapi (see issue #187 and Windows notes below)

Complete API

devices = HID.devices()

  • Return array listing all connected HID devices

HID.setDriverType(type)

  • Linux only
  • Sets underlying HID driver type
  • type can be "hidraw" or "libusb", defaults to "hidraw"
  • NOTE: this function is currently disabled in node-hid@^0.7.1 due to incompatibilities with prebuild.

device = new HID.HID(path)

  • Open a HID device at the specified platform-specific path

device = new HID.HID(vid,pid)

  • Open first HID device with specific VendorId and ProductId

device.on('data', function(data) {} )

  • data - Buffer - the data read from the device

device.on('error, function(error) {} )

  • error - The error Object emitted

device.write(data)

  • data - the data to be synchronously written to the device
  • Returns number of bytes actually written

device.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,...])
  • Returns number of bytes actually written

device.getFeatureReport(report_id, report_length)

  • report_id - HID feature report id to get
  • report_length - length of report

Windows notes

Mice and keyboards

In general you cannot access USB HID keyboards or mice.
The OS owns these devices.

Xbox 360 Controller on Windows 10

For reasons similar to mice & keyboards it appears you can't access this controller on Windows 10.

Prepend byte to hid_write()

Because of a limitation in the underlying hidapi library, if you are using hid_write() you should prepend a byte to any data buffer, e.g.

var device = new HID.HID(vid,pid);
var buffer = Array(64).fill(0x33); // device has 64-byte report
if(os.platform === 'win32') {
  buffer.unshift(0);  // prepend throwaway byte
}

Linux notes

Selecting driver type

(NOTE: The multi-driver feature of HID.setDriverType() is currently disabled. See issue #242 )

By default as of node-hid@0.7.0, the hidraw driver is used to talk to HID devices. Before node-hid@0.7.0, 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:

npm install node-hid@0.5.7

or:

npm install node-hid --build-from-source --driver=libusb

udev device permissions

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.

Compiling from source

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-gyp

  • Linux (kernel 2.6+) : install examples shown for Ubuntu

    • 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:sudo apt install libusb-1.0-0 libusb-1.0-0-dev
    • libudev-dev: (Fedora only) yum install libusbx-devel

  • Mac OS X 10.8+

  • Windows XP, 7, 8, 10

    • Visual C++ compiler and Python 2.7
      • either:
        • npm install --global windows-build-tools
        • add %USERPROFILE%\.windows-build-tools\python27 to PATH, like PowerShell: $env:Path += ";$env:USERPROFILE\.windows-build-tools\python27"
      • or:

To build node-hid from source for your project:

npm install node-hid --build-from-source

To build node-hid for development:

  • 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 run prepublish                                 # get the needed hidapi submodule
npm install --build-from-source                    # rebuilds the module with C code
node ./src/show-devices.js

You will 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 gypcompile    # "node-gyp build" build native code

Using node-hid in Electron projects

In your electron project, add electron-rebuild to your devDependencies. Then in your package.json scripts add:

  "postinstall": "electron-rebuild --force"

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 differnt version of Node.js then electron-rebuild hasn't been run and Electron is trying to use node-hid not built for it.

If you want a specific version of electron, do something like:

  "postinstall": "electron-rebuild -v 0.36.5 --force -m . -w node-hid"

If using node-hid with webpack, you may find it useful to list node-hid as an external in your webpack-config.js:

  externals: {
    "node-hid": 'commonjs node-hid'
  }

(You can see an example of this in Blink1Control2's webpack-config.js

Using node-hid in NW.js projects

(TBD)

Support

Please use the node-hid github issues page for support questions and issues.