PersonalFME

Internet-Gateway für die analoge Funkalarmierung

personalfme

Dokumentation

Version 1.1.0

Ralf Rettig

veröffentlicht: "2023-01-14 13:30:28 +0000" (rev. 4793f3c)


Kapitel 1. Features

  • Software zum Empfang von Fünftonfolgen des analogen BOS-Funks, besonders geeignet für Minicomputer wie den Raspberry Pi

  • Sehr hohe Zuverlässigkeit der Tonfolgenerkennung

  • Getestet im Dauerbetrieb (>100 Tage)

  • Auswertung des Funksignals über die Soundkarte

  • Integriertes Gateway zum Weiterleiten der Alarmierungen über das Internet per Messenger-App (mittels www.Groupalarm.de) und E-Mail

  • Ansteuerung von externen Programmen und Skripten (z.B. für Torsteuerungen, optische Alarmierungen)

  • Versand der Alarmdurchsage per E-Mail

  • Flexible Konfiguration von Alarmierungen, Probealarmen und zeitabhängigen Alarmierungen (z.B. nachts, am Wochenende, Infoalarme) über eine XML-Datei

  • Erfüllt die relevanten Anforderungen der Technischen Richtlinie der BOS für Geräte für die Funkalarmierung

  • Erweiterung um zusätzliche Audioformate über Plugins möglich

  • Lauffähig unter Linux und Windows

Kapitel 2. Erste Schritte

Installation und Voraussetzungen

Das Programm benötigt für die Auswertung des Funksignals eine Soundkarte. Prinzipiell sind Soundkarten mit 48 000 Hz Maximalfrequenz geeignet. Die beste Rauschbeständigkeit bei schlechtem Empfang ergibt sich bei mindestens 96 000 Hz Maximalfrequenz. PC-Soundkarten erfüllen dies in der Regel.

Warnung

Rechtlicher Hinweis: Es wird darauf hingewiesen, dass das willentliche unbefugte Erlangen von Informationen aus nicht-öffentlichen Funkdiensten, z.B. der Behörden und Organisationen mit Sicherheitsaufgaben (BOS) strafbar ist. Dies gilt auch für die Auswertung von Fünftonfolgen. Die vorschriftsgemäße Benutzung des Programms liegt allein in der Verantwortung des Nutzers.

Linux

Die Software stellt folgende Voraussetzungen an Ihr System:

  • fertig eingerichtetes Linux-System inklusive Soundkarte (z.B. Raspberry Pi 3 Modell B mit Cirrus Logic Audio Card), siehe „Raspberry Pi“
  • pulseaudio Soundserver eingerichtet im Systemmodus mit hoher Prozesspriorität, siehe „Pulseaudio-Konfiguration im Systemmodus“
  • kompiliertes Binärpaket von personalfme für Ihr System

Ohne eine Konfiguration des Soundservers pulseaudio im Systemmodus ist lediglich ein Betrieb von personalfme im Vordergrund möglich.

Unter Rasberry Pi OS (Debian) 11 Bullseye ist die Erzeugung des Binärpakets aus dem Quellcode relativ einfach. Laden Sie diesen zunächst herunter:

					$ sudo apt-get -y update
					$ sudo apt install -y git
					$ git clone https://github.com/erl987/personalfme
					$ cd personalfme
					$ git submodule update --init --recursive
					$ git checkout tags/v1.1.0
				

Konfigurieren Sie dann das Buildsystem:

					$ sudo apt install build-essential cmake openssl libssl-dev
					$ sudo apt install portaudio19-dev libxerces-c-dev libsndfile-dev
					$ sudo apt install libalglib-dev ncurses-dev
					$ sudo apt install libboost-all-dev libpoco-dev
					$ cd path/to/personalfme
					$ mkdir build
					$ cd build
					$ cmake -DCMAKE_BUILD_TYPE=Release ..
				

Jetzt kann personalfme übersetzt und das Binärpaket erzeugt werden ("n" steht dabei für die Anzahl der eingesetzten CPU-Kerne):

					$ make -jn
					$ sudo make package
				

Weil personalfme für den Betrieb als Hintergrunddienst etliche Einstellungen benötigt, empfiehlt sich unbedingt die Installation über das Binärpaket. Danach sollte der Hintergrunddienst personalfme laufen und beim Systemstart automatisch gestartet werden.

					$ sudo dpkg -i personalfme_1.1.0-1_amd64.deb
					$ sudo apt-get -f install
				

Sofern das Audiosystem noch nicht für den Systemmodus von Pulseaudio eingerichtet wurde, wird der Hintergrunddienst von personalfme zunächst nicht laufen. Nähere Informationen zur Einrichtung finden sich hier: „Pulseaudio-Konfiguration im Systemmodus“.

Entfernt werden kann das Paket durch folgenden Befehl (ohne die Konfigurationsdateien):

					$ sudo apt-get remove personalfme
				

Oder vollständig durch:

					$ sudo apt-get purge personalfme
				

Aufgrund der Vielzahl von Distributionen und Architekturen werden für personalfme keine fertigen Binärpakete zur Verfügung gestellt. Das Programm wurde für Rasperry Pi OS 11, Debian 11 Bullseye und Ubuntu 22.04 LTS getestet.

Windows

Die Software benötigt die Laufzeitbibliothek für C++ 2022 (Visual C++ Redistributable for Visual Studio 2022, x86). Falls noch nicht vorhanden, kann die Installationsdatei vc_redist.x86.exe unter folgender Internetadresse heruntergeladen werden: https://aka.ms/vs/17/release/vc_redist.x86.exe. Nach dessen Installation wird die Software personalfme selbst durch Ausführen des Installationspaketes personalfme-1.1.0--win32.exe installiert. Sie läuft unter 32-bit und 64-bit Microsoft Windows 8.1 und allen neueren Windows-Betriebssystemen. Das Programm lässt sich durch die Verknüpfung im Startmenü vollständig deinstallieren. Dabei werden die Daten und Einstellungen im Arbeitsverzeichnis nicht gelöscht.

Konfiguration für die erste Benutzung

Die Bedienung des Programms ist auf allen Betriebssystemen identisch. Es wird über die zentrale XML-Konfigurationsdatei config.xml gesteuert. Unter Linux wird diese Datei im Verzeichnis /etc/personalfme und unter Windows im Verzeichnis personalfme innnerhalb des Ordners Dokumente und Einstellungen des Benutzers (z.B. C:\Users\UserName\Documents\personalfme) gespeichert. Vorlagen für die Konfiguration liegen im Ordner personalfme\beispiele bereit.

Anmerkung

Falls bei einem Update schon eine XML-Konfigurationsdatei config.xml vorhanden war, wird diese bei der Installation nicht überschrieben. Eventuelle Syntaxänderungen aufgrund der neuen Version müssen manuell durchgeführt werden. Das Installationsprogramm informiert darüber, ob dies nötig sein könnte. Die jeweils aktuelle Konfiguration ist in diesem Handbuch beschrieben.

Das Programm ist mit den installierten Standardeinstellungen bereits lauffähig und zeichnet damit sämtliche Alarmierungen auf. Beachten Sie dazu die rechtlichen Hinweise! Eine Quelle für Verzögerungen bei der Alarmierung kann die tägliche Resynchronisation eines DSL-Anschlusses sein. Allerdings versucht personalfme automatisch über einen längeren Zeitraum die Alarmierung zuzustellen. Falls das Programm nicht läuft, erhalten Sie im nächsten Kapitel Hinweise für die Eingrenzung des Problems.

Linux

Der Demon personalfme wird über systemd gesteuert. Mit dem folgenden Befehl kann die Funktionsfähigkeit überprüft werden:

					$ sudo systemctl status personalfme
				

Die Ausgabe sollte als Status active (running) ergeben, z.B.:

					personalfme.service - Selcall internet gateway daemon
					   Loaded: loaded (/lib/systemd/system/personalfme.service; ...
					   Active: active (running) since Fr 2016-07-22 19:58:10 ...
					  Process: 948 ExecStart=/usr/bin/personalfme -r config.xml ...
							(code=exited, status=0/SUCCESS)
					 Main PID: 971 (personalfme)
					   CGroup: /system.slice/personalfme.service
							   └─971 /usr/bin/personalfme -r config.xml --daemon

					Jul 22 19:58:09 ubuntu systemd[1]: Starting Selcall internet ...
					Jul 22 19:58:10 ubuntu systemd[1]: Started Selcall internet ...
				

Sofern nicht schon vorher der Benutzer fme-daemon für die Benutzung der Soundkarte freigegeben wurde, wird personalfme zunächst nicht starten. In diesem Fall muss die im Kapitel „Pulseaudio-Konfiguration im Systemmodus“ beschriebene Konfiguration noch umgesetzt werden.

Windows

Achten Sie darauf, dass für den nun folgenden Funktionstest das Audiokabel eingesteckt ist. Testen Sie, ob das Programm über die Desktopverknüpfung personalfme startet.

personalfme eignet sich für den Dauerbetrieb. Daher hat es einen Eintrag im Autostart-Menü. Damit erfolgt automatisch ein Start des Programms (mit der Konfigurationsdatei config.xml) nach einem Neustart. Bedenken Sie, dass automatische Updates bei Windows regelmäßig zu Neustarts führen. Währenddessen ist personalfme nicht verfügbar.

Bedienung des Programms

personalfme ist als Gateway für den Dauerbetrieb konzipiert und wird daher unter aller Betriebssystemen über die Kommandozeile gesteuert. Unter Windows gibt es eine Desktopverknüpfung PersonalFME Kommandozeile, die automatisch in das richtige Verzeichnis für die Bedienung führt. Die Programmbefehle lauten unter allen Betriebssystemen:

BefehlBeschreibung

personalfme -r config.xml

oder:

personalfme -r „/etc/personalfme/config.xml“

bzw.

personalfme -r „C:\Users\config.xml“

Startet die Auswertung des Funksignals. Wenn die Konfigurationsdatei ohne Pfad angegeben ist, wird davon ausgegangen, dass sie im Konfigurationsverzeichnis (siehe personalfme –pwd) liegt.
personalfme -a Gibt die verfügbaren Audiogeräte aus. Achten Sie darauf, dass das Audiokabel eingesteckt ist.
personalfme -hGibt eine Hilfe aus.
personalfme -pwdGibt das Konfigurationsverzeichnis des Programms (den Ordner personalfme) aus.

personalfme -t config.xml

oder:

personalfme -t „/etc/personalfme/config.xml“

bzw.

personalfme -t „C:\Users\config.xml“

Testet die Konfigurationsdatei ohne die Auswertung zu starten. Wenn die Konfigurationsdatei ohne Pfad angegeben ist, wird davon ausgegangen, dass sie im Konfigurationsverzeichnis (siehe personalfme –pwd) liegt.

personalfme -vGibt die Versions- und Copyright-Informationen aus.

Die Alarmierungen und alle relevanten Vorgänge und Fehlermeldungen werden in der Datei personalfme_log.txt unter Linux im Log-Verzeichnis /var/log/personalfme bzw. unter Windows im Arbeitsverzeichnis personalfme protokolliert. Die Datei ist als UTF-8 kodiert. Für eine korrekte Darstellung der Umlaute benötigen Sie einen UTF-8 fähigen Editor, unter Windows z.B. Notepad++. Der Standardeditor von Windows ist dafür nicht geeignet.

Testen Sie zunächst eine neu erstellte Konfigurationsdatei über den Aufruf von personalfme –t “config.xml”. Damit lassen sich mögliche Fehler in der XML-Datei ermitteln. Bei einer expliziten Angabe des kompletten Pfades kann die Konfigurationsdatei in jedem Ordner liegen.

Schließen Sie vor dem Start des Programms unter Windows zunächst das Audiokabel an die Soundkarte an, andernfalls werden die Soundgeräte nicht erkannt und Sie erhalten eine Fehlermeldung.

Anmerkung

Stellen Sie Lautstärke Ihres Funkempfängers bzw. die Verstärkung durch die Soundkarte eher leise und keinesfalls zu hoch ein. Wenn das Eingangssignal übersteuert ist, könnten Alarmierungen nicht korrekt erkannt werden. Wenn Sie starke Verzerrungen und Knacken in den Aufnahmen Ihrer Alarmdurchsagen haben, ist dies ein deutlicher Hinweis. Ein zu leises Signal wird automatisch digital auf die optimale Lautstärke angepasst. Soundkarten haben einen analogen und einen digitalen Verstärker, unter Linux ist die Einstellung der analogen Verstärkung (PGA) eventuell schwierig zu finden.

Die folgende Tabelle gibt einen Überblick über die relevanten Verzeichnisse unter verschiedenen Betriebssystemen:

BeschreibungLinuxWindows
Konfigurationsverzeichnis. Enthält die XML-Konfigurationsdatei config.xml. /etc/personalfme C:\Users\UserName\Documents\personalfme
Log-Dateiverzeichnis. Enthält die Protokolldatei von personalfme. /var/log/personalfme C:\Users\UserName\Documents\personalfme
Datenverzeichnis. Enthält die aufgezeichneten Audiodateien der Alarmierungen. /var/lib/personalfme C:\Users\UserName\Documents\personalfme

Linux

Unter Linux wird der Dauerbetrieb über einen systemd-Demon sichergestellt. In Übereinstimmung mit den Konventionen wird unter Linux der Programmname personalfme benutzt. Weitere Informationen können nach der Installation auch der manpage man personalfme entnommen werden.

Anmerkung

Das Programm kann auch im Vordergrund, z.B. mit personalfme -r config.xml gestartet werden.

Der Systemdienst kann folgendermaßen gestartet bzw. gestoppt werden:

					$ sudo systemctl start personalfme
					$ sudo systemctl stop personalfme
				

Überprüfen Sie nach jedem Start, ob der Dienst auch wirklich läuft:

					$ sudo systemctl status personalfme
				

Der Status sollte active (running) sein. Ein Neustart des Dienstes ist nach einer Anpassung der XML-Konfigurationsdatei nötig, damit die Änderungen wirksam werden:

					$ sudo systemctl restart personalfme
				

Kapitel 3. Konfiguration des Programms

Anmerkung

Die Anwendungsbeispiele in diesem Kapitel gelten sowohl für Windows als auch für Linux.

Das Programm wird vollständig über eine einzige XML-Konfigurationsdatei config.xml gesteuert. Die folgende einfache Datei reicht für die Standardeinstellungen:


<?xml version="1.0" encoding="UTF-8"?>

<config	xmlns="http://www.personalfme.de/v1"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.personalfme.de/v1
		C:/Users\Benutzer\AppData\Roaming\PersonalFME\schema\config.xsd">

<protocol default="on"/>
<!--Hier kann der Benutzer seine Konfiguration einfügen-->
</config>

	

Damit werden alle Alarmierungen protokolliert und deren Alarmdurchsagen aufgezeichnet, jedoch keine Nachrichten versendet.

Anmerkung

Die Pfadangabe für die XML-Schema-Datei (im Beispiel: C:/Users\Benutzer\AppData\Roaming\PersonalFME\schema\config.xsd) wird von PersonalFME ignoriert und kann daher beliebige Angaben erhalten.

Der Benutzer erstellt die eigentliche Konfiguration zwischen den <config>-Auszeichnern. Die XML-Datei muss UTF-8 kodiert sein, damit die Umlaute korrekt wiedergegeben werden. Stellen Sie das in Ihrem Editor sicher. Empfehlenswert ist z.B. der freie Editor Notepad++. Sofern in wenigen Fällen nicht anders angegeben, ist die Reihenfolge der Auszeichner beliebig. Benutzen Sie für Ihre Konfiguration die Vorlage complex_config.xml im Ordner PersonalFME\beispiele.

Ein Beispiel für eine umfangreiche Konfigurationsdatei ist:


<?xml version="1.0" encoding="UTF-8"?>

<config	xmlns="http://www.personalfme.de/v1"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.personalfme.de/v1
		C:/Users\Benutzer\AppData\Roaming\PersonalFME\schema\config.xsd">

	<audio>
		<driver>MME</driver>
		<device>Microsoft Soundmapper - Input</device>
	</audio>
	<voiceCaptureTime>30</voiceCaptureTime>
	<protocol default="off"/>
	<audioFormat>Ogg</audioFormat>
	<minDetectionDist>10</minDetectionDist>
	<playTone>false</playTone>

	<logins>
		<email>
			<smtpServer>mail.gmx.net</smtpServer>
			<port>465</port>
			<security type="TLS"/>
			<authentification type="simplePassword">
				<user>user@gmx.de</user>
				<password>passwort</password>
			</authentification>
			<senderName>Funkalarm</senderName>
			<senderMailAddress>user@gmx.de</senderMailAddress>
			<trials>10</trials>
			<waitTime>60</waitTime>
			<connections>1</connections>
		</email>
	</logins>

	<alarms>
		<all>
			<default>
				<alarms>
					<infoalarm>
						<email>
							<organization>Einsatzleitung</organization>
							<unit>OrgL</unit>
							<recipient>
								<address>test2@test2.de</address>
							</recipient>
							<message>Alarmierung ausgelöst.</message>
							<attachVoice>false</attachVoice>
						</email>
					</infoalarm>
				</alarms>
			</default>
		</all>
		<code call="12345">
			<default>
				<alarms>
					<email>
						<organization>HiOrg OV A-Dorf</organization>
						<unit>Alarmgruppe A</unit>
						<recipient>
							<address>test@test.de</address>
						</recipient>
						<message>Einsatz für die Alarmgruppe A.</message>
						<attachVoice>true</attachVoice>
					</email>
				</alarms>
			</default>

			<weeklyException>
				<validity>
					<validWeeks>
						<week>5</week>
					</validWeeks>
					<weekday>Fr</weekday>
					<begin>10:05:00</begin>
					<end>10:20:00</end>
				</validity>
				<alarms>
					<email>
						<organization>HiOrg OV A-Dorf</organization>
						<unit>SEG</unit>
						<recipient>
							<address>test2@test2.de</address>
						</recipient>
						<message>Probealarm</message>
						<attachVoice>false</attachVoice>
					</email>
				</alarms>
			</weeklyException>
		</code>
	</alarms>
</config>

	

Im Folgenden werden alle möglichen Einstellungen gegliedert nach den Abschnitten der XML-Datei erläutert.

Basiseinstellungen

In den Basiseinstellungen werden die grundlegenden Funktionalitäten gesteuert. Sämtliche Einstellungen haben hier Standardwerte und können daher auch wegelassen werden.

Syntax:


<audio>
	<driver>MME</driver>
	<device>Microsoft Soundmapper - Input</device>
</audio>
<voiceCaptureTime>25</voiceCaptureTime>
<protocol default="off"/>
<audioFormat>Ogg</audioFormat>
<minDetectionDist>10</minDetectionDist>
<playTone>false</playTone>

			

Soundkarteneinstellung (<audio>)

Standard (wenn wegelassen): Standardaudiogerät des Systems

In fast allen Anwendungsfällen kann diese Einstellung weggelassen und das Standardgerät benutzt werden. Eine mögliche Ausnahme sind Notebooks, deren Standardgerät evtl. ein Umgebungsmikrofon und nicht die Mikrofonbuchse ist.

Einstellungsmöglichkeiten:

  • <driver>: Name des benutzten Soundkartentreibers (unter Windows in der Regel MME, WASAPI, …; unter Linux meist ALSA)
  • <device>: Name des benutztes Audiogeräts / -ausgangs

Es reicht aus, den Namen soweit in Kleinbuchstaben anzugeben, dass er eindeutig ist. Die verfügbaren Audiogeräte und -treiber werden in der PersonalFME-Kommandozeile über den folgenden Befehl ermittelt: PersonalFME –a

				C:\Program Files (x86)\PersonalFME\bin>personalfme -a

				Verfügbare Audio-Eingabegeräte:

				Treiber: MME
				- Microsoft Soundmapper - Input
				- FrontMic (Realtek High Definiti (-----> Standardgerät)
			

Wenn kein Audiokabel einsteckt ist, erhalten Sie die folgende Ausgabe:

				C:\Program Files (x86)\PersonalFME\bin>personalfme -a

				Fehler:
				Kein Audio-Eingabegerät verfügbar. Eventuell ist in der
				Mikrofonbuchse kein Kabel eingesteckt.
			

Länge der Sprachaufzeichnung nach einer Alarmierung (<voiceCaptureTime>)

Standard (wenn weggelassen): 30 Sekunden

Einstellungsmöglichkeiten: Länge der Sprachaufzeichnung in Sekunden. Die Sprachaufzeichnung kann nicht ausgeschaltet werden, d.h. eine Angabe von 0 Sekunden ist nicht zulässig.

Protokollierung fremder Alarmierungen (<protocol>)

Standard (wenn weggelassen): Protokollierung fremder Alarmierungen ist ausgeschaltet ("off")

Einstellungsmöglichkeiten:

  • <protocol default="on"/>: Alle erkannten Alarmierungen werden protokolliert und die Alarmdurchsage aufgenommen.
  • <protocol default="off"/>: Ausschließlich die Alarmschleifen, die im Block <alarms> eingetragen sind, werden protokolliert sowie deren Sprachdurchsage aufgenommen.

Warnung

Rechtlicher Hinweis: Benutzen Sie die Einstellung <protocol default="on"/> nur, wenn Sie zur Aufzeichnung sämtlicher Alarmierungen auf dem Funkkanal befugt sind. Das Protokollieren bzw. Aufzeichnen fremder Alarmierungen stellt eine bewusstes Mithören dar und ist strafbar.

Audio-Dateiformat (<audioFormat>)

Standard (wenn weggelassen): WAV-Format

Einstellungsmöglichkeiten:

  • <audioFormat>WAV</audioFormat>: WAV-Format (unkomprimiert)
  • <audioFormat>Ogg</audioFormat>: Ogg Vorbis-Format (komprimiert)

Das WAV-Format benötigt deutlich mehr Speicherplatz und E-Mail-Übertragungen dauern länger, allerdings kann es von den meisten Betriebssystemen standardmäßig abgespielt werden. Das Ogg Vorbis-Format ist ein komprimiertes Format und benötigt wesentlich weniger Speicherplatz (ca. um den Faktor 5), jedoch kann die Datei unter Windows nur mit geeigneter Software abgespielt werden (z.B. VLC Media Player oder RealPlayer). Auf dem mobilen Betriebssystem Android funktioniert dies ohne zusätzliche Software. Falls weitere Audio-Plugins installiert sind, können die weiteren Formate analog angegeben werden.

Unterdrückung von Mehrfachalarmierungen (<minDetectionDist>)

Standard (wenn weggelassen): keine Unterdrückung von Mehrfachalarmierungen (0 Sekunden)

Einstellungsmöglichkeiten: Angabe der Zeit in Sekunden, in der nach einer erkannten Alarmierung für diese Tonfolge jede weitere Alarmierung unterdrückt wird. Damit wird vermieden dass bei wiederholten Fünftonfolgen (z.B. durch einen Alarmumsetzer) doppelte Alarmierungen versandt werden. In vielen Fällen sind 10 Sekunden eine gute Wahl.

Alarmton bei einer Alarmierung (<playTone>)

Standard (wenn weggelassen): kein Alarmton

Einstellungsmöglichkeiten:

  • <playTone>false</playTone>: kein Alarmton
  • <playTone>true</playTone>: Alarmton des Systems (Beep) nach Erkennen einer Alarmierung

Logineinstellungen für den Nachrichtenversand

Syntax:


<logins>
	<email>
		<!--Einstellungen für Emails-->
	</email>
	<groupalarm2>
		<!--Einstellungen für Groupalarm-->
	</groupalarm2>
	<external>
		<!--Einstellungen für externe Programmaufrufe-->
	</external>
</logins>

			

Für jedes Alarmierungs-Gateway mit Netzwerkverbindung (Groupalarm, E-Mail) ist jeweils die Angabe der notwendigen Login-Daten im Auszeichner <logins> erforderlich. Im Auszeichner <alarms> wird dann festgelegt, bei welchen Fünftonfolgen welche Nachrichten versandt werden. Außerdem kann ein anderes Verhalten während eines Probealarms festgelegt werden. Nicht benötigte Alarmierungsarten werden weggelassen.

Allgemeine Einstellungsmöglichkeiten (außer für das Starten externer Programme):

  • <trials>: Anzahl der Sendeversuche bei fehlender Verbindung.

    Standard (wenn weggelassen): 10 Versuche

  • <waitTime>: Anzahl der Sendeversuche bei fehlender Verbindung.

    Standard (wenn weggelassen): 60 Sekunden

  • <connections>: Anzahl der parallelen Verbindungen. Dies ist eine Spezialoption für Experten. Nur in wenigen Fällen ist es sinnvoll, mehr als eine parallele Verbindung zu nutzen.

    Standard (wenn weggelassen): 1 Verbindung

Für die meisten Anwender sind die Standardoptionen angemessen und diese Auszeichner können daher meist weggelassen werden. U.a. wird durch die wiederholten Sendeversuche sichergestellt, dass ein Versand der Nachrichten mit geringer Zeitverzögerung auch bei einer Resychronisation einer DSL-Leitung stattfindet.

E-Mail (<email>)

Syntax:


<email>
	<smtpServer>mail.gmx.net</smtpServer>
	<port>465</port>
	<security type="TLS"/>
	<authentification type="simplePassword">
		<user>user@gmx.de</user>
		<password>passwort</password>
	</authentification>
	<senderName>Funkalarm</senderName>
	<senderMailAddress>user@gmx.de</senderMailAddress>
	<trials>10</trials>
	<waitTime>60</waitTime>
	<connections>1</connections>
</email>

				

Die folgenden notwendigen Angaben sind vom E-Mail-Provider zu erfahren.

  • <smtpServer>: SMTP-Servername
  • <port>: Server-Port
  • <security>: Verschlüssung der Verbindung.

    Verfügbare Optionen:
    • <security type="TLS"/>: TLS/SSL-Verschlüsselung (Standardport: 465)
    • <security type="TLSSTART"/>: TLSSTART-Verschlüsselung (Standardport: 587). Falls keine verschlüsselte Verbindung zustande kommt, wird der Verbindungsaufbau abgebrochen.
    • <security type="none"/>: Keine Verschlüsselung (Standardport: 25). Nur innerhalb sicherer Netze zu empfehlen.
  • <authentification>: Authentifizierung des Benutzers

    Standard (wenn weggelassen): keine Authentifizierung

    Verfügbare Optionen:
    • <authentification type="simplePassword">: Authentifizierung über unverschlüsseltes Password und Benutzername
    • <authentification type="encryptedPassword">: Authentifizierung über verschlüsseltes Password und Benutzername
    Anzugeben sind jeweils:

    <user>: Benutzername

    <password>: Passwort

    Warnung

    Das Passwort des E-Mail-Accounts wird unverschlüsselt in der XML-Konfigurationsdatei gespeichert. Sorgen Sie durch Festlegung der Benutzerrechte und Begrenzung des Zugangs zum Rechner dafür, dass das Passwort geschützt bleibt. Geben Sie die XML-Konfigurationsdatei nicht mit Ihrem Passwort weiter.
  • <senderMailAddress>: E-Mail-Adresse des Absenders
  • <senderName>: Absendername. Optional, kann weggelassen werden. Beispiel:
    
    <senderName>Funkalarm</senderName>
    <senderMailAddress>alarm@test.de</senderMailAddress>
    
    						
    Führt zu folgender Absenderangabe:
    Funkalarm <alarm@test.de>

Groupalarm (<groupalarm2>)

www.groupalarm.de ist ein kostenpflichtiger externer Dienst für den schnellen Versand von Gruppenalarmierungen über eine Messenger-App und auch traditionelle Telefondienste. Detaillierte Informationen zur Konfiguration von Groupalarm gibt es unter: https://docs.groupalarm.de, die Konfiguration Ihrer Organisation erfolgt unter https://app.groupalarm.com.

Syntax:


<groupalarm2>
	<organizationid>12345</organizationid>
	<apitoken>U&s4j4&tw!rw5*w6NPWB9^sL3M6Gx</apitoken>
	<proxy>
		<address>proxy.orga.de</address>
		<port>8080</port>
		<username>user</username>
		<password>passwd</password>
	</proxy>
	<trials>10</trials>
	<waitTime>60</waitTime>
	<connections>1</connections>
</groupalarm2>

				

  • <organizationid>: ID Ihrer Organisation bei Groupalarm ("Organisation" -> ... -> "Einstellungen" auf https://app.groupalarm.com)
  • <apitoken>: Der Schlüssel zum Auslösen eines Alarms (Sie können Ihren API-Schlüssel unter "Admin" -> "Berechtigungen" -> "API-Schlüssel" erzeugen). Geben Sie dem API-Schlüssel einen sinnvollen Namen wie z.B. PersonalFME.

    Warnung

    Der API-Schlüssel funktioniert wie ein Passwort und sollte entsprechend behandelt werden. Jeder kann mit diesem Schlüssel Alarmierungen auslösen. Er wird unverschlüsselt in der XML-Konfigurationsdatei gespeichert. Sorgen Sie durch Festlegung der Benutzerrechte und Begrenzung des Zugangs zum Rechner dafür, dass der Schlüssel nicht in falsche Hände gerät. Geben Sie die XML-Konfigurationsdatei nicht mit Ihrem Passwort weiter.
  • <proxy>: Proxy-Server

    Standard (wenn weggelassen): Keine Nutzung eines Proxy-Servers

    Einstellungen:

    • <address>: Name des Proxy-Servers
    • <port>: Port des Servers

      Standard (wenn weggelassen): Port 8080

    • <username>: Benutzername für den Proxy-Server

      Standard (wenn weggelassen): kein Benutzername

    • <password>: Passwort für den Proxy-Server

      Standard (wenn weggelassen): kein Passwort

    In vielen Einrichtungen ist der Datenverkehr ins Internet nur über einen Proxy-Server möglich.

Externe Programme / Skripte (<external>)

Abweichend von den Gateways die auf Netzwerkverbindungen beruhen, gibt es nur die folgende optionale Einstellungsmöglichkeit:
  • <maxSessions>: Maximale Anzahl der gleichzeitig laufenden externe Programme, die durch eine Alarmierung gestartet wurden

    Standard (wenn weggelassen): maximal 10 gleichzeitige Programmausführungen

Beispiel:

<logins>
	<external>
		<maxSessions>15</maxSessions>
	</external>
</logins>

			
In den meisten Fällen reicht die folgende minimale Konfiguration mit den Standardeinstellungen aus:

<logins>
	<external/>
</logins>

			

Anmerkung

Es können nur so viele externe Programme bzw. Skripte gleichzeitig ausgeführt werden wie im Auszeichner <maxSessions> festgelegt. Dies betrifft nur die Situation, wenn mehrere Alarmierungen kurz hinteinander Programmausführungen starten und diese länger laufen. Bei Bedarf kann der Standardwert auch erhöht werden.

Nachrichtenversand

Für jede Fünftonfolge für die eine Nachricht versandt werden soll, muss im Block <alarms> ein Block im Format <code call="12345"> vorhanden sein.

Syntax:


<alarms>
	<all>
		<!--Optionale Alarmierungen, die immer ausgelöst werden-->
	</all>
	<fallback>
		<!--Optionale Alarmierungen, die ausgelöst werden wenn keine andere für diese Fünftonfolge ausgelöst wird-->
	</fallback>
	<code call="12345">
		<default>
			<alarms>
				<groupalarm2>
					<!--Groupalarm-Nachricht-->
				</groupalarm2>
			</alarms>
		</default>
		<weeklyException>
			<validity>
				<!--Gültigkeit des Probealarms-->
			</validity>
			<alarms>
				<email>
					<!--E-Mail-Nachricht-->
				</email>
			</alarms>
		</weeklyException>
		<monthlyException>
			<!--monatliche Ausnahme-->
		</monthlyException>
		<singleTimeException>
			<!--einmalige Ausnahme-->
		</singleTimeException>
	</code>
	<code call="23456">
		<!--weitere Alarmschleife-->
	</code>
</alarms>

			

Jeder Block <code call="12345"> muss zunächst einen Block <default> enthalten. Dieser definiert die Alarmierungen die immer dann ausgeführt werden, wenn gerade keine Ausnahme gültig ist. Danach können die Ausnahmen (z.B. Probealarme) in beliebiger Anzahl und Reihenfolge definiert werden.

Alarmierung unter Normalbedingungen (<default>)

Innerhalb des Auszeichners <alarms> werden die auszulösenden Alarmierungen definiert. Es können beliebig viele Groupalarm- und E-Mail-Nachrichten definiert werden (also auch mehrere von einem Typ). Wenn unter Normalbedingungen kein Nachrichtenversand erfolgen soll, muss der Auszeichner trotzdem angegeben werden, bleibt jedoch leer:


<code call="12345">
	<default/>
</code>

					

In diesem Fall wird die Alarmierung trotzdem protokolliert und die Alarmdurchsage aufgenommen (auch wenn <protocol default="off"/>).

Alarmierungen bei Ausnahmen (z.B. bei Probealarmen, Wochenenden, nachts)

Folgende Ausnahmen stehen zur Verfügung.

  • Wochentägliche Ausnahme (<weeklyException>): Probealarm / Ausnahme an einem bestimmten Wochentag, z.B. an jedem Sonntag um 19:00 Uhr, am 1. Samstag im Monat um 10:00 Uhr, oder in jeder Nacht von Freitag 18:00 Uhr bis 24:00 Uhr.
  • Monatliche Ausnahme (<monthlyException>): Probealarm / Ausnahme an einem bestimmten Tag des Monats, z.B. an jedem 1. des Monats um 13:00 Uhr.
  • Einmalige Ausnahme (<singleTimeException>): Einmaliger Zeitraum, z.B. während eines Urlaubs vom 05.01.2016 00:00 Uhr – 12.01.2016 00:00 Uhr.

Es können beliebig viele Ausnahmen definiert werden. Dadurch lassen sich auch komplexere Szenarien konstruieren (z.B. andere Alarmierungen während der Nacht, am Wochenende, …).

Jede Ausnahme benötigt einen Block <validity> in welchem die zeitliche Gültigkeit festgelegt wird. Im Block <alarms> werden die zu versendenden Nachrichten festgelegt. Hier gelten dieselben Regeln wie für den Auszeichner <default>. Es sind beliebig viele Nachrichten möglich. Falls während des Ausnahmezeitraums alle Alarmierungen unterdrückt werden sollen, muss der Auszeichner leer bleiben (also: <alarms/>).

Für alle Arten von Ausnahmen werden die Beginn- und Enduhrzeit wie folgt festgelegt:

  • <begin>: Beginn des Probealarms / Ausnahme (Uhrzeit), z.B. <begin>10:05:00</begin>
  • <end>: Ende des Probealarms / Ausnahme (Uhrzeit), z.B. <end>10:20:00</end>. Die angegebene Uhrzeit zählt nicht mehr zur Ausnahme. Das Beispiel bedeutet also, dass die Ausnahme ab 10:20:00 nicht mehr gilt. Für Mitternacht kann 24:00:00 angegeben werden.

Wochentägliche Ausnahme <weeklyException>

Die Gültigkeit beträgt maximal 24 Stunden ab dem Beginn. Bei Bedarf können mehrere Ausnahmen hintereinander gehängt werden. Wenn die Uhrzeit im Auszeichner <end> vor der im Auszeichner <begin> liegt, endet die Ausnahme am nächsten Tag.

Syntax:


<weeklyException>
	<validity>
		<validWeeks>
			<week>5</week>
		</validWeeks>
		<weekday>Fr</weekday>
		<begin>10:05:00</begin>
		<end>10:20:00</end>
	</validity>
	<alarms>
		<!--Alarm-Nachrichten-->
	</alarms>
</weeklyException>

					

Einstellungsmöglichkeiten:

  • <validWeeks>: Wochen des Monats in denen der Probealarm / die Ausnahme gültig ist.
    • entweder für jede Woche des Monats:
      
      <validWeeks>
      	<all/>
      </validWeeks>
      
      										
    • oder unter einzelner Angabe der Wochen (hier z.B. 1. und 3. Woche):
      
      <validWeeks>
      	<week>1</week>
      	<week>3</week>
      </validWeeks>
      
      										
      Dabei steht 5 für die letzte Woche des Monats, je nach Monat also entweder die 4. oder die 5. Woche.
  • <weekday>: Wochentag an dem der Probealarm / die Ausnahme gültig ist. Die Angabe erfolgt mit den deutschen Abkürzungen: Mo, Di, Mi, Do, Fr, Sa, So.

Monatliche Ausnahme <monthlyException>

Die Gültigkeit beträgt maximal 24 Stunden ab dem Beginn. Bei Bedarf können mehrere Ausnahmen hintereinander gehängt werden. Wenn die Uhrzeit im Auszeichner <end> vor der im Auszeichner <begin> liegt, endet die Ausnahme am nächsten Tag.

Falls der Tag in einem Monat nicht existiert, wird die Ausnahme ausgelassen (z.B. 31. des Monats).

Syntax:


<monthlyException>
	<validity>
		<validMonths>
			<month>3</month>
		</validMonths>
		<day>3</day>
		<begin>13:00:00</begin>
		<end>13:10:00</end>
	</validity>
	<alarms>
		<!--Alarm-Nachrichten-->
	</alarms>
</monthlyException>


					

Einstellungsmöglichkeiten

  • <validMonths>: Monate in denen der Probealarm / die Ausnahme gültig ist:
    • entweder für jeden Monat des Jahres:
      
      <validMonths>
      	<all/>
      </validMonths>
      
      								
    • oder unter einzelner Angabe der Monate (Beispiel: 6. und 12. Monat)
      
      <validMonths>
      	<month>6</month>
      	<month>12</month>
      </validMonths>
      
      								
  • <day>: Tag im Monat an dem der Probealarm / die Ausnahme gültig ist

Einmalige Ausnahme <singleTimeException>

Syntax (die Reihenfolge muss eingehalten werden):


<singleTimeException>
	<validity>
		<beginDate>2016-01-05</beginDate>
		<begin>10:00:00</begin>
		<endDate>2016-01-27</endDate>
		<end>20:00:00</end>
	</validity>
	<alarms>
		<!--Alarm-Nachrichten-->
	</alarms>
</singleTimeException>

					

Einstellungsmöglichkeiten

  • <beginDate>: Datum des Beginns. Angabe im Format: JJJJ-MM-TT (mit JJJJ = Jahr, MM = Monat, TT = Tag), z.B. für den 05.01.2016: <beginDate>2016-01-05</beginDate>
  • <endDate>: Datum des Endes. Angabe im Format: JJJJ-MM-TT.

Zudem müssen die Uhrzeit des Beginns und des Endes angegeben werden.

E-Mails <email>

Syntax (hier ist die Reihenfolge strikt einzuhalten):


<email>
	<organization>HiOrg OV A-Dorf</organization>
	<unit>SEG</unit>
	<recipient>
		<address>test2@test2.de</address>
	</recipient>
	<message>Probealarm</message>
	<attachVoice>false</attachVoice>
</email>

				

Einstellungsmöglichkeiten:

  • <organization>: Bezeichnung der Einrichtung, z.B. HiOrg A-Dorf
  • <unit>: Bezeichnung der alarmierten Einheit, z.B. SEG. Die versandte E-Mail erhält dann den Betreff Einsatzalarmierung HiOrg A-Dorf, SEG bzw. Probealarm HiOrg A-Dorf, SEG.
  • <recipient>: Empfänger der E-Mail nach dem Schema:
    
    <recipient>
    	<name>Helfer 1</name>
    	<address>helfer1@test.de</address>
    </recipient>
    <recipient>
    	<name>Helfer 2</name>
    	<address>helfer2@test.de</address>
    </recipient>
    
    						
    Es können beliebig viele Empfänger hintereinander angegeben werden. Die Angabe des Namens (<name>) ist optional.
  • <message>: Text, welcher in der E-Mail übermittelt wird. Umlaute sind möglich (UTF-8 kodiert).
  • <attachVoice>: Versand mit / ohne Sprachaufzeichnung:
    • <attachVoice>true</attachVoice>: Versand mit Alarmdurchsage
    • <attachVoice>false</attachVoice>: Versand ohne Alarmdurchsage

    Es kann gewählt werden, ob die E-Mail inklusive der Alarmdurchsage versandt wird. Ohne diese Option wird die E-Mail sofort nach dem Alarmeingang versandt, andernfalls unmittelbar nach Ende der Sprachaufzeichnung (Länge definiert im Auszeichner <voiceCaptureTime>).

Groupalarm (<groupalarm2>)

Syntax (ein Groupalarm-Event pro <groupalarm2>-Tag):


<groupalarm2>
	<alarm>
		<!--<template>SEG-Alarm</template>-->
		<definition>
			<resources>
				<!--<all/>-->
				<units>
					<unit>B</unit>
				</units>
				<labels>
					<label>
						<label>Kraftfahrer</label>
						<amount>1</amount>
					</label>
					<label>
						<label>CBRN</label>
						<amount>2</amount>
					</label>
				</labels>
				<scenarios>
					<scenario>SEG-Alarm</scenario>
				</scenarios>
				<persons>
					<person>
						<firstName>Max</firstName>
						<lastName>Mustermann</lastName>
					</person>
				</persons>
			</resources>
			<message type="template">SEG-Alarm</message>
		</definition>
	</alarm>
	<eventOpenPeriodInHours>2.5</eventOpenPeriodInHours>
</groupalarm2>

				

Einstellungsmöglichkeiten

  • <template>: Benutzung einer Alarmvorlage von Groupalarm (Best-Effort Alarmierung). Die Auswahl aller alarmierten Resourcen sowie der Alarmachricht erfolgt unter "Konfiguration" -> "Alarmvorlagen". In diesem Fall wird der Eventname immer durch die Alarmvorlage bestimmt.
  • <definition>: Detaillierte Definition der alarmierten Resourcen:
    • <resources>: Definition der Alarmempfänger (Best-Effort Alarmierung). Es können entweder beliebige Kombinationen von Einheiten, Personen, usw. oder Vollalarm ausgelöst werden.
      • <all>: Vollalarm für alle Mitglieder der Organisation. Keine anderen Resourcen können ausgewählt werden.
      • <units>: Alarm an die definierten Einheiten bei Groupalarm (<unit>). Hier wird der Name der Einheit angegeben (wie z.B. "B" oder "FGr_N", die Einstellung erfolgt unter "Konfiguration" -> "Einheiten").
      • <labels>: Alarm an die definierten Labels von Groupalarm. Dies sind definierte Funktionen über Einheiten hinweg, z.B. für Kraftfahrer (<label>). Angegeben werden jeweils der Name des Labels (definiert unter "Konfiguration" -> "Labels") sowie die benötigte Anzahl.
      • <scenarios>: Alarmierung von definierten Szenarien von Groupalarm. Dies sind Kombinationen von z.B. verschiedenen Einheiten. Angegeben werden jeweils der Name des Szenarios (<scenario>, definiert unter "Konfiguration" -> "Szenarien").
      • <persons>: Alarm an die definierten Teilnehmer von Groupalarm (<name>), definiert unter "Konfiguration" -> "Teilnehmer").
    • <message>: Definition der Alarmnachricht. Es bestehen folgende Wahlmöglichkeiten:
      • <message type="template">: Vordefinierte Groupalarm-Nachricht, angegeben wird der Name der Textvorlage ("Konfiguration" -> "Textvorlagen").
      • <message type="freeText">: Frei definierte Nachricht:

        Beispiel: <message type="freeText">Probealarm für die SEG.</message>

  • <eventOpenPeriodInHours>: Die Alarmierung wird nach dem angegeben Zeitraum geschlossen. Zum Beispiel stehen nach diesem Zeitraum die alarmierten und zugesagten Kräfte wieder für neue Alarmierungen zur Verfügung. Für Details wird auf die Dokumentation von Groupalarm verwiesen.

Externe Programme / Skripte (<external>)

Es können beliebige externe Programme oder auch Skripte (z.B. Python-Skripte) ausgeführt werden. Es wird lediglich erwartet, dass sie bei erfolgreicher Ausführung den Wert 0 zurückgeben. Ein anderer Wert signalisiert einen Fehler.

Syntax:


<external>
	<command>python script.py</command>
	<arguments>"Argument 1" $CODE "$TIME" $TYPE</arguments>
</external>

				

Einstellungsmöglichkeiten

  • <command>: Programmbefehl (z.B. programm.exe oder python). Das Programm muss mit einem absoluten Pfad angegeben werden oder über eine Umgebungsvariable erreichbar sein.
  • <arguments>: Programmargumente in beliebiger Anzahl, verfügbar sind auch die folgenden Platzhalter:
    • $CODE: alarmierte Schleife, z.B. "25634"
    • $TIME: Uhrzeit der Alarmierung im Format "Sonntag, 04.12.2016 18:30:50"
    • $TYPE: Art der Alarmierung (entweder "Einsatzalarmierung" oder "Probealarm")

Anmerkung

Sämtliche Ausgaben des externen Programms werden lediglich über die Standardausgabe angezeigt und nicht protokolliert. Im Fehlerfall wird jedoch eine Nachricht auf Basis des Rückgabewerts des Programms protokolliert.

Mehrere externe Programme sind möglich, diese werden diese parallel aufgerufen. Es können auch länger laufende Programme genutzt werden. Insgesamt in die Anzahl der gleichzeitig laufenden Programminstanzen standardmäßig auf zehn begrenzt (für eine Änderung siehe „Externe Programme / Skripte (<external>)“). Es empfiehlt sich, den Platzhalter für die Uhrzeit in Anführungszeichen zu setzen um diesen trotz Leerzeichen als ein einziges Argument zu übergeben.

Spezielle Alarmnachrichten

Die Elemente <all> und <fallback> sind optional und dienen zur Konfiguration von Alarmnachrichten, die nicht auf eine einzelne Alarmschleife beschränkt sind.

Auslösung für sämtliche Fünftonfolgen (<all>)

Hier können Alarmnachrichten definiert werden, die für sämtliche eingehende Alarmierungen versandt werden. Zum Beispiel können damit Infoalarme für Führungskräfte oder Torsteuerungen realisiert werden. Innerhalb eines <all>-Elements können sämtliche Alarm-Gateways wie auch sämtliche Ausnahmen genauso wie für einzelne Alarmschleifen benutzt werden (siehe „Nachrichtenversand“).

Syntax:


	<alarms>
		<all>
			<default>
				<alarms>
					<infoalarm>
						<email>
							<!--Definition der Alarmnachricht-->
						</email>
					</infoalarm>
					<external>
						<!--Definition der Alarmnachricht-->
					</external>
				</alarms>
			</default>

			<!--Beliebige Ausnahmen können definiert werden-->
			<weeklyException>
				<!--Definition der Ausnahme-->
			</weeklyException>
		</all>

		<code call="12345">
			<!--Alarmierungen für die einzelnen Fünftonfolgen-->
		</code>
	</alarms>

				

Die hier definierten Ausnahmen sind völlig unabhängig von den Alarmierungen für die einzelnen Alarmschleifen. Der Status "Einsatzalarmierung" bzw. "Probealarm" wird jedoch ausschließlich durch die ausgelöste Alarmschleife bestimmt. Eine Ausnahme bestimmt bei <all> lediglich die ausgelöste Aktion. Zusätzlich zu den verfügbaren Gateways können hier auch sogenannte Infoalarme versandt werden:

Infoalarme <infoalarm>

Syntax:


<infoalarm>
	<email>
		<!--Definition der Alarmnachricht-->
	</email>
</infoalarm>

					

Infoalarme können ausschließlich innerhalb eines <all>-Elements benutzt werden. Ein Infoalarm bedeutet, dass bei jeglichem erkannten Alarm die innerhalb des <infoalarm>-Elements definierte Nachricht versandt wird. Es können sämtliche Gateways für den Versand von Infoalarmen benutzt werden und es sind auch mehrere Infoalarme möglich. Jedoch müssen diese separat in mehreren <infoalarm>-Elementen definiert werden.

Ein Infoalarm enthält folgende Informationen:

  • ausgelöste Alarmschleife, z.B. "25634"
  • Alarmzeitpunkt
  • Art der Alarmierung (entweder "Einsatzalarmierung" oder "Probealarm")
  • nur bei E-Mail: Liste der sonstigen ausgelösten Alarmierungen
  • nur bei Groupalarm: Zusammenfassung der ausgelösten Alarmierungen
  • nur bei externen Programmaufrufen: keine weiteren Informationen

Auslösung als Rückfallebene (<fallback>)

In diesem Element können Alarmnachrichten definiert werden, die immer dann ausgelöst werden wenn keine andere Nachricht für die Alarmschleife ausgelöst wird. Das Kriterium ist dabei der Alarmzeitpunkt, da zum Beispiel zu bestimmten Zeitpunkten Alarmierungen aufgrund von Ausnahmen unterdrückt sein könnten. Die Alarmnachrichten in einem eventuellen <all>-Element bleiben unberücksichtigt.

Syntax:


<alarms>
	<fallback>
		<default>
			<alarms>
				<email>
					<!--Definition der Alarmnachricht-->
				</email>
				<groupalarm2>
					<!--Definition der Alarmnachricht-->
				</groupalarm2>
			</alarms>
		</default>

		<!--Beliebige Ausnahmen können definiert werden-->
		<weeklyException>
			<!--Definition der Ausnahme-->
		</weeklyException>
	</fallback>

	<code call="12345">
		<!--Alarmierungen für die einzelnen Fünftonfolgen-->
	</code>
</alarms>

				

Innerhalb des <fallback>-Elements gilt genau die gleiche Syntax wie bei der Definition von Alarmnachrichten für spezifische Codes (siehe „Nachrichtenversand“). Eine versandte Nachricht ist für den Empfänger nicht von anderen Nachrichten unterscheidbar, d.h. sie enthält die identischen Informationen.

Typische Fehlerquellen

Die XML-Dateien werden vor der Verwendung durch den XML-Parser validiert, d.h. auf ihre Korrektheit überprüft. Daher ist es nicht möglich, dass fehlerhafte Konfigurationsdateien in das Programm geladen werden. Überprüfen Sie dennoch sorgfältig Benutzernamen, Passwörter, … da diese durch den Parser nicht überprüft werden können.

Zur Vermeidung einer fehlerhaften Konfiguration folgt eine Einführung in XML in aller Kürze.

Die XML-Konfigurationsdatei von PersonalFME muss immer mit dem folgenden Header beginnen:


<?xml version="1.0" encoding="UTF-8"?>

<config	xmlns="http://www.personalfme.de/v1"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://www.personalfme.de/v1
			C:/Users\Benutzer\AppData\Roaming\PersonalFME\schema\config.xsd">

			

Dementsprechend muss sie mit dem Endauszeichner </config> enden.

Sämtliche Blöcke stehen zwischen einem Beginn- <block> und einem Endauszeichner </block>. Wenn ein Block leer ist, kann auch folgendermaßen abgekürzt werden: <block/>.

Der XML-Parser erzeugt Fehlermeldungen in englischer Sprache. Dabei wird immer die Zeile (line) und die Spalte (column) angegeben, in der der Fehler erkannt wurde. Es empfiehlt sich, den Bereich um diese Angaben herum genau mit der Dokumentation zu vergleichen um den Fehler zu finden. Eine typische Ausgabe ist:

			XML-parser error:
			file:   C:\Users\Benutzer\Documents\PersonalFME\config.xml
			line:   55, column: 11
			error:  element 'email' is not allowed for content model
					'All(groupalarm2?,email?,external?)'
			

Liste der inkompatiblen Änderungen der Konfigurationsdateien

In den folgenden Versionen wurden Änderungen an der Syntax der XML-Konfigurationsdatei durchgeführt, die nicht abwärtskompatibel sind:

  • Version 0.2.1: neue vereinfachte Syntax für Groupalarm-Auslösungen (Auszeichner: <groupalarm>)
  • Version 1.1.0: neue Syntax für den neuen Dienst von Groupalarm.de (Auszeichner: <groupalarm2>), <groupalarm> wurde entfernt.

Kapitel 4. Konfiguration eines Linux-Systems für personalfme

personalfme unterstützt ab Version 0.2.1 Linux. Ein zuverlässiger Dauerbetrieb ist möglich. Unter Linux ist eine spezielle Konfiguration des Soundsystems notwendig, damit personalfme als Hintergrundprozess laufen kann. Dieses Kapitel bezieht sich auf Raspberry Pi OS 11 und Debian 11 Bullseye. Versionen vor personalfme 1.0.0 unterstützen auch Raspbian (Debian) 9 Stretch, Raspbian (Debian) 8 Jessie sowie Ubuntu 16.04 LTS. Im Falle eines Minicomputers ist eventuell die Nachrüstung unbedingt benötigter Komponenten nötig.

Abhängigkeiten

personalfme benötigt die folgenden Abhängigkeiten zu anderen Paketen:
PaketVersionverfügbar in Debian 8 Jessieverfügbar in Debian 9/10/11
libalglib-dev>= 3.8jaja
libboost-dev>= 1.59neinja
libc6 >= 2.14jaja
libgcc1 >= 1:4.0jaja
libncurses5>= 5.5jaja
libpoco-dev (libpocofoundation, libpoconet, libpoconetssl, libpocoutil)>= 1.6.0neinja
libportaudio2>= 19+svn20101113jaja
libsndfile1>= 1.0.20jaja
libstdc++6>= 5jaja
libxerces-c3.1>= 3.1jaja

Pulseaudio-Konfiguration im Systemmodus

Hintergrunddienste können vom pulseaudio-Soundserver ausschließlich im Systemmodus Daten von der Soundkarte erhalten. Deshalb muss die Standardinstallation von pulseaudio umkonfiguriert werden.

Warnung

Die Entwickler von pulseaudio raten auf allen Systemen - ausgenommen eingebetteten Systemen - aus Sicherheitsgründen von der Nutzung des Systemmodus ab. Aus diesem Grund sollte personalfme ausschließlich auf eingebetteten Systemen ohne echte Benutzer (z.B. auf einem Minicomputer) als Hintergrundprozess genutzt werden.

pulseaudio wird zunächst standardmäßig wie folgt installiert (sofern noch nicht vorhanden):

					$ sudo apt-get install pulseaudio
				

Für den Systemmodus sind die folgenden Neueinträge in der Datei /etc/pulse/daemon.conf nötig, welche die entsprechenden Standardeinstellungen überschreiben:

					daemonize = yes
					system-instance = yes
					exit-idle-time = -1
				

Nur auf dem Raspberry Pi sind die folgenden zusätzlichen Änderungen sinnvoll:

					resample-method = speex-fixed-4
					default-sample-rate = 96000
				

Weiterhin muss in der Datei /etc/pulse/client.conf der folgende Eintrag hinzugefügt werden:

					autospawn = no
				

Damit pulseaudio zuverlässig auch bei hoher Systemlast läuft, muss eine hohe Prozesspriorität zugelassen werden. Dazu muss der Benutzer pulse in die Datei /etc/security/limits.conf eingetragen werden:

					pulse 	- nice		-11
					pulse 	- rtprio	99
				

Im Systemmodus werden die für die Soundkarte zugelassenen Benutzer über die Mitgliedschaft in der Gruppe fme-daemon gesteuert. Fügen Sie den Benutzer des personalfme Demons zu dieser Gruppe zu:

					$ sudo usermod -a -G pulse-access fme-daemon
				

Dieser Benutzer wird bei der Installation der Software neu angelegt. Anschließend kann für pulseaudio ein Demon installiert werden. Standardmäßig ist keiner vorhanden, eine systemd Konfigurationsdatei liegt im Verzeichnis /linux/debian des Sourcecodes von personalfme bereit.

					$ sudo cp ./linux/debian/pulseaudio.service /lib/systemd/system
					$ sudo systemctl enable pulseaudio.service
					$ sudo systemctl start pulseaudio.service
					$ sudo systemctl status pulseaudio.service
				

pulseaudio sollte nun im Systemmodus laufen und beim Systemstart automatisch gestartet werden.

Raspberry Pi

Die Software personalfme kann zuverlässig auf Minicomputern eingesetzt werden. In diesem Kapitel werden Hinweise zur Installation auf einem Raspberry Pi 3 gegeben. Die Systemlast im Hintergrundbetrieb liegt bei etwa 5 - 10%. Als Besonderheit verfügt der Raspberry Pi über keine Soundkarte und keine Echtzeituhr. Diese müssen entsprechend nachgerüstet werden. Als geeignet hat sich z.B. folgende Konfiguration erwiesen:

  • Raspberry Pi 3 Modell B
  • Cirrus Logic Audio Card
  • PiFace SHIM Realtime Clock Board für Raspberry Pi

Als Betriebssystem bietet sich Raspberry Pi OS 11 an. Mittlerweile steht für die Cirrus Logic Audio Card ein Treiber im Standardkernel zur Verfügung. Damit ist die Installation relativ einfach geworden. Eine genaue Beschreibung findet sich auf dieser Webseite: http://www.horus.com/~hias/cirrus-driver.html. Für den Betrieb als Audiorecorder ist es notwendig, einmal ein "Use Case Script" Record_from_Linein.sh auszuführen, um die Soundkarte entsprechend zu konfigurieren. Näheres ist im oben genannten Link beschrieben.

Anmerkung

Sollte es zu Übersteuerungen kommen, welche sich durch starkes Knacken im Audiosignal äußern, kann die analoge Verstärkung ("Volume") durch Anpassung des "Use Case Scripts" Record_from_Linein.sh verändert werden. Die digitale Verstärkung ("Digital Volume") spielt dabei keine Rolle, da personalfme die Lautstärke automatisch anpasst.
					# Datei "Record_from_Linein.sh"
					record_from_line 0
					# Beispiel für eine analoge Verstärkung von 0 dB
				
Die Standardeinstellung ist +8 dB und kann laut Datenblatt des Soundchips von 0 dB bis +31 dB in 1dB-Stufen angepasst werden. Es ist zweckmäßig, die analoge Verstärkung beim Auftreten von Übersteuerungen auf 0 dB zu reduzieren, d.h. abzuschalten.

Die Echtzeituhr muss zunächst ebenfalls konfiguriert werden: http://www.piface.org.uk/assets/piface_clock/PiFaceClockguide.pdf bzw. https://github.com/piface/PiFace-Real-Time-Clock. Ohne Echtzeituhr startet der Raspberry Pi mit der letzten gespeicherten Zeit und aktualisiert seine Zeit nur über das Internet. Für eine zuverlässige Alarmierung und Bewertung von Probealarmen muss aber zu jedem Zeitpunkt die korrekte Zeit vorliegen.

Kapitel 5. Lizenzen

Dieses Programm steht unter der GNU General Public License Version 3 oder einer neueren Version. Das Programm darf daher frei weitergegeben und verändert werden, solange der Quellcode frei zugänglich bleibt. Der Autor übernimmt keinerlei Verantwortung für das korrekte Funktionieren der Software und eventuelle Folgen aus einem Programmfehler.

Warnung

Es wird darauf hingewiesen, dass das willentliche unbefugte Erlangen von Informationen aus nicht-öffentlichen Funkdiensten, z.B. der Behörden und Organisationen mit Sicherheitsaufgaben (BOS) strafbar ist. Dies gilt auch für die Auswertung von Fünftonfolgen. Die vorschriftsgemäße Nutzung des Programms liegt allein in der Verantwortung des Nutzers.

Copyright (c) 2010-2023 Ralf Rettig

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Lizenzen von Drittsoftwarekomponenten

PortAudio Portable Real-Time Audio Library

Copyright (c) 1999-2011 Ross Bencina and Phil Burk

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND ON INFRINGEMENT.

IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Alglib

Copyright (c) Sergey Bochkanov (ALGLIB project)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Libsndfile

Copyright (c) 2005-2015 Erik de Castro Lopo ()

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) version 3.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Libvorbis

Copyright (c) 2002-2015 Xiph.org Foundation

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

- Neither the name of the Xiph.org Foundation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Apache Xerces

This product includes software developed by The Apache Software Foundation (http://www.apache.org/).

Portions of this software were originally based on the following:

- software copyright (c) 1999, IBM Corporation., http://www.ibm.com.

Libexpat

Copyright (c) 1998-2000 Thai Open Source Software Center Ltd and Clark Cooper

Copyright (c) 2001-2022 Expat maintainers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

FLAC

Copyright (C) 2000-2009 Josh Coalson

Copyright (C) 2011-2022 Xiph.Org Foundation

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

- Neither the name of the Xiph.Org Foundation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LAME MP3 Encoder

Copyright (C) 2000 Don Melton

Copyright (C) 2011-2017 Robert Hegemann

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

MPG123

Copyright (c) 1995-2020 by Michael Hipp and others, free software under the terms of the LGPL v2.1

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

OPUS

Copyright 2001-2011 Xiph.Org, Skype Limited, Octasic,

Jean-Marc Valin, Timothy B. Terriberry,

CSIRO, Gregory Maxwell, Mark Borgerding,

Erik de Castro Lopo

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

- Neither the name of Internet Society, IETF or IETF Trust, nor the names of specific contributors, may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Opus is subject to the royalty-free patent licenses which are specified at:

Xiph.Org Foundation: https://datatracker.ietf.org/ipr/1524/

Microsoft Corporation: https://datatracker.ietf.org/ipr/1914/

Broadcom Corporation: https://datatracker.ietf.org/ipr/1526/