Control External Equipment with a Raspberry Pi and USB Relay Board

Tokyo Devices USB relay boards make it easy to switch relays on and off from a Raspberry Pi over USB.

This guide covers the TDFA30301, TDFA30303, and IWT313-USB. You’ll install the TD-USB command-line utility on Raspberry Pi OS and write a Python script that toggles a relay once per second.

By the end, you should be able to hear the relay clicking on and off.

1. Choosing a USB Relay Board

All three boards can be controlled by passing a numeric relay state to the TD-USB utility. The main differences are the number of relay channels, contact rating, and power requirements.

The TDFA30301 uses 0 or 1 to control its single relay.

The TDFA30303 and IWT313-USB use a bitmask, with each bit representing one relay channel. For example:

• 1 turns on channel 1 only.
• 3 is 11 in binary, so it turns on channels 1 and 2.
• 0 turns off all channels.

2. What You’ll Need

The TDFA30301 and TDFA30303 are powered directly over USB. The IWT313-USB requires a separate 12 V power supply, such as an AC adapter or a general-purpose regulated 12 V supply.

3. Install the Required Tools

Run the following commands on your Raspberry Pi to install the packages required to build TD-USB:

sudo apt update
sudo apt install -y git build-essential libusb-dev python3

These packages provide:

• git for downloading the source code
• build-essential for compiling TD-USB
• libusb-dev for communicating with USB devices
• python3 for running the example script

4. Configure USB Device Permissions

Add a udev rule so that TD-USB can access the relay board without requiring root privileges.

The following configuration supports all three boards:

sudo tee /etc/udev/rules.d/99-usb-tokyodevices.rules <<'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="32ee", ATTR{idProduct}=="1786", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="32ee", ATTR{idProduct}=="1787", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="16c0", ATTR{idProduct}=="05df", MODE="0666"
EOF

Reload the udev rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

Disconnect and reconnect the USB relay board after applying the new rules.

If you are using the IWT313-USB, connect a 12 V AC adapter or another suitable 12 V power supply to its power input terminals.

5. Build the TD-USB Utility

Clone the TD-USB repository from GitHub and build it on the Raspberry Pi:

git clone https://github.com/tokyodevices/td-usb.git
cd td-usb
make

Run the utility without any arguments to verify that the build succeeded:

./td-usb

If the command displays version or usage information, TD-USB is ready to use.

6. Test the Relay from the Command Line

Before writing any Python code, confirm that you can control the relay directly with TD-USB.

Run the commands for your board model.

TDFA30301

./td-usb tdfa30301 set 1
./td-usb tdfa30301 get
./td-usb tdfa30301 set 0

TDFA30303

./td-usb tdfa30303 set 1
./td-usb tdfa30303 get
./td-usb tdfa30303 set 0

IWT313-USB

./td-usb iwt313 set 1
./td-usb iwt313 get
./td-usb iwt313 set 0

The set 1 command turns on relay channel 1, while set 0 turns off all channels. The get command prints the current relay state as a number.

7. Toggle the Relay Every Second with Python

Now let’s call TD-USB from Python and toggle relay channel 1 once per second.

Create a file named blink_relay.py inside the td-usb directory. Enable only the MODEL line that corresponds to your board:

#!/usr/bin/env python3
import subprocess
import time

# Enable exactly one line for the board you are using.
MODEL = "tdfa30301"   # TDFA30301
# MODEL = "tdfa30303" # TDFA30303
# MODEL = "iwt313"    # IWT313-USB

try:
    while True:
        subprocess.run(["./td-usb", MODEL, "set", "1"], check=True)
        print("ON")
        time.sleep(1)

        subprocess.run(["./td-usb", MODEL, "set", "0"], check=True)
        print("OFF")
        time.sleep(1)

except KeyboardInterrupt:
    subprocess.run(["./td-usb", MODEL, "set", "0"], check=True)
    print("\nRelay turned off. Exiting.")

Make the script executable:

chmod +x blink_relay.py

Then run it:

./blink_relay.py

If everything is working correctly, the relay will alternate between on and off once per second.

Press Ctrl+C to stop the script. The interrupt handler turns the relay off before the program exits.

Summary

• The TDFA30301, TDFA30303, and IWT313-USB can all be controlled with the TD-USB command-line utility.
• On Raspberry Pi OS, you first need to configure USB permissions and build TD-USB from source.
• Python can control the relays by invoking ./td-usb with subprocess.run().

Test the relay without a connected load first. Before connecting real equipment, consult the product manual and verify the contact rating, wiring requirements, and applicable electrical safety precautions.