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

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

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

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

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.

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
-------

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 software free; free even from restrictions associated with the GPL. 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.
 * Move the Linux variant to recommended libusb version (1.x)
 * Make bindings for Python and Java
 * Maybe reconstruct the GUI utility
 * Maybe port the Windows variant to GNU (mingw) toolchain
 
Making a proper library will be hard, because of 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. We won't support this in the library itself. Neither we'll support locking for multiple thread access.


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
b43921bb	4	The goal of this little project is to provide open-source API for Chinese low-cost USB HID relays
e0716ab3	5	(search on eBay for "5V USB Relay Programmable Computer Control For Smart Home").
	6
	7	![](http://vusb.wdfiles.com/local--files/project:driver-less-usb-relays-hid-interface/relay2.jpg)
	8
	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
	13	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.
	14
	15	License
	16	-------
	17
	18	We are not associated with the manufacturer(s) of these devices or author(s) of the original software offered by eBay sellers.
	19
	20	Our intent is to make this software free; free even from restrictions associated with the GPL. 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.
	21
b43921bb	22	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	23
	24	Current state
	25	-------------
	26
	27	A simple command-line utility for Linux (x86 or x64) and Windows.
	28	This is enough for our own usage.
	29
	30	- Windows version builds with VC++ and WDK 7.1
b43921bb	31	- Linux version builds with gcc and libusb v. 0.1. Tested on RH and Ubuntu.
e0716ab3	32
	33
	34	To do:
	35	-------
	36
	37	* Reconstruct the API library, which will be binary compatible with the original software package.
b43921bb	38	* Move the Linux variant to recommended libusb version (1.x)
e0716ab3	39	* Make bindings for Python and Java
b43921bb	40	* Maybe reconstruct the GUI utility
	41	* Maybe port the Windows variant to GNU (mingw) toolchain
	42
	43	Making a proper library will be hard, because of 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. We won't support this in the library itself. Neither we'll support locking for multiple thread access.
	44
	45
	46	Misc.
	47	-----
	48
	49	Related projects:
	50
	51	[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.