[usb-relay-hid.git] / README.md

usb-relay-hid
=============

![](http://vusb.wdfiles.com/local--files/project:driver-less-usb-relays-hid-interface/relay2.jpg)

The goal of this little project is to provide open-source API for low-cost USB HID relays 
(search on eBay for "5V USB Relay Programmable Computer Control For Smart Home").

The big advantage of HID-based interface is that no kernel drivers and no simulated COM-ports are needed. It is easy to detect and address the connected devices.

Unfortunatey, the vendors currently offer only API library for Windows, and only in binary form.

We are not associated with the manufacturer(s) of these devices or author(s) of the original software offered by eBay sellers.
Our intent is to make this device usable on Linux (and any other OS that supports libusb) as well as on 64-bit Windows.

The main project web page is on the [V-USB wiki](http://vusb.wikidot.com/project:driver-less-usb-relays-hid-interface "driver-less-usb-relays-hid-interface"). This is because the firmware of the device is based on [V-USB](http://www.obdev.at/products/vusb/index.html). V-USB enables amazingly simple and low-cost USB hardware solutions. This repository, however,  contains only the host side software.


License
-------

Currently we reuse some code from other V-USB projects, which is dual-licensed: GPL + commercial. Until we remove this code, we cannot set any other license. 

We could not locate any copyright information in the software package offered by the eBay sellers. No source code was reused from that package, besides of the C API header (the .h file).

Current state
-------------

A simple command-line utility for Linux (x86 or x64) and Windows.
This is enough for our own usage.

- Windows version builds with VC++ and WDK 7.1.
- Linux version builds with gcc and libusb v. 0.1. Tested on RH and Ubuntu.


To do:
-------

 * Reconstruct the API library, which will be binary compatible with the original software package, and minimal decent documentation.
 * Move the Linux variant to newer libusb version (1.x)
 * Make bindings for Python and Java
 * Maybe, reconstruct the GUI utility
 * Maybe, port the Windows variant to GNU (mingw) toolchain
 
The original API library does not handle hot-plug and removal of USB devices. The command-line utility isn't affected by hot plug/removal, but GUI clients of the library will need to re-enumerate the devices or react to PnP events in OS-specific way. Caller must provide locking in case of accessing the library from multiple threads.


Misc.
-----

Related projects:

[USB Relay](https://github.com/johannesk/usb-relay)  by Johannes Krude - complete project with hardware and firmware, based on V-USB, but not HID - so requires a driver.
Commit	Line	Data
3fef637d P	1	usb-relay-hid
	2	=============
	3
e0716ab3	4	![](http://vusb.wdfiles.com/local--files/project:driver-less-usb-relays-hid-interface/relay2.jpg)
e0716ab3	5
a73939ba	6	The goal of this little project is to provide open-source API for low-cost USB HID relays
	7	(search on eBay for "5V USB Relay Programmable Computer Control For Smart Home").
	8
e0716ab3	9	The big advantage of HID-based interface is that no kernel drivers and no simulated COM-ports are needed. It is easy to detect and address the connected devices.
	10
	11	Unfortunatey, the vendors currently offer only API library for Windows, and only in binary form.
	12
a73939ba	13	We are not associated with the manufacturer(s) of these devices or author(s) of the original software offered by eBay sellers.
	14	Our intent is to make this device usable on Linux (and any other OS that supports libusb) as well as on 64-bit Windows.
	15
e0716ab3	16	The main project web page is on the [V-USB wiki](http://vusb.wikidot.com/project:driver-less-usb-relays-hid-interface "driver-less-usb-relays-hid-interface"). This is because the firmware of the device is based on [V-USB](http://www.obdev.at/products/vusb/index.html). V-USB enables amazingly simple and low-cost USB hardware solutions. This repository, however, contains only the host side software.
e0716ab3	17
a73939ba	18
a73939ba	19
e0716ab3	20	License
	21	-------
	22
a73939ba	23	Currently we reuse some code from other V-USB projects, which is dual-licensed: GPL + commercial. Until we remove this code, we cannot set any other license.
e0716ab3	24
b43921bb	25	We could not locate any copyright information in the software package offered by the eBay sellers. No source code was reused from that package, besides of the C API header (the .h file).
e0716ab3	26
	27	Current state
	28	-------------
	29
	30	A simple command-line utility for Linux (x86 or x64) and Windows.
	31	This is enough for our own usage.
	32
a73939ba	33	- Windows version builds with VC++ and WDK 7.1.
b43921bb	34	- Linux version builds with gcc and libusb v. 0.1. Tested on RH and Ubuntu.
e0716ab3	35
	36
	37	To do:
	38	-------
	39
a73939ba	40	* Reconstruct the API library, which will be binary compatible with the original software package, and minimal decent documentation.
a73939ba	41	* Move the Linux variant to newer libusb version (1.x)
e0716ab3	42	* Make bindings for Python and Java
a73939ba	43	* Maybe, reconstruct the GUI utility
a73939ba	44	* Maybe, port the Windows variant to GNU (mingw) toolchain
b43921bb	45
a73939ba	46	The original API library does not handle hot-plug and removal of USB devices. The command-line utility isn't affected by hot plug/removal, but GUI clients of the library will need to re-enumerate the devices or react to PnP events in OS-specific way. Caller must provide locking in case of accessing the library from multiple threads.
b43921bb	47
	48
	49	Misc.
	50	-----
	51
	52	Related projects:
	53
	54	[USB Relay](https://github.com/johannesk/usb-relay) by Johannes Krude - complete project with hardware and firmware, based on V-USB, but not HID - so requires a driver.