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
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
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.
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.
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
Powering up a machine can be done using Wake On LAN. This is done by by sending a specific Ethernet packet and must be enabled both in the BIOS and the OS.
Install the necessary commands:
sudo apt install ethtool sudo apt install wakeonlan
Check if WakeOnLan is enabled (adapt interface name):
ifconfig INTERFACE=eth0 sudo ethtool $INTERFACE | grep -i wake-on
Wake-on should be g.
If not, activate it:
ethtool -s $INTERFACE wol g
Get a local machine's MAC address:
MACHINE=Maia IP_ADDRESS=`getent hosts $MACHINE.local | cut -d ' ' -f 1` MAC_ADDRESS=`ip neighbour | grep $IP_ADDRESS\ dev | cut -d ' ' -f 5` echo "\"$MACHINE.local\" has IP address \"$IP_ADDRESS\" and MAC address \"$MAC_ADDRESS\""
Shut down the machine and wake it up:
wakeonlan $MAC_ADDRESS
Sending a wake-on-LAN command can be done as follows:
sudo apt install -y netcat-openbsd
WAKEUP_STRING=`printf 'F%.0s' {1..12}`
BROADCAST_ADDRESS='192.168.1.255'
BROADCAST_ADDRESS='255.255.255.255'
DISCARD_PORT=9
MACHINE=Maia
IP_ADDRESS=`getent hosts $MACHINE.local | cut -d ' ' -f 1`
MAC_ADDRESS=`ip neighbour | grep $IP_ADDRESS\ dev | cut -d ' ' -f 5`
MAC_16=`printf "$(echo $MAC_ADDRESS | sed 's/://g')%.0s" {1..16}`
MAGIC_PACKET=`echo "$WAKEUP_STRING$MAC_16" | sed -e 's/../\\\x&/g'`
echo -ne $MAGIC_PACKET | nc -w1 -u -b $BROADCAST_ADDRESS $DISCARD_PORT
One can mimic this to send a shutdown command:
SHUTDOWN_STRING=`printf '0%.0s' {1..12}`
MAGIC_PACKET=`echo "$SHUTDOWN_STRING$MAC_16" | sed -e 's/../\\\x&/g'`
echo -ne $MAGIC_PACKET | nc -w1 -u -b $BROADCAST_ADDRESS $DISCARD_PORT
One then needs a script which is launched at reboot (with crontab -e)
and listens to the discard port 9...
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
- under development
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.
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, the LEDs correspond to any kind of binary output.
Many RPi peripherals are controlled over I2C (Inter-Integrated Circuit serial bus) whose pins are part of the 40-pin General Purpose Input/Ouput (GPIO) connector.
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