1. Home
2. USB Relay Board Programming

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.