Denkovi Relay Command Line Tool

Denkovi Relay Command Line Tool is software for controlling all Denkovi USB relay boards from command line promt

Brief description

The main goal of this project is to help to all our customers to use our USB relay boards easily and without any programming knowledge. This tool is actually shell for all our USB relay boards and it does not matter which is the relay board, the command is the same. Just type one command and the the tool will set, get relay status or even will take temperature value from the board sensor (if any). It can be integrated in other software and you don't need to know much about how the USB relay board work. With this tool it is like a "game" and it takes literaly minutes to create for example PHP script and control the USB relay board from smartphone browser.

Features

• Multiplatform: supported by Windows and Linux and macOS;
• Simple and user friendly commands - list, read/write relays and i/o status, timers;
• Practically supports unlimited number of relay boards connected to the host computer;
• Typical applications for this software are:
  • Create desktop icons to turn particular relays;
  • Create BAT/BASH files to make more complex logic (like timers for example);
  • The commands can be executed from PHP script;
  • Control our USB relay boards from Android / iPhone mobile devices;
  • The USB relays can be controlled from each software/platform which can run external executable files or commands in command line promt.

Important!

List with currently supported Denkovi relay boards

Tested with the following OS

• Windows - 7 and above
• Linux - Ubuntu, openSUSE, CentOS
• Raspbian - Strech or Buster (Raspberry PI 3 and above)
• macOS - Catalina

System requirements

• Java - the recommended is Oracale Java 8 Java SE Runtime Environment (JRE) / Java SE Development Kit (JDK), but other JRE / JDK builds and versions (8 or above) also should work;
• For some Denkovi modules - additional drivers must be installed (for example FTDI VCP or Microchip drivers). Please refer to their documentation for more information or download the full software packages.

Installation and running

The first step must be done is to download the appropriate archive file.

Version history may be downloaded from here

Next, we need to extract the archive. We should see the below files:

The next step is to check if we have Oracle Java 1.8. Open the cmd.exe or the terminal and write the following command:

For Oraclae Java you should get similar message like below:

If Java version is different than 1.8 or it is not installed, it is recommend to update/install it. For the various OS, the steps for installing/updating java are different - they can be found on Google or Orcale web site.

Finally, we run the tool. Without any parameters, it simple prints help instructions and shows usage information:

If we get something like this, then it is OK:

If you are behind proxy or firewall, you can use the following format of the java command. It is possible the proxy server and port to be different for your case:

Commands

LIST command

This command lists all the supported USB devices connected to computer currently.

For Linux/Raspbian,when we work with FTDI devices and make LIST, we may see the following (empty device):

This usualy means that we have to execute the following two commands every time when we plug the device to the USB port:

and then make the LIST command.

Regarding the MCP devices (USB 4 Relay v2) the LIST command supports several more additional modifications. Each variant uses different HID library for better OS compability. The reason is there is not well working HID library for all known OS. We've tried to chose the correct default library according to the OS, but the user can always do that in the described way below. For all LIST command variants, execute the following command:

and you will get all the implemented HID libraries at that moment:

Now we can work with the desired library, or example:

Device descriptions

Since the LIST command returns array of devices as well as their factory descriptions, depending on the description value, we may distinguish the following relations:

• FT245R USB FIFO - this is either USB 4 Relay v1 either USB 8 Relay either USB 4 Relay with TCN75 sensor. All of them use the same chipset - FT245RL;
• FT232 USB UART - this is USB 16 Relay (uses FT232RL);
• MCP2200 USB Serial Port Emulator Microchip Technology Inc. - this is USB 4 Relay v2 (MCP2200);

Addressing (identifying) devices

Open by serial number

USB relay boards can be accessed by their serial number, retrieved by the LIST command.

Open by ID

They can be accessed also by their ID. This is the number under the device is listed (lexicographicly) in the system at the moment along with the other devices from the same type. This can be also retrieved by the LIST command.

Open by IP:Port

This type of addressing is only for the Wi-Fi 16 Relay Boards

Device types

The following device types are accepted by the tool. The below types define how the hardware to be initiated and configured by the software:

• 4 - for device USB 4 Relay v1
• 4r4io_abcd - for device USB 4 Relay v1 but working with the four additional i/o lines. abcd define the i/o direction for In1, In2, In3, In4 (FT245R IO.0, IO2, IO4, IO6); 0 is input, 1 is output. Examples: 4r4io_1111, 4r4io_0000, 4r4io_1100...
• 4v2 - for MCP based device USB 4 Relay v2
• 4v2-library - the same like the above command but with expressly stated HID library, for example 4v2-hidapi, 4v2-purejavahidapi, 4v2-hid4java;
• 4r4iov2_abcd - for MCP device USB 4 Relay v2 but working with the four additional i/o lines. abcd define the i/o direction for In1, In2, In3, In4 (MCP2200 GP4, GP5, GP6, GP7); 0 is input, 1 is output. Examples: 4r4iov2_1111, 4r4iov2_0000, 4r4iov2_1100...;
• 4r4iov2_abcd-library - the same like the above command, but with expressly stated HID library, for example 4r4iov2_1111-hidapi, 4r4iov2_0000-purejavahidapi, 4r4iov2_1100-hid4java;
• 8 - for device USB 8 Relay
• 16 - for device USB 16 Relay
• wifi16-tcp - for device WiFi 16 Relay (using TCP)
• wifi16-udp - for device WiFi 16 Relay (using UDP)
• 8inv2 - for USB 8 DI module
• 8inv2-library - the same like the above command but with expressly stated HID library, for example 8inv2-hidapi, 8inv2-purejavahidapi, 8inv2-hid4java;

STATUS command

With this command we retrieve the relays (i/o) status. There are two variants of these commands:

Single relay (i/o) status

The reply is 1 or 0 - for relays (ON or OFF), for i/o (HIGH or LOW level).

Getting Relay1 status of USB 4 Relay v1

Getting In2 status of USB 4 Relay v1. (For this device [RELAY or I/O NUMBER] is from 1 to 8, where 1..4 are Relay1...Relay4 and from 5 to 8 are In1 to In4). We specifiy that the additional 4 i/o lines (FT245R IO.0, IO.2, IO.4 and IO.6 - please take a look here) are working as inputs.

Getting Relay4 status of USB 4 Relay v2

Getting In4 status of USB 4 Relay v2. (For this device [RELAY or I/O NUMBER] is from 1 to 8, where 1..4 are Relay1...Relay4 and from 5 to 8 are In1 to In4). Also here we specifiy that the additional 4 i/o lines (MCP2200 GP4, GP5, GP6 and GP7 - please take a look here) are working as inputs. Finally, here we might need to use exactly the hidapi library. So we do:

For USB 8 Relay, if we wanted to get Relay7 status:

For USB 16 Relay, if we wanted to get Relay11 status:

For WiFi 16 Relay, we get Relay3 status using TCP protocol:

or for UDP version it would be:

All relays (i/o) status

The replay consist of 0 or 1 with count depending of the hardware determined by the [DEVICE TYPE]. It is in ascending order. If there the hardware supports i/o (like USB 4 Relay v1, USB 4 Relay v2), firstly they are populated the relays and after them are following the i/o lines.

Getting relays status of USB 4 Relay v1

Getting relays and i/o status of USB 4 Relay v1. We specify the i/o port to work as 4 inputs:

and for i/o interrpreted as outputs it would be:

Getting relays status of USB 4 Relay v2

Getting relays and i/o status of USB 4 Relay v2. We specify the i/o port to work as 4 inputs:

and for i/o interpreted as outputs it would be:

Getting USB 8 Relay relays status

Getting USB 16 Relay relays status

For WiFi 16 Relay, we do:

Setting relays (i/o) commands

The command changes state of single or all relays (i/o).

The reply of these commands is the same like this one from the STATUS for all relays (i/o) command.

Single relay (i/o) setting

This command sets only the specify relay (i/o) without changing the rest.

Setting Relay1 in ON of USB 4 Relay v1

Setting i/o (In1) in LOW level of USB 4 Relay v1. Here we need to specify the i/o to be outputs

Setting Relay4 in OFF of USB 4 Relay v2

Setting i/o (In2) in HIGH level of USB 4 Relay v2. Here we need to specify the i/o to be outputs

Setting Relay3 in OFF of USB 8 Relay

Setting Relay1 in OFF of USB 16 Relay

For WiFi 16 Relay, we set Relay2 in OFF in this way:

Setting all relays (i/o) in ON(HIGH) / OFF(LOW)

This command acts like the above command but instead of only one relay (i/o) it sets all the relays (i/o) in same state - ON (HIGH) or OFF (LOW).

For example:

or

Setting all relays (i/o) with TURN command

This command sets all the relays (i/o) at the same time with the specified states

Setting all USB 4 Relay v1 relays in ON

Setting all USB 4 Relay v1 relays in OFF and all i/o in HIGH level. Here we state the i/o to be outputs as well:

Setting all USB 4 Relay v2 relays in OFF

Setting all USB 4 Relay v2 relays in ON and all i/o in LOW level. Here we state the i/o to be outputs as well:

Setting Relay1..Relay4 in OFF and Relay5..Relay8 in ON of USB 8 Relay

Setting all relays but Relay1 in ON of USB 16 Relay

Setting odd relays in ON of WiFi 16 Relay

TEMPERATURE command

Get the temperature value (only if the relay board support temperature sensors - for example USB 4 Relay with TCN75A)

Getting temperature in Celsius:

Getting temperature in Fahrenheit:

TIMER command

Exectues time-critical operations. Well known fact is that every time when we run the command line tool the jvm is runned and this takes significant time. Many users contacted us with requests to execute timer commands for time-critical operations. That's why we added such command. It can perform single pulse, many pulses and even cycles with more complex sequences of pulses and every pulse can be with different time (in miliseconds).

Expected reply: current cycle and relays statuses during every switching

Example for setting all relays ON for 10ms, all OFF for 50ms and all ON for 25ms for device USB 4 Relay v1:

The below example makes all relays ON for 10ms and all OFF for 100ms - 5 times for device USB 8 Relay:

The below example makes first relay ON for 10ms and OFF for 1sec - 5 times for device USB 16 Relay:

Typical applications

Run it from the command promt

The commands are the same for Windows / Linux / Raspbian / macOS.

Create shortcuts

Now type

java -jar "path/to/the/jar/file" and the command in our case which is "DAE0007l 16 all 1"

Name it "ALL ON". When you click it if all the settings are correct, the relays should be all ON.

Now, you can create the same way ALL OFF command or whatever shortcut you need.

BAT / BASH files

Very often for many applications it is required some relay to be turned on, wait several seconds and then off. This is so called timer function. With our command line tool this can be done in several easy steps in Windows:

1. Create new text file and save it as .BAT file. For example "Pulse5.BAT".
2. Open the file and type the following commands (USB 16, work with relay 1) and save it.
   • java -jar DenkoviRelayCommandLineTool.jar DAE00000 16 1 1
   • PING 1.1.1.1 -n 1 -w 5000 >NUL
   • java -jar DenkoviRelayCommandLineTool.jar DAE00000 16 1 0
3. Now you can just click it. Relay 1 will be turned ON for 5 seconds and then will be turned OFF.

It is the same story for Linux:

1. Create new text file and save it as .VIM file. For example "Pulse5.VIM".
2. Open the file and type the following commands (USB 16, work with relay 1) and save it.
   • #!/bin/bash
   • java -jar DenkoviRelayCommandLineTool.jar DAE00000 16 1 1
   • sleep 5
   • java -jar DenkoviRelayCommandLineTool.jar DAE00000 16 1 0
3. Now you can just click it. Relay 1 will be turned ON for 5 seconds and then will be turned OFF.

PHP

Just use the function shell_exec() :

<?php

$output = shell_exec('java -jar DenkoviRelayCommandLineTool.jar DAE00000 16 1 0');

?>

Bellow it is shown video how it is possible to acess USB 4 relay board from Android tablet