README.md

   1 usb-relay-hid
   2 =============
   3
   4 The goal of this little project is to provide open-source API for Chinese low-cost USB HID relays
   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
  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).
  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
  31 - Linux version builds with gcc and libusb v. 0.1. Tested on RH and Ubuntu.
  32
  33
  34 To do:
  35 -------
  36
  37  * Reconstruct the API library, which will be binary compatible with the original software package.
  38  * Move the Linux variant to recommended libusb version (1.x)
  39  * Make bindings for Python and Java
  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.