You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 4-6.RSVP →
node-hid - npm Package Compare versions
Comparing version 1.0.0 to 1.1.0
| { | ||
| "name": "node-hid", | ||
| "description": "USB HID device access library", | ||
| "version": "1.0.0", | ||
| "version": "1.1.0", | ||
| "author": "Hans Hübner <hans.huebner@gmail.com> (https://github.com/hanshuebner)", | ||
@@ -6,0 +6,0 @@ "bugs": "https://github.com/node-hid/node-hid/issues", |
@@ -12,3 +12,3 @@ How to publish node-hid | ||
| cd node-hid | ||
| npm run prepublish # get the hidapi submodule | ||
| npm run prepublishOnly # get the hidapi submodule | ||
| npm install --build-from-source # rebuilds the C code | ||
@@ -15,0 +15,0 @@ node ./src/show-devices.js # simple tests |
227
README.md
@@ -8,48 +8,53 @@ # node-hid - Access USB HID devices from Node.js # | ||
| * [Platform Support](#platform-support) | ||
| * [Supported Node versions](#supported-node-versions) | ||
| * [Supported Electron versions](#supported-electron-versions) | ||
| * [Installation](#installation) | ||
| * [Installation Special Cases](#installation-special-cases) | ||
| * [Examples](#examples) | ||
| * [Usage](#usage) | ||
| * [List all HID devices connected](#list-all-hid-devices-connected) | ||
| * [Cost of HID.devices() and new HID.HID()](#cost-of-hiddevices-and-new-hidhid-for-detecting-device-plugunplug) | ||
| * [Opening a device](#opening-a-device) | ||
| * [Picking a device from the device list](#picking-a-device-from-the-device-list) | ||
| * [Reading from a device](#reading-from-a-device) | ||
| * [Writing to a device](#writing-to-a-device) | ||
| * [Complete API](#complete-api) | ||
| * [devices = HID.devices()](#devices--hiddevices) | ||
| * [HID.setDriverType(type)](#hidsetdrivertypetype) | ||
| * [device = new HID.HID(path)](#device--new-hidhidpath) | ||
| * [device = new HID.HID(vid,pid)](#device--new-hidhidvidpid) | ||
| * [device.on('data', function(data) {} )](#deviceondata-functiondata--) | ||
| * [device.on('error', function(error) {} )](#deviceonerror-functionerror--) | ||
| * [device.write(data)](#devicewritedata) | ||
| * [device.close()](#deviceclose) | ||
| * [device.pause()](#devicepause) | ||
| * [device.resume()](#deviceresume) | ||
| * [device.read(callback)](#devicereadcallback) | ||
| * [device.readSync()](#devicereadsync) | ||
| * [device.readTimeout(time_out)](#devicereadtimeouttime_out) | ||
| * [device.sendFeatureReport(data)](#devicesendfeaturereportdata) | ||
| * [device.getFeatureReport(report_id, report_length)](#devicegetfeaturereportreport_id-report_length) | ||
| * [device.setNonBlocking(no_block)](#devicesetnonblockingno_block) | ||
| * [Windows notes](#windows-notes) | ||
| * [Mice and keyboards](#mice-and-keyboards) | ||
| * [Xbox 360 Controller on Windows 10](#xbox-360-controller-on-windows-10) | ||
| * [Prepend byte to hid_write()](#prepend-byte-to-hid_write) | ||
| * [Linux notes](#linux-notes) | ||
| * [Selecting driver type](#selecting-driver-type) | ||
| * [udev device permissions](#udev-device-permissions) | ||
| * [Compiling from source](#compiling-from-source) | ||
| * [To build node-hid from source for your project:](#to-build-node-hid-from-source-for-your-project) | ||
| * [To build node-hid for development:](#to-build-node-hid-for-development) | ||
| * [Using node-hid in Electron projects](#using-node-hid-in-electron-projects) | ||
| * [Using node-hid in NW.js projects](#using-node-hid-in-nwjs-projects) | ||
| * [Support](#support) | ||
| * [node-hid - Access USB HID devices from Node.js](#node-hid---access-usb-hid-devices-from-nodejs) | ||
| * [Platform Support](#platform-support) | ||
| * [Supported Platforms](#supported-platforms) | ||
| * [Supported Node versions](#supported-node-versions) | ||
| * [Supported Electron versions](#supported-electron-versions) | ||
| * [Installation](#installation) | ||
| * [Installation Special Cases](#installation-special-cases) | ||
| * [Examples](#examples) | ||
| * [Usage](#usage) | ||
| * [List all HID devices connected](#list-all-hid-devices-connected) | ||
| * [Cost of HID.devices() and <code>new HID.HID()</code> for detecting device plug/unplug](#cost-of-hiddevices-and-new-hidhid-for-detecting-device-plugunplug) | ||
| * [Opening a device](#opening-a-device) | ||
| * [Picking a device from the device list](#picking-a-device-from-the-device-list) | ||
| * [Reading from a device](#reading-from-a-device) | ||
| * [Writing to a device](#writing-to-a-device) | ||
| * [Complete API](#complete-api) | ||
| * [devices = HID.devices()](#devices--hiddevices) | ||
| * [HID.setDriverType(type)](#hidsetdrivertypetype) | ||
| * [device = new HID.HID(path)](#device--new-hidhidpath) | ||
| * [device = new HID.HID(vid,pid)](#device--new-hidhidvidpid) | ||
| * [device.on('data', function(data) {} )](#deviceondata-functiondata--) | ||
| * [device.on('error, function(error) {} )](#deviceonerror-functionerror--) | ||
| * [device.write(data)](#devicewritedata) | ||
| * [device.close()](#deviceclose) | ||
| * [device.pause()](#devicepause) | ||
| * [device.resume()](#deviceresume) | ||
| * [device.read(callback)](#devicereadcallback) | ||
| * [device.readSync()](#devicereadsync) | ||
| * [device.readTimeout(time_out)](#devicereadtimeouttime_out) | ||
| * [device.sendFeatureReport(data)](#devicesendfeaturereportdata) | ||
| * [device.getFeatureReport(report_id, report_length)](#devicegetfeaturereportreport_id-report_length) | ||
| * [device.setNonBlocking(no_block)](#devicesetnonblockingno_block) | ||
| * [Mac notes](#mac-notes) | ||
| * [Keyboards and Mice](#keyboards-and-mice) | ||
| * [Windows notes](#windows-notes) | ||
| * [Keyboards and Mice](#keyboards-and-mice-1) | ||
| * [Xbox 360 Controller on Windows 10](#xbox-360-controller-on-windows-10) | ||
| * [Linux notes](#linux-notes) | ||
| * [Selecting driver type](#selecting-driver-type) | ||
| * [udev device permissions](#udev-device-permissions) | ||
| * [Compiling from source](#compiling-from-source) | ||
| * [Linux (kernel 2.6 ) : (install examples shown for Debian/Ubuntu)](#linux-kernel-26--install-examples-shown-for-debianubuntu) | ||
| * [Mac OS X 10.8 ](#mac-os-x-108) | ||
| * [Windows 7, 8, 10](#windows-7-8-10) | ||
| * [Building node-hid from source, for your projects](#building-node-hid-from-source-for-your-projects) | ||
| * [Build node-hid for <code>node-hid</code> development:](#build-node-hid-for-node-hid-development) | ||
| * [Electron projects using node-hid](#electron-projects-using-node-hid) | ||
| * [NW.js projects using node-hid](#nwjs-projects-using-node-hid) | ||
| * [Support](#support) | ||
| ## Platform Support | ||
@@ -83,9 +88,6 @@ `node-hid` supports Node.js v6 and upwards. For versions before that, | ||
| * Electron v1 to (³) | ||
| * Electron v5 | ||
| * Electron v1 to | ||
| * Electron v7 | ||
| ³ Electron v1.8 currently has issues, but prebuilt binaries are provided. | ||
| ## Installation | ||
@@ -251,7 +253,12 @@ | ||
| To send FEATURE reports, use `device.sendFeatureReport()`. | ||
| 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. | ||
| ```js | ||
@@ -264,6 +271,7 @@ device.write([0x00, 0x01, 0x01, 0x05, 0xff, 0xff]); | ||
| 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) | ||
| - You must send the exact number of bytes for your chosen OUTPUT or FEATURE report. | ||
| - Both `device.write()` and `device.sendFeatureReport()` return | ||
| number of bytes written + 1. | ||
| - For devices using Report Ids, the first byte of the array to `write()` or | ||
| `sendFeatureReport()` must be the Report Id. | ||
@@ -300,3 +308,4 @@ | ||
| - `data` - the data to be synchronously written to the device | ||
| - `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 | ||
@@ -353,5 +362,12 @@ | ||
| ## Mac notes | ||
| ### Keyboards and Mice | ||
| The OS will prevent USB HID keyboards or mice, or devices that appear as a keyboard to the OS (such as some barcode readers or RFID scanners). This is a security precaution. Otherwise, it would be trivial to build keyloggers. | ||
| There are non-standard work-arounds for this, but in general you cannot use `node-hid` to access keyboard-like devices. | ||
| ## Windows notes | ||
| ### Keyboards and mice | ||
| ### Keyboards and Mice | ||
| The OS will prevent USB HID keyboards or mice, or devices that appear as a keyboard to the OS (such as some barcode readers or RFID scanners). This is a security precaution. Otherwise, it would be trivial to build keyloggers. | ||
@@ -363,11 +379,2 @@ There are non-standard work-arounds for this, but in general you cannot use `node-hid` to access keyboard-like devices. | ||
| ### 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. | ||
| ```js | ||
| 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 | ||
| } | ||
| ``` | ||
@@ -382,3 +389,12 @@ | ||
| 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`: | ||
| ```js | ||
| 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 node-hid@0.5.7 | ||
@@ -391,11 +407,3 @@ ``` | ||
| Or during runtime, you can use `HID.setDriverType('libusb')` immediately after require()-ing `node-hid`: | ||
| ```js | ||
| var HID = require('node-hid'); | ||
| HID.setDriverType('libusb'); | ||
| ``` | ||
| ### udev device permissions | ||
@@ -433,24 +441,24 @@ Most Linux distros use `udev` to manage access to physical devices, | ||
| * Linux (kernel 2.6+) : (install examples shown for Debian/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:`apt install libusb-1.0-0 libusb-1.0-0-dev` | ||
| * libudev-dev: `apt install libudev-dev` (Debian/Ubuntu) / | ||
| `yum install libusbx-devel` (Fedora) | ||
| ### Linux (kernel 2.6+) : (install examples shown for Debian/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:`apt install libusb-1.0-0 libusb-1.0-0-dev` | ||
| * libudev-dev: `apt install libudev-dev` (Debian/Ubuntu) / | ||
| `yum install libusbx-devel` (Fedora) | ||
| * Mac OS X 10.8+ | ||
| * [Xcode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12) | ||
| ### Mac OS X 10.8+ | ||
| * [Xcode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12) | ||
| * 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: | ||
| * [Python 2.7](https://www.python.org/downloads/windows/) | ||
| * [Visual Studio Express 2013 for Desktop](https://www.visualstudio.com/downloads/download-visual-studio-vs#d-2013-express) | ||
| ### Windows 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: | ||
| * [Python 2.7](https://www.python.org/downloads/windows/) | ||
| * [Visual Studio Express 2013 for Desktop](https://www.visualstudio.com/downloads/download-visual-studio-vs#d-2013-express) | ||
| ### To build `node-hid` from source for your project: | ||
| ### Building `node-hid` from source, for your projects | ||
@@ -461,3 +469,3 @@ ``` | ||
| ### To build `node-hid` for development: | ||
| ### Build `node-hid` for `node-hid` development: | ||
@@ -491,3 +499,3 @@ * check out a copy of this repo | ||
| ## Using `node-hid` in Electron projects | ||
| ## Electron projects using `node-hid` | ||
| In your electron project, add `electron-rebuild` to your `devDependencies`. | ||
@@ -500,13 +508,11 @@ Then in your package.json `scripts` add: | ||
| 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 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 you want a specific version of electron, do something like: | ||
| 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`: | ||
| ``` | ||
| "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: { | ||
@@ -516,9 +522,24 @@ "node-hid": 'commonjs node-hid' | ||
| ``` | ||
| Examples of `node-hid` in Electron: | ||
| * [electron-hid-toy](https://github.com/todbot/electron-hid-toy) - a simple example of using `node-hid`, that will hopefully always track the latest Electron release | ||
| * [electron-hid-test](https://github.com/todbot/electron-hid-test) - even simpler example of using `node-hid` | ||
| * [Blink1Control2](https://github.com/todbot/Blink1Control2/) - a complete application, using webpack (e.g. see its [webpack-config.js](https://github.com/todbot/Blink1Control2/blob/master/webpack.config.js)) | ||
| ## Using `node-hid` in NW.js projects | ||
| (TBD) | ||
| ## NW.js projects using `node-hid` | ||
| 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 . | ||
| ``` | ||
| ## Support | ||
@@ -525,0 +546,0 @@ |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
No alert changes
Improved metrics
- Total package byte prevSize
508207
0.81%- Number of lines in readme file
535
4.09%No dependency changes