Latest revision as of 11:31, 2 January 2018

The xPL actions device allows to launch scripts or executables with parameters from any xPL device. This allows to build complex home control sequences, even with condition checks. In this point of view, the actions device allows more elaborate control than the central xPL device.

As an example, pushing an EIB button can result not only in opening the entrance door, but also in turning-on selected lights if the button has been pushed after sunset.

The actions device is often controlled by xPL messages originating from the central xPL device. Additionally to sending xPL messages to controlled devices such as lights and shutters, it can perform local actions on a computer, such as displaying an alert message, sending an e-mail or backing-up files.

Before all, make sure you have installed an xPL hub.

Install xPL actions device

Download the xPL actions script.

Move the script to xPL scripts directory:

SCRIPTS_BASE_DIR=/home/control/Documents/Controls
mv xpl-actions.pl $SCRIPTS_BASE_DIR
chown control:users $SCRIPTS_BASE_DIR/*.pl
chmod 775 $SCRIPTS_BASE_DIR/*.pl

Create the /home/control/Documents/Controls/Actions directory.

Create the /home/control/Documents/Controls/Actions/play.bash file, changing the constants accordingly to your setup:

#!/bin/bash

#-------------------------------------------------------------------------------
# Constants
#
DEFAULT_SOUND_FILE='/home/control/Documents/Controls/Sounds/pop.wav'
PLAY_COMMAND='/usr/bin/aplay'

#-------------------------------------------------------------------------------
# Command line arguments
#
sound_file=
while [ "$1" != '' ] ; do
  case $1 in
    -f | --file   ) shift ; sound_file=$1 ;;
  esac
  shift
done

#===============================================================================
# Play sound
#

if [ -e "$sound_file" ] ; then
  echo "Playing file: $sound_file"
  $PLAY_COMMAND $sound_file > /dev/null 2>&1
else
  sound_file=$DEFAULT_SOUND_FILE
  $PLAY_COMMAND $sound_file > /dev/null 2>&1
  echo "File \"$sound_file\" not found"
fi

Test it:

SCRIPTS_BASE_DIR=/home/control/Documents/Controls
$SCRIPTS_BASE_DIR/Actions/play.bash -f /home/control/Documents/Controls/Sounds/ring.wav

Test xPL actions device

Test it on a BeagleBone:

su control
SCRIPTS_BASE_DIR=/home/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-actions.pl -h
$SCRIPTS_BASE_DIR/xpl-actions.pl -v -n test

Open a 2nd terminal window (on any machine with xPL installed) and monitor the xPL protocol:

SCRIPTS_BASE_DIR=/home/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-monitor.pl -vf

Open another terminal and have xPL play a sound:

SCRIPTS_BASE_DIR=/home/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-send.pl -v -d dspc-actions.test -c actions.basic command=play.bash file=/home/control/Documents/Controls/Sounds/ring.wav

Launch the xPL actions device at startup

The xPL actions launcher is to start after the xPL hub.

A different instance of the actions launcher can run on different machines. If this is the case, they are distinguished by their name.

Debian with SystemD

On Debian with systemd (such as Raspbian or Ubuntu), the scripts can be defined as services.

Edit /lib/systemd/system/xpl-actions.service:

[Unit]
Description=xPL actions
After=xpl-hub.service

[Service]
Type=simple
User=control
Group=users
ExecStart=/home/control/Documents/Controls/xpl-actions.pl -n home
Restart=always

[Install]
WantedBy=multi-user.target

Activate the service:

su
systemctl enable xpl-actions.service
service xpl-actions start

Reboot and check:

ps aux | grep -v grep | grep -i xpl
ps ax | grep -i xpl | grep -v grep | sed 's/.*\/Controls\///'
systemctl list-units --type=service --state=running | grep xpl
service xpl-actions status

Ubuntu with Upstart

On Ubuntu, the xPL actions device starts-up once xpl-hub_started has been emitted.

Edit /etc/init/xpl-actions.conf:

################################################################################
# xPL actions launcher
#
description "xPL actions launcher"
version     "1.0"
author      "Francois Corthay"

#-------------------------------------------------------------------------------
# Configuration variables
#
env SCRIPTS_DIR='/home/control/Documents/Controls'
env SCRIPT_NAME='xpl-actions.pl'
env PARAMETERS='-n lounge'

#-------------------------------------------------------------------------------
# Start and stop conditions
#
start on xpl-hub_started
stop on shutdown
respawn
setuid control
setgid audio

#-------------------------------------------------------------------------------
# Start daemon
#
exec $SCRIPTS_DIR/$SCRIPT_NAME $PARAMETERS

Start the device and test it:

su root
service xpl-actions start
service xpl-actions status
initctl list | grep xpl

SCRIPTS_BASE_DIR=/home/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-send.pl -v -d dspc-actions.lounge -c actions.basic command=play.bash

Mac OS

On Mac OS, the xPL actions device starts-up later than the hub.

Edit /Library/LaunchDaemons/xpl-actions.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 actions launcher</string>
    <key>OnDemand</key>
    <false/>
    <key>UserName</key>
    <string>francois</string>
    <key>ProgramArguments</key>
    <array>
      <string>/Users/control/Documents/Controls/xpl-actions.pl</string>
      <string>-n</string>
      <string>lounge</string>
      <string>-w</string>
      <string>25</string>
      <string>-d</string>
      <string>/Users/control/Documents/Controls/Actions</string>
    </array>
  </dict>
</plist>

Start the device and test it:

su root
launchctl load /Library/LaunchDaemons/xpl-actions.plist

SCRIPTS_BASE_DIR=/Users/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-send.pl -v -d dspc-actions.lounge -c actions.basic command=play.bash