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

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

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

This project provides 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.
Ebay vendors currently offer only an 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.

The project home page is on the [V-USB wiki](http://vusb.wikidot.com/project:driver-less-usb-relays-hid-interface "driver-less-usb-relays-hid-interface") - 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 contains only the host side software.


Binary downloads, documentation, bugs, TO-DOs and more
----------------------

All this is in the [Github project](http://git.io/bGcxrQ) : releases, wiki pages and Issues. 


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

* A simple command-line utility for Linux (x86 or x64), Apple OS X and Windows (XP and newer, 32 and 64-bit).

* Shared library for Linux (x86 or x64), Apple OS X and Windows.

* Python (CPython) - supported thru the shared library 

The Windows version of the shared lib, `USB_RELAY_DEVICE.DLL`, is backward compatible with the binary from the device vendor.
Windows GUI demo app is similar to the device vendor's but written in C++/CLI.

Required to build:

- Windows version: builds with VC++ and WDK 7.1, or VC++ 2013 "community edition" with its matching SDK (Win8.1).
- Linux version builds with gcc and libusb v. 0.1. Tested on RH, Ubuntu, Mint.
- OS-X 10.9+ version builds with Xcode and plain IOKit libraries. 


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).
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
4d4cf25a	6	This project provides open-source API for low-cost USB HID relays
a73939ba	7	(search on eBay for "5V USB Relay Programmable Computer Control For Smart Home").
a73939ba	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.
4d4cf25a	10	Ebay vendors currently offer only an API library for Windows, and only in binary form.
e0716ab3	11
4d4cf25a	12	We are not associated with the manufacturer(s) of these devices or author(s) of the original software offered by ebay sellers.
b7b53e13	13
4d4cf25a P	14	The project home page is on the [V-USB wiki](http://vusb.wikidot.com/project:driver-less-usb-relays-hid-interface "driver-less-usb-relays-hid-interface") - 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.
4d4cf25a P	15	This repository contains only the host side software.
e0716ab3	16
e0716ab3	17
a73939ba	18
b7b53e13	19	Binary downloads, documentation, bugs, TO-DOs and more
b7b53e13	20	----------------------
a73939ba	21
8553cfb5	22	All this is in the [Github project](http://git.io/bGcxrQ) : releases, wiki pages and Issues.
e0716ab3	23
e0716ab3	24
e0716ab3	25
	26	Current state
	27	-------------
	28
4d4cf25a	29	* A simple command-line utility for Linux (x86 or x64), Apple OS X and Windows (XP and newer, 32 and 64-bit).
b7b53e13	30
4d4cf25a	31	* Shared library for Linux (x86 or x64), Apple OS X and Windows.
e0716ab3	32
4d4cf25a	33	* Python (CPython) - supported thru the shared library
8553cfb5	34
	35	The Windows version of the shared lib, `USB_RELAY_DEVICE.DLL`, is backward compatible with the binary from the device vendor.
	36	Windows GUI demo app is similar to the device vendor's but written in C++/CLI.
	37
	38	Required to build:
b7b53e13	39
b7b53e13	40	- Windows version: builds with VC++ and WDK 7.1, or VC++ 2013 "community edition" with its matching SDK (Win8.1).
8553cfb5	41	- Linux version builds with gcc and libusb v. 0.1. Tested on RH, Ubuntu, Mint.
728ea86e	42	- OS-X 10.9+ version builds with Xcode and plain IOKit libraries.
e0716ab3	43
e0716ab3	44
b7b53e13	45	License
b7b53e13	46	-------
b43921bb	47
b7b53e13	48	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.
b43921bb	49
b7b53e13	50	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).