Infrastructure
In this document a simple overview is given of the AlertR infrastructure for version 0.900.
AlertR uses a client/server based infrastructure. The server contains all the logic and is informed by the clients of the state of the sensors. When a sensor triggers, the server decides what to do next.
The general infrastructure is shown in the following image:
At the moment, there are 4 types of instances/clients (so called nodes) in a general AlertR infrastructure:
- Server
- Sensor Client
- Alert Client
- Manager Client
Also, all sensors and alerts provided by the sensor and alert clients are grouped in a so called alertLevels.
This section explains each type of instances AlertR has.
The Server is the main component of the AlertR system. All clients connect to the it via a TCP connection. The server contains the logic that decides what to do when a sensor triggers and keeps track of the complete state of all components (state a sensor is in, data a sensor hold, clients connected, and so on).
The Sensor Client is a client that manages one or more sensors. The sensor can be anything from a Raspberry Pi GPIO pin to a command that is executed and its result is checked. It does not matter. Important for AlertR is that the sensor can be abstracted to either be "triggered" or "normal". When the sensor can be put into these states, it can be used by AlertR (for example an incoming phone call which can be triggered via an Asterisk server).
Furthermore, a sensor can hold data (for example, a temperature, a stock market value, and so on). However, holding data is completely optional.
In order to keep the server as simple as possible, the Sensor Client has to decide if a sensor has triggered an alarm or not. This means that the server only gets the information about "triggered"/"normal" states.
The image above shows some cases for sensors. For example, it can be a window/door alarm switch which will trigger when the window/door is opened. The door bell can be a sensor which triggers when someone rings the bell at your door. But not only hardware events can be sensors for an AlertR system. A simple ping can be used to test if a host is up (or your Internet connection). Also a script which tests a service of yours can be a sensor. Like mentioned before, there is no limitation of what a sensor can be as long as it can be abstracted to "triggered"/"normal" states.
The Alert Client is a client that gets informed by the server if an action should be performed. It can be seen as an "actuator" of the AlertR system (actually, the name "Alert" stems from the beginning of the AlertR system where it was originally planned as alarm system). The client can have one or more alerts that it can activate and deactivate. An alert can be anything from a Raspberry Pi GPIO which is used as a switch and set to high and low to making a call via an Asterisk server. The alerts perform an action when a Sensor Client tells the server that a sensor became "triggered" or became "normal" (depending on your configuration).
In the image above there are some cases for alerts. A D-Bus notification can be used as an alert for example. When someone rings at your door you can get a notification message on your PC via D-Bus that the door bell has rung. Or you can get a message when a stock market price is below/above a certain threshold or your Internet connection is down. The same goes for Kodi (former XBMC) notifications. Also a movie or music that is played on Kodi can be paused when someone is at your door. Additionally, a webcam stream can be shown via picture in picture on a Kodi system when someone rings at your door bell or a motion sensor has triggered. Again, as long as it can work with the "triggered"/"normal" state abstraction, it can be used by the AlertR system.
The Manager Client is a client that holds a copy of the state of the system. It is used to give an overview about the current state of the AlertR system and all its sensors. Also the client is used to change the used System Profile of the AlertR system (see System Profile in terminology for a description).
Again the image above shows some cases for a Manager Client. A web access portal can be a manager client. A website shows the state of the AlertR system, for example for mobile devices like an Android phone. Or another example for a useful manager client in an alarm system context with AlertR can be a client with a PIN keypad. This client allows the user to activate/deactivate the alarm system when the correct PIN has been entered on the keypad. Or for Linux PCs a small console manager client can give an overview about the current state of the system.
This section explains some basic terminology that is necessary to understand and set up an AlertR system.
An instance/component of the AlertR system is called Node. Each Node has a type. The current types for clients are Sensor Client, Alert Client, and Manager Client. The Server is a node in the AlertR system as well.
A Sensor provides the AlertR system with a state for something. For example, a Sensor can be a motion detection sensor. To be used as a Sensor for the AlertR system, the state that the Sensor holds must be abstractable to "triggered" and "normal". A Sensor is connected to a Sensor Client. Each Sensor Client must have on but can have multiple Sensors that provide the AlertR system with information.
Additionally, a Sensor can hold data. At the moment, a Sensor can hold no data, integer data, or float data. This data can be used to check values such as the current temperature in a room.
A Sensor Alert is an event raised if a Sensor changes its state (for example a motion detection sensor detected movement). The Sensor then changes its state, for example, from "normal" to "triggered". If the Sensor decides that it is no longer "triggered" and changes back to the "normal" state, a Sensor Alert event is raised as well. The decision if an Sensor Alert event is raised is done by the Node that manages the Sensor. When the server receives the information from the Sensor Client, it will process it and decide what to do.
An Alert is an actuator that performs an action when a Sensor Alert event is received from the server. For example, this can be a switch that is turned on when a Sensor Alert for a "triggered" state in a sensor occurred. If afterwards a Sensor Alert event for a "normal" state in a sensor is received, the switch could be turned off again. Each Alert is managed by an Alert Client which has at least one but can have multiple Alerts configured.
A System Profile is a global state in which the AlertR system currently operates. This allows the AlertR system to behave differently when a Sensor becomes "triggered" depending which System Profile is currently used. For example, when AlertR is used in an alarm system context, a System Profile called "Activated" and a System Profile called "Deactivated" can be set up. The AlertR system has to configure at least one System Profile but can have multiple.
Originally, when AlertR was designed as a simple alarm system, it had two global states ("Activated" and "Deactivated"). However, this generalization to System Profiles allows for more flexibility (for example, in cases where no distinction between "Activated" and "Deactivated" is needed or when using AlertR in an alarm system context, one can set up three System Profiles called "Activated", "Deactivated", and "Home and Secure").
An Alert Level is a logical group of Sensors and Alerts (when AlertR was originally designed as simple alarm system it was a level, hence the name). Whenever a Sensor triggers a Sensor Alert event, all Alerts belonging to the same Alert Level will get informed about the Sensor Alert. Each Alert Level is configured on the server side. All Sensors and Alerts are a member of at least one Alert Level, but can be a member of multiple ones.
Each Alert Level is a member of at least one System Profile, but can be part of multiple ones. This allows the AlertR system to behave differently when a Sensor Alert event is received by the server. More specifically, this means that depending on the System Profile currently used by the AlertR system, the Alerts get informed of the Sensor Alert event or not.
This section gives an example and describes how everything works together. In this example, the AlertR system is used in an alarm system context. A detailed infrastructure overview is shown in this image:
In this image you can see that Alerts and Sensors are members of Alert Levels. Furthermore, Alert Levels are members of System Profiles.
The server has configured two Alert Levels configured, as well as two System Profiles called "Activated" and "Deactivated" since we use the AlertR system in an alarm system context.
Alert Level 1 has the name "Alarm" and is member of the System Profile "Activated". This means that this Alert Level only forwards a Sensor Alert event to all corresponding Alerts when the AlertR system uses the System Profile "Activated" as global state. This is useful in an alarm system context and you monitor if windows are opened or not. Surely, you only want an alarm raised if you are not at home and not each time when you open a window yourself. Furthermore, the Alert Level is configured to only forward a Sensor Alert event to all corresponding Alerts if a Sensor Alert event for the state "triggered" is received by a Sensor ("Alarm 'triggered': True"), but not for the state "normal" ("Alarm 'normal': False"). This is also useful for the windows example above. An alarm should only be raised when the window was opened, but not when it was closed. Additionally, the option "Instrumentation Activated" is set to "False". This is a feature for more advanced users that gives them great flexibility and modification possibilities. However, the details of this feature are unnecessary to understand the basics of an AlertR system. In short: Alert Levels can have an instrumentation script given which is executed when a Sensor Alert event for this Alert Level is received. This instrumentation script then gets the content of the Sensor Alert, processes it, and returns a result. The result can be anything from a modified Sensor Alert to a suppressed Sensor Alert hat should not be handled.
Alert Level 2 has the name "Notification". This Alert Level is a member of the System Profiles "Activated" and "Deactivated" and thus will always forward a received Sensor Alert regardless of the System Profile the AlertR system currently uses. For example, when someone rings at your door bell you always want to be notified at your PC and not only when the alarm system is activated. Also, the Alert Level is configured to only trigger if a Sensor Alert event for the state "triggered" is received and the instrumentation is again deactivated.
Now let us take a look at the Sensors and Alerts. The Sensor "Window Alarm" is set to trigger the Alert Levels 1 and 2 and the Sensor "Door Bell" only the Alert Level 2. On the other side, the Alerts "D-Bus Notification" and "Kodi Notification" are member of Alert Level 2. The Alert "Siren" is only member of Alert Level 1.
When the AlertR system uses the System Profile "Deactivated" and the "Window Alarm" Sensor changes its state to "triggered", only Alert Level 2 issues a Sensor Alert event which means that only "Kodi Notification" and "D-Bus Notification" informs the user about the alarm. When the AlertR system uses the System profile "Activated", the "Window Alarm" Sensor also activates the "Siren" Alert. On the other hand, when the "Door Bell" Sensor changes its state to "triggered", the Alerts "Kodi Notification" and "D-Bus Notification" always get a Sensor Alert event regardless of the currently used System Profile.
The AlertR system is able to send push notifications to Android devices using Google Firebase and the AlertR Android App. In order to use this feature you have to create an account at alertr.de and install the AlertR Alert Client Push Notification in your AlertR system. The Alert Client will send a push notification to your devices when a Sensor Alert event is received. The infrastructure for this service uses an end-to-end encryption. This means it is built in such a way that the notifications can not be read by anyone but you (and anyone you want them to read). The following image shows the infrastructure:
The received Sensor Alert will be encrypted with a secret that is shared between the AlertR Alert Client Push Notification and your Android devices. This ensures that neither the alertr.de push service nor the Google Firebase service is able to read the notification. The notification will be sent on a channel that you choose. The channel is used to be able to receive the same notification on multiple devices you own or want to be able to receive the notification. In order to prevent multiple uses of the same channel by different users and therefore collisions, the channel is linked to your alertr.de account. In the unlikely event that an attacker is able to deduce your used channel, only devices that know your used secret are able to decrypt the notification. Therefore, he or she is not able to read your notifications. This is shown in the infrastructure image as an example. An attacker subscribes for the channel "MyAlarm" that is used by another user. The notification is encrypted with the secret "MySecret". But only the device using this secret is able to decrypt the notification.