doc/Readme_USB-Relay-DLL.md

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