npm install node-hid
- Node.js v0.8 - v4.x+
- Mac OS X 10.8, Linux (kernel 2.6+), and Windows XP+
- libudev-dev, libusb-1.0-0-dev (if Linux, see Compile below)
- git
node-hid uses node-pre-gyp to store pre-built binary bundles, so usually no compiler is needed to install.
Platforms we pre-build binaries for:
- Mac OS X x64: v0.10, v0.12, v4.2.x
- Windows x64 & x86: v0.10, v0.12, v4.2.x
- Linux Debian/Ubuntu x64: v4.2.x
- Raspberry Pi arm: v4.2.x
If node-hid doesn't have a pre-built binary for your system, it will attempt to compile locally. In which case you'll need the Compiler tools mentioned 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 & rumblers.powermate.js
- Read Griffin PowerMate knob and change its LED
To 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.
Here is some 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>
NOTE: Most keyboard & mice-like HID devices cannot be seen by node-hid
on Windows & Mac. This is not a limitation of node-hid
but a limitation of all user-space libraries. This is a security feature of the OS to prevent input device snooping.
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);
device
will contain a handle to the device.
If an error occurs opening the device, an exception will be thrown.
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) {});
All reading is asynchronous.
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:
- The
write()
method sends OUTPUT reports. To send Feature reports, see thesendFeatureReport()
method below. - Some devices use reportIds for OUTPUT reports. If that is the case,
the first byte of the array to
write()
should be the reportId.
var device = new HID.HID(path);
chunk
- Buffer - the data read from the device
error
- The error Object emitted
data
- the data to be synchronously written to the device
Closes the device. Subsequent reads will raise an error.
Pauses reading and the emission of data
events.
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.
Low-level function call to initiate an asynchronous read from the device.
callback
is of the form callback(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,...]
)
report_id
- HID feature report id to getreport_length
- length of report
- Xbox 360 Controller on Windows 10 -- does not work
These are not available on Linux, only Mac and Windows. For reason why, and to ask for its addition, see: signal11/hidapi#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 node-pre-gyp
cannot find a pre-built binary for you), you will need the following tools:
- All OSes:
- node-gyp installed globally:
npm install -g node-gyp
- node-pre-gyp installed globally:
npm install -g node-pre-gyp
- node-gyp installed globally:
- Mac OS X 10.8+
- Windows XP+
- Visual C++ compiler and Python 2.7, via 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: - Python 2.7
- Visual Studio Express 2013 for Desktop
- Visual C++ compiler and Python 2.7, via either:
- Linux (kernel 2.6+)
- Compiler tools (
apt-get install build-essential git
for Debian/Ubuntu/Raspian) - gcc-4.8+ (
apt-get install gcc-4.8 g++-4.8 && export CXX=g++-4.8
) - libudev-dev (Fedora:
yum install libusbx-devel
) - libusb-1.0-0-dev (Ubuntu versions missing
libusb.h
only)
- Compiler tools (
To build node-hid:
- check out a copy of this repo
- change into its directory
- update the submodules
- build the node package
- node-pre-gyp to rebuild the C code:
git clone https://github.com/node-hid/node-hid.git
cd node-hid # must change into node-hid directory
git submodule update --init # done on publish automatically
npm install # rebuilds the module
node-pre-gyp rebuild # rebuilds the C code
You will likely see some warnings from the C compiler as it compiles hidapi. This is expected.
In 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
npm install node-pre-gyp
./node_modules/.bin/node-pre-gyp rebuild --runtime=node-webkit --target=0.12.3
You can change 0.12.3 to version nwjs that you want to deploy.
Please use the node-hid github issues page for support questions and issues.