Infrastructure

Infrastructure

In this document a simple overview is given of the alertR infrastructure for version 0.500.

Table of Contents

alertR System Infrastructure

• Clients
  • Sensor Client
  • Alert Client
  • Manager Client
• Terminology
  • Node
  • Sensor
  • Alert
  • SensorAlert
  • AlertLevel
    • Example
• Push Notification

# alertR System Infrastructure

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 alarm is triggered, the server decides what to do next.

The general infrastructure is shown in the following image:

At the moment, there are 3 types of clients (so called nodes) in a general alertR infrastructure:

• Sensor
• Alert
• Manager

Also, all sensors and alerts provided by the sensor and alert clients are grouped in a so called alertLevels.

## Clients

This section explains each type of client alertR has.

### Sensor Client

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). Additionally, a sensor can also hold data such as a temperature. But this is optional and is not needed in many cases.

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 and not the details about what happened.

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 alertR. 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.

### Alert Client

The alert client is a client that gets informed by the server if a sensor has triggered and an alarm should be raised. It can be seen as the "executer" of alertR. The client can have one or more alerts that it can activate. An alert can be anything from a Raspberry Pi GPIO which is set to high and turns on a siren to making a call via an Asterisk server.

In the image above there are some cases for alerts. A D-Bus notification can be 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 ringed. The same goes for a XBMC (or now Kodi) notification. Also a movie or music that is played on XBMC can be paused when someone is at your door. Additionally, a webcam stream can be shown via picture in picture on a XBMC 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 alertR.

### Manager Client

The manager client is a client that gets informed about the state of the alertR system. It is used to give an overview about the current state of the monitoring and alarm system and all its sensors. Also the client is used to switch the activation state the alertR system.

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, and alertR can be activated/deactivated via the website. Or another example for a useful manager client for an home alarm system with alertR can be a client with a PIN keypad. This client allows the user to activate/deactivate the alertR system after 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.

## Terminology

This section explains some basic terminology that is necessary to understand and set up an alertR system.

### Node

A client that is connected to the alertR server is called node. Each node has a type. The current types are Sensor Client, Alert Client, and Manager Client.

### Sensor

A sensor provides the alertR system with a state for something. For example, a sensor can be a motion 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 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.

### SensorAlert

A sensorAlert is raised if a Sensor has reached a state that triggers an alarm (for example a motion sensor detected movement). For that, the Sensor changes its state from "normal" to "triggered" (note that sensorAlerts for changes from "triggered" to "normal" are also possible). The decision if an alarm state is reached is done by the Node that manages the Sensor. When the server received the information from the Sensor Client, it will check to which AlertLevel it belongs. Afterwards, it will inform all Alert Clients with the same AlertLevel that a sensorAlert for this AlertLevel occurred. To have a better notion how this works, please see the AlertLevel Example.

### Alert

An alert is an entity that reacts to a SensorAlert. For example, this can be a siren that is turned on when a SensorAlert occurred. Each alert is managed by an Alert Client. One Alert Client can have multiple alerts.

### AlertLevel

An alertLevel can be seen as a logical group of Sensors and Alerts. Whenever a Sensor triggers an alarm, all Alerts belonging to the same alertLevel will get informed about the SensorAlert. Each alertLevel is configured on the server side. All Sensors and Alerts are a member of at least one alertLevel. When a Sensor triggers an alarm, the client informs the server about it. Then the server looks up to which alertLevel this Sensor belongs and notifies all Alerts which also belong to this alertLevel. Naturally, Sensors and Alerts can belong to multiple alertLevels.

#### Example

A more detailed infrastructure overview is shown in this image:

In this image you can see that Sensors and Alerts belong to alertLevels. In order to understand the concept of alertLevels, an example is given in the following.

The server has configured two alertLevels.

alertLevel 1 has the name "Alarm" and has set the option "TriggerAlways" to "False". This means that this alertLevel only triggers an alarm when alertR is activated. This is useful for example when alertR is used as an home alarm system 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 alertLevel is configured to only trigger an alarm if an alarm for the state "triggered" is received ("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 "Rules Activated" is set to "False". AlertLevels can have complex rules which are chained via Boolean operators like AND or OR. With the help of this, you can create a complex rule set. For example, an alarm only triggers when multiple sensors have triggered at the same time, or motion detectors have triggered in a specific order, or a specific sensor has triggered on a specific day. But for this alertLevel it is not needed.

alertLevel 2 has the name "Notification". This alertLevel is set to trigger always and not only when alertR is activated. This can be useful for notifications. 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 alertLevel is configured to only trigger if an alarm for the state "triggered" is received and the rules are again deactivated.

Now let us take a look at the sensors and alerts. The sensor "Window Alarm" is set to trigger the alertLevels 1 and 2 and the sensor "Door Bell" the alertLevel 2. On the other side the alerts "D-Bus Notification" and "XBMC Notification" are set to belong to alertLevel 2. The alert "Siren" is set to belong to alertLevel 1.

When alertR is deactivated and the "Window Alarm" sensor is triggered, only alertLevel 2 triggers an alarm which means that only "XBMC Notification" and "D-Bus Notification" informs the user about the alarm. When alertR is activated, the "Window Alarm" sensor also activates the "Siren" alert. On the other hand, when the "Door Bell" sensor is triggered, the alerts "XBMC Notification" and "D-Bus Notification" always raise an alarm regardless of whether alertR is activated or not.

## Push Notification

alertR 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. The Alert Client will send a push notification to your devices when a sensor alert 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. However, in the unlikely event that a collision occurs or 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.