Writing Code for the USB Relay Board
Some users may want to write their own software to work with the USB Relay board. EtherTek
Circuits has provided an Application Programming Interface (API) by way of a Dynamically
Linked Library (DLL) that users can use to communicate to the USB Relay board. The
USBrelay_DLL.dll can be used with many programming languages. Some example code is listed
below.
Download the programming pack here: Programmer's Pack
Win32 ASM example code: Download it here.
Coded using: RADASM IDE
C-Sharp 2010 .NET example code: Download
it here.
Visual Basic 2010 .NET example code: Download it here.
Active PERL example code: Download it
here.
The DLL Functions are Listed Below
TestDLL
Purpose:
To test connectivity to the DLL without the need of a USB Relay board plugged in.
Calling Parameters:
1. supply a 32 bit pointer to a buffer (minimum 4 bytes).
Return Value:
If the function fails, the return value will be FALSE. If the function succeeds, the return
value will be TRUE and the buffer will contain OK.
FindUSBrelayBoards
Purpose:
To gather a list of all USB Relay Boards attached to the control device.
Calling Parameters:
1. supply a 32 bit pointer to a buffer (1024 byte) that will hold the list of USB Relay
Boards.
Return Value:
If the function fails, the return value will be FALSE. If the function succeeds, the return
value will be TRUE. When the function completes successfully, each unique identifier for
each USB Relay board found will be placed in a zero terminated string. Each identifier will
be separated by a "|". The string also is ending in a "|". The calling program will have to
parse out the identifiers.
Example: 800A|801C|805F|
GetManufacturerString
Purpose:
To poll the Manufacturer specified in the device firmware for a specific device ID.
Calling Parameters:
1. product identifier (32 bit). This typically is one of the IDs given by
FindUSBrelayBoards.
2. supply a 32 bit pointer to a buffer (512 byte) that will hold the manufacturer string of
the USB Relay board.
Return Value:
If the function fails, the return value will be FALSE. If the function succeeds, the return
value will be TRUE. When the function completes successfully, the buffer will contain a
zero terminated character string containing the manufacturer.
GetProductString
Purpose:
To poll the Product specified in the device firmware for a specific device ID.
Calling Parameters:
1. product identifier (32 bit). This typically is one of the IDs given by
FindUSBrelayBoards.
2. supply a 32 bit pointer to a buffer (512 byte) that will hold the product string of the
USB Relay board.
Return Value:
If the function fails, the return value will be FALSE. If the function succeeds, the return
value will be TRUE. When the function completes successfully, the buffer will contain a
zero terminated character string containing the product string.
GetVersionString
Purpose:
To poll the Version specified in the device firmware for a specific device ID.
Calling Parameters:
1. product identifier (32 bit). This typically is one of the IDs given by
FindUSBrelayBoards.
2. supply a 32 bit pointer to a buffer (512 byte) that will hold the version string of the
USB Relay board.
Return Value:
If the function fails, the return value will be FALSE. If the function succeeds, the return
value will be TRUE. When the function completes successfully, the buffer will contain a
zero terminated character string containing the version.
WriteUSBrelay
Purpose:
To control the relays and LEDS.
Calling Parameters:
1. product identifier (32 bit). This typically is one of the IDs given by
FindUSBrelayBoards.
2. command DWORD (see list below).
3. secondary DWORD used for LED status (see list below).
Return Value:
If the function fails, the return value will be FALSE. If the function succeeds, the return
value will be TRUE.
Command DWORD List:
Command DWORD - 0x00 - Relay 1 De-Energized - Secondary DWORD - Don't care.
Command DWORD - 0x01 - Relay 1 Energized - Secondary DWORD - Don't care.
Command DWORD - 0x02 - Relay 2 De-Energized - Secondary DWORD - Don't care.
Command DWORD - 0x03 - Relay 2 Energized - Secondary DWORD - Don't care.
Command DWORD - 0x04 - Relay 3 De-Energized - Secondary DWORD - Don't care.
Command DWORD - 0x05 - Relay 3 Energized - Secondary DWORD - Don't care.
Command DWORD - 0x06 - Relay 4 De-Energized - Secondary DWORD - Don't care.
Command DWORD - 0x07 - Relay 4 Energized - Secondary DWORD - Don't care.
Command DWORD - 0x08 - Relay 5 De-Energized - Secondary DWORD - Don't care.
Command DWORD - 0x09 - Relay 5 Energized - Secondary DWORD - Don't care.
Command DWORD - 0x0A - RESERVED - Has no effect - Secondary DWORD - Don't care.
Command DWORD - 0x0B - Set LED status - Secondary DWORD - A bit mask in the format
00000000000000000000000000xxxxxx. All upper bits must be zero except for bit 6,5,4,3,2,1
set = LED on, not set = LED off.
ReadUSBrelays
Purpose:
To retrieve the status of relays, LEDS enabled, and firmware version number.
Calling Parameters:
1. product identifier (32 bit). This typically is one of the IDs given by
FindUSBrelayBoards.
2. supply a 32 bit pointer to a buffer (32 byte) that will hold the status bytes.
Return Value:
If the function fails, the return value will be FALSE. If the function succeeds, the return
value will be TRUE. When the function completes successfully, the returned buffer contains
a series of bytes representing relay status, LEDS enabled, and firmware. See below for an
in-depth explanation of the returned bytes.
Return Value Format:
BYTE 1 = Relay 1 Status. 0x00 = De-Energized. 0x01 = Energized.
BYTE 2 = Relay 2 Status. 0x00 = De-Energized. 0x01 = Energized.
BYTE 3 = Relay 3 Status. 0x00 = De-Energized. 0x01 = Energized.
BYTE 4 = Relay 4 Status. 0x00 = De-Energized. 0x01 = Energized.
BYTE 5 = Relay 5 Status. 0x00 = De-Energized. 0x01 = Energized.
BYTE 6 = Power Indicator. Always 0x01.
BYTE 7 = LED Status. Format = 00xxxxxx.
- Bit 8 and 7 are always zero.
- Bit 6,5,4,3,2,1 will be LED on if bit is set, or LED off if bit is not
set.
- Bit 1 = Relay 1 LED.
- Bit 2 = Relay 2 LED.
- Bit 3 = Relay 3 LED.
- Bit 4 = Relay 4 LED.
- Bit 5 = Relay 5 LED.
- Bit 6 = Heartbeat LED.
BYTE 9 = Firmware decimal separator. Will always be 0x2E = ASCII .
BYTE 10 = Firmware Medium byte. Example: 0x30 = ASCII 0
BYTE 11 = Firmware Low byte. Example: 0x30 = ASCII 0
BYTES 12 through 32 are zero.
Our Story
EtherTek Circuits started its business in 2001. Ever since we have provided remote monitoring and control solutions for Remote Tower Sites, the Oil & Gas industry, Telemetry systems for Agriculture, Municipalities, Mines, Solar Farms, Hydro Plants, and the Military.
Useful Links
Our Contacts
PO Box 1576,
Princeton, B.C. V0X-1W0 CANADA
+1 (250) 295-6794
+1 (250) 868-0448