Tutorial SensorClientRaspberryPi DS18B20
In this document a tutorial for the version 0.502 is given.
This tutorial describes the basic configuration of the AlertR Sensor Client Raspberry Pi with a connected DS18B20 temperature sensor. 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:~$ python alertRinstaller.py -l
[...]
alertR Sensor Client Raspberry Pi
---------------------------------
Instance:
sensorClientRaspberryPi
Type:
sensor
Version:
0.400-1
Dependencies:
1: RPi.GPIO (lowest version: 0.5.2)
Description:
This client handles Raspberry Pi GPIO pins as sensors. It either polls the state of a GPIO pin or uses an interrupt on a falling/rising edge and triggers an alert if the state has changed/interrupt has occurred (or a state change if it goes back from a state in which it triggers an alert to a normal state). This means it notifies the server if an alert was triggered by a sensor. A sensor connected to the GPIO pin can be anything you like for example a PIR (Passive InfraRed) sensor, a magnetic switch on a window, a water leak alarm sensor, a smoke detector and so on.
[...]
In order to install the AlertR Sensor Client Raspberry Pi, 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 python-pip
root@towel:/home/sqall# pip install RPi.GPIO
Obviously, the AlertR Sensor Client Raspberry Pi should be installed on a Raspberry Pi. Please note that older versions of the Raspberry Pi packages need root permissions in order to access the GPIO pins. If you are installing the AlertR instance on an older Raspberry Pi operating system with older packages, make sure it works without root permissions before creating a new user account for the AlertR instance. If it only works with root permissions, please omit all steps that use the new alertr user and instead use the root user account.
It is always a good idea to have an own user for a daemon. Therefore, we create a user that runs the AlertR Sensor Client Raspberry Pi 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
Additionally, the user has to be in the group gpio in order to access the GPIO pins:
root@towel:/home/sqall# addgroup alertr gpioTo 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 sensorClientRaspberryPi
alertr@towel:~$ python alertRinstaller.py -i sensorClientRaspberryPi -t ./sensorClientRaspberryPi/
This tutorial connects two DS18B20 temperature sensor to the Raspberry Pi. I only give a short description of what has to be done. It is tested on Raspbian 9 with a 4.14.34 Linux kernel. If you use a different operating system or an older Linux kernel, please do a quick search on Google (there are tones of sites explaining how to connect the DS18B20 sensor to a Raspberry Pi).
The circuit diagram to connect two DS18B20 to the Raspberry Pi looks like this:
The DS18B20 temperature sensors are connected parallel. If you want to have more DS18B20 sensors, just add them. If you want to have only one DS18B20 sensor connected to your Raspberry Pi, just remove one. Furthermore, the DS18B20 is connected to GPIO 4. This time, it is the Raspberry Pi name for the GPIO and not the actually pin number. Please pay attention to this.
If you do not have a breadboard or do not want to use one for this simple circuit, you can build something lazy as I did:
This is just a luster terminal with a resistor. It can be connected directly to the Raspberry Pi GPIO, GND and 3,3V power supply. Do not be confused because of the DS18B20 sensor in this picture. It is a water proof one and looks different because of this.
After everything is connected to the Raspberry Pi, we have to add some settings to the operating system. The Raspbian distribution offers modules that can communicate with the DS18B20 temperature sensor. In order to load them on start up we have to add them to the /etc/modules file:
[...]
# DS18B20
w1-gpio pullup=1
w1-therm
[...]Additionally, we have to add the following lines to the /boot/config.txt file:
[...]
# DS18B20
dtoverlay=w1-gpio-pullup,gpiopin=4,extpullup=on
[...]After that, we reboot the Raspberry Pi. When it comes up again, we check if everything worked out. We can do this by listing the /sys/bus/w1/devices/ directory:
root@towel:/home/sqall# ls -la /sys/bus/w1/devices/
total 0
drwxr-xr-x 2 root root 0 Jun 9 17:18 .
drwxr-xr-x 4 root root 0 Jun 9 17:18 ..
lrwxrwxrwx 1 root root 0 Jun 3 19:39 28-031600c1baff -> ../../../devices/w1_bus_master1/28-031600c1baff
lrwxrwxrwx 1 root root 0 Jun 3 19:39 31-051310c1bbcd -> ../../../devices/w1_bus_master1/31-051310c1bbcd
lrwxrwxrwx 1 root root 0 Jun 3 19:39 w1_bus_master1 -> ../../../devices/w1_bus_master1If it looks similar to this, then everything has worked out. The driver found two temperature devices with the ID 28-031600c1baff and 31-051310c1bbcd. We can print the measured temperature manually like the following:
root@towel:/home/sqall# cat /sys/bus/w1/devices/28-031600c1baff/w1_slave
c9 01 4b 46 7f ff 0c 10 47 : crc=47 YES
c9 01 4b 46 7f ff 0c 10 47 t=28562The sensor measured a temperature of 28.562 degrees Celsius. Now everything is finished, and we can set up the AlertR client.
The following describes the configuration of the alertR Sensor Client Raspberry Pi. It shows a basic configuration that can be used as a template for own installations.
For security reasons, the alertR system enforces a TLS connection. 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/sensorClientRaspberryPi/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 add the following line to the server user credentials file /home/alertr/server/config/users.csv (which was set up during the server installation.):
user_temp_pi, password_temp_pi, sensor, sensorClientRaspberryPi
Remember to restart the AlertR server in order to activate the user credentials.
This tutorial assumes the alert levels configured in the AlertR Server tutorial. The client will use the following for its configuration:
| AlertLevel | Name | Functionality |
|---|---|---|
| 0 | Dummy | Used for sensors that do not trigger. |
| 1 | Silent Notification | Used to silently notify the user. |
AlertLevel 0 is used for one DS18B20 sensor that should not trigger any alert.
AlertLevel 1 is used for sensors that trigger a sensorAlert, but not an urgent one. This silent notification is used for one DS18B20 sensor if the temperature gets below a certain threshold. This alertLevel triggers always despite if the alarm system is activated or not.
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:~/sensorClientRaspberryPi/config$ cp config.xml.template config.xml
The configuration file itself is split into the following parts:
- General
- SMTP
- Update
- Sensors
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="/home/alertr/sensorClientRaspberryPi/config/logfile.log"
level="INFO" />
<server
host="localhost"
port="44556"
caFile="/home/alertr/sensorClientRaspberryPi/config/alertr_server.crt" />
<client
certificateRequired="False"
certFile="/absolute/path/to/client.crt"
keyFile="/absolute/path/to/client.key" />
<credentials
username="user_switch_pi"
password="password_switch_pi" />
</general>
Section log is used to configure the log file setup. The file attribute sets the location for the log file. Please note that this has to be the absolute path to the location. 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. The caFile attribute sets the location of the certificate file that is used to authenticate the server (see Certificate). Please make sure that the location is an absolute path to the file.
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.
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="sensorClientRaspberryPi@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
host="raw.githubusercontent.com"
port="443"
location="/sqall01/alertR/master/"
caFile="/etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem" />
</update>
Section server is used to configure the remote update repository. Normally, the default configuration can be used here (which is this repository). The host attribute gives the remote server location of the repository. The port attribute gives the port on which the repository is reachable (AlertR uses HTTPS for it). The location attribute sets the location on the remote repository. The caFile attribute gives the local location of the certificate that is used to verify the HTTPS connection. The default value is the location on Debain/Ubuntu distributions of the current certificate that is used by Github.
The sensors section configures the sensors of this client. In our tutorial configuration, the section looks like this:
<sensors>
<sensor>
<general
id="0"
description="Temperature Living Room"
alertDelay="0"
triggerAlert="False"
triggerAlertNormal="False" />
<alertLevel>1</alertLevel>
<gpio
type="ds18b20"
sensorName="28-031600c1baff"
interval="30"
hasThreshold="False"
threshold="15.0"
ordering="LT" />
</sensor>
<sensor>
<general
id="1"
description="Temperature Greenhouse"
alertDelay="0"
triggerAlert="True"
triggerAlertNormal="True" />
<alertLevel>1</alertLevel>
<gpio
type="ds18b20"
sensorName="31-051310c1bbcd"
interval="30"
hasThreshold="True"
threshold="10.0"
ordering="LT" />
</sensor>
</sensors>
Each configured sensor is set up in its own <sensor>...</sensor> context. The context has three main sections: general, alertLevel and gpio. The following describes the settings of each section.
Section general is used to configure the basic sensor settings. The id attribute gives the local id of the configured sensor. This id has to be unique for each sensor of this client. Since we configure two sensors, we give them the id 0 and 1. The description attribute gives a short description of the sensor. The alertDelay attribute sets how long in seconds the server has to wait until a sensorAlert is triggered. Normally, this is set to 0 to immediate react on a sensorAlert. But in some situations it might be necessary to react on a sensorAlert after a certain time and not directly. For our tutorial sensors we set this value to 0. The triggerAlert attribute sets if the sensor triggers a sensorAlert with the state "triggered" and triggerAlertNormal sets if the sensor triggers a sensorAlert with the state "normal". For the Temperature Living Room sensor we do not want any sensorAlert whereas for the Temperature Greenroom we want them.
The alertLevel sections set the alertLevel the sensor triggers. In our tutorial, one sensor triggers alertLevel 0 and one alertLevel 1. But it is not limited to only one alertLevel per sensor. If another alertLevel should be triggered, an additional alertLevel section is added with the corresponding alertLevel.
Section gpio configures the GPIO sensor settings. The type attribute sets the type of the GPIO sensor. In both cases, this is set to ds18b20. The ds18b20 type fetches the data of the temperature sensor and sends it to the server. The sensorName attribute needs the ID of the DS18B20 sensor the data is fetched from. The interval attribute is used to set the interval in seconds in which the data is fetched from the sensor. The hasThreshold attribute sets if this sensor has a threshold which could be exceeded. In this tutorial, the Temperature Living Room sensor has none (and therefore does not trigger any sensorAlert) and the Temperature Greenroom has one. The threshold attribute sets the temperature that triggers a sensorAlert when exceeded. The ordering attribute sets what kind of threshold we have set. In our tutorial, the Temperature Greenroom should trigger a sensorAlert if the current temperature is below (LT = lower than) 10 degrees Celsius. Perhaps we have plants in our greenroom that cannot stand temperatures below that?
If you want the AlertR client to start automatically after a reboot of the host, you have to set it up. In this tutorial, I will give two examples on how to set up the autostart of the AlertR client depending on your system using systemd or just init.d.
An init.d script is provided by the AlertR installation. The only thing you have to do is to copy and configure it correctly. The following command copies it to the correct location, sets the permissions correctly and installs it:
root@towel:/home/alertr/sensorClientRaspberryPi/init.d_example# cp alertRsensorRaspberryPi.sh /etc/init.d/
root@towel:/etc/init.d# chown root:root alertRsensorRaspberryPi.sh
root@towel:/etc/init.d# chmod 755 alertRsensorRaspberryPi.sh
root@towel:/etc/init.d# update-rc.d alertRsensorRaspberryPi.sh defaults
Adding system startup for /etc/init.d/alertRsensorRaspberryPi.sh ...
/etc/rc0.d/K20alertRsensorRaspberryPi.sh -> ../init.d/alertRsensorRaspberryPi.sh
/etc/rc1.d/K20alertRsensorRaspberryPi.sh -> ../init.d/alertRsensorRaspberryPi.sh
/etc/rc6.d/K20alertRsensorRaspberryPi.sh -> ../init.d/alertRsensorRaspberryPi.sh
/etc/rc2.d/S20alertRsensorRaspberryPi.sh -> ../init.d/alertRsensorRaspberryPi.sh
/etc/rc3.d/S20alertRsensorRaspberryPi.sh -> ../init.d/alertRsensorRaspberryPi.sh
/etc/rc4.d/S20alertRsensorRaspberryPi.sh -> ../init.d/alertRsensorRaspberryPi.sh
/etc/rc5.d/S20alertRsensorRaspberryPi.sh -> ../init.d/alertRsensorRaspberryPi.sh
Next we have to configure the init.d script correctly. The following changes have to be made to the script:
[...]
# change USER to the user which runs the alertRclient
# NOTE: older versions of the Raspberry Pi packages need to be run as "root"
# in order to access the GPIO pins
USER=alertr
# change DAEMON to the path to run the alertRclient
DAEMON=/home/alertr/sensorClientRaspberryPi/alertRclient.py
[...]
In order to work correctly, the AlertR client has to be executable. With the following, we change the permissions of the AlertR client:
alertr@towel:~/sensorClientRaspberryPi$ chmod 755 alertRclient.py
To start the client as daemon, we can now execute:
root@towel:/home/alertr/sensorClientRaspberryPi# /etc/init.d/alertRsensorRaspberryPi.sh start
The log file of the client (it is created in the directory you have configured in the General Section) should now show the following:
[...]
07/27/2016 19:42:26 INFO: [alertRclient.py] Initializing sensors.
07/27/2016 19:42:27 INFO: [alertRclient.py] Connecting to server.
07/27/2016 19:42:28 INFO: [alertRclient.py] Starting watchdog thread.
07/27/2016 19:42:28 INFO: [alertRclient.py] Starting update check thread.
07/27/2016 19:42:28 INFO: [alertRclient.py] Client started.
If your system uses systemd for its autostart, you have to configure the alertR client a bit different. Copying the template and setting permissions is still the same:
root@towel:/home/alertr/sensorClientRaspberryPi/init.d_example# cp alertRsensorRaspberryPi.sh /etc/init.d/
root@towel:/etc/init.d# chown root:root alertRsensorRaspberryPi.sh
root@towel:/etc/init.d# chmod 755 alertRsensorRaspberryPi.sh
Configuring the init.d script correctly is also the same:
[...]
# change USER to the user which runs the alertRclient
# NOTE: older versions of the Raspberry Pi packages need to be run as "root"
# in order to access the GPIO pins
USER=alertr
# change DAEMON to the path to run the alertRclient
DAEMON=/home/alertr/sensorClientRaspberryPi/alertRclient.py
[...]
Now, systemd has to be configured. For this we copy the template service file to the correct location and install the service:
root@towel:/home/alertr/sensorClientRaspberryPi/init.d_example# cp alertRsensorRaspberryPi.service /etc/systemd/system/
root@towel:/home/alertr/sensorClientRaspberryPi# systemctl enable alertRsensorRaspberryPi.service
The alertR client can be started with the following command:
root@towel:/home/alertr/sensorClientRaspberryPi# service alertRsensorRaspberryPi.sh status
The log file of the client (it is created in the directory you have configured in the General Section) should now show the following:
[...]
07/27/2016 19:42:26 INFO: [alertRclient.py] Initializing sensors.
07/27/2016 19:42:27 INFO: [alertRclient.py] Connecting to server.
07/27/2016 19:42:28 INFO: [alertRclient.py] Starting watchdog thread.
07/27/2016 19:42:28 INFO: [alertRclient.py] Starting update check thread.
07/27/2016 19:42:28 INFO: [alertRclient.py] Client started.
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 no error can be seen, please start the AlertR client manually and check if an error occurs that is not printed into the log file. This can be done by just executing the AlertR client as the user that it normally runs with.
alertr@towel:~/sensorClientRaspberryPi$ ./alertRclient.py
If you still have problems and do not know how to solve them, you can use the Github Issues.