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