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
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by0.81%
508207
- Number of lines in readme file
- increased by4.09%
535
No dependency changes