03 Relays - rotor-rig/racebox GitHub Wiki

To control hooters and make sound signals, Racebox works with relays, which are simply switches to turn an electric circuit on and off.

If Racebox recognises that a USB relay controller is plugged in and that the software support is working, the lightning symbol in the top right of the program will not have a line through it. You may still need to set the right driver for your device, even if it can see the active relay, otherwise Racebox might send the wrong commands to it. More on this further down the page.

5 Volts? 250 Volts?

Relays used with Racebox are rated for 5 volts and 250 volts. Typical descriptions say something like: 5v,10A / 250VAC,10A / 30VDC. This is confusing, but what it means is it uses 5 volts to operate the switch and the circuit it controls can be anything up to a 10amp 250 volt (AC) mains circuit. A USB device only uses small voltages, this is why these devices specify 5 volts to turn the switch on or off. Usually Racebox would be controlling a horn system running 12 volt DC currents (and not 250 volt AC mains) as this is typical of automotive devices, so these relays are well within their normal limits. If you are using a 12v airhorn and lights system, a 5v / 12v relay would be sufficient, but the 5v / 250v ones will work as well.

Cables

When testing one of the relays, it did not work at all with the first two USB cables. Behind the scenes, the operating system reported that the relay had connected and then immediately disconnected. With the third cable, it worked well which suggests good quality cables are a wise investment.

Software Required

To install support for a relay it is important to identify what type it is. When you purchase a relay the product description might say it is "driverless" - this is usually a HID relay. If the description talks about serial communications, COM ports, baud rates and AT commands it is likely a serial relay.

Serial Relays

Serial relays communicate with the computer system via a serial port as the name suggests. But these days there isn't a real serial port - they were replaced many years ago by USB sockets (USB stands for universal serial bus). But the way the computer talks to the relay is the same as if the old serial port still existed. So when you plug in one of these relays, the computer sees it as a serial device.

To allow Python to talk to a serial port you must install support by typing:

pip3 install pyserial

(sometimes the command is just pip rather than pip3)

(also you may need to add --break-system-packages as an option at
the end of the pip3 command - it is a long story)

Serial ports on Windows are named COM1, COM2, COM3 etc. On Ubuntu and Debian, they are named /dev/ttyUSB0, /dev/ttyUSB1 etc.

To check which port your device is using and what type it is, in Windows you use the Device Manager and look in the serial ports section. On Ubuntu/Debian you can type sudo dmesg to see what messages were recorded by the system when the relay was plugged in.

To tell Racebox which port to use, add this line to rbconfig.ini (in this case, for COM1) in the Relays section:

serialrelayport = COM1

rbconfig.ini is created in the Racebox folder when the program is first started.

To turn the relay on and off, the computer sends codes to the serial port in a certain order. These codes are stored in Racebox in rbrelayconfig.py in the lib folder, so you do not have to know what they are. But you do have to know what type of serial relay it is.

Relays with a normal USB A connector are usually CH340 or CH341 devices.
Relays that have micro USB connectors are sometimes PL2303 devices.
Relays from KMTronic (FTDI devices) are FT232R devices.

CH340 devices work by default in Racebox (in other words, the serialdriver is assumed to be ch340 if no config is set).

If you have a PL2303 device add this line to rbconfig.ini in the Relays section:

serialdriver = pl2303

and if you have the FT232R device add:

serialdriver = ft232r

Arduino Micro-controllers

A micro-controller is a good choice for interfacing Racebox with a relay. It avoids the platform issues that can be faced using serial and HID USB relays. The controller needs to have an appropriate sketch to interpret the Racebox commands and send the right signal to the relay. But another Rotor-Rig repository on Github already has one you can use here that uses the ABCD protocol which was designed for use with Racebox.

In Racebox, you can specify the "abcd" protocol in rbconfig.ini in the Relays section by using the line

serialdriver = abcd

This sends simple commands to the micro-controller. An A means turn on the first channel and an a means turn off the first channel. A B means turn on the second channel (etc). You can probably set up many different micro-controllers and relays to work with the ABCD protocol, but so far only the Arduino UNO with the 4 Relays Shield has been tested.

Arduinos use serial communications to exchange data with a computer, so you will need to set the correct serial port. The ports mentioned above for serial USB relays are likely to work:

serialrelayport = COM1

in rbconfig.ini in the Relays section (for example) but if you have set up the Arduino and uploaded a sketch to it you will already have set a serial port do that, so the same port should work with Racebox. Just be aware that if you use both the Arduino IDE and Racebox at the same time, your computer may temporarily assign a second COM port to Racebox to avoid a conflict - this can cause confusion!

HID Relays

HID relays do not appear to work reliably with Python on Windows, so at this point they are not supported by Racebox. It may be possible to get the software module to work, but it is not straightforward. Therefore the instructions here relate to Linux systems only.

Racebox supports one commonly found HID relay with a vendor ID (VID) of 16c0 and product ID (PID) of 05df. These sometimes have www.dcttech.com written on the relay.

On Ubuntu and Debian systems, install usbrelay like this:

sudo apt install usbrelay

Installing usbrelay adds required HID libraries and solves some permissions issues on Linux platforms. Typing usbrelay in a terminal session should list your relay if it is plugged in. You can then check the details and check it is supported by Racebox.

You also need to install the Python HID support. In a terminal type:

pip install hid

As only one HID relay is supported, this should now work by default if you plug it in and start Racebox.

These instructions about the HID package may be useful: PyPi HID

To check the setup, plug in your relay and in a command prompt type:

usbrelay

this prints:
Device Found
type: 16c0 05df
path: /dev/hidraw3
serial_number:
Manufacturer: www.dcttech.com
Product: USBRelay2
Release: 100
Interface: 0
Number of Relays = 2
BITFT_1=0
BITFT_2=0

then:

usbrelay BITFT_1=1

turns on the first relay and:

usbrelay BITFT_1=0

turns it off.

NB usbrelay does not show information for USB serial relays, only HID.

To work on Linux the user must be in the dialout group
(some docs also suggest plugdev) - you may already have this permission
but if not:

sudo usermod -a -G dialout myusername