Tutorial ManagerClientKeypad
(For version 1.000)
This tutorial describes the basic configuration of the AlertR Manager Client Keypad. It can be used as foundation to develop an own AlertR system setup. This tutorial assumes you have set up the AlertR Server according to the provided Server Tutorial.
The client is described as the following by the installation:
sqall@towel:~$ ./alertRinstaller.py -l
[...]
AlertR Manager Client Keypad
----------------------------
Instance:
managerClientKeypad
Type:
manager
Version:
0.901-0
Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: urwid (pip packet: urwid) (lowest version: 2.1.0)
Description:
This client manages the state of the AlertR system. It can change the used system profile after you entered a correct PIN. If AlertR is, for example, used in an alarm system context, it can change the used system profile from "alarm system activated" to "alarm system deactivated" and vice versa. Furthermore, it allows a delayed system profile change allowing you, for example, in an alarm system context to chose "activate the alarm system in X seconds" and then leave the building. It is written to work as a client with keypad and small display (original for a Raspbery Pi, but is not limited to it). In an alarm system context, the client should be near an entrance to allow the user to activate/deactivate the alarm system while leaving/entering.
[...]
In order to install the AlertR Manager Client Keypad, we first have to fulfill all prerequisites. On a Debian/Ubuntu Linux you can install everything with the following commands:
root@towel:/home/sqall# apt-get install python3-pip
root@towel:/home/sqall# pip3 install urwid requests
It is always a good idea to have an own user for a daemon. Therefore, we create a user that runs the AlertR Manager Client Keypad called alertr:
root@towel:/home/sqall# adduser --disabled-password alertr
Adding user `alertr' ...
Adding new group `alertr' (1002) ...
Adding new user `alertr' (1002) with group `alertr' ...
Creating home directory `/home/alertr' ...
Copying files from `/etc/skel' ...
Changing the user information for alertr
Enter the new value, or press ENTER for the default
Full Name []:
Room Number []:
Work Phone []:
Home Phone []:
Other []:
Is the information correct? [Y/n] y
To switch into this user in the terminal you can use the following command:
root@towel:/home/sqall# su alertr
Please note that this is only possible as root user. If you are trying this command as another user you will get a password prompt for the user alertr, which does not have a password.
Afterwards, you can use the installation script provided by AlertR to install the client.
alertr@towel:~$ wget https://raw.githubusercontent.com/sqall01/alertR/master/alertRinstaller.py
alertr@towel:~$ mkdir managerClientKeypad
alertr@towel:~$ chmod 755 alertRinstaller.py
alertr@towel:~$ ./alertRinstaller.py -i managerClientKeypad -t ./managerClientKeypad/
As the description of the client already mentioned, this client is built for giving a user the direct ability to change the System Profile of the AlertR system. If we use AlertR in an alarm system context for example, it is best suited to be installed on a Raspberry Pi that is placed somewhere near an entrance door (or similar positions) to allow the direct use. For example, you could use a small display connected via HDMI to the Raspberry Pi and a small USB keypad to give the user the ability to enter a PIN code. The following shows an example setup for it:
The small display used here is also able to output audio via its built-in speakers. This allows us to use the audio capabilities of the AlertR Manager Client Keypad.
The following describes the configuration of the AlertR Manager Client Keypad. It shows a basic configuration that can be used as a template for own installations.
For security reasons, it is strongly recommended to use a TLS connection for your AlertR system. Hence, all tutorials will use TLS. However, for testing purposes AlertR gives you the option to disable TLS. If you do so, you have to disable it for the complete AlertR system.
During the installation of the AlertR server, you created a certificate file with the name alertr_server.crt. This file is needed by the client in order to verify the connection. Please copy it to the host you are installing this client on. This tutorial assumes that you have stored the certificate file in the following location: /home/alertr/managerClientKeypad/config/alertr_server.crt.
The client has to authenticate itself before it can work with the server. Therefore, we need to set up user credentials on the AlertR server for this client. We execute the following command with the manageUsers.py script of the server which is located in the installation directory of the server (see Users Management for further information):
alertr@towel:/home/alertr/server# ./manageUsers.py -a -u user_keypad -p password_keypad -t manager -i managerClientKeypad
Please make sure that the AlertR Server is not running while adding a user.
Otherwise it can lead to an inconsistent state and a corrupted database.
Are you sure to continue?
(y/n): y
Every AlertR installation has a template configuration file with detailed comments that describe the functionality of each option. To use it as a draft, you can just copy the template file and modify your new configuration file.
alertr@towel:~/managerClientKeypad/config$ cp config.xml.template config.xml
alertr@towel:~/managerClientKeypad/config$ chmod 700 config.xml
The configuration file itself is split into the following parts:
- General
- SMTP
- Update
- Manager
In this tutorial, we are going through each of these parts separately and describe why we configured it like that.
The general section is used for options such as certificate file location. In our tutorial configuration, the section looks like this:
<general>
<log
file="./logfile.log"
level="INFO" />
<server
host="localhost"
port="44556" />
<ssl
enabled="True">
<server
caFile="./config/alertr_server.crt" />
<client
certificateRequired="False"
certFile="/path/to/client.crt"
keyFile="/path/to/client.key" />
</ssl>
<credentials
username="user_keypad"
password="password_keypad" />
<connection
persistent="False" />
</general>
Section log is used to configure the log file setup. The file attribute sets the location for the log file. Make sure it exists and is writable by the user that starts the AlertR client. Otherwise the client will not start. For example, the directory /var/log is usually only writable by the root user and users of the group syslog. If you want the client log file in this directory, please create a sub-directory for the AlertR client log file and set the correct permissions on it. The level attribute sets the log level. Possible values are DEBUG, INFO, WARNING, ERROR, CRITICAL.
Section server is used to configure the server connection setup. The host and port attribute sets the address and port of the AlertR server. The port was previously configured in the server configuration file. The address can either be a name that can be resolved by the DNS system or an IP address.
Section ssl is used to configure the TLS/SSL setup. The enabled attributes gives you the option to disable or enable it. This setting has to be the same for your complete AlertR setup. It is strongly recommended to enable TLS/SSL and only disable it in a testing environment. In this tutorial, we enable TLS/SSL. The caFile attribute in the server section sets the location of the certificate file that is used to authenticate the server (see Certificate). Section client is used to configure the client connection setup. The certificateRequired attribute determines if the client needs a certificate to connect to the server or not. The certFile and keyFile are used to determine the client certificate and key file. Since this tutorial is not using client certificates, we do not have to set sane values here.
Section credentials is used to configure the login credentials of this client. The credentials were configured in a previous step of this Tutorial and must be the same as in this configuration file.
Section connection is used to configure the connection to the server. The persistent attribute is used to configure if the connection to the server has to be persistent. This means that if the client disconnects, a Sensor Alert is created by the server.
The smtp section is used for options that configure the used SMTP server. In our tutorial configuration, the section looks like this:
<smtp>
<general
activated="True"
fromAddr="managerClientKeypad@alertr.de"
toAddr="myalarmaddress@example.org" />
<server
host="127.0.0.1"
port="25" />
</smtp>
Section general is used to configure the basic options of the eMail notification. The eMail notification is used if problems on the AlertR client occur that can not be solved (like connection problems). The activated attribute determines if the eMail notification is activated or not. If it is deactivated, the rest of the options in the whole smtp section are ignored. The fromAddr attribute sets the used eMail address from which the eMail notification is sent. The toAddr attribute determines the eMail address the notification is sent to.
Section server is used to configure the SMTP server that is used to send the eMail notification. The host attribute sets the address and the port attribute sets the port of the used SMTP server. At the moment, only "127.0.0.1" is allowed as address and port 25. This means you have to set up a local SMTP server in order to send eMail notifications. Personally, I would suggest to set up a local Postfix SMTP server that can forward eMails like in this Tutorial. Please note that the local SMTP server has to accept eMails from localhost without any authentication since it is not supported by AlertR yet.
The update section is used to give the online repository for updates. In our tutorial configuration, the section looks like this:
<update>
<server
url="https://raw.githubusercontent.com/sqall01/alertR/master/" />
</update>
Section server is used to configure the remote update repository. Normally, the default configuration can be used here (which is this repository). The url attribute gives the remote server location of the repository. Only the https protocol is allowed here if you want to change it.
The manager section configures special options of this client. In our tutorial configuration, the section looks like this:
<manager>
<general
description="Keypad Manager Towel" />
<audio
enabled="True"
playSilence="True" />
<keypad
timeDelayedChange="20">
<pin>123456</pin>
<pin>9876</pin>
</keypad>
<sensorwarningstates>
<sensor
username="user_switch_pi"
clientSensorId="0"
warningState="True">
<profile>0</profile>
</sensor>
</sensorwarningstates>
</manager>
The context has four main sections: general, audio, keypad and sensorwarningstates. The following describes the settings of each section.
Section general is used to configure the basic manager settings. The description attribute gives the description of this manager client.
Section audio is used to configure the audio capabilities of the manager. It is able to give feedback via audio when the user enters numbers. The enabled attributes either enables or disables it. It obviously can either be True or False. In our example, we want to use the audio option. The playSilence attribute is used to play an audio file with silence all the time. This can be handy when, for example, HDMI is used to output the audio. Some speakers turn themselves off when no audio signal is received. However, since the AlertR client only plays short sounds as feedback, the speakers often need to much time to turn on again and therefore do not output the audio signal. Hence, it is activated in our example.
Section keypad configures the keypad of the AlertR client. The client itself offers the user two options after a PIN was entered successful. One of these options is to change the System Profile of the AlertR system after a certain amount of time. This time in seconds can be configured with the timeDelayedChange attribute. The PINs accepted by the AlertR client are also configured in this section. This can be only one or multiple ones. In our example, we configure two different PINs 123456 and 9876. Both allow users to access the AlertR client.
Section sensorwarningstates is used to output a warning if the user wants to change the System Profile of the AlertR system and a certain sensor is in a state configured here. Let us assume for our example we have also configured a AlertR Sensor Client Raspberry Pi as described in this tutorial. It has two sensors configured, a Window with the id 0 and a Mechanical Switch with the id 1. We want to get a warning issued if the Window is open when we want to change the System Profile. Then we add a sensor to this section with the attribute username set to the username of the AlertR Sensor Client Raspberry Pi which is in our example user_switch_pi. The id of the sensor as configured on the client is set in the attribute clientSensorId. The attribute warningState decides if we want a warning issued when the sensor is in the state triggered or normal. In our case, we want a warning issued for the triggered state. Next we have to configure the target System Profiles for which we get this warning. Since we use our AlertR system in this example in an alarm system context as described in our AlertR Server tutorial, we have a System Profile "Activated" with id 0 and a System Profile "Deactivated" with id 1. We want only a warning if we activate our alarm system, hence we add a profile for id 0. If we want also a warning if we change to other System Profiles, we can add additional profile settings. In the case we want multiple sensors checked, we can just add additional sensor settings. If we do not want any checked, we can just leave the sensorwarningstates section empty.
Since this client is built to interact with the user directly, we can start it to see if everything works.
alertr@towel:~/managerClientKeypad$ ./alertRclient.py
The output should look something like this:
However, a malicious user could still exit the client by hitting CTRL+C and gain direct access to the Raspberry Pi. Therefore, we need to build some kind of kiosk mode for this AlertR client.
Since the Raspbian distribution uses systemd, we can use it to run the AlertR client in a kiosk like mode on tty1. But please note, this does only work if you do not start a X session and you only access your Raspberry Pi via ssh (since we now block the tty1 for login). To do this, we have to create a service unit. First of all, we have to create the directory /etc/systemd/system/getty@tty1.service.d/ (if it does not already exist).
root@towel:/home/sqall# mkdir /etc/systemd/system/getty@tty1.service.d/After this, we have to create the file /etc/systemd/system/getty@tty1.service.d/override.conf and place the following in there:
[Service]
ExecStart=
ExecStart=-/bin/su alertr -c /home/alertr/managerClientKeypad/alertRclient.py
StandardInput=tty
StandardOutput=ttySince systemd executes everything as user root, we want to change the user. Therefore, this executes the command su and starts the AlertR client as user alertr. You can test if everything works by restarting the service:
root@towel:/home/sqall# systemctl daemon-reload
root@towel:/home/sqall# systemctl restart getty@tty1.serviceIf you do not get any error message and the AlertR client starts on your tty1 and is shown on your display, everything works.
If you experience problems, please check the log file first. If it is not helpful, change the log level to DEBUG and check again.
If you still have problems and do not know how to solve them, you can ask on the community page on reddit or you can use the Github Issues.