Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
U

usbrelay

> 编程语言
Open source

Control usb relay - based on hidapi

365 stars0 likes0 views
WebsiteGitHub

About

Control usb relay - based on hidapi

USB Relay Driver For Linux

A cheap USB relay available from Ebay with 1,2,4 or 8 relay output. The double throw relay ratings are 10A 250VAC each.

The USB device is HID compatible and comes with Windows control software. This code can control the relay vi HIDAPI which is a cross platform library. This code was tested under linux both on x86 and Raspberry Pi ARM. The program is command line only as it is likely to be used by shell scripts.

The output of lsusb for the device is:

…

HIDAPI

http://www.signal11.us/oss/hidapi

HIDAPI is a fairly recent addition to linux and is available as a package for Fedora 20 but not for Pidora (F18). The package was built for Pidora (Fedora 18) using the F20 hidapi source package.

Installing Debian Packages:

This code is a maintained package in Debian (and Raspian). Use normal apt-get commands:

$ sudo apt-get install usbrelay

Installing Fedora Packages:

The packages are available in Fedora36+

$ sudo dnf install usbrelay-common python3-usbrelay usbrelay-mqtt

Other Linux platforms will need to build the source, see below

Protocol:

The relay modules does not set the USB serial number but has a unique serial when the HID device is queried, the current state of the relays is also sent with the serial. The HID serial is matched and the ON/OFF command is sent to the chosen relay.

Building The Code:

The usual make, make install dance assuming the hidapi and hidapi-devel packages have been installed. Note that there are two options for the hidapi library: hidapi-hidraw or hidapi-libusb. Different distributions have better results with one or the other. YMMV.

$ sudo apt-get install libhidapi-dev libhidapi-hidraw0 git 
$ git clone https://github.com/darrylb123/usbrelay
$ cd usbrelay
$ make
$ sudo make install

### Test with a usbrelay plugged in
$ sudo usbrelay

### Build the python interface using the instructions below

To choose the alternative hidapi libraries, add the option to the make command line

### hidapi-hidraw - This is the default if no option is given
$ make HIDAPI=hidraw
### hidapi-libusb
$ make HIDAPI=libusb

Docker Build:

You can also build using Docker. Assuming you have Docker installed (only tested with version 18), execute the build script:

$ ./build.sh

The usbrelay binary, libusbrelay.so and libusbrelay_py.so libraries will be built in the root directory of the repo.

Usage:

The code needs to access the device. This can be achieved either by running the program with root privileges (so sudo is your friend) or by copying 50-usbrelay.rules to /etc/udev/rules.d, note Debian derivatives have a group 'plugdev' designed for this function. Edit 50-usbrelay.rules and substitute GROUP="plugdev" for GROUP="usbrelay"

$ sudo cp 50-usbrelay.rules /etc/udev/rules.d
$ sudo udevadm control -R

Add users that need to operate the relays to the usbrelay group

Fedora:

bash
sudo usermod -a -G usbrelay 

Debian/Ubuntu:

bash
sudo usermod -a -G plugdev 
$ sudo usbrelay --help
Usage: usbrelay [OPTION...] [ACTION...]
Control or query USB HID relays.

  -d, --debug                Produce debugging output
  -q, --quiet                Be quiet
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Without ACTION, the actual state of all relays is printed to stdout.
ACTION can be one of:
RELID_N=[0|1] to switch the N-th relay off or on
RELID=NEWID to change relay ID

Report bugs to https://github.com/darrylb123/usbrelay/issues.

Running the program without arguments will display each module that matches device 16c0:05df or 0519:2018. The program can be invoked with the debug (-d) or quiet (-q) flags. The debug information is sent to stderr while the state is sent to stdout for use in scripts. The only limit to the number of these relays that can be plugged in and operated at once is the number of USB ports. Using neither the -d or -q flags just prints the state of the relays to stdout.

$ sudo usbrelay
PSUIS_1=1
PSUIS_2=0
$ sudo usbrelay -d (--debug)
Device Found
  type: 16c0 05df
  path: /dev/hidraw1
  serial_number: PSUIS
  Manufacturer: www.dcttech.com
  Product:      USBRelay2
  Release:      100
  Interface:    0
PSUIS_1=1
PSUIS_2=0
$ sudo usbrelay -q (--quiet)
$

To get the relay state

$ sudo usbrelay
PSUIS_1=1
PSUIS_2=0

To use the state in a script:

$ eval $(sudo usbrelay)
$ echo $PSUIS_2
0

To set the relay state of 1 or more modules at once:

$ sudo usbrelay PSUIS_2=0
$ sudo usbrelay PSUIS_2=1 PSUIS_1=0
$ sudo usbrelay PSUIS_2=0 PSUIS_1=1 0U70M_1=0 0U70M_2=1

Operate relay 9 to set the state of all relays together

$ sudo usbrelay PSUIS_9=0
$ sudo usbrelay PSUIS_9=1 0U70M_9=1

The path to a device can be used in lieu of the serial, this can be useful for devices with corrupted serials

$ sudo usbrelay /dev/hidraw1_1=0

Alternatively if using libusb instead of hidraw you may use the usb device path

Device Found
  type: 0519 2018
  path: 0001:0015:00
  serial_number: A0001
Manufacturer: Ucreatefun.com
  Product:      HIDRelay
  Release:      1
  Interface:    0
  Number of Relays = 9
  Module_type = 2

$ sudo usbrelay 0001:0015:00_1=0

Change the serial permanently

Use the fictitious relay 0 to set the serial permanently. If you have duplicate serials, make sure only one is plugged in when you change it. Maximum of 5 character serial (A-Z0-9 only). It is probably sensible to change one module at a time to avoid serial collisions. If the serial contains characters that are not A-Z0-9 and therefore an illegal ID, you may also use the device path to set the serial as above

$ sudo usbrelay
ZXCV_1=0
ZXCV_2=0

$ sudo usbrelay ZXCV_0=ZAQ12 
( or sudo usbrelay /dev/hidraw4_0=ZAQ12 )
ZXCV_1=0
ZXCV_2=0
Setting new serial

$ sudo usbrelay
ZAQ12_1=0
ZAQ12_2=0

Python Extension:

This also optionally includes a python extension. In order to build the python extension, you must have the Python 3 development libraries installed. The docker build process will produce the python library as well.

Debian:

##Install Python3 dev package
# sudo apt install libpython3-dev python3-venv pip
# sudo pip install build

Fedora:

##Install Python3 dev package
# sudo dnf install python3-devel
# sudo dnf install python3-build

With the dependency installed, the library can be built and installed with:

##Build libusbrelay_py.so
$ cd usbrelay_py
$ make
##Install to global python
$ sudo make install

Once installed, the library can be used by any python script, assuming it is running as a user with suitable permissions per the changes to udev above.

The following is a test script included as tests/usbrelay_test.py, showing how to use the library:

…

Any

MQTT support

MQTT support requires the successful installation of the python library described above. Check this first (with a module plugged in) by running:

bash
sudo python3 test.py

MQTT support provides capability of using Home Assistant or nodered with usbrelay. The capability is made up of:

  • usbrelayd
  • usbrelay.service
  • usbrelayd.conf

usbrelayd

A python daemon using libusbrelay to connect to an MQTT server. When the daemon starts, it publishes the state of all usbrelay devices found and subscribes to command topics for each relay. To install:

Debian

bash
sudo apt-get install python3-paho-mqtt
sudo cp usbrelayd /usr/sbin
sudo cp usbrelayd.conf /etc/usbrelayd.conf

Fedora

bash
sudo useradd usbrelay
sudo dnf install python3-paho-mqtt
sudo cp usbrelayd /usr/sbin
sudo cp usbrelayd.conf /etc/usbrelayd.conf

Modify /etc/usbrelayd.conf to suit your circumstances.

usbrelay.service

A systemd unit for controlling and monitoring the usbrelayd daemon. The file comes configured for Fedora and needs to be modified for Debian.

Debian

Edit usbrelayd.service and change

SupplementaryGroups=usbrelay

to

SupplementaryGroups=plugdev

To install:

bash
sudo cp usbrelayd.service /etc/systemd/system
sudo systemctl daemon-reload

50-usbrelay.rules

A udev rule file that reacts and starts/stops the usbrelayd.service when a module is pluggedin or removed. The file should be installed with the initial installation. The file comes configured for Fedora and needs to be modified for Debian.

Debian

Edit 50-usbrelay.rules and change

GROUP="usbrelay"

to

GROUP="plugdev"

To install:

bash
sudo cp 50-usbrelay.rules /etc/udev/rules.d
sudo udevadm control -R

Operation

After installation and configuration confirm the correct operation.

…

MQTT Topics for controlling usbrelays

  • Current state: stat/SERIAL/Relay (eg stat/OMG12/1 )
  • Command: cmnd/SERIAL/Relay ON/OFF (eg cmnd/OMG12/2 )

Using mosquitto client tools

mosquitto_sub -h your_mqtt_broker -t stat/OMG12/1
mosquitto_pub -h your_mqtt_broker -t cmnd/OMG12/1 -m ON
 

Home Assistant Auto Configuration

The usbrelayd mqtt daemon can register all it's connected relay modules with Home Assistant.

Add the topic name that your instance of HomeAssistant is configured to listen for in /etc/usbrelayd.conf

[HOMEASSISTANT]
# Set this to get usbrelayd to publish the relays with HomeAssistant's
# discovery protocol.
# The default value for HA is "homeassistant"
TOPIC = homeassistant

Each relay module will register as a device under the MQTT integration in HomeAssistant with a switch for each relay. This only really works well for dcttech relays which can read the relay state.

Running usbrelayd in docker

Build the image

bash
git clone https://github.com/darrylb123/usbrelay.git
cd usbrelay
docker build -f Dockerfile.usbrelayd -t usbrelayd .

Run the docker container

Note the container needs to run in privileged mode to access the USB device. The default usbrelayd.conf requires a your mqtt broker to have the hostname 'mqtt',substitute an alternative usbrelay.conf file

bash
docker run --rm -it --privileged -v "/path/to/myusbrelayd.conf":/etc/usbrelayd.conf usbrelayd

To make the usbrelayd container start on boot and restart on failure

bash
docker run -d --restart unless-stopped --privileged -v "/path/to/myusbrelayd.conf":/etc/usbrelayd.conf usbrelayd

Enjoy

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

C

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言