commandline/README-hidusb-relay-cmd.txt

   1 Command line utility for Chinese USB HID relays
   2 (USB 1.1 HID devices, VEN=5824 (0x16c0) DEV=1503 (0x05DF), based on the V-USB project)
   3
   4 Rev. 1.2 (22-Nov-2014)
   5
   6 Usage:
   7   usbrelay-cmd [ID=XXXXX] ON|OFF <num>   -- turn the relay ON or OFF
   8
   9       where <num> is the relay number: 1-2 or "ALL"
  10
  11   usbrelay-cmd STATUS         -- print state of one relay device with its "unique ID"
  12   usbrelay-cmd ENUM           -- print state of all devices and their "unique IDs"
  13
  14 Parameter ID=XXXXX  specifies one relay device if several are connected.
  15 Without the ID= parameter, if several devices are connected, the program uses any one of them.
  16 The ID string is case sensitive.
  17
  18 Examples:
  19
  20   usbrelay-cmd id=ABCDE on 1
  21   usbrelay-cmd id=ABCDE OFF ALL
  22   usbrelay-cmd id=ABCDE STATUS
  23
  24   usbrelay-cmd ON ALL  -- uses first found relay device
  25   usbrelay-cmd STATUS  -- uses first found relay device
  26
  27
  28 REMARKS
  29
  30 The Enum command lists the IDs of all available relay devices.
  31 The ID strings are case sensitive and should be exactly as output by the "enum" command.
  32
  33 Each relay has two contact pairs: Normally Open and Normally Closed.
  34 The OFF state is the "normal" state, when the red LED is off, and the Normally Open contacts are disconnected.
  35 The ON state is when the red LED is on, and the Normally Open contacts are connected.
  36
  37 Note: In the original s/w readme, "Open" means ON, "Close" means OFF.
  38
  39 This program has been tested with 1- and 2-relay devices.
  40
  41 On Linux, this program requires root access by default!
  42 To grant access to non-root users, define udev rule for the devices:
  43 Example:
  44    SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", MODE:="0666"
  45
  46
  47 BUILDING
  48
  49 For Windows XP and later:
  50  - Using the in-box hid.dll
  51  - Build with VC++ 2008 and WDK 7.1, or VC++ 2013 "community edition" with WDK 8.1
  52
  53 For Linux (PC, x86):
  54  - using the old libusb (v. 0.1; usb.h)
  55  - tested on Centos 5, Ubuntu 12.04, Mint
  56
  57 SOURCE based on a V-USB HID example.
  58 LICENSE: TBD!
  59          Should be non-GPL; rewrite all prototype code!
  60
  61 >>> Target for 1st public release:
  62 ================================
  63 1. Remove GPL encumberment
  64 2. Make a .so for Linux (Windows already has orig DLL)
  65
  66 Other TODO's
  67 ============
  68
  69  *** Check that these devices indeed have unique IDs!
  70   The orig. h file mentions  function:   usb_relay_device_set_serial(int hHandle, char serial[5]);
  71   which may be used by mfg to burn the ID? but the orig. DLL does not export it.
  72   In detection code (find by "unique ID"), check only by product name, Ignore vendor string?
  73
  74 TODO: Make a .so callable from Java, Python etc.
  75       For this, move to libusb 1.x (libusb.h)?
  76 TODO: provide the original API "usb_relay_device.h" API, compatible with the orig. usb_relay_device.dll
  77       The orig .h file and example are in orig dir (slightly adapted and updated to VC2008)
  78      In orig .h file relay state "open" means ON (the red LED is on). "Close" means OFF (the red LED is off)
  79 ~~
  80
  81 Uses code by:
  82 Copyright: (c) 2008 by OBJECTIVE DEVELOPMENT Software GmbH
  83 Author: Christian Starkjohann
  84 Creation Date: 2008-04-11
  85
  86 ~~
  87 The relay device ID - from HID attributes:
  88 vendorName = "www.dcttech.com" -> this site does not exist (squatted)
  89 productName = "USBRelayN" where N=1|2|4
  90