Difference between revisions of "Install state"

From xPL
Jump to: navigation, search
(→‎Install xPL home state device)
 
(21 intermediate revisions by one user not shown)
Line 1: Line 1:
−
 
−
 
−
::<html>
 
−
<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>
 
−
</html>
 
−
 
−
 
 
The [http://en.wikipedia.org/wiki/XPL_Protocol xPL] home state device stores the current state of different devices
 
The [http://en.wikipedia.org/wiki/XPL_Protocol xPL] home state device stores the current state of different devices
 
such as lights, shutters, etc…
 
such as lights, shutters, etc…
Line 13: Line 6:
 
The state update is best controlled with the help of the [[install central|central xPL device]].
 
The state update is best controlled with the help of the [[install central|central xPL device]].
  
−
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 home state device =
+
= Home state information =
  
−
Download the [http://www.dspc.ch/xPL/Downloads/xpl-homeState.pl xPL home state] script.
+
The home state information is stored in an [https://en.wikipedia.org/wiki/XML XML] file.
 +
It is categorised in 4 hierarchy levels:
 +
* the ''room''
 +
* the ''kind'', such as <code>lights</code>, <code>shutters</code>, etc…
 +
* the ''object'': an object of the kind given by an identifier, such as <code>table</code> for the lamp above the table
 +
* the ''value'', such as <code>on</code> or <code>off</code>
  
−
Move the script to xPL scripts directory:
+
The following example shows a possible content of <code>/home/control/Documents/Controls/state.xml</code>:
−
SCRIPTS_BASE_DIR=/home/control/Documents/Controls
+
  <?xml version="1.0" encoding="ISO-8859-1"?>
−
  mv xpl-homeState.pl $SCRIPTS_BASE_DIR
+
  <state>
−
  chown control:users $SCRIPTS_BASE_DIR/*.pl
+
  <lounge name="lights" center="off" entry="off" stand="off" table="off" />
−
  chmod 775 $SCRIPTS_BASE_DIR/*.pl
+
  <lounge name="shutters" center="up" east="up" west="up" />
 +
  <lounge name="audio" balance="0" power="on" mute="off" source="CD" surround="stereoSub" volume="50" />
 +
  <lounge name="screen" aspect="43" input="RGB" power="on" />
 +
  <study name="lights" ceiling="off" stand="off" />
 +
  <study name="shutters" window="louvresDown" />
 +
  <study name="audio" balance="0" source="CD" power="off" volume="30" />
 +
  </state>
  
−
= Configure xPL home state device =
+
The home state information is both updated and queried with the help of [https://en.wikipedia.org/wiki/XPL_Protocol#Protocol xPL messages].
  
−
Edit <code>/home/control/Documents/Controls/centralActions.xml</code>:
+
= Install xPL home state device =
−
<?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>
+
  
−
The comments in the beginning of the file show the structure of the rules.
+
Install <code>XML::Simple</code>:
−
Each line defines a pattern which, compared to an incoming xPL message, can trigger one or more other messages.
+
sudo apt install libxml-simple-perl
−
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.
+
Download the [http://www.dspc.ch/xPL/Downloads/xpl-homeState.pl xPL home state] script:
−
This has no effect in the interpretation of the commands:
+
SCRIPTS_BASE_DIR=/home/control/Documents/Controls
−
it's only purpose is to structure the XML file and to allow commenting out parts of the configuration items
+
cd $SCRIPTS_BASE_DIR
−
or adding comments in the file.
+
wget http://www.dspc.ch/xPL/Downloads/xpl-homeState.pl
 +
chown control:users *.pl
 +
chmod 775 *.pl
  
−
The configuration file is read anew each time a new xPL message arrives.
+
Create the <code>/home/control/Documents/Controls/state.xml</code> state file based on the preceeding example, but adapted to your needs.
−
This allows to edit and update the rules without having to stop and restart the xPL central device.
+
The file doesn't need to be complete: objects will be added by the xPL <code>update</code> or <code>set</code> messages.
  
 
= Test xPL home state device =
 
= Test xPL home state device =
Line 75: Line 57:
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  SCRIPTS_BASE_DIR=/home/control/Documents/Controls
 
  $SCRIPTS_BASE_DIR/xpl-monitor.pl -vf
 
  $SCRIPTS_BASE_DIR/xpl-monitor.pl -vf
 +
The monitor will help by showing the responses of the home state device.
  
−
Open another terminal and send a message to the serial port:
+
Open another terminal and query a value:
 
  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 -c pingPong.basic message=ping
+
cat $SCRIPTS_BASE_DIR/state.xml | grep 'study.*lights'
 +
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask
  
−
The monitor should display the <code>ping</code> message,
+
Modify a value:
−
directly followed by a <code>pong</code> message emitted by the xPL central device.
+
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling value=on command=update
 +
cat $SCRIPTS_BASE_DIR/state.xml | grep 'study.*lights'
 +
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask
 +
 
 +
Modify a value and trigger an action:
 +
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling value=off command=set
 +
cat $SCRIPTS_BASE_DIR/state.xml | grep 'study.*lights'
 +
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask
 +
Additionally to updating the state file, this command will trigger an <code>act</code> message
 +
which can be used by the [[install central|central xPL device]] to actually turn off the light.
 +
 
 +
Try to modify a value and don't trigger an action:
 +
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling value=off command=set
 +
cat $SCRIPTS_BASE_DIR/state.xml | grep 'study.*lights'
 +
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask
 +
As the value of the <code>ceiling</code> lamp was already <code>off</code>,
 +
this command will not trigger an <code>act</code> message.
 +
This feature will prevent objects to flicker or temporarily mute when an identical command is sent more than once.
  
 
= Launch the xPL home state device at startup =
 
= Launch the xPL home state device at startup =
  
−
The xPL central device is to be launched after the xPL hub.
+
The xPL home state device is to be launched after the xPL hub.
 +
 
 +
== 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-homeState.service</code>:
 +
[Unit]
 +
Description=xPL homeState
 +
After=xpl-hub.service
 +
 +
[Service]
 +
Type=simple
 +
User=control
 +
Group=users
 +
ExecStart=/home/control/Documents/Controls/xpl-homeState.pl -n home
 +
Restart=always
 +
 +
[Install]
 +
WantedBy=multi-user.target
 +
 
 +
Activate the service:
 +
su
 +
systemctl enable xpl-homeState.service
 +
service xpl-homeState 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-homeState status
  
−
== Ubuntu ==
+
== Ubuntu with Upstart ==
  
−
On Ubuntu, the xPL central device starts-up once <code>xpl-hub_started</code> has been emitted.
+
On Ubuntu, the xPL home state device starts-up once <code>xpl-hub_started</code> has been emitted.
  
 
Edit <code>/etc/init/xpl-homeState.conf</code>:
 
Edit <code>/etc/init/xpl-homeState.conf</code>:
 
  ################################################################################
 
  ################################################################################
−
  # xPL central message parser
+
  # xPL home state manager
 
  #
 
  #
−
  description "xPL central message parser"
+
  description "xPL home state manager"
 
  version    "1.0"
 
  version    "1.0"
 
  author      "Francois Corthay"
 
  author      "Francois Corthay"
Line 123: Line 155:
 
Start the device and test it:
 
Start the device and test it:
 
  su root
 
  su root
−
  service xpl-central start
+
  service xpl-homeState start
−
  service xpl-central status
+
  service xpl-homeState 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 -c pingPong.basic message=ping
+
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask
  
 
== Mac OS ==
 
== Mac OS ==
  
−
On Mac OS, the xPL central device starts-up later than the hub.
+
On Mac OS, the xPL home state device starts-up later than the hub.
  
−
Edit <code>/Library/LaunchDaemons/xpl-central.plist</code>:
+
Edit <code>/Library/LaunchDaemons/xpl-homeState.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 139: Line 172:
 
   <dict>
 
   <dict>
 
     <key>Label</key>
 
     <key>Label</key>
−
     <string>xPL central message parser</string>
+
     <string>xPL home state manager</string>
 
     <key>OnDemand</key>
 
     <key>OnDemand</key>
 
     <false/>
 
     <false/>
Line 146: Line 179:
 
     <key>ProgramArguments</key>
 
     <key>ProgramArguments</key>
 
     <array>
 
     <array>
−
       <string>/Users/control/Documents/Controls/xpl-central.pl</string>
+
       <string>/Users/control/Documents/Controls/xpl-homeState.pl</string>
 
       <string>-n</string>
 
       <string>-n</string>
−
       <string>lounge</string>
+
       <string>home</string>
 
       <string>-w</string>
 
       <string>-w</string>
 
       <string>25</string>
 
       <string>25</string>
−
       <string>-a</string>
+
       <string>-s</string>
−
       <string>/Users/control/Documents/Controls/centralActions.xml</string>
+
       <string>/home/control/Documents/Controls/state.xml</string>
 
     </array>
 
     </array>
 
   </dict>
 
   </dict>
Line 159: Line 192:
 
Start the device and test it:
 
Start the device and test it:
 
  su root
 
  su root
−
  launchctl load /Library/LaunchDaemons/xpl-central.plist
+
  launchctl load /Library/LaunchDaemons/xpl-homeState.plist
 
   
 
   
 
  SCRIPTS_BASE_DIR=/Users/control/Documents/Controls
 
  SCRIPTS_BASE_DIR=/Users/control/Documents/Controls
−
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -c pingPong.basic message=ping
+
  $SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask
  
−
[[Category: install]]
+
[[Category: all]] [[Category: install]] [[Category: xPL]]

Latest revision as of 20:35, 8 January 2022

The xPL home state device stores the current state of different devices such as lights, shutters, etc… This information can be retrieved by clients such as web 2.0 pages in order to display the proper state of the devices to be controlled.

The state update is best controlled with the help of the central xPL device.

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

Home state information

The home state information is stored in an XML file. It is categorised in 4 hierarchy levels:

  • the room
  • the kind, such as lights, shutters, etc…
  • the object: an object of the kind given by an identifier, such as table for the lamp above the table
  • the value, such as on or off

The following example shows a possible content of /home/control/Documents/Controls/state.xml: 

<?xml version="1.0" encoding="ISO-8859-1"?>
<state>
  <lounge name="lights" center="off" entry="off" stand="off" table="off" />
  <lounge name="shutters" center="up" east="up" west="up" />
  <lounge name="audio" balance="0" power="on" mute="off" source="CD" surround="stereoSub" volume="50" />
  <lounge name="screen" aspect="43" input="RGB" power="on" />
  <study name="lights" ceiling="off" stand="off" />
  <study name="shutters" window="louvresDown" />
  <study name="audio" balance="0" source="CD" power="off" volume="30" />
</state>

The home state information is both updated and queried with the help of xPL messages.

Install xPL home state device

Install XML::Simple: 

sudo apt install libxml-simple-perl

Download the xPL home state script: 

SCRIPTS_BASE_DIR=/home/control/Documents/Controls
cd $SCRIPTS_BASE_DIR
wget http://www.dspc.ch/xPL/Downloads/xpl-homeState.pl
chown control:users *.pl
chmod 775 *.pl

Create the /home/control/Documents/Controls/state.xml state file based on the preceeding example, but adapted to your needs. The file doesn't need to be complete: objects will be added by the xPL update or set messages.

Test xPL home state device

Test it on a BeagleBone: 

su control
SCRIPTS_BASE_DIR=/home/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-homeState.pl -h
$SCRIPTS_BASE_DIR/xpl-homeState.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

The monitor will help by showing the responses of the home state device.

Open another terminal and query a value: 

su control
SCRIPTS_BASE_DIR=/home/control/Documents/Controls
cat $SCRIPTS_BASE_DIR/state.xml | grep 'study.*lights'
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask

Modify a value: 

$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling value=on command=update
cat $SCRIPTS_BASE_DIR/state.xml | grep 'study.*lights'
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask

Modify a value and trigger an action: 

$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling value=off command=set
cat $SCRIPTS_BASE_DIR/state.xml | grep 'study.*lights'
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask

Additionally to updating the state file, this command will trigger an act message which can be used by the central xPL device to actually turn off the light.

Try to modify a value and don't trigger an action: 

$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling value=off command=set
cat $SCRIPTS_BASE_DIR/state.xml | grep 'study.*lights'
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask

As the value of the ceiling lamp was already off, this command will not trigger an act message. This feature will prevent objects to flicker or temporarily mute when an identical command is sent more than once.

Launch the xPL home state device at startup

The xPL home state 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-homeState.service: 

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

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

[Install]
WantedBy=multi-user.target

Activate the service: 

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

Ubuntu with Upstart

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

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

################################################################################
# xPL home state manager
#
description "xPL home state manager"
version     "1.0"
author      "Francois Corthay"

#-------------------------------------------------------------------------------
# Configuration variables
#
env SCRIPTS_DIR='/home/control/Documents/Controls'
env SCRIPT_NAME='xpl-homeState.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-homeState start
service xpl-homeState status
initctl list | grep xpl

SCRIPTS_BASE_DIR=/home/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask

Mac OS

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

Edit /Library/LaunchDaemons/xpl-homeState.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 home state manager</string>
    <key>OnDemand</key>
    <false/>
    <key>UserName</key>
    <string>control</string>
    <key>ProgramArguments</key>
    <array>
      <string>/Users/control/Documents/Controls/xpl-homeState.pl</string>
      <string>-n</string>
      <string>home</string>
      <string>-w</string>
      <string>25</string>
      <string>-s</string>
      <string>/home/control/Documents/Controls/state.xml</string>
    </array>
  </dict>
</plist>

Start the device and test it: 

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

SCRIPTS_BASE_DIR=/Users/control/Documents/Controls
$SCRIPTS_BASE_DIR/xpl-send.pl -v -c state.basic room=study kind=lights object=ceiling command=ask
Retrieved from "http://www.dspc.ch/xPL/index.php?title=Install_state&oldid=620"