diff --git a/README.md b/README.md index c2b64da..2412aa6 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # crelay #### Controlling different relay cards for home automation with a Linux software -### About -This software is intended to run on Linux systems to control different relay cards in a unified way. It provides several interfaces for controlling the relays locally or remotely. The relays can be controlled by a human being via a device like smartphone or web browser, or directly by an intelligent device as used in the Internet of Things. +### About +Ever bougth 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 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, 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 @@ -14,13 +16,14 @@ The software was designed with the following requirements in mind: 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 (http://www.conrad.de/ce/de/product/393905), see Note 1 below -- Sainsmart USB 4-channel relay card (http://www.sainsmart.com/sainsmart-4-channel-5v-usb-relay-board-module-controller-for-automation-robotics.html), see Note 2 below -- HID API compatible relay cards (1/2/4/8 channel) +- [Conrad USB 4-channel relay card](http://www.conrad.de/ce/de/product/393905), see Note 1 below +- [Sainsmart USB 4/8-channel relay card](http://www.sainsmart.com/sainsmart-4-channel-5v-usb-relay-board-module-controller-for-automation-robotics.html), see Note 2 below +- [HID API compatible relay cards (1/2/4/8 channel)](http://www.ebay.com/itm/For-Smart-Home-5V-USB-Relay-2-Channel-Programmable-Computer-Control-/190950124351) - Generic GPIO controlled relays, see Note 3 below
The following picture shows a high level view on the modular software architecture. + ![Software architechture](screenshots/sw-architecture.png)

@@ -36,6 +39,7 @@ The following picture shows a high level view on the modular software architectu
### Nice to have (wishlist) +- Integrated MQTT client - ThingSpeak Talkback App (https://thingspeak.com/docs/talkback) - Multiple cards support - Access control for Web GUI and HTTP API @@ -45,9 +49,10 @@ The following picture shows a high level view on the modular software architectu ### Screenshots #### Web GUI -![Screenshot](screenshots/crelay-screenshot1.png) -

-![Screenshot](screenshots/crelay-screenshot2.png) +![Screenshot](screenshots/crelay-screenshot1.png "Web GUI with Conrad card connected") +
+---------- +![Screenshot](screenshots/crelay-screenshot2.png "Web GUI with GPIO relays connected")

#### Command line interface @@ -58,8 +63,8 @@ The following picture shows a high level view on the modular software architectu Currently supported relay cards: - Conrad USB 4-channel relay card - Sainsmart USB 4-channel relay card - - Generic GPIO relays - HID API compatible relay card + - Generic GPIO relays The card which is detected first will be used. The program can be run in interactive (command line) mode or in daemon mode with @@ -90,7 +95,8 @@ The following picture shows a high level view on the modular software architectu
### HTTP API -An HTTP API is provided to access the server from external clients. This API is compatible with the PiRelay Android app. Therefore this app can be used on your Android phone to control crelay remotely. +An HTTP API is provided to access the server from external clients. This API is compatible with the PiRelay Android app. Therefore this app can be used on your Android phone to control crelay remotely. +I am considering to add a more universally usable Json format based API in the future. - API url: 
ip_address[:port]/gpio
@@ -151,17 +157,31 @@ On some not so recent Linux distributions (like Debian Weezy) the HIDAPI library 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. +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. +
### Installation of prebuilt binaries -To save you the hassle of building crelay from source, prebuild binaries are provided for selected architectures. Just save the binary from the bin/ directory on your host system and execute it. +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](https://github.com/ondrej1024/crelay/releases/latest). 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
+
+ +### Distribution specific packages +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_.ipk + +If anyone wants to build packages for other Linux distributions, please feel free to do so and share it here. + +
+ ### Configuration 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. @@ -216,16 +236,27 @@ The modular architecture of *crelay* makes it possible to easily add new relay c 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.
+### Credits +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é](https://github.com/dsacre) who discovered the communication protocol of the Conrad card +* [Darryl Bond](https://github.com/darrylb123), who discovered the communication protocol of the HID API cards +* User stav from the RPi forum, who discovered the communication protocol of the Sainsmart card + +
+ +### Notes + ##### Note 1 (Conrad USB 4-channel relay card): 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 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.
-##### Note 2 (Sainsmart USB 4-channel relay card): +##### Note 2 (Sainsmart USB 4/8-channel relay card): 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 @@ -237,4 +268,4 @@ To prevent automatic loading of the driver, add the following line to /etc/modpr
##### Note 3 (GPIO controlled relays): -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. +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. diff --git a/bin/armv6/crelay b/bin/armv6/crelay deleted file mode 100755 index cfe0325..0000000 Binary files a/bin/armv6/crelay and /dev/null differ diff --git a/bin/x86_64/crelay b/bin/x86_64/crelay deleted file mode 100755 index efb73bb..0000000 Binary files a/bin/x86_64/crelay and /dev/null differ