Difference between revisions of "Install central"

From xPL
Jump to: navigation, search
(→‎Test xPL central device)
(→‎Ubuntu)
 
(21 intermediate revisions by one user not shown)
Line 3: Line 3:
 
and can trigger other messages based on a set of rules stored in an [http://en.wikipedia.org/wiki/XML XML] file.
 
and can trigger other messages based on a set of rules stored in an [http://en.wikipedia.org/wiki/XML XML] file.
  
−
Before all,make sure you have installed an [[install xpl hub|xPL hub]].
+
Before all, make sure you have installed an [[install xpl hub|xPL hub]].
  
 
= Install xPL central device =
 
= Install xPL central device =
  
 
Install <code>XML::Simple</code>:
 
Install <code>XML::Simple</code>:
 +
sudo apt install libxml-simple-perl
 +
 +
Alternatively, you can do it the CPAN way:
 
  su
 
  su
−
  perl -MFile::Find=find -MFile::Spec::Functions -Tlw -e 'find { wanted => sub { print canonpath $_ if /\.pm\z/ }, no_chdir => 1 }, @INC' 2> /dev/null | grep -i XML
+
  perl -MFile::Find=find -MFile::Spec::Functions -Tlw -e 'find { wanted => sub { print canonpath $_ if /\.pm\z/ }, no_chdir => 1 }, @INC' 2> /dev/null | grep -i 'xml.*simple'
 
  perl -MCPAN -e "install 'XML::Simple'"
 
  perl -MCPAN -e "install 'XML::Simple'"
 
  exit
 
  exit
  
−
If <code>XML::SAX::Expat</code> doesn't install properly and blocks the installation of <code>XML::Simple</code>, try:
+
If <code>XML::SAX::Expat</code> doesn't install properly and blocks the installation of <code>XML::Simple</code>,
 +
which was the case on my  [[install BeagleBone| Ubuntu BeagleBone]], try:
 
  su
 
  su
 
  apt-get install libxml-sax-expat-incremental-perl
 
  apt-get install libxml-sax-expat-incremental-perl
Line 20: Line 24:
 
  exit
 
  exit
  
−
Download the [http://www.dspc.ch/xPL/Downloads/xpl-serial_port.pl xPL central device] script.
+
Download the [http://www.dspc.ch/xPL/Downloads/xpl-central.pl xPL central device] script.
  
 
Move the script to xPL scripts directory:
 
Move the script to xPL scripts directory:
Line 28: Line 32:
 
  chmod 775 $SCRIPTS_BASE_DIR/*.pl
 
  chmod 775 $SCRIPTS_BASE_DIR/*.pl
  
−
= Test xPL central device =
+
= Configure xPL central device =
  
 +
Edit <code>/home/control/Documents/Controls/centralActions.xml</code>:
 +
<?xml version="1.0" encoding="ISO-8859-1"?>
 +
&lt;!--
 +
  possible rules:
 +
    messageType_source_target_class_name1_value1_name2_value2="messageType target class name1=value1 name2=value2"
 +
    messageType_source_target_class_name1_value1_name2_value2="messageType target class name1=value1 name2=value2|messageType target class name1=value1 name2=value2"
 +
    messageType_source_target_class_name1_value1_name2_value2="messageType target class name1=value1 name2=value2|sleep 100 ms|messageType target class name1=value1 name2=value2"
 +
-->
 +
<actions>
 +
  <pingPong
 +
    xpl-cmnd_any_any_pingPong.basic_message_ping="xpl-trig * pingPong.basic message=pong"
 +
  />
 +
    <eib
 +
    xpl-trig_any_any_eib.basic_group_01.01.001_data_0x00="xpl-cmnd dspc-state.home state.basic command=update room=study level=lights object=ceiling value=off"
 +
    xpl-trig_any_any_eib.basic_group_01.01.001_data_0x01="xpl-cmnd dspc-state.home state.basic command=update room=study level=lights object=ceiling value=on"
 +
    xpl-trig_any_any_eib.basic_group_01.01.002_data_0x00="xpl-cmnd dspc-state.home state.basic command=update room=study level=lights object=stand value=off"
 +
    xpl-trig_any_any_eib.basic_group_01.01.002_data_0x01="xpl-cmnd dspc-state.home state.basic command=update room=study level=lights object=stand value=on"
 +
    xpl-cmnd_any_any_state.basic_command_set_room_study_level_lights_object_ceiling_value_off="xpl-cmnd dspc-eib.home eib.basic group=1/1/1 data=0x00"
 +
    xpl-cmnd_any_any_state.basic_command_set_room_study_level_lights_object_ceiling_value_on="xpl-cmnd dspc-eib.home eib.basic group=1/1/1 data=0x01"
 +
    xpl-cmnd_any_any_state.basic_command_set_room_study_level_lights_object_stand_value_off="xpl-cmnd dspc-eib.home eib.basic group=1/1/2 data=0x00"
 +
    xpl-cmnd_any_any_state.basic_command_set_room_study_level_lights_object_stand_value_on="xpl-cmnd dspc-eib.home eib.basic group=1/1/2 data=0x01"
 +
  />
 +
</actions>
  
−
::<html>
+
The comments in the beginning of the file show the structure of the rules.
−
<a title="By Dsmurat (+) [LGPL (http://www.gnu.org/licenses/lgpl.html)], via Wikimedia Commons" href="http://commons.wikimedia.org/wiki/File%3AUnder_construction_icon-blue.svg"><img width="512" alt="Under construction icon-blue" src="//upload.wikimedia.org/wikipedia/commons/thumb/d/d5/Under_construction_icon-blue.svg/512px-Under_construction_icon-blue.svg.png"/></a>
+
Each line defines a pattern which, compared to an incoming xPL message, can trigger one or more other messages.
−
</html>
+
The format of these rules has been defined in order to allow to write one per line.
 +
If a parameter of a message to be sent contains a space character, that character has to be replaced by an underscore.
  
 +
The rules are grouped in parts such as <code>pingPong</code> and <code>eib</code> in the preceeding example.
 +
This has no effect in the interpretation of the commands:
 +
it's only purpose is to structure the XML file and to allow commenting out parts of the configuration items
 +
or adding comments in the file.
 +
 +
The configuration file is read anew each time a new xPL message arrives.
 +
This allows to edit and update the rules without having to stop and restart the xPL central device.
 +
 +
= Test xPL central device =
  
 
Test it on a [[install BeagleBone|BeagleBone]]:
 
Test it on a [[install BeagleBone|BeagleBone]]:
Line 40: Line 77:
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  $SCRIPTS_BASE_DIR/xpl-central.pl -h
 
  $SCRIPTS_BASE_DIR/xpl-central.pl -h
−
  $SCRIPTS_BASE_DIR/xpl-central.pl -v -n test
+
  $SCRIPTS_BASE_DIR/xpl-central.pl -v -n home
  
 
Open a 2nd terminal window (on any machine with xPL installed) and monitor the xPL protocol:
 
Open a 2nd terminal window (on any machine with xPL installed) and monitor the xPL protocol:
Line 46: Line 83:
 
  $SCRIPTS_BASE_DIR/xpl-monitor.pl -vf
 
  $SCRIPTS_BASE_DIR/xpl-monitor.pl -vf
  
−
The monitor should echo the serial port incoming messages.
+
Open another terminal and send a message to be processed by the central device:
−
 
+
−
Open another terminal and send a message to the serial port:
+
 
  su control
 
  su control
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
−
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -t cmnd -d dspc-serPort.test -c serPort.basic command='hello world'
+
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -c pingPong.basic message=ping
 +
 
 +
The monitor should display the <code>ping</code> message,
 +
directly followed by a <code>pong</code> message emitted by the xPL central device.
  
 
= Launch the xPL central device at startup =
 
= Launch the xPL central device at startup =
  
−
The xPL serial port device is to be launched after the xPL hub.
+
The xPL central device is to be launched after the xPL hub.
  
−
If the serial port equipment needs an initialisation command,
+
== Debian with SystemD ==
−
the xPL device controlling the equipment trough the xPL serial port needs to be launched after the xPL serial port.
+
  
−
The following example shows the installation of an xPL serial port device
+
On Debian with [https://wiki.debian.org/systemd systemd] (such as [https://www.raspbian.org/ Raspbian]
−
connected to a  [http://www.tapko.de/sim-knx.html Tapko EIB/KNX to RS232 converter].
+
or [https://www.ubuntu.com/ Ubuntu]), the scripts can be defined as services.
  
−
== Ubuntu ==
+
Edit <code>/lib/systemd/system/xpl-central.service</code>:
 +
[Unit]
 +
Description=xPL central
 +
After=xpl-hub.service
 +
 +
[Service]
 +
Type=simple
 +
User=control
 +
Group=users
 +
ExecStart=/home/control/Documents/Controls/xpl-central.pl -n home
 +
Restart=always
 +
 +
[Install]
 +
WantedBy=multi-user.target
 +
 
 +
Activate the service:
 +
su
 +
systemctl enable xpl-central.service
 +
service xpl-central 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-central status
 +
 
 +
== Ubuntu with Upstart ==
  
−
On Ubuntu, the xPL serial port device starts-up once <code>xpl-hub_started</code> has been emitted.
+
On Ubuntu, the xPL central device starts-up once <code>xpl-hub_started</code> has been emitted.
−
Once launched, it emits <code>xpl-eibSerialPort_started</code> for the next xPL device to control the serial port equipment.
+
  
−
Edit <code>/etc/init/xpl-eibSerialPort.conf</code>:
+
Edit <code>/etc/init/xpl-central.conf</code>:
 
  ################################################################################
 
  ################################################################################
−
  # xPL serial port for Tapko EIB/KNX to RS232 bridge
+
  # xPL central message parser
 
  #
 
  #
−
  description "xPL EIB bridge serial port"
+
  description "xPL central message parser"
 
  version    "1.0"
 
  version    "1.0"
 
  author      "Francois Corthay"
 
  author      "Francois Corthay"
Line 80: Line 142:
 
  #
 
  #
 
  env SCRIPTS_DIR='/home/control/Documents/Controls'
 
  env SCRIPTS_DIR='/home/control/Documents/Controls'
−
  env SCRIPT_NAME='xpl-serial_port.pl'
+
  env SCRIPT_NAME='xpl-central.pl'
−
  env PARAMETERS='-n eib -e \\x0A\\x0D /dev/ttyO1 baudrate 9600 databits 8 parity none stopbits 1 handshake none'
+
  env PARAMETERS='-n home'
 
   
 
   
 
  #-------------------------------------------------------------------------------
 
  #-------------------------------------------------------------------------------
Line 90: Line 152:
 
  respawn
 
  respawn
 
  setuid control
 
  setuid control
−
  setgid dialout
+
  setgid users
−
+
−
#-------------------------------------------------------------------------------
+
−
# Startup signalling
+
−
#
+
−
post-start script
+
−
  sudo initctl emit xpl-eibSerialPort_started
+
−
end script
+
 
   
 
   
 
  #-------------------------------------------------------------------------------
 
  #-------------------------------------------------------------------------------
Line 106: Line 161:
 
Start the device and test it:
 
Start the device and test it:
 
  su root
 
  su root
−
  service xpl-eibSerialPort start
+
  service xpl-central start
−
  service xpl-eibSerialPort status
+
  service xpl-central status
 +
initctl list | grep xpl
 
   
 
   
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
−
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -t cmnd -d dspc-serPort.eib -c serPort.basic command='gci'
+
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -c pingPong.basic message=ping
−
$SCRIPTS_BASE_DIR/xpl-send.pl -v -t cmnd -d dspc-serPort.eib -c serPort.basic command='dts \$15'
+
−
$SCRIPTS_BASE_DIR/xpl-send.pl -v -t cmnd -d dspc-serPort.eib -c serPort.basic command='tds (1/1/1) 1'
+
  
 
== Mac OS ==
 
== Mac OS ==
  
−
On Mac OS, the xPL serial port device starts-up later than the hub.
+
On Mac OS, the xPL central device starts-up later than the hub.
  
−
Edit <code>/Library/LaunchDaemons/xpl-eibSerialPort.plist</code>:
+
Edit <code>/Library/LaunchDaemons/xpl-central.plist</code>:
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?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">
 
  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
Line 124: Line 178:
 
   <dict>
 
   <dict>
 
     <key>Label</key>
 
     <key>Label</key>
−
     <string>xPL EIB bridge serial port</string>
+
     <string>xPL central message parser</string>
 
     <key>OnDemand</key>
 
     <key>OnDemand</key>
 
     <false/>
 
     <false/>
Line 131: Line 185:
 
     <key>ProgramArguments</key>
 
     <key>ProgramArguments</key>
 
     <array>
 
     <array>
−
       <string>/Users/control/Documents/Controls/xpl-serial_port.pl</string>
+
       <string>/Users/control/Documents/Controls/xpl-central.pl</string>
 
       <string>-n</string>
 
       <string>-n</string>
−
       <string>eib</string>
+
       <string>lounge</string>
 
       <string>-w</string>
 
       <string>-w</string>
 
       <string>25</string>
 
       <string>25</string>
−
       <string>-e</string>
+
       <string>-a</string>
−
       <string>\x0A\x0D</string>
+
       <string>/Users/control/Documents/Controls/centralActions.xml</string>
−
      <string>/dev/tty.PL2303-0020131D</string>
+
−
      <string>baudrate</string>
+
−
      <string>9600</string>
+
−
      <string>databits</string>
+
−
      <string>8</string>
+
−
      <string>parity</string>
+
−
      <string>none</string>
+
−
      <string>stopbits</string>
+
−
      <string>1</string>
+
−
      <string>handshake</string>
+
−
      <string>none</string>
+
 
     </array>
 
     </array>
 
   </dict>
 
   </dict>
Line 155: Line 198:
 
Start the device and test it:
 
Start the device and test it:
 
  su root
 
  su root
−
  launchctl load /Library/LaunchDaemons/xpl-eibSerialPort.plist
+
  launchctl load /Library/LaunchDaemons/xpl-central.plist
 
   
 
   
 
  SCRIPTS_BASE_DIR=/Users/control/Documents/Controls
 
  SCRIPTS_BASE_DIR=/Users/control/Documents/Controls
−
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -t cmnd -d dspc-serPort.eib -c serPort.basic command='gci'
+
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -c pingPong.basic message=ping
−
$SCRIPTS_BASE_DIR/xpl-send.pl -v -t cmnd -d dspc-serPort.eib -c serPort.basic command='dts \$15'
+
−
$SCRIPTS_BASE_DIR/xpl-send.pl -v -t cmnd -d dspc-serPort.eib -c serPort.basic command='tds (1/1/1) 1'
+
  
−
[[Category: install]]
+
[[Category: all]] [[Category: install]] [[Category: xPL]]

Latest revision as of 15:27, 29 December 2017

The central xPL device can be compared to a central station. It monitors all xPL messages and can trigger other messages based on a set of rules stored in an XML file.

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

Install xPL central device

Install XML::Simple: 

sudo apt install libxml-simple-perl

Alternatively, you can do it the CPAN way: 

su
perl -MFile::Find=find -MFile::Spec::Functions -Tlw -e 'find { wanted => sub { print canonpath $_ if /\.pm\z/ }, no_chdir => 1 }, @INC' 2> /dev/null | grep -i 'xml.*simple'
perl -MCPAN -e "install 'XML::Simple'"
exit

If XML::SAX::Expat doesn't install properly and blocks the installation of XML::Simple, which was the case on my Ubuntu BeagleBone, try: 

su
apt-get install libxml-sax-expat-incremental-perl
ln -s /usr/share/perl5/XML/SAX/ParserDetails.ini /usr/local/share/perl/5.14.2/XML/SAX/ParserDetails.ini
perl -MCPAN -e "install 'XML::Simple'"
exit

Download the xPL central device script.

Move the script to xPL scripts directory: 

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

Configure xPL central device

Edit /home/control/Documents/Controls/centralActions.xml: 

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  possible rules:
    messageType_source_target_class_name1_value1_name2_value2="messageType target class name1=value1 name2=value2"
    messageType_source_target_class_name1_value1_name2_value2="messageType target class name1=value1 name2=value2|messageType target class name1=value1 name2=value2"
    messageType_source_target_class_name1_value1_name2_value2="messageType target class name1=value1 name2=value2|sleep 100 ms|messageType target class name1=value1 name2=value2"
-->
<actions>
  <pingPong
    xpl-cmnd_any_any_pingPong.basic_message_ping="xpl-trig * pingPong.basic message=pong"
  />
   <eib
    xpl-trig_any_any_eib.basic_group_01.01.001_data_0x00="xpl-cmnd dspc-state.home state.basic command=update room=study level=lights object=ceiling value=off"
    xpl-trig_any_any_eib.basic_group_01.01.001_data_0x01="xpl-cmnd dspc-state.home state.basic command=update room=study level=lights object=ceiling value=on"
    xpl-trig_any_any_eib.basic_group_01.01.002_data_0x00="xpl-cmnd dspc-state.home state.basic command=update room=study level=lights object=stand value=off"
    xpl-trig_any_any_eib.basic_group_01.01.002_data_0x01="xpl-cmnd dspc-state.home state.basic command=update room=study level=lights object=stand value=on"
    xpl-cmnd_any_any_state.basic_command_set_room_study_level_lights_object_ceiling_value_off="xpl-cmnd dspc-eib.home eib.basic group=1/1/1 data=0x00"
    xpl-cmnd_any_any_state.basic_command_set_room_study_level_lights_object_ceiling_value_on="xpl-cmnd dspc-eib.home eib.basic group=1/1/1 data=0x01"
    xpl-cmnd_any_any_state.basic_command_set_room_study_level_lights_object_stand_value_off="xpl-cmnd dspc-eib.home eib.basic group=1/1/2 data=0x00"
    xpl-cmnd_any_any_state.basic_command_set_room_study_level_lights_object_stand_value_on="xpl-cmnd dspc-eib.home eib.basic group=1/1/2 data=0x01"
  />
</actions>

The comments in the beginning of the file show the structure of the rules. Each line defines a pattern which, compared to an incoming xPL message, can trigger one or more other messages. The format of these rules has been defined in order to allow to write one per line. If a parameter of a message to be sent contains a space character, that character has to be replaced by an underscore.

The rules are grouped in parts such as pingPong and eib in the preceeding example. This has no effect in the interpretation of the commands: it's only purpose is to structure the XML file and to allow commenting out parts of the configuration items or adding comments in the file.

The configuration file is read anew each time a new xPL message arrives. This allows to edit and update the rules without having to stop and restart the xPL central device.

Test xPL central device

Test it on a BeagleBone: 

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

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 send a message to be processed by the central device: 

su control
SCRIPTS_BASE_DIR=/home/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c pingPong.basic message=ping

The monitor should display the ping message, directly followed by a pong message emitted by the xPL central device.

Launch the xPL central device at startup

The xPL central device is to be launched after the xPL hub.

Debian with SystemD

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

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

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

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

[Install]
WantedBy=multi-user.target

Activate the service: 

su
systemctl enable xpl-central.service
service xpl-central 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-central status

Ubuntu with Upstart

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

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

################################################################################
# xPL central message parser
#
description "xPL central message parser"
version     "1.0"
author      "Francois Corthay"

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

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

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

Start the device and test it: 

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

SCRIPTS_BASE_DIR=/home/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c pingPong.basic message=ping

Mac OS

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

Edit /Library/LaunchDaemons/xpl-central.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 central message parser</string>
    <key>OnDemand</key>
    <false/>
    <key>UserName</key>
    <string>control</string>
    <key>ProgramArguments</key>
    <array>
      <string>/Users/control/Documents/Controls/xpl-central.pl</string>
      <string>-n</string>
      <string>lounge</string>
      <string>-w</string>
      <string>25</string>
      <string>-a</string>
      <string>/Users/control/Documents/Controls/centralActions.xml</string>
    </array>
  </dict>
</plist>

Start the device and test it: 

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

SCRIPTS_BASE_DIR=/Users/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c pingPong.basic message=ping
Retrieved from "http://www.dspc.ch/xPL/index.php?title=Install_central&oldid=483"