Heyu
Heyu Overview
Description
Heyu is a driver and control program for managing Power Line Interface Modules such as those made by X10. This program is only useful if you have such a module connected to your server. Note that while there are alpha level quality drivers for the USB versions (e.g. CM15) the drivers and links below relate to the serial port versions (such as the CM11a).
This How-to describes the installation of heyu only on SME Server. Please refer to Heyu's product and help pages for operation.
Links
Heyu home page
Optional Frontends:
http://heyu.tanj.com/heyu_links.html
Neil Cherry's Home Automation website contains a wealth of information about X10 and newer automation technologies.
Installation Procedures
Obtaining the software
The software is available only in source form from: http://heyu.tanj.com/download/
create and go into a temporary directory to work with the files and download the latest version. For example:
wget http://heyu.tanj.com/download/heyu-2.3.2.tgz
Expand the software:
tar xvzf heyu-2.3.2.tgz
Enter the newly created directory (in this case heyu-2.3.2).
Installation
Heyu needs to be compiled and installed to work thus you will need to temporarily install gcc.
yum install gcc ./Configure make make install
You will be asked for the serial port of your PLC module (e.g. my CM11a is on /dev/ttyS5).
When asked, you should choose to put the x10.conf file into /etc/heyu. This will also serve as your "basedir" for state and schedule files used by heyu.
The binary should have the path /usr/local/bin/heyu.
man pages will also be installed.
Now let's clean up. You can remove the temporary directory where you created and compiled the heyu program.
You should also remove gcc:
Configuring to start Automatically
Depending on how you plan to use Heyu, you may wish to have it start automatically on reboot. This would be necessary for example if you wish it to run scheduled timers.
Tell heyu to start the heyu engine automatically on a start command by editing /etc/heyu/x10.conf and adding the line:
START_ENGINE AUTO
Let's make sure it starts if and when we reboot.
db configuration set heyu service status enabled ln -s /etc/rc.d/init.d/e-smith-service /etc/rc.d/rc7.d/S99heyu
You will also need to create a start up script /etc/init.d/heyu:
#! /bin/sh
# Start script for Heyu (X10) communication process
HEYU_BIN=/usr/local/bin/heyu
# Source function library
. /etc/rc.d/init.d/functions
RETVAL=0
prog=heyu
case "$1" in
start)
echo -n $"Starting $prog: "
daemon $HEYU_BIN start
touch /var/lock/subsys/heyu
echo
exit 0
;;
stop)
echo -n $"Shutting down $prog: "
killproc $HEYU_BIN
rm -f /var/lock/subsys/heyu
echo
;;
reload)
echo -n $"Reloading $prog daemon configuration: "
$HEYU_BIN restart
RETVAL=$?
echo
;;
restart)
$0 stop
$0 start
;;
status)
status $prog
;;
*)
echo $"Usage: $0 {start|stop|reload|restart|status}"
RETVAL=1
esac
exit $RETVAL
Initial Configuration
Don't forget to edit the /etc/heyu/x10.conf file to update things like your longitude and latitude and other useful settings.
Note that any changes made to x10.conf need to be re-read by heyu. The simplest way is to issue the following command from the command line:
heyu restart
Initial Launch
If you created the script to start Heyu automatically then you should Start Heyu via:
/etc/rc.d/rc7.d/S99heyu start
This should be all you need. if you wish to monitor commands going through the X10 interface then in an open terminal window issue the command:
heyu monitor
Use via another application
Overview
As given in the references, heyu is often used by higher level applications such as web application. In this case, it should be noted that the application's identity will be passed to heyu and thus certain resources may not be accessible to the application. For example, the serial port (e.g. ttyS5) normally has the ownership of user=root,group=uucp, and permission 0660. Normally heyu can access this because it runs as root.
If, however, you have a web application it may be running as www hence would not be able to have heyu access the serial port. Group membership or permissions can be adjusted as needed with consideration to the security implications of those changes.
Changing permission on serial port
In the case of the serial port, you could either modify its ownership or its permissions. In this example, we will allow others to have read/write permission specifically on the serial port of interest (e.g. ttyS5). By default udev only allows user and group with read/write and other has no access.
The serial port's permissions and ownership are recreated dynamically on reboot by udev. So we need to modify udev's rules to achieve our objective. Specifically the directory /etc/udev/permissions.d/ contains the permissions and in SME the default permissions are in /etc/udev/permissions.d/50-udev.permissions.
We will add a template to specifically override the permissions for our serial port.
mkdir -p /etc/e-smith/templates-custom/etc/udev/permissions.d/ touch /etc/e-smith/templates-custom/etc/udev/permissions.d/41-udev.heyu.permissions
Edit the new file above (41-udev.heyu.permissions) using an editor with the contents as follows:
# special exception to allow heyu running under www to access the relevant # serial port ttyS5:root:uucp:0666
Now expand the template and reboot to verify the changes worked
expand-template /etc/udev/permissions.d/41-udev.heyu.permissions signal-event reboot
After reboot verify that only your serial port has been changed.
Special notes
Udev follows permission rules in the order in which they appear. So the serial port rule is named to preceed the default set of permissions (hence 41 at the beginning of the file).
This procedure works for CentOS 4 (SME 7) but will change in CentOS 5 (SME 8) to use rules.d instead.
Reference Information
Documentation
Heyu is very well documented and includes man pages. Start with:
man heyu
Note also the other utilities available in the "SEE ALSO" section of the man page.
Additional Software
There are a number of front end programs which utilize Heyu including those to configure and monitor such as at:
http://heyu.tanj.com/heyu_links.html
And also some that allow things like x10 commands to trigger scripts in your server or integrate with perl scripts. Keep in mind that X10 signals are not secure so any commands you have triggered from an x10 signal may be accessible by others.
http://www.linuxha.com/athome/index.html#Software
User experience
Users who have implemented this how-to should add their experiences as data points of success for others. Please sign your experience using four tildes (~).
- Tested with SME Server 7.3 and X10's CM11a - Works (Christian 20:52, 13 October 2008 (UTC))
- - Serial port is via a Lava Link 2 port serial card