node-hid - npm Package Compare versions

Comparing version 0.0.15 to 0.1.0

hidapi/README.txt

@@ -1,10 +0,12 @@
-HID API for Windows, Linux, and Mac OS X
+         HIDAPI library for Windows, Linux, FreeBSD and Mac OS X
+        =========================================================
 
 About
-------
+======
 
 HIDAPI is a multi-platform library which allows an application to interface
-with USB and Bluetooth HID-Class devices on Windows, Linux, and Mac OS X. 
-On Windows, a DLL is built.  On other platforms (and optionally on Windows),
-the single source file can simply be dropped into a target application.
+with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and Mac
+OS X.  HIDAPI can be either built as a shared library (.so or .dll) or
+can be embedded directly into a target application by adding a single source
+file (per platform) and a single header.
 
@@ -15,2 +17,3 @@ HIDAPI has four back-ends:
 	* Linux/libusb (using libusb-1.0)
+	* FreeBSD (using libusb-1.0)
 	* Mac (using IOHidManager)
@@ -30,15 +33,18 @@
 
-Linux/libusb (linux/hid-libusb.c):
+Linux/FreeBSD/libusb (libusb/hid-libusb.c):
 This back-end uses libusb-1.0 to communicate directly to a USB device. This
 back-end will of course not work with Bluetooth devices.
 
+HIDAPI also comes with a Test GUI. The Test GUI is cross-platform and uses
+Fox Toolkit (http://www.fox-toolkit.org).  It will build on every platform
+which HIDAPI supports.  Since it relies on a 3rd party library, building it
+is optional but recommended because it is so useful when debugging hardware.
+
 What Does the API Look Like?
------------------------------
+=============================
 The API provides the the most commonly used HID functions including sending
 and receiving of input, output, and feature reports.  The sample program,
-which communicates with a heavily modified version the USB Generic HID
-sample which is part of the Microchip Application Library (in folder
-"Microchip Solutions\USB Device - HID - Custom Demos\Generic HID - Firmware"
-when the Microchip Application Framework is installed), looks like this
-(with error checking removed for simplicity):
+which communicates with a heavily hacked up version of the Microchip USB
+Generic HID sample looks like this (with error checking removed for
+simplicity):
 
@@ -100,42 +106,169 @@ #include <windows.h>
 
+If you have your own simple test programs which communicate with standard
+hardware development boards (such as those from Microchip, TI, Atmel,
+FreeScale and others), please consider sending me something like the above
+for inclusion into the HIDAPI source.  This will help others who have the
+same hardware as you do.
+
 License
---------
+========
 HIDAPI may be used by one of three licenses as outlined in LICENSE.txt.
 
 Download
----------
-It can be downloaded from github
+=========
+HIDAPI can be downloaded from github
 	git clone git://github.com/signal11/hidapi.git
 
 Build Instructions
--------------------
-To build the console test program:
-  Windows:
-    Build the .sln file in the windows/ directory.
-  Linux:
-    cd to the linux/ directory and run make.
-  Mac OS X:
-    cd to the mac/ directory and run make.
+===================
 
-To build the Test GUI:
-  The test GUI uses Fox toolkit, available from www.fox-toolkit.org.
-  On Debian-based systems such as Ubuntu, install Fox using the following:
-	sudo apt-get install libfox-1.6-dev
-  On Mac OSX, install Fox from ports:
-	sudo port install fox
-  On Windows, download the hidapi-externals.zip file from the main download
-  site and extract it just outside of hidapi, so that hidapi-externals and
-  hidapi are on the same level, as shown:
+This section is long. Don't be put off by this. It's not long because it's
+complicated to build HIDAPI; it's quite the opposite.  This section is long
+because of the flexibility of HIDAPI and the large number of ways in which
+it can be built and used.  You will likely pick a single build method.
 
-     Parent_Folder
-       |
-       +hidapi
-       +hidapi-externals
+HIDAPI can be built in several different ways. If you elect to build a
+shared library, you will need to build it from the HIDAPI source
+distribution.  If you choose instead to embed HIDAPI directly into your
+application, you can skip the building and look at the provided platform
+Makefiles for guidance.  These platform Makefiles are located in linux/
+libusb/ mac/ and windows/ and are called Makefile-manual.  In addition,
+Visual Studio projects are provided.  Even if you're going to embed HIDAPI
+into your project, it is still beneficial to build the example programs.
 
-  Then to build:
-    On Windows, build the .sln file in the testgui/ directory.
-    On Linux and Mac, run make from the testgui/ directory.
 
-To build using the DDK (old method):
+Prerequisites:
+---------------
 
+	Linux:
+	-------
+	On Linux, you will need to install development packages for libudev,
+	libusb and optionally Fox-toolkit (for the test GUI). On
+	Debian/Ubuntu systems these can be installed by running:
+	    sudo apt-get install libudev-dev libusb-1.0-0-dev libfox-1.6-dev
+
+	If you downloaded the source directly from the git repository (using
+	git clone), you'll need Autotools:
+	    sudo apt-get install autotools-dev
+
+	FreeBSD:
+	---------
+	On FreeBSD you will need to install GNU make, libiconv, and
+	optionally Fox-Toolkit (for the test GUI). This is done by running
+	the following:
+	    pkg_add -r gmake libiconv fox16
+
+	If you downloaded the source directly from the git repository (using
+	git clone), you'll need Autotools:
+	    pkg_add -r autotools
+
+	Mac:
+	-----
+	On Mac, you will need to install Fox-Toolkit if you wish to build
+	the Test GUI. There are two ways to do this, and each has a slight
+	complication. Which method you use depends on your use case.
+
+	If you wish to build the Test GUI just for your own testing on your
+	own computer, then the easiest method is to install Fox-Toolkit
+	using ports:
+		sudo port install fox
+
+	If you wish to build the TestGUI app bundle to redistribute to
+	others, you will need to install Fox-toolkit from source.  This is
+	because the version of fox that gets installed using ports uses the
+	ports X11 libraries which are not compatible with the Apple X11
+	libraries.  If you install Fox with ports and then try to distribute
+	your built app bundle, it will simply fail to run on other systems.
+	To install Fox-Toolkit manually, download the source package from
+	http://www.fox-toolkit.org, extract it, and run the following from
+	within the extracted source:
+		./configure && make && make install
+
+	Windows:
+	---------
+	On Windows, if you want to build the test GUI, you will need to get
+	the hidapi-externals.zip package from the download site.  This
+	contains pre-built binaries for Fox-toolkit.  Extract
+	hidapi-externals.zip just outside of hidapi, so that
+	hidapi-externals and hidapi are on the same level, as shown:
+
+	     Parent_Folder
+	       |
+	       +hidapi
+	       +hidapi-externals
+
+	Again, this step is not required if you do not wish to build the
+	test GUI.
+
+
+Building HIDAPI into a shared library on Unix Platforms:
+---------------------------------------------------------
+
+On Unix-like systems such as Linux, FreeBSD, Mac, and even Windows, using
+Mingw or Cygwin, the easiest way to build a standard system-installed shared
+library is to use the GNU Autotools build system.  If you checked out the
+source from the git repository, run the following:
+
+	./bootstrap
+	./configure
+	make
+	make install     <----- as root, or using sudo
+
+If you downloaded a source package (ie: if you did not run git clone), you
+can skip the ./bootstrap step.
+
+./configure can take several arguments which control the build. The two most
+likely to be used are:
+	--enable-testgui
+		Enable build of the Test GUI. This requires Fox toolkit to
+		be installed.  Instructions for installing Fox-Toolkit on
+		each platform are in the Prerequisites section above.
+
+	--prefix=/usr
+		Specify where you want the output headers and libraries to
+		be installed. The example above will put the headers in
+		/usr/include and the binaries in /usr/lib. The default is to
+		install into /usr/local which is fine on most systems.
+
+Building the manual way on Unix platforms:
+-------------------------------------------
+
+Manual Makefiles are provided mostly to give the user and idea what it takes
+to build a program which embeds HIDAPI directly inside of it. These should
+really be used as examples only. If you want to build a system-wide shared
+library, use the Autotools method described above.
+
+	To build HIDAPI using the manual makefiles, change to the directory
+	of your platform and run make. For example, on Linux run:
+		cd linux/
+		make -f Makefile-manual
+
+	To build the Test GUI using the manual makefiles:
+		cd testgui/
+		make -f Makefile-manual
+
+Building on Windows:
+---------------------
+
+To build the HIDAPI DLL on Windows using Visual Studio, build the .sln file
+in the windows/ directory.
+
+To build the Test GUI on windows using Visual Studio, build the .sln file in
+the testgui/ directory.
+
+To build HIDAPI using MinGW or Cygwin using Autotools, use the instructions
+in the section titled "Building HIDAPI into a shared library on Unix
+Platforms" above.  Note that building the Test GUI with MinGW or Cygwin will
+require the Windows procedure in the Prerequisites section above (ie:
+hidapi-externals.zip).
+
+To build HIDAPI using MinGW using the Manual Makefiles, see the section
+"Building the manual way on Unix platforms" above.
+
+HIDAPI can also be built using the Windows DDK (now also called the Windows
+Driver Kit or WDK). This method was originally required for the HIDAPI build
+but not anymore. However, some users still prefer this method. It is not as
+well supported anymore but should still work. Patches are welcome if it does
+not. To build using the DDK:
+
    1. Install the Windows Driver Kit (WDK) from Microsoft.
@@ -152,6 +285,51 @@ 2. From the Start menu, in the Windows Driver Kits folder, select Build
 
---------------------------------
+Cross Compiling
+================
 
+This section talks about cross compiling HIDAPI for Linux using autotools.
+This is useful for using HIDAPI on embedded Linux targets.  These
+instructions assume the most raw kind of embedded Linux build, where all
+prerequisites will need to be built first.  This process will of course vary
+based on your embedded Linux build system if you are using one, such as
+OpenEmbedded or Buildroot.
+
+For the purpose of this section, it will be assumed that the following
+environment variables are exported.
+
+	$ export STAGING=$HOME/out
+	$ export HOST=arm-linux
+
+STAGING and HOST can be modified to suit your setup.
+
+Prerequisites
+--------------
+
+Note that the build of libudev is the very basic configuration.
+
+Build Libusb. From the libusb source directory, run:
+	./configure --host=$HOST --prefix=$STAGING
+	make
+	make install
+
+Build libudev. From the libudev source directory, run:
+	./configure --disable-gudev --disable-introspection --disable-hwdb \
+		 --host=arm-linux --prefix=$STAGING
+	make
+	make install
+
+Building HIDAPI
+----------------
+
+Build HIDAPI:
+
+	PKG_CONFIG_DIR= \
+	PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \
+	PKG_CONFIG_SYSROOT_DIR=$STAGING \
+	./configure --host=$HOST --prefix=$STAGING
+
+
 Signal 11 Software - 2010-04-11
                      2010-07-28
                      2011-09-10
+                     2012-05-01
+                     2012-07-03

package.json

 {
-  "author": "",
-  "name": "node-hid",
-  "version": "0.0.15",
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/andtan/node-hid.git"
-  },
-  "scripts": {
-    "install": "cd ./src/ && node-waf configure build install"
-  },
-  "main": "./src/HID",
-  "engines": {
-    "node": "~0.6.11"
-  },
-  "dependencies": {},
-  "devDependencies": {}
+    "name": "node-hid",
+    "description": "USB HID device access library",
+    "version": "0.1.0",
+    "author": {
+        "name": "Hans Hübner",
+        "email": "[e-mail]",
+        "url": "https://github.com/hanshuebner"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git://github.com/hanshuebner/node-hid.git"
+    },
+    "scripts": {
+        "install": "sh install.sh"
+    },
+    "main": "./src/HID",
+    "engines": {
+        "node": ">=0.8.0"
+    },
+    "license": "MIT/X11",
+    "dependencies": {},
+    "devDependencies": {}
 }

README.md

 # node-hid - Access USB HID devices from node.js #
 
-Prerequisites:
+## Installation
 
-Mac OS (I use 10.6.8) or Linux (I use Ubuntu 11.10 with Linux 3.0 on x86_64)
-node.js v0.6, built from source.
+### Prerequisites:
 
-Pull the required submodule:
+* Mac OS (I use 10.6.8) or Linux (kernel 2.6+) or Windows XP+
+* node.js v0.8
+* libudev (Linux only)
 
-git submodule init
-git submodule update
+### Compile from source on Linux or OSX
 
-Build the extension:
+Use npm to execute all installation steps:
 
 ```
-$ cd src/
-$ node-waf configure build
+npm install
 ```
 
-Try it:
+### Compile from source on Windows
 
+Use node-gyp to compile the extension.
+
+## Test it
+
+In the ```src/``` directory, various JavaScript programs can be found
+that talk to specific devices in some way.  The ```show-devices.js```
+program can be used to display all HID devices in the system.
+
+## How to Use
+
+### Load the extension
+
 ```
-$ node show-devices.js
-devices: [ { vendorId: 1452,
+var HID = require('HID');
+```
+
+### Get a list of all HID devices in the system:
+
+```
+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,
@@ -43,2 +70,36 @@ path: 'USB_05ac_0253_0x100a148e0',
 
+### Opening a device
+
+Before a device can be read from or written to, it must be opened:
+
+```
+var device = new HID.HID(path);
+```
+
+```device``` will contain a handle to the device.  The ```path``` can
+be determined by a prior HID.devices() call.  If an error occurs
+opening the device, an exception will be thrown.
+
+### Reading from a device
+
+Reading from a device is performed using the read call on a device
+handle:
+
+```
+device.read(function(error, data) {});
+```
+
+All reading is asynchronous.
+
+### Writing to a device
+
+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]);
+```
+
+### Support
+
 If you need help, send me an email ([e-mail])

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Install scripts

Supply chain risk

Install scripts are run when the package is installed. The majority of malware in npm is hidden in install scripts.

Found 1 instance in 1 package

Non-existent author

Supply chain risk

The package was published by an npm account that no longer exists.

Found 1 instance in 1 package

Native code

Supply chain risk

Contains native code which could be a vector to obscure malicious code, and generally decrease the likelihood of reproducible or reliable installs.

Found 1 instance in 1 package

Misc. License Issues

License

(Experimental) A package's licensing information has fine-grained problems.

Found 1 instance in 1 package

Copyleft License

License

(Experimental) Copyleft license information was found.

Found 1 instance in 1 package

Debug access

Supply chain risk

Uses debug, reflection and dynamic code execution features.

Found 1 instance in 1 package

Mixed license

License

(Experimental) Package contains multiple licenses.

Found 1 instance in 1 package

Non-permissive License

License

(Experimental) A license not known to be considered permissive was found.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Install scripts

Supply chain risk

Install scripts are run when the package is installed. The majority of malware in npm is hidden in install scripts.

Found 1 instance in 1 package

Copyleft License

License

(Experimental) Copyleft license information was found.

Found 1 instance in 1 package

Mixed license

License

(Experimental) Package contains multiple licenses.

Found 1 instance in 1 package

No contributors or author data

Maintenance

Package does not specify a list of contributors or an author in package.json.

Found 1 instance in 1 package

Non-permissive License

License

(Experimental) A license not known to be considered permissive was found.

Found 1 instance in 1 package

Unidentified License

License

(Experimental) Something that seems like a license was found, but its contents could not be matched with a known license.

Found 2 instances in 1 package

Improved metrics

Number of package files

89

increased by20.27%

Number of low license alerts

4

decreased by-33.33%

Lines of code

151

increased by7.86%

Number of low maintenance alerts

1

decreased by-50%

Number of lines in readme file

105

increased by138.64%

Worsened metrics

Total package byte prevSize

920696

decreased by-85.5%

Number of medium license alerts

1

increased byInfinity%

Number of high supply chain risk alerts

2

increased by100%

Number of low supply chain risk alerts

1

increased byInfinity%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes