Difference between revisions of "Install xpl hub"
(→Mac OS) |
(→Mac OS) |
||
(23 intermediate revisions by one user not shown) | |||
Line 3: | Line 3: | ||
= Install the hub = | = Install the hub = | ||
+ | |||
+ | Install the Perl library to find the Ethernet interfaces: | ||
+ | su | ||
+ | apt update | ||
+ | apt install libio-interface-perl | ||
+ | perl -MIO::Interface::Simple '-E say $_->address for grep { $_->is_running && defined $_->address } IO::Interface::Simple->interfaces' | ||
Download the [http://www.dspc.ch/xPL/Downloads/xPL_base.tar.bz2 xPL base tarball]. | Download the [http://www.dspc.ch/xPL/Downloads/xPL_base.tar.bz2 xPL base tarball]. | ||
+ | |||
It contains: | It contains: | ||
* <code>xpl-hub.pl</code>: the hub | * <code>xpl-hub.pl</code>: the hub | ||
Line 19: | Line 26: | ||
you will have to adapt the path everywhere it is given hereafter. | you will have to adapt the path everywhere it is given hereafter. | ||
SCRIPTS_BASE_DIR=/home/control/Documents/Controls | SCRIPTS_BASE_DIR=/home/control/Documents/Controls | ||
− | + | mkdir -p $SCRIPTS_BASE_DIR | |
+ | chown -R control:users $SCRIPTS_BASE_DIR/.. | ||
Extract it: | Extract it: | ||
cd $SCRIPTS_BASE_DIR | cd $SCRIPTS_BASE_DIR | ||
+ | curl http://www.dspc.ch/xPL/Downloads/xPL_base.tar.bz2 --output xPL_base.tar.bz2 | ||
tar -xvjpf xPL_base.tar.bz2 | tar -xvjpf xPL_base.tar.bz2 | ||
+ | rm xPL_base.tar.bz2 | ||
+ | chown -R control:users $SCRIPTS_BASE_DIR/* | ||
= Test the hub = | = Test the hub = | ||
Line 29: | Line 40: | ||
Lanch the hub: | Lanch the hub: | ||
su control | su control | ||
− | /home/control/Documents/Controls/xpl-hub.pl -h | + | |
− | + | SCRIPTS_BASE_DIR=/home/control/Documents/Controls | |
+ | $SCRIPTS_BASE_DIR/xpl-hub.pl -h | ||
+ | $SCRIPTS_BASE_DIR/xpl-hub.pl -vl /tmp/xpl-hub.log | ||
Monitor xPL messages: open a second terminal window and: | Monitor xPL messages: open a second terminal window and: | ||
su control | su control | ||
− | /home/control/Documents/Controls/xpl-monitor.pl -h | + | |
− | + | SCRIPTS_BASE_DIR=/home/control/Documents/Controls | |
+ | $SCRIPTS_BASE_DIR/xpl-monitor.pl -h | ||
+ | $SCRIPTS_BASE_DIR/xpl-monitor.pl -v | ||
Send a message: open a third terminal window and: | Send a message: open a third terminal window and: | ||
− | /home/control/Documents/Controls/xpl-send.pl -h | + | SCRIPTS_BASE_DIR=/home/control/Documents/Controls |
− | + | $SCRIPTS_BASE_DIR/xpl-send.pl -h | |
+ | $SCRIPTS_BASE_DIR/xpl-send.pl -vc hbeat.end world=hello | ||
You should see the corresponding <code>world=hello</code> message in the second terminal window. | You should see the corresponding <code>world=hello</code> message in the second terminal window. | ||
Line 55: | Line 71: | ||
* some xPL clients may have to wait for other clients to be up and running | * some xPL clients may have to wait for other clients to be up and running | ||
− | == Ubuntu == | + | == Debian with SystemD == |
+ | |||
+ | On Debian with [https://wiki.debian.org/systemd systemd] (such as [https://www.raspbian.org/ Raspbian] | ||
+ | or [https://www.ubuntu.com/ Ubuntu]), the scripts can be defined as services. | ||
+ | |||
+ | Edit <code>/lib/systemd/system/xpl-hub.service</code>: | ||
+ | [Unit] | ||
+ | Description=xPL hub | ||
+ | Wants=network-online.target | ||
+ | After=network-online.target | ||
+ | |||
+ | [Service] | ||
+ | Type=simple | ||
+ | User=control | ||
+ | Group=users | ||
+ | ExecStart=/home/control/Documents/Controls/xpl-hub.pl -l /tmp/xpl-hub.log | ||
+ | Restart=always | ||
+ | |||
+ | [Install] | ||
+ | WantedBy=multi-user.target | ||
+ | |||
+ | Activate the service: | ||
+ | su | ||
+ | systemctl enable xpl-hub.service | ||
+ | service xpl-hub start | ||
+ | |||
+ | Reboot and check: | ||
+ | ps ax | grep -v grep | grep -i xpl | ||
+ | ps aux | grep -i xpl | grep -v grep | sed 's/.*\/Controls\///' | ||
+ | systemctl list-units --type=service --state=running | grep xpl | ||
+ | service xpl-hub status | ||
+ | |||
+ | == Ubuntu with upstart == | ||
− | On Ubuntu | + | On Ubuntu with [http://upstart.ubuntu.com/ upstart], the sequencing can base on events. |
Because of this, one has to allow the members of group <code>users</code> to emit events without typing-in a password. | Because of this, one has to allow the members of group <code>users</code> to emit events without typing-in a password. | ||
Line 78: | Line 126: | ||
env SCRIPTS_DIR='/home/control/Documents/Controls' | env SCRIPTS_DIR='/home/control/Documents/Controls' | ||
env SCRIPT_NAME='xpl-hub.pl' | env SCRIPT_NAME='xpl-hub.pl' | ||
− | env | + | env PARAMETERS='-l /tmp/xpl-hub.log' |
#------------------------------------------------------------------------------- | #------------------------------------------------------------------------------- | ||
# Start and stop conditions | # Start and stop conditions | ||
# | # | ||
− | start on ( | + | start on (filesystem and net-device-up) |
stop on shutdown | stop on shutdown | ||
respawn | respawn | ||
Line 99: | Line 147: | ||
# Start daemon | # Start daemon | ||
# | # | ||
− | exec $SCRIPTS_DIR/$SCRIPT_NAME | + | exec $SCRIPTS_DIR/$SCRIPT_NAME $PARAMETERS |
− | Once the xPL hub has been launched, the <code> xpl-hub_started</code> event is | + | Once the xPL hub has been launched, the <code> xpl-hub_started</code> event is emiited. |
Test launching the daemon: | Test launching the daemon: | ||
Line 110: | Line 158: | ||
service xpl-hub status | service xpl-hub status | ||
ps ax | grep -v grep | grep -i xpl | ps ax | grep -v grep | grep -i xpl | ||
+ | initctl list | grep xpl | ||
== Mac OS == | == Mac OS == | ||
Line 148: | Line 197: | ||
launchctl list | grep -i xpl | launchctl list | grep -i xpl | ||
− | [[Category: install]] | + | [[Category: all]] [[Category: install]] [[Category: xPL]] |
Latest revision as of 17:43, 12 January 2024
My xPL hub is based on John Bent's xPL ToolKit for Perl.
Contents
Install the hub
Install the Perl library to find the Ethernet interfaces:
su apt update apt install libio-interface-perl perl -MIO::Interface::Simple '-E say $_->address for grep { $_->is_running && defined $_->address } IO::Interface::Simple->interfaces'
Download the xPL base tarball.
It contains:
-
xpl-hub.pl
: the hub -
xpl-monitor.pl
: a monitor which allows to view the xPL messages -
xpl-send.pl
: a utility for sending xPL messages -
xPL
: a directory containing Perl functions common to all the scripts
Move it to the location you want the scripts to reside.
This could be /opt/xPL/
or /usr/opt/xPL/
.
I personally create a control
user who will run these scripts
and I place the files in /home/control/Documents/Controls/
on a Linux machine
or in /Users/control/Documents/Controls
on a Mac.
Obviously, if you place the scripts in a different location than mine,
you will have to adapt the path everywhere it is given hereafter.
SCRIPTS_BASE_DIR=/home/control/Documents/Controls mkdir -p $SCRIPTS_BASE_DIR chown -R control:users $SCRIPTS_BASE_DIR/..
Extract it:
cd $SCRIPTS_BASE_DIR curl http://www.dspc.ch/xPL/Downloads/xPL_base.tar.bz2 --output xPL_base.tar.bz2 tar -xvjpf xPL_base.tar.bz2 rm xPL_base.tar.bz2 chown -R control:users $SCRIPTS_BASE_DIR/*
Test the hub
Lanch the hub:
su control SCRIPTS_BASE_DIR=/home/control/Documents/Controls $SCRIPTS_BASE_DIR/xpl-hub.pl -h $SCRIPTS_BASE_DIR/xpl-hub.pl -vl /tmp/xpl-hub.log
Monitor xPL messages: open a second terminal window and:
su control SCRIPTS_BASE_DIR=/home/control/Documents/Controls $SCRIPTS_BASE_DIR/xpl-monitor.pl -h $SCRIPTS_BASE_DIR/xpl-monitor.pl -v
Send a message: open a third terminal window and:
SCRIPTS_BASE_DIR=/home/control/Documents/Controls $SCRIPTS_BASE_DIR/xpl-send.pl -h $SCRIPTS_BASE_DIR/xpl-send.pl -vc hbeat.end world=hello
You should see the corresponding world=hello
message in the second terminal window.
The hub also logs the connected clients:
cat /tmp/xpl-hub.log
If it works, stop all the running xPL scripts.
Launch the hub at startup
Launching the xPL system on a machine requires the following sequencing:
- once the file system and the Ethernet connections are up, the xPL hub can be started
- once the hub is up, most of the xPL clients can be started
- some xPL clients may have to wait for other clients to be up and running
Debian with SystemD
On Debian with systemd (such as Raspbian or Ubuntu), the scripts can be defined as services.
Edit /lib/systemd/system/xpl-hub.service
:
[Unit] Description=xPL hub Wants=network-online.target After=network-online.target [Service] Type=simple User=control Group=users ExecStart=/home/control/Documents/Controls/xpl-hub.pl -l /tmp/xpl-hub.log Restart=always [Install] WantedBy=multi-user.target
Activate the service:
su systemctl enable xpl-hub.service service xpl-hub start
Reboot and check:
ps ax | grep -v grep | grep -i xpl ps aux | grep -i xpl | grep -v grep | sed 's/.*\/Controls\///' systemctl list-units --type=service --state=running | grep xpl service xpl-hub status
Ubuntu with upstart
On Ubuntu with upstart, the sequencing can base on events.
Because of this, one has to allow the members of group users
to emit events without typing-in a password.
To do so, edit /etc/sudoers
and add:
# Allow users to emit upstart events %users ALL=(ALL) NOPASSWD:/sbin/initctl
In order to have the system launch the xPL hub, edit /etc/init/xpl-hub.conf
:
################################################################################ # xPL hub - hub for the home control automation system # description "xPL hub" emits xpl-hub_started version "1.0" author "Francois Corthay" #------------------------------------------------------------------------------- # Configuration variables # env SCRIPTS_DIR='/home/control/Documents/Controls' env SCRIPT_NAME='xpl-hub.pl' env PARAMETERS='-l /tmp/xpl-hub.log' #------------------------------------------------------------------------------- # Start and stop conditions # start on (filesystem and net-device-up) stop on shutdown respawn setuid control setgid users #------------------------------------------------------------------------------- # Startup signalling # post-start script sudo initctl emit xpl-hub_started end script #------------------------------------------------------------------------------- # Start daemon # exec $SCRIPTS_DIR/$SCRIPT_NAME $PARAMETERS
Once the xPL hub has been launched, the xpl-hub_started
event is emiited.
Test launching the daemon:
service xpl-hub start service xpl-hub status
Reboot the machine and check for the daemon:
service xpl-hub status ps ax | grep -v grep | grep -i xpl initctl list | grep xpl
Mac OS
On Mac OS, the xPL agents can be started as Launch Daemons.
The Mac OS launchd
daemon was designed to remove the need for dependency ordering among daemons.
In order to cope with this, the xPL scripts come with a -w
parameter
which defines a waiting time, in seconds, before the script actually does anything.
In order to have the system launch the xPL hub, edit /Library/LaunchDaemons/xpl-hub.plist
:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>xPL hub</string> <key>UserName</key> <string>control</string> <key>OnDemand</key> <false/> <key>ProgramArguments</key> <array> <string>/Users/control/Documents/Controls/xpl-hub.pl</string> <string>-w</string> <string>20</string> <string>-l</string> <string>/tmp/xpl-hub.log</string> </array> </dict> </plist>
Launch the daemon:
launchctl load /Library/LaunchDaemons/xpl-hub.plist launchctl list | grep -i xpl
Reboot the Mac and check for the daemon:
ps ax | grep -v grep | grep -i xpl launchctl list | grep -i xpl