utilities - fcorthay/xPL GitHub Wiki

Some general purpose services can show handy in a home control system.

The utilities directory contains:

  • xpl-alert.pl : a service emitting audio alerts on demand
  • xpl-notify.py : a service allowing to push notifications on a smartphone
  • xpl-actions.pl : the ability to launch commands with an xPL command
  • xpl-dawnDusk.pl : a service emitting a message at dawn, sunrise, sunset and dusk
  • xpl-location.py : a service receiving satellite navigation messages and updating a location file

Table of Contents

Audio alerts

The audio alerts are simply sounds being played on request.

Make sure that the control user has access to the audio output: 

groups control
sudo usermod -G audio control

Test playing a sound: 

# su control
aplay -l
SOUND_FILES_LOCATION=~/Controls/xPL/utilities/sounds
aplay $SOUND_FILES_LOCATION/ring.wav

The command aplay only deals with .wav files. If one wants to work with other file formats, an option is ffplay: 

sudo apt install -y ffmpeg
ffplay -nodisp -autoexit -loglevel quiet $SOUND_FILES_LOCATION/eurovision.mp3

SDL_AUDIODRIVER="alsa" AUDIODEV="dmix:Loopback,0,0" /usr/bin/ffplay -nodisp -autoexit -loglevel quiet $SOUND_FILES_LOCATION/ring.wav

In that case, the configuration item playCommand has to be adapted.

Test the service: 

XPL_BASE_DIR=/home/control/Controls/xPL
$XPL_BASE_DIR/utilities/xpl-alert.pl -h
$XPL_BASE_DIR/utilities/xpl-alert.pl -v

In another window, send the command: 

XPL_BASE_DIR=/home/control/Controls/xPL
$XPL_BASE_DIR/xPL-base/xpl-send.py -v -c alert.basic command=play soundFile=ring.wav

Push notifications

ntfy is a simple publish–subscribe notification service. It is basically served on ntfy.sh, but it is also possible to self-host the service.

Start by installing the phone app or by running the web app. Create a topic or subscribe to if if you have already created one.

Send your first notification (adapt topic name): 

TOPIC='myTopic'
curl -d 'my first message' ntfy.sh/$TOPIC

Test the service (adapt topic name): 

TOPIC='myTopic'
XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/utilities/xpl-notify.py -h
$XPL_BASE_DIR/utilities/xpl-notify.py -T $TOPIC -v

In another terminal window: 

XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/xPL-base/xpl-send.py -v -c notify.basic message='Hi'

A typical usage would be to have xpl-central to send notifications on the reception of specific xPL messages such as a press on the doorbell button.

Notes

The RPi itself can also subscribe to a topic and even run commands on message reception. The commands can be specified in a configuraqtion file.

Ntfy messages can include action buttons which can be associated with HTTP requests.

Launch commands

Test the service: 

XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/utilities/xpl-actions.py -h
$XPL_BASE_DIR/utilities/xpl-actions.py -v

In another terminal window: 

XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/xPL-base/xpl-send.py -v -c actions.basic command=ls.bash
$XPL_BASE_DIR/xPL-base/xpl-send.py -v -c actions.basic command=ls.bash directory=/home

The command is meant to execute some action. In the python version, the terminal outputs of the commands are logged in the files specified by the logFile parameter: 

cat /tmp/xpl-actions.log

Dawn and dusk

Test the service: 

XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/utilities/xpl-dawnDusk.pl -h
$XPL_BASE_DIR/utilities/xpl-dawnDusk.pl -v

In another terminal window: 

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

In a further terminal window: 

XPL_BASE_DIR=~/Controls/xPL
$XPL_BASE_DIR/xPL-base/xpl-send.py -v -c dawnDusk.basic command=status query=all

Device location

under development
Global Navigation Satellite Systems (GNSS) allows to determine the geographic coordinates of a device. Smartphone applications such as Sensor Logger or GPSLogger allow to send GNSS data to a personal server.

The device location service receives HTTP requests, sends a corresponding xPL message and stores the data in a log file.

Further developments should present the locations as an HTML page and keep alive a Schmitt-trigger mechanism to alert when a device reaches a given distance from a reference point. This could be used to automatically open a garage door, for example.

GPIO control

The RPi has a 40-pin General Purpose Input/Ouput (GPIO) connector whose pins can be individually watched or controlled. They are defined either as buttons or LEDs. Yet the buttons don't necessarily have to be physical buttons: the corresponding pins can be driven by any binary input. Similarly, thze LEDs correspond to any kind of binary output.

Launch the services at startup

Launching these utilitiy services at startup us done similarly to the xPL hub. For the audio alert copy the reference service description, xpl-alert.service, to your system: 

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

Edit it to your personal usage.

Here what it looks like: 

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

[Service]
Type=simple
User=control
Group=users
ExecStart=/home/control/Controls/xPL/utilities/xpl-alert.pl -s ring.wav
Restart=always

[Install]
WantedBy=multi-user.target

Activate the service: 

SERVICE='xpl-alert'
sudo systemctl enable $SERVICE.service
sudo service $SERVICE start

Reboot and check: 

SERVICE='xpl-alert'
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 $SERVICE status
⚠️ **GitHub.com Fallback** ⚠️