Commit | Line | Data |
---|---|---|
8401c785 | 1 | How to use USB_RELAY_DEVICE DLL |
06f54e1f | 2 | =============================== |
8401c785 | 3 | |
4 | Version 1.0 | |
5 | ||
6 | Changes to the original DLL: | |
06f54e1f | 7 | ---------------------------- |
8401c785 | 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 | |
06f54e1f | 13 | --------------------------------- |
8401c785 | 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 | ||
06f54e1f P |
20 | `#include <usb_relay_device.h>` |
21 | ||
22 | `#pragma comment(lib, "usb_relay_device.lib")` | |
8401c785 | 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 | ||
662d41ca | 31 | * `usb_relay_init()` |
8401c785 | 32 | Call this before calling other functions |
33 | ||
662d41ca | 34 | * `usb_relay_device_enumerate` |
8401c785 | 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 | ||
662d41ca | 39 | * `usb_relay_device_open` |
8401c785 | 40 | Opens one Relay board device by its usb_relay_device_info structure, |
41 | obtained from usb_relay_device_enumerate(). | |
42 | ||
662d41ca | 43 | * `usb_relay_device_open_with_serial_number` |
8401c785 | 44 | Opens one Relay board device by its serial number string. |
45 | These strings can be obtained from usb_relay_device_enumerate(). | |
46 | ||
662d41ca | 47 | * `usb_relay_device_open_one_relay_channel` |
8401c785 | 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 | ||
662d41ca | 53 | * `usb_relay_device_open_all_relay_channel` |
8401c785 | 54 | Turns ON all channels on a board. |
55 | ||
662d41ca | 56 | * `usb_relay_device_close_one_relay_channel` |
8401c785 | 57 | Turns OFF one channel of a Relay board. |
58 | Parameters: | |
662d41ca | 59 | - device handle, obtained from `usb_relay_device_open()` |
8401c785 | 60 | - Index: integer from 1 to the maximal number of channels on a board. |
61 | ||
662d41ca | 62 | * `usb_relay_device_close_all_relay_channel` |
8401c785 | 63 | Turns OFF all channels on a board. |
64 | ||
662d41ca | 65 | * `usb_relay_device_get_status` |
8401c785 | 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 | ||
662d41ca P |
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()` | |
8401c785 | 73 | |
662d41ca | 74 | * `usb_relay_exit` |
8401c785 | 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) | |
06f54e1f | 91 | --------------------------------------- |
8401c785 | 92 | TBD |
93 | ||
94 | Python (CPython) | |
06f54e1f | 95 | ------------------- |
8401c785 | 96 | TBD |
97 | ||
98 | GCC or MinGW applications | |
06f54e1f | 99 | -------------------------- |
8401c785 | 100 | TBD |
101 |