A web server to control relays
This is a web server designed to provide access to a relay board. This project depends on echttp and houseportal.
See the gallery for a view of HouseRelays's web UI.
The primary intent is to support a distributed network of relay boards, to avoid pulling electric wires from one side of the home to the other: a small set of relay boards is installed, each board located close to existing wiring or near the equipment to control. Each relay board is attached to a small computer (e.g. Raspberry Pi Zero W). The typical use is to control sprinklers, a garage door, etc. By using such a micro-service architecture, the application may run anywhere in the home and still access all the devices, regardless of their locations.
The secondary intent is to share a relay board between multiple independent applications: sprinkler system, garage door controller, etc. Each application controls only those devices that it is configured for. A gear configuration attribute allows an application to select which points it wants to control.
A third intent is to share access to digital inputs, e.g. reed relay status. Since the overhead of web polling is relatively high and the timing of HTTP requests is not really accurate, this server stores a limited history of input changes, which clients can access at a lower rate. The sampling rate of inputs is typically 100ms and about 6 seconds worth of the most recent changes is kept available. Since these are input points, multiple applications may access them simultanously.
This way relay boards may be installed at convenient points across the home, and be accessed by separate applications independently of the relays or applications physical locations.
- Install the OpenSSL development package(s).
- Install echttp.
- Install houseportal.
- Clone this GitHub repository.
- make
- sudo make install
- Edit /etc/house/relays.json (see below)
The typical hardware supported by this applications are relay boards controlled through 5V TTL digital pins. These are wired to the digital I/O pins of a Raspberry Pi, Odroid or other small Linux computers. Depending on the model, these board are either controlled using open-drain outputs (active low) or 3-state outputs (active high).
The hardware interface is configured through the HouseDepot file "/relays.json", or through the local file /etc/house/relays.json if local storage is enabled.
Note
The group name is not used for HouseDepot. This is because the relays interface is different for each computer: which configuration to load depends on the name of the computer that this service is running on.
A typical exemple of configuration is:
{
"relays" : {
"iochip" : 0,
"points" : [
{
"name" : "relay1",
"gpio" : 4,
"mode" : "output",
"on" : 0,
"gear" : "valve",
"pulse" : 700,
"connection" : 1,
"description": "Relay 1"
},
{
"name" : "relay2",
"gpio" : 17,
"mode" : "output",
"on" : 0,
"gear" : "valve",
"connection" : 2,
"description": "Relay 2"
}
]
}
}
The iochip item must match the Linux gpiod chip index. The gpio item must match the gpiod line offset (this also matches the usual Raspberry Pi naming convention for I/O pin names, e.g. GPIO4, GPIO17).
The mode can be input or output. If the item is missing, the mode defaults to output. All control requests that target an input point are ignored.
If on is 0, the point is configured as open-drain with pull-up enabled, the on command sets the output to 0, and the off command sets the output to 1.
If on is 1, an output point is configured as push-pull, the on command sets the output to 1, and the off command sets the output to 0.
The gear attribute can be used by applications to filter which control points to show on their user interface. Typical values are valve (irrigation) and light.
The pulse attribute is optional. If present, it represents a duration in milliseconds and sets a limit to how long the control may be maintained active (regardless of the request). The intent of this attribute is to protect gears that would be damaged if maintained active for an excessive duration, for example a coil under high current. If this attribute is set, any request with no pulse, or with a pulse value greater than this limit, with be silently interpreted as a request with this pulse limit's duration.
This pulse limit is not exact as it is sensitive to the polling period, and that polling period depends on the requested accuracy. As a general rule, a limit in thousands of milliseconds should be set to 1 second less than the actual gear limit, a limit in hundreds of milliseconds should be set to 50 milliseconds less than the actual gear limit, and any more precise limit should be set to 10 milliseconds less than the actual gear limit. for example a pulse limit of 6000 milliseconds may cause an actual pulse anywhere between 5 and 7 seconds, while a pulse limit of 6001 milliseconds may produce an actual pulse anywhere between 5991 and 6011 milliseconds.
Warning
There are ways to overcome this protection mechanism, for example by repeating the request at a high frequency. Use common sense.
The connection and description items are informational. The connection item can be used to match the markings on the relays motherboard. The description item can be used to store any useful comment about this point's purpose or special properties.
This program implements the House control API, including the sequence of changes extension.
The server is also capable of serving static pages, location in /usr/share/house/public/relays. The URL of each page must start with /relays.
The Linux kernel supports declaring fake GPIO that can be controlled by test scripts. There are two such GPIO simulators: gpio-mockup and gpio-sim. Both work by declaring an additional GPIO chip. In order to simplify testing with such a simulator without tinkering with the configuration, HouseRelay supports a --chip=N command line option that superseeds the relays.iochip item in the configuration.
For example, if the gpio-mockup module was loaded and created device /dev/gpiochip2, then the following command forces HouseRelay to interface with the gpio-mockup GPIO pins:
houserelays --chip=2
GPIO pins 0 and 1 may not be accessible, as they might be already used depending on the system configuration. Use gpioinfo to check the status of the GPIO pins.
The provided Makefile supports building private Debian packages. These are not official packages:
-
They do not follow all Debian policies.
-
They are not built using Debian standard conventions and tools.
-
The packaging is not separate from the upstream sources, and there is no source package.
To build a Debian package, use the debian-package target:
make debian-package