Difference between revisions of "Install xpl hub"

From xPL
Jump to: navigation, search
(Install the hub)
(Mac OS)
 
(12 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 21: Line 28:
 
  mkdir -p $SCRIPTS_BASE_DIR
 
  mkdir -p $SCRIPTS_BASE_DIR
 
  chown -R control:users $SCRIPTS_BASE_DIR/..
 
  chown -R control:users $SCRIPTS_BASE_DIR/..
mv xPL_base.tar.bz2 $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 $SCRIPTS_BASE_DIR/xPL_base.tar.bz2
+
  rm xPL_base.tar.bz2
 
  chown -R control:users $SCRIPTS_BASE_DIR/*
 
  chown -R control:users $SCRIPTS_BASE_DIR/*
  
Line 33: Line 40:
 
Lanch the hub:
 
Lanch the hub:
 
  su control
 
  su control
 +
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  $SCRIPTS_BASE_DIR/xpl-hub.pl -h
 
  $SCRIPTS_BASE_DIR/xpl-hub.pl -h
  $SCRIPTS_BASE_DIR/xpl-hub.pl -v
+
  $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
 +
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  $SCRIPTS_BASE_DIR/xpl-monitor.pl -h
 
  $SCRIPTS_BASE_DIR/xpl-monitor.pl -h
Line 61: Line 70:
 
* once the hub is up, most of the xPL clients 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
 
* some xPL clients may have to wait for other clients to be up and running
 +
 +
== 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 ==
 
== Ubuntu with upstart ==
Line 118: Line 159:
 
  ps ax | grep -v grep | grep -i xpl
 
  ps ax | grep -v grep | grep -i xpl
 
  initctl list | grep xpl
 
  initctl list | grep xpl
 
== Debian with SystemD ==
 
 
On Debian with [https://wiki.debian.org/systemd systemd] (such as https://www.raspbian.org/),
 
the scripts can be defined as services.
 
 
Edit <code>/lib/systemd/system/xpl-hub.service</code>:
 
[Unit]
 
Description=xPL hub
 
After=network.target
 
 
[Service]
 
Type=simple
 
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
 
 
Reboot and check:
 
ps ax | grep -v grep | grep -i xpl
 
service xpl-hub status
 
  
 
== Mac OS ==
 
== Mac OS ==
Line 182: Line 197:
 
  launchctl list | grep -i xpl
 
  launchctl list | grep -i xpl
  
[[Category: all]] [[Category: all]] [[Category: install]] [[Category: xPL]]
+
[[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.

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