doc/Readme_USB-Relay-DLL.md

   1 How to use USB_RELAY_DEVICE DLL
   2 ===============================
   3
   4 Version 1.0
   5
   6 Changes to the original DLL:
   7 ----------------------------
   8  - 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
  11
  12 Windows, Visual C++ applications
  13 ---------------------------------
  14
  15 Include file name: usb_relay_device.h
  16 Library file name: usb_relay_device.lib
  17
  18 Put the following lines in your source file:
  19
  20    `#include <usb_relay_device.h>`
  21
  22    `#pragma comment(lib, "usb_relay_device.lib")`
  23
  24 The file usb_relay_device.dll must be installed with your application.
  25 Use either 32-bit or 64-bit DLL, matching your application.
  26 The DLL may require VC++ redistributable runtime library.
  27
  28 Using the API:
  29 --------------
  30
  31  * `usb_relay_init()`
  32  Call this before calling other functions
  33
  34  * `usb_relay_device_enumerate`
  35  Enumerates all Relay devices plugged into the PC.
  36  Returns list of usb_relay_device_info structures.
  37  Caller should free this list by passing it to usb_relay_device_free_enumerate().
  38
  39  * `usb_relay_device_open`
  40  Opens one Relay board device by its usb_relay_device_info structure,
  41  obtained from usb_relay_device_enumerate().
  42
  43  * `usb_relay_device_open_with_serial_number`
  44  Opens one Relay board device by its serial number string.
  45  These strings can be obtained from usb_relay_device_enumerate().
  46
  47  * `usb_relay_device_open_one_relay_channel`
  48   Turns ON one channel of a Relay board.
  49   Parameters:
  50      - device handle, obtained from usb_relay_device_open()
  51      - Index: integer from 1 to the maximal number of channels on a board.
  52
  53  * `usb_relay_device_open_all_relay_channel`
  54   Turns ON all channels on a board.
  55
  56  * `usb_relay_device_close_one_relay_channel`
  57   Turns OFF one channel of a Relay board.
  58   Parameters:
  59      - device handle, obtained from `usb_relay_device_open()`
  60      - Index: integer from 1 to the maximal number of channels on a board.
  61
  62  * `usb_relay_device_close_all_relay_channel`
  63   Turns OFF all channels on a board.
  64
  65  * `usb_relay_device_get_status`
  66   Get status of all channels on a board as a bit mask.
  67   The least significant bit in returned value corresponds to channel 1.
  68   Bit value 1 means the corresponding relay is switched ON, value 0 means the relay is OFF.
  69
  70  * `usb_relay_device_close`
  71   Closes the Relay device handle opened by `usb_relay_device_open()` or
  72    `usb_relay_device_open_with_serial_number()`
  73
  74 * `usb_relay_exit`
  75   Finalizes the library
  76
  77 Error handling
  78 ---------------
  79 If error occurred, the API functions that return error code return -1;
  80 functions that return handles or pointers return NULL.
  81 Application is responsible to check the returned value.
  82
  83 Notes
  84 -------
  85  * The library does not detect hot plug/unplug of USB devices.
  86  * The library is not thread-safe. Client application must ensure that
  87   only one thread calls the library.
  88
  89
  90 Managed .NET applications (C#, VB.NET)
  91 ---------------------------------------
  92 TBD
  93
  94 Python (CPython)
  95 -------------------
  96 TBD
  97
  98 GCC or MinGW applications
  99 --------------------------
 100 TBD
 101