doc/Readme_USB-Relay-DLL.md

   1 How to use USB_RELAY_DEVICE DLL
   2 ===============================
   3
   4 Version 2.0
   5
   6 Changes to the original DLL:
   7 ----------------------------
   8  - The type used for handles changed from int to intptr_t, for 64-bit compatibility.
   9    This should be binary compatible with existing 32-bit clients.
  10  - Added helper functions for use from managed languages and scripts; see below, and
  11    `usb_relay_device_lib_version`
  12
  13
  14 Functions:
  15 ---------
  16
  17  * `usb_relay_init`
  18  Call this before calling other functions
  19
  20  * `usb_relay_device_enumerate`
  21  Enumerates all Relay devices plugged into the PC.
  22  Returns list of usb_relay_device_info structures.
  23  Caller should free this list by passing it to usb_relay_device_free_enumerate().
  24
  25  * `usb_relay_device_open`
  26  Opens one Relay board device by its usb_relay_device_info structure,
  27  obtained from usb_relay_device_enumerate().
  28
  29  * `usb_relay_device_open_with_serial_number`
  30  Opens one Relay board device by its serial number string.
  31  These strings can be obtained from usb_relay_device_enumerate().
  32
  33  * `usb_relay_device_open_one_relay_channel`
  34   Turns ON one channel of a Relay board.
  35   Parameters:
  36      - device handle, obtained from usb_relay_device_open()
  37      - Index: integer from 1 to the maximal number of channels on a board.
  38
  39  * `usb_relay_device_open_all_relay_channel`
  40   Turns ON all channels on a board.
  41
  42  * `usb_relay_device_close_one_relay_channel`
  43   Turns OFF one channel of a Relay board.
  44   Parameters:
  45      - device handle, obtained from `usb_relay_device_open()`
  46      - Index: integer from 1 to the maximal number of channels on a board.
  47
  48  * `usb_relay_device_close_all_relay_channel`
  49   Turns OFF all channels on a board.
  50
  51  * `usb_relay_device_get_status`
  52   Get status of all channels on a board as a bit mask.
  53   The least significant bit in returned value corresponds to channel 1.
  54   Bit value 1 means the corresponding relay is switched ON, value 0 means the relay is OFF.
  55
  56  * `usb_relay_device_close`
  57   Closes the Relay device handle opened by `usb_relay_device_open()` or
  58    `usb_relay_device_open_with_serial_number()`
  59
  60  * `usb_relay_exit`
  61   Finalizes the library
  62
  63  *  `usb_relay_device_lib_version`
  64    Returns the version of the library.
  65    The lower 16 bits are the library version. Higher bits: undefined, ignore.
  66    Note: this function is extension of the original library.
  67
  68
  69
  70 Helper functions for managed callers and scripts
  71 ------------------------------------------------
  72
  73 The following functions help to use this lib in managed languages by avoiding dereferencing C pointers.
  74 Native C or C++ callers do not have to use these.
  75 All these functions are extension of the original library.
  76 The `ptr_usb_relay_device_info parameter` is pointer to `struct usb_relay_device_info`, converted to a pointer-sized integer.
  77 Type `int` means the "C" integer (which usually is 32-bit), `ptr` is a pointer-sized integer.
  78
  79  * `ptr_usb_relay_device_info usb_relay_device_next_dev(ptr_usb_relay_device_info)`
  80     Returns pointer to the next element of device list obtained from `usb_relay_device_enumerate`
  81
  82  *  `int usb_relay_device_get_num_relays(ptr_usb_relay_device_info)`
  83     Returns number of relay channels on the device. Values <= 0 are not valid and mean error.
  84
  85  *  `ptr usb_relay_device_get_id_string(ptr_usb_relay_device_info)`
  86     Returns the "serial number" string of the device, as pointer to constant C string (one-byte characters, null terminated).
  87
  88  * `int usb_relay_device_get_status_bitmap(intptr_t hHandle)`
  89    Returns the states of all channels on a relay device as a bit mask.
  90    This is same as `usb_relay_device_get_status` but without dereferencing pointers.
  91    Negative returned values indicate error. Else, bits 0-7 of the value are states of each channel.
  92
  93
  94 Error handling
  95 ---------------
  96 If error occurred, the API functions that return error code return -1;
  97 functions that return handles or pointers return NULL.
  98 Application is responsible to check the returned value.
  99
 100 Notes
 101 -------
 102  * The library does not detect hot plug/unplug of USB devices.
 103  * The library is not thread-safe. Client application must ensure that
 104   only one thread calls the library.
 105
 106 Windows, Visual C++ applications
 107 ---------------------------------
 108
 109 Include file name: `usb_relay_device.h`
 110 Library file name: `usb_relay_device.lib`
 111
 112 Put the following lines in your source file:
 113
 114    `#include <usb_relay_device.h>`
 115
 116    `#pragma comment(lib, "usb_relay_device.lib")`
 117
 118 The library can be also loaded dynamically.
 119 The file `usb_relay_device.dll` must be installed with your application.
 120 Use either 32-bit or 64-bit DLL, matching your application.
 121 The DLL may require VC++ redistributable runtime library.
 122
 123
 124 Linux C/C++  applications (gcc, llvm)
 125 -----------------
 126 Same as above, except the  #pragma. The library name is `usb_relay_device.so`.
 127
 128 Python (CPython)
 129 -------------------
 130 Python programs can use this library via the Ctypes module. Examples are in Test directory.
 131 Be sure to use the correct variant (32 or 64-bit) for your Python interpreter.
 132
 133 Managed .NET applications (C#, VB.NET, Powershell)
 134 ---------------------------------------
 135 Managed programs can use this library via PInvoke.
 136 Be sure to use the correct variant (32 or 64-bit).
 137 TBD.
 138
 139 GCC or MinGW applications on Windows
 140 ------------------------------------
 141 TBD
 142