Skip to content

Tutorials

sqall01 edited this page Oct 12, 2021 · 28 revisions
Clone this wiki locally

Tutorials

In this document a list of existing official tutorials for AlertR are shown.

If a tutorial is missing or you have an idea that is not shown there, feel free to write one yourself and contribute it. It would be great if other users can benefit from your contribution.

Please make sure you read the Installation documentation to understand how the installation process works as well as how Infrastructure of an AlertR installation looks like. As a starting point, use the Server Tutorial and then add easy to use clients such as the AlertR Sensor Client Ping and AlertR Manager Client Console to your test configuration.

List of Tutorials

AlertR Alert Clients

AlertR Manager Clients

AlertR Sensor Clients

AlertR Server

Developers

AlertR Alert Client Dbus

This tutorial describes the basic installation and configuration of the AlertR Alert Client Dbus. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Alert Client Dbus
------------------------
Instance:
alertClientDbus

Type:
alert

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: dbus(lowest version: 1.2.0)

Description:
This client handles triggered alerts and is written to show a message notification via D-Bus. It works with all window managers that support D-Bus and implement the freedesktop.org specification. For example, you can run it as a service on your workstation and as soon as an event happens (front door opens, door bell rings, service goes down, incoming phone call, and so on) it shows a notification on the display.
[...]

AlertR Alert Client Dbus Tutorial

AlertR Alert Client Executer

This tutorial describes the basic installation and configuration of the AlertR Alert Client Executer. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Alert Client Executer
----------------------------
Instance:
alertClientExecuter

Type:
alert

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)

Description:
This client handles triggered sensors and is written to execute a configured script or command with arguments. The arguments are configured and the command is executed on a triggered sensor alert event or when the system profile has changed. This allows you to interact with non-AlertR components or integrate your own code into the AlertR system.
[...]

AlertR Alert Client Executer Tutorial

AlertR Alert Client Push Notification

This tutorial describes the basic installation and configuration of the AlertR Alert Client Push Notification. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Alert Client Push Notification
-------------------------------------
Instance:
alertClientPushNotification

Type:
alert

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: lightweightpush (pip packet: lightweightpush) (lowest version: 0.0.5)

Description:
This client handles triggered sensor alerts and is written to send an end-to-end encrypted push notification on the configured channel when it receives a sensor alert. It needs an account at https://alertr.de and the receiving devices to have the AlertR App installed. For each alert you configure, you can customize the message content by using template files. Special keywords will be replaced by information about the received sensor alert.
[...]

AlertR Alert Client Push Notification Tutorial

AlertR Alert Client Raspberry Pi - Siren

This tutorial describes the basic installation and configuration of the AlertR Alert Client Raspberry Pi. It focuses on connecting a homemade siren to the Raspberry Pi. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Alert Client Raspberry Pi
--------------------------------
Instance:
alertClientRaspberryPi

Type:
alert

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: RPi.GPIO (pip packet: RPi.GPIO) (lowest version: 0.5.2)

Description:
This client handles triggered alerts and is written to set/unset GPIO pins of a Raspberry Pi. This means it gets notified by the server if a sensor was triggered and can set/unset configured GPIO pins, for example, to activate a siren. However, the sensor can also just be used as a switch and the configured alert can switch on and off the configured GPIO pins.
[...]

AlertR Alert Client Raspberry Pi - Siren Tutorial

AlertR Manager Client Console

This tutorial describes the basic installation and configuration of the AlertR Manager Client Console. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Manager Client Console
-----------------------------
Instance:
managerClientConsole

Type:
manager

Version:
0.900-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 is a manager client for the AlertR system. It shows the current state of all sensors, the connected clients and if the currently active system profile.
[...]

AlertR Manager Client Console Tutorial

AlertR Manager Client Database

This tutorial describes the basic installation and configuration of the AlertR Manger Client Database. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Manager Client Database
------------------------------
Instance:
managerClientDatabase

Type:
manager

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: MySQLdb (pip packet: mysqlclient) (lowest version: 1.4.6)

Description:
This client stores the state of the AlertR system in a database for external usage. It uses a MySQL database to store all information about the AlertR system. External components, such as a website, can use the information in the database for their purposes. In the case of a website, it can process the data and show a visualization to the user. In order to let external components interact with the AlertR system, the manager client can set up a local UNIX socket server.
[...]

AlertR Manager Client Database Tutorial

AlertR Manager Client Keypad

This tutorial describes the basic installation and configuration of the AlertR Manager Client Keypad. It also shows a usual setup environment in which it can be used. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Manager Client Keypad
----------------------------
Instance:
managerClientKeypad

Type:
manager

Version:
0.900-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.
[...]

AlertR Manager Client Keypad Tutorial

AlertR Sensor Client Executer

This tutorial describes the basic installation and configuration of the AlertR Sensor Client Executer. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Sensor Client Executer
-----------------------------
Instance:
sensorClientExecuter

Type:
sensor

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)

Description:
This client handles scripts as sensors and informs the AlertR system if a sensor has triggered and/or the state of a sensor has changed. This means it executes configured scripts in an interval. Each sensor is basically a cronjob for the AlertR system. The sensor has two options to be triggered: 1) The sensor is triggered if the script exits with an exit code not equal to 0 or a time out. 2) The script outputs that the sensor should be triggered with the help of a well-defined protocol or a time out (see the developer tutorials for examples). For instance, you can execute a script that checks if the Internet connection is available and which triggers if no Internet connection is up.
[...]

AlertR Sensor Client Executer Tutorial

AlertR Sensor Client Executer - lm-sensors

This tutorial describes the integration of the Linux tool "lm-sensors" into the AlertR system. With the help of it, you are able to integrate all sensors that can be read by "lm-sensors" (for example CPU temperature) into your infrastructure and utilize them as any other of your AlertR sensor. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Sensor Client Executer
-----------------------------
Instance:
sensorClientExecuter

Type:
sensor

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)

Description:
This client handles scripts as sensors and informs the AlertR system if a sensor has triggered and/or the state of a sensor has changed. This means it executes configured scripts in an interval. Each sensor is basically a cronjob for the AlertR system. The sensor has two options to be triggered: 1) The sensor is triggered if the script exits with an exit code not equal to 0 or a time out. 2) The script outputs that the sensor should be triggered with the help of a well-defined protocol or a time out (see the developer tutorials for examples). For instance, you can execute a script that checks if the Internet connection is available and which triggers if no Internet connection is up.
[...]

AlertR Sensor Client Executer - lm-sensors Tutorial

AlertR Sensor Client FIFO

This tutorial describes the basic installation and configuration of the AlertR Sensor Client FIFO. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Sensor Client FIFO
-------------------------
Instance:
sensorClientFIFO

Type:
sensor

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)

Description:
This client is build for the integration of already developed scripts or other software into the AlertR system as a sensor. For each sensor it creates a FIFO file on the file system and monitors it. Other scripts/programs can write into the FIFO file to change the state of the associated sensor. For example, you can use a cronjob to write into the FIFO file at specific times to trigger a sensor event, or the ISC DHCP server can write into the FIFO file each time a client in a specific subnet requests an IP address, or a script can read the temperature of your thermostat periodically and can write it into the FIFO file. The possibilities to use this client to integrate other components into the AlertR system are endless.
[...]

AlertR Sensor Client FIFO Tutorial

AlertR Sensor Client GPS

This tutorial describes the basic installation and configuration of the AlertR Sensor Client GPS. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Sensor Client GPS
------------------------
Instance:
sensorClientGPS

Type:
sensor

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: Crypto (pip packet: pycryptodome) (lowest version: 3.10.1)
3: shapely (pip packet: Shapely) (lowest version: 1.7.1)

Description:
This client handles the GPS position of a device as a sensor. It allows you to build a geofence which triggers an alarm as soon as the device leaves it (or enters it). With this you can build home automation (e.g., turn on the thermostats as soon as I am coming home) as well as alarm systems for movable objects (e.g., car leaves the "home zone" in which it normally drives). Currently, only ChasR is supported as GPS provider (https://alertr.de/chasr).
[...]

AlertR Sensor Client GPS Tutorial

AlertR Sensor Client iCalendar

This tutorial describes the basic installation and configuration of the AlertR Sensor Client iCalendar. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Sensor Client iCalendar
------------------------------
Instance:
sensorClientICalendar

Type:
sensor

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: icalendar (pip packet: icalendar) (lowest version: 4.0.2)
3: dateutil (pip packet: python-dateutil) (lowest version: 2.7.3)
4: pytz (pip packet: pytz) (lowest version: 2019.3)

Description:
This client handles calendar services as a sensor. For this, reminders in this calendar are used to trigger sensor alerts. Every calendar service that gives the option to retrieve the calendar data as .ics file via an URL can be used with this sensor client. For example, you can combine this sensor client with your Google calendar to generate sensor alerts every time a reminder is triggered. These sensor alerts can then be instrumented by AlertR to perform a certain task (e.g., display a message on your Kodi media center setup). Furthermore, this allows you to generate a schedule in your calender which then trigger certain tasks in your AlertR system.
[...]

AlertR Sensor Client iCalendar Tutorial

AlertR Sensor Client Ping

This tutorial describes the basic installation and configuration of the AlertR Sensor Client Ping. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Sensor Client Ping
-------------------------
Instance:
sensorClientPing

Type:
sensor

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)

Description:
This client is specialized to just ping a server as a sensor and informing the AlertR system if a host is reachable or not. The sensor is triggered if the server is not reachable or a time out occur.
[...]

AlertR Sensor Client Ping Tutorial

AlertR Sensor Client Raspberry Pi - Switch (Polling)

This tutorial describes the basic installation and configuration of the AlertR Sensor Client Raspberry Pi. It focuses on connecting two switches (one switch that monitors a window and one mechanical switch) to the Raspberry Pi. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Sensor Client Raspberry Pi
---------------------------------
Instance:
sensorClientRaspberryPi

Type:
sensor

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: RPi.GPIO (pip packet: 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. Furthermore, this client also supports DS18B20 temperature sensors.
[...]

AlertR Sensor Client Raspberry Pi - Switch (Polling) Tutorial

AlertR Sensor Client Raspberry Pi - Door Bell (Interrupt)

This tutorial describes the basic installation and configuration of the AlertR Sensor Client Raspberry Pi. It focuses on connecting a door bell to the Raspberry Pi. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Sensor Client Raspberry Pi
---------------------------------
Instance:
sensorClientRaspberryPi

Type:
sensor

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: RPi.GPIO (pip packet: 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. Furthermore, this client also supports DS18B20 temperature sensors.
[...]

AlertR Sensor Client Raspberry Pi - Door Bell (Interrupt) Tutorial

AlertR Sensor Client Raspberry Pi - DS18B20

This tutorial describes the basic installation and configuration of the AlertR Sensor Client Raspberry Pi. It focuses on connecting two DS18B20 temperature sensors to the Raspberry Pi. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Sensor Client Raspberry Pi
---------------------------------
Instance:
sensorClientRaspberryPi

Type:
sensor

Version:
0.900-0

Dependencies:
1: requests (pip packet: requests) (lowest version: 2.20.0)
2: RPi.GPIO (pip packet: 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. Furthermore, this client also supports DS18B20 temperature sensors.
[...]

AlertR Sensor Client Raspberry Pi - DS18B20 Tutorial

AlertR Server

This tutorial describes the basic installation and configuration of the AlertR Server. The client is described as the following by the installation script:

sqall@towel:~$ ./alertRinstaller.py -l

[...]
AlertR Server
-------------
Instance:
server

Type:
server

Version:
0.900-0

Dependencies:
1: bcrypt (pip packet: bcrypt) (lowest version: 3.1.4)
2: requests (pip packet: requests) (lowest version: 2.20.0)

Description:
The server handles the logic of the AlertR system. It is mandatory in order to use AlertR. It uses SQLite as storage backend and a CSV file as user backend.
[...]

AlertR Server Tutorial

Developer - AlertR Sensor Client Executer Output

This tutorial describes how to create a basic script that is executed by the AlertR Sensor Client Executer and its exit code is processed by AlertR.

Developer - AlertR Sensor Client Executer Output Tutorial

Developer - AlertR Sensor Client Executer Processable Output

This tutorial describes how to create a basic script that is executed by the AlertR Sensor Client Executer and its output is processed by AlertR.

Developer - AlertR Sensor Client Executer Processable Output Tutorial

Developer - AlertR Sensor Client FIFO Write

This tutorial describes how to create a basic script that writes into a FIFO file provided by the AlertR Sensor FIFO Executer. With a FIFO file you can trigger an event in the AlertR system as soon as it occurs in contrast to the AlertR Sensor Client Executer which executes scripts in an interval.

Developer - AlertR Sensor Client FIFO Write

Developer - Calendar Schedule

This tutorial describes how you can use your calendar (for example your Google Calendar) as schedule for actions that are then executed by your AlertR system. As example scenario it explains how to setup your Google Calendar to use the reminders to switch on and off a light and to execute a script.

Developer - Calendar Schedule

Developer - Instrument Sensor Alerts on the Server

This tutorial describes how you can instrument every Sensor Alert event in AlertR on the server. As example scenario it explains how to setup a reminder for an open window in winter in order to not forget to close it.

Developer - Instrument Sensor Alerts on the Server

Developer - Instrument Sensor Alerts with Clients

This tutorial describes how you can instrument every Sensor Alert event in AlertR with a combination of AlertR clients. As example scenario it explains how to setup a reminder for an open window in winter in order to not forget to close it.

Developer - Instrument Sensor Alerts with Client