Ever bought a cute little USB relay card and wanted to use it on a Linux based device or computer? Chances are that your were out of luck because the Linux software support for the card provided by the manufacturer was non existent. Conrad, Sainsmart, Denkovi and friends are still completely ignoring the existence of this operating system. That's why I started this project.
This software is intended to run on Linux systems to control USB relay cards from different manufacturers in a unified way. It provides several interfaces for controlling the relays locally or remotely via the network. The relays can be controlled by a human being via a device like smartphone or web browser, via a cloud service (e.g. IFTTT), or directly by an intelligent device as used in the Internet of Things.
The software was designed with the following requirements in mind:
- simple, intuitive usage and interface
- as little dependencies as possible (libraries, drivers, external programs)
- runs on a variety of Linux distributions, different hardware platforms
- lightweight, can run on simple devices
- easily expandable (adding relay card types and user interfaces)
New relay cards support can be added by providing the cards driver code for detecting the card, reading and setting the relays. Currently the following relay cards are supported:
- Conrad USB 4-channel relay card, see Note 1 below
- Sainsmart USB 4/8-channel relay card, see Note 2 below
- HID API compatible relay cards (1/2/4/8 channel)
- Sainsmart USB 16-channel relay control module
- Generic GPIO controlled relays, see Note 3 below
The used relay card is automatically detected. No complicated port or communication parameter settings required. Just plug in your card and play.
The following picture shows a high level view on the modular software architecture.
- Command line mode and daemon mode with Web GUI
- Automatic detection of relay card
- Reading of current relay states
- Setting of new relay states
- Single pulse generation on relay contact
- HTTP API for external clients (e.g. Smartphone/tablet apps)
- Multiple relay card type support
- Support for configuration file with custom parameters
- Multiple cards support (command line interface and HTTP API)
- IFTTT support (see tutorial)
- Integrated MQTT client (work in progress)
- Multiple cards support for Web GUI
- JSON format HTTP API
- Access control for Web GUI and HTTP API
- Programmable timers for relay actions
This is the Web GUI provided by the integrated web server. The web page dynamically adapts to the detected relay card as shown.
$ crelay
crelay, version 0.14
This utility provides a unified way of controlling different types of relay cards.
Currently supported relay cards:
- Conrad USB 4-channel relay card
- Sainsmart USB 4/8-channel relay card
- HID API compatible relay card
- Sainsmart USB-HID 16-channel relay card
- Generic GPIO relays
The card which is detected first will be used, unless -s switch and a serial number is passed.
The program can be run in interactive (command line) mode or in daemon mode with
built-in web server.
Interactive mode:
crelay [-s <serial number>] -i | [<relay number>] [ON|OFF]
The state of any relay can be read or it can be changed to a new state.
If only the relay number is provided then the current state is returned,
otherwise the relays state is set to the new value provided as second parameter.
The USB communication port is auto detected. The first compatible device
found will be used, unless -s switch and a serial number is passed.
Daemon mode:
crelay -d [<relay1_label> [<relay2_label> [<relay3_label> [<relay4_label>]]]]
In daemon mode the built-in web server will be started and the relays
can be completely controlled via a Web browser GUI or HTTP API.
Optionally a personal label for each relay can be supplied which will
be displayed next to the relay name on the web page.
To access the web interface point your Web browser to the following address:
http://<my-ip-address>:8000
To use the HTTP API send a POST or GET request from the client to this URL:
http://<my-ip-address>:8000/gpio
An HTTP API is provided to access the server from external clients. This API is compatible with the PiRelay Android app. Therefore the app can be used on your Android phone to control crelay remotely.
Additionally to the existing API a universal Json format based API should be imlpemented. This would make it easier for third party clients to send API requests and parse the response. Any volunteer who wants to contribute is very welcome.
- API url:
ip_address[:port]/gpio
- Method:
POST or GET
-
Reading relay states
Required Parameter: none -
Setting relay state
Required Parameter:pin=[1|2|3 ...], status=[0|1|2] where 0=off 1=on 2=pulse
Optional Parameter:serial=serial_number
-
Response from server:
Relay 1:[0|1] Relay 2:[0|1] Relay 3:[0|1] Relay 4:[0|1]
The installation procedure is usually perfomed directly on the target system. Therefore a C compiler and friends should already be installed. Otherwise a cross compilation environment needs to be setup on a PC (this is not described here).
- Install dependencies (package names may vary depending on your distribution):
If you have a Debian, Ubuntu or derivative distribution:
apt-get install libftdi1 libftdi-dev libhidapi-libusb0 libhidapi-dev libusb-1.0-0 libusb-1.0-0-dev
If you have OpenSUSE or a derivative distribution:
zypper install libftdi1-devel libftdi0-devel libhidapi-libusb0 libhidapi-devel libusb-1_0-devel libusb-1_0-0 libftdi1 libftdi1-2
- Build dependencies from source (optional):
On some not so recent Linux distributions (like Debian Weezy) the HIDAPI library is not yet packaged, so it needs to be build from the source code. Follow these instructions to do that:
apt-get install libudev-dev libusb-1.0-0-dev
git clone git://github.com/signal11/hidapi.git
./bootstrap
./configure
make
sudo make install
- Clone crelay git repository :
git clone https://github.com/ondrej1024/crelay
cd crelay
- Alternatively get latest source code version :
wget https://github.com/ondrej1024/crelay/archive/master.zip
unzip master.zip
cd crelay-master
- Build and install :
cd src
make [DRV_CONRAD=n] [DRV_SAINSMART=n] [DRV_HIDAPI=n]
sudo make install
Note: Optionally, you can exclude specific relay card drivers (and their dependencies) from the build, if you don't need them. To do this, specify the driver name as parameter of the "make" command as shown above.
To save you the hassle of building crelay from source, prebuild binaries are provided for selected architectures. Just save the binary for your architecture on your host system and execute it.
The binaries can be downloaded from the Latest release page.
Note: The binaries use shared librabries, so you might need to install the needed libs to your system, if not already done previously:
apt-get install libftdi1 libhidapi-libusb0 libusb-1.0-0
Currently, there are official OpenWRT packages available for different architectures from the developement snapshot repositories. They can be downloaded here:
https://downloads.openwrt.org/snapshots/trunk/[arch]/generic/packages/packages/crelay<ver>_<arch>.ipk
If anyone wants to build packages for other Linux distributions, please feel free to do so and share it here.
When running in daemon mode. the parameters for crelay can be customized via the configuration file crelay.conf which should be placed in the /etc/ system folder. An example file is provided together with the programs source code in the conf/ folder.
################################################
#
# crelay config file
#
# This file is read by crelay in daemon mode
# from /etc/crelay.conf
#
################################################
# HTTP server parameters
################################################
[HTTP server]
server_iface = 0.0.0.0 # listen interface IP address
#server_iface = 127.0.0.1 # to listen on localhost only
server_port = 8000 # listen port
relay1_label = Device 1 # label for relay 1
relay2_label = Device 2 # label for relay 2
relay3_label = Device 3 # label for relay 3
relay4_label = Device 4 # label for relay 4
relay5_label = Device 5 # label for relay 5
relay6_label = Device 6 # label for relay 6
relay7_label = Device 7 # label for relay 7
relay8_label = Device 8 # label for relay 8
# GPIO driver parameters
################################################
[GPIO drv]
#num_relays = 8 # Number of GPIOs connected to relays (1 to 8)
#active_value = 1 # 1: active high, 0 active low
#relay1_gpio_pin = 17 # GPIO pin for relay 1 (17 for RPi GPIO0)
#relay2_gpio_pin = 18 # GPIO pin for relay 2 (18 for RPi GPIO1)
#relay3_gpio_pin = 27 # GPIO pin for relay 3 (27 for RPi GPIO2)
#relay4_gpio_pin = 22 # GPIO pin for relay 4 (22 for RPi GPIO3)
#relay5_gpio_pin = 23 # GPIO pin for relay 5 (23 for RPi GPIO4)
#relay6_gpio_pin = 24 # GPIO pin for relay 6 (24 for RPi GPIO5)
#relay7_gpio_pin = 25 # GPIO pin for relay 7 (25 for RPi GPIO6)
#relay8_gpio_pin = 4 # GPIO pin for relay 8 ( 4 for RPi GPIO7)
# Sainsmart driver parameters
################################################
[Sainsmart drv]
num_relays = 4 # Number of relays on the Sainsmart card (4 or 8)
The modular architecture of crelay makes it possible to easily add new relay card drivers.
See example files relay_drv_sample.c and relay_drv_sample.h in the src directory for details on how to write your own low level driver functions.
In order to start crelay as daemon automatically on system boot it can be configured as systemd service. The service file is provided here:
systemd/crelay.service
To enable the service, run the following commands:
cp systemd/crelay.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable crelay.service
Start/stop the service manually with these commands:
systemctl start crelay.service
systemctl stop crelay.service
The support for the different relay cards in crelay has only been possible thanks to the valuable contributions of the following people who reverse engineered the communication protocols of the cards and provided the protocol specifications.
-
Dominic Sacré who discovered the communication protocol of the Conrad USB card
-
Darryl Bond, who discovered the communication protocol of the HID API cards
-
Steve Crow, who discovered the communication protocol of the Sainsmart USB cards
-
Kevin Hilman, who implemented and tested the support for the Sainsmart 16-channel control module
-
Andrew Lunn, who contributed cleanup patches
-
Andrey Shevtsov, who contributed the initial multiple cards implementation
-
Alberto Bursi, who contributed documentation for OpenSUSE build support
-
Derek Atkins, who contributed multiple cards handling for the Sainsmart 16 Channel HID controller and HTTP API
-
Paweł Dembicki, who contributed to the GPIO driver
The relay card software provided by Conrad is Windows only and uses a binary runtime DLL which implements the communication protocol between the host computer and the card. Thanks to a raspberrypi.org forum member, the communication protocol was discovered and made public. This made it possible to develop an open source driver for the Conrad card which can run on any Linux distribution.
Earlier versions of this program needed the cp210x kernel driver for the Silabs CP2104 chip with GPIO support. The official in-kernel cp210x driver does not support GPIO operations. Therefore the Silabs driver from their home page needed to be used: http://www.silabs.com/products/mcu/pages/usbtouartbridgevcpdrivers.aspx
The current version of crelay uses libusb to talk directly to the CP2104 on the Conrad card, therefore the cp210x kernel driver is not needed anymore.
The Sainsmart card uses the FTDI FT245RL chip. This chip is controlled directly through the open source libFTDI library. No Kernel driver is needed. However on most Linux distributions, the ftdi_sio serial driver is automatically loaded when the FT245RL chip is detected. In order to grant the crelay software access to the card, the default driver needs to be unloaded:
rmmod ftdi_sio
To prevent automatic loading of the driver, add the following line to /etc/modprobe.d/blacklist.conf:
blacklist ftdi_sio
Both 4 and 8 channel versions are supported. However, there seems to be no way to automatically detect which version of the card is used. Therefore the number of relay channles can be configured in the configuration file.
Since GPIO pin configuration is strictly device specific, the generic GPIO mode is disabled by default and can only be used in daemon mode. In order to enable it, the specific GPIO pins used as relay control lines have to be specified in the configuration file, [GPIO drv] section.