XPL hub - fcorthay/xPL GitHub Wiki

Table of Contents

Base scripts

The xPL-base directory contains:

  • common.pl, common.py: modules providing common functions to all scripts
  • xpl-hub.pl, xpl-hub.py: the hub
  • xpl-monitor.pl, xpl-monitor.py: a monitor which allows to view the xPL messages
  • xpl-send.pl, xpl-send.py: a utility for sending xPL messages

Test the hub

Perl hub and utilities

Launch the hub: 

su control

XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/xPL-base/xpl-hub.pl -h
$XPL_BASE_DIR/xPL-base/xpl-hub.pl -vl /tmp/xpl-hub.log

Monitor xPL messages: open a second terminal window and: 

su control

XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/xPL-base/xpl-monitor.pl -h
$XPL_BASE_DIR/xPL-base/xpl-monitor.pl -vf

Send a message: open a third terminal window and: 

XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/xPL-base/xpl-send.pl -h
$XPL_BASE_DIR/xPL-base/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.

Python hub and utilities

The Python hub works similarly to the Perl hub. The scripts can be mixed (e.g. Perl hub and Python monitor). Only the Python scripts terminate with .py (e.g. $XPL_BASE_DIR/xPL-base/xpl-monitor.py instead of $XPL_BASE_DIR/xPL-base/xpl-monitor.pl).

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
The daemon definition files are presented here with the reference to the Perl scripts. Change .pl to .py if Python is preferred.

Debian with SystemD

On Debian with systemd (or derivatives such as Raspbian or recent Ubuntu versions), the hub can be defined as a service.

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/Controls/xPL/xPL-base/xpl-hub.pl -l /tmp/xpl-hub.log
Restart=always

[Install]
WantedBy=multi-user.target

Alternatively, copy it from the repository: 

XPL_BASE_DIR=~/Controls/xPL
SERVICE='xpl-hub'
sudo cp $XPL_BASE_DIR/services/$SERVICE.service /lib/systemd/system/

Activate the service: 

SERVICE='xpl-hub'
sudo systemctl enable $SERVICE.service
sudo service $SERVICE 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
sudo service xpl-hub status | cat

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/Controls/xPL/xPL-base'
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 starts doing 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/Controls/xPL/xPL-base/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
⚠️ **GitHub.com Fallback** ⚠️