#########################################################################################################
# Titel: SDS2DB-Beschreibung.txt
# Autor: Michael Kaden
# Datum: 22.11.2015
#
# Copyright (C) 2015 Michael Kaden
#
# Dieses Programm ist freie Software. Sie knnen es unter Beachtung der Nutzungsbedingungen benutzen, 
# weitergeben und modifizieren.
# Die Verffentlichung dieses Programms erfolgt in der Hoffnung, dass es Ihnen von Nutzen sein wird, 
# aber OHNE IRGENDEINE GARANTIE, sogar ohne die Garantie der MARKTREIFE oder der VERWENDBARKEIT FR EINEN 
# BESTIMMTEN ZWECK.
##########################################################################################################


Einfhrung
----------

SDS2DB ist ein Linux-Programm, das auf einem PC/Server als Hintergrunddienst(Daemon) luft und die von mittels PEI-Schnittstelle(n) verbundenen Tetra-Funkgert(en) empfangenen SDS-Meldungen in eine MySQL-Datenbank schreibt.


Entwicklungsstand / Zuverlssigkeit / Support
---------------------------------------------

SDS2DB wurde/wird seit 2012 fr den eigenen Anwendungszweck in Freizeit entwickelt und ist kein professionelles Produkt eines Software-Entwicklers. SDS2DB luft in meinem Anwendungsfall, unter Debian-"Squeeze" sowie Debian-"Jessi", lnger als 2 Jahre produktiv und ohne Abstrze.
Ich leiste keinen Support fr SDS2DB und empfehle die Installation und Benutzung des Programms nur Benutzern, die tiefergehende Kenntnisse in der Einrichtung und Benutzung von Linux-Systemen auf der Kommando-Konsole (ohne grafische Oberflche) haben. 


Programm-/Verzeichnis-Struktur
------------------------------

SDS2DB besteht aus verschiedenen Linux-(Bash-)Shellskripten. Die Verzeichnisstuktur zeigt sich wie folgt:

/etc/init.d/sds2db -> symbolischer Link zu /usr/local/sds2db/etc/init.d/sds2db
/usr/local/sds2db/SDS2DB-Beschreibung -> Programmbeschreibung
/usr/local/sds2db/SDS2DB-Nutzungsbedingungen -> Sie mssen diesen Nutzungsbedingungen zustimmen, wenn Sie SDS2DB benutzen wollen
/usr/local/sds2db/sds2db_tables.sql -> Datei enthlt MySQL-Kommandos zur Erstellung der durch SDS2DB benutzten Datenbanktabellen
/usr/local/sds2db/bin/pei.init -> Initialisiert die Funkgerte fr das SDS-Routing zu SDS2DB
/usr/local/sds2db/bin/read -> liest zeilenweise Daten der PEI-Schnittstelle(n) und erstellt Spooldateien im Read-Spool-Verzeichnis
/usr/local/sds2db/bin/write -> schreibt alle Dateien im Write-Spool-Verzeichnis an die passende(n) PEI-Schnittstelle(n)
/usr/local/sds2db/bin/regular.run -> wird whrend der Programmlaufzeit mintlich ausgefhrt, um Alive-Meldungen in die Datenbank zu schreiben
/usr/local/sds2db/bin/sds2db -> liest die Dateien im Read-Spool-Verzeichnis, erkennt SDS-Meldungen, schreibt die SDS-Meldungen in die Datenbank
/usr/local/sds2db/etc/sds2db.conf -> SDS2DB Konfigurationsdatei
/usr/local/sds2db/etc/init.d/sds2db -> SDS2DB-Init-Skript
/usr/local/sds2db/var/log -> SDS2DB-Log-Verzeichnis 
/usr/local/sds2db/var/run -> Verzeichnis enthlt temporre, whrend der Programmlaufzeit erzeugte Dateien
/usr/local/sds2db/var/spool/read -> Read-Spool-Verzeichnis
/usr/local/sds2db/var/spool/write -> Write-Spool-Verzeichnis


Skripte im Detail
-----------------

pei.init

+ Funktion:
  Dieses Skript wird beim Starten des sds2db-Daemons oder bei jeder nderung des Operating Mode (Einschalten des FuG, DMO/TMO-Wechsel) 
  aufgerufen und bergibt Initialisierungskommandos fr das FuG an den sds2db-Write-Spooler.

+ Zweck:
  - die PEI-Schnittstelle auf Standardeinstellungen setzen
  - das Routing fr bentigte Services vom MS zum TE aktivieren (Status, LIP, Text Messaging)
  - die Idenditt (ITSI) des FuG abfragen 


read

+ Funktion:
  Dieses Skript liest alle Zeichen einer seriellen (RS232) Schnittstelle zeilenweise in einer Endlosschleife und schreibt 
  alle empfangenen Zeilen in je eine Spool-Datei. Die Spool-Dateien werden dann vom Skript sds2db weiterverarbeitet. 
  Fr jede konfigurierte Schnittstelle, auf der sds2db lauschen soll, wird ein eigener Read-Spooler gestartet.

+ Zweck:
  Das Script dient als Read-Spooler der Entkopplung des Einlesens der empfangenen Daten von der anschlieenden Weiterverarbeitung.


write

+ Funktion:
  Dieses Skript liest alle Dateien im Write-Spool-Verzeichnis ein, schreibt den Inhalt in das sds2db-Logfile der Schnittstelle und an 
  die passende serielle Schnittstelle.

+ Zweck:
  Das Skript ermglicht als Write-Spooler die Verarbeitung der aus verschiedenen Skripten an das/die FuG(s) zu sendenden AT-Kommandos.


regular.run

+ Funktion:
  Dieses Skript wird mittels Cron-Job regelmig wiederholt ausgefhrt. 
  Der Cron-Job wird beim Starten des Init-Skripts fr "sds2db" erstellt und beim Beenden wieder entfernt.
  Es werden AT Kommandos an die PEI-Schnittstelle eines verbundenen TETRA FuGs gesendet, um die Betriebsbereitschaft abzufragen. 
  Die Antworten werden durch "sds2db" in das sds2db-Logfile geschrieben und hier zyklisch ausgewertet, um einen "Alive"-Eintrag in einer 
  Datenbanktabelle aufzufrischen. Zustzlich wird ein "Alive"-Eintrag dieses Hosts in einer Datenbanktabelle aufgefrischt.
 
+ Zweck:
  Diese Informationen knnen so in anderen Anwendungen, z.B. Einsatzfhrungssoftware oder Status-Frontend ausgewertet werden, um z.B. die
  Funktionsbereitschaft des Statusservers und der verbundenen FuGs zu monitoren.


sds2db

+ Funktion:
  Dieses Skript liest alle im Read-Spooler-Verzeichnis erzeugten Dateien in einer Endlosschleife ein. 
  Diese Read-Spooler-Dateien enthalten jeweils eine Zeile, die durch die Read-Spooler von dem an der jeweiligen seriellen Schnittstelle 
  angeschlossenen Gert empfangen haben.
  Alle empfangenen Zeilen werden, um Log-Informationen erweitert, in ein Logfile geschrieben.
  Empfangene Zeilen, die als "CTSDSR unsolicited Result Codes" erkannt werden, werden zustzlich gem ETSI EN 300 392-5 
  als SDS interpretiert und im Rohformat in eine MySQL-Datenbank geschrieben.
  Die Protokolle Text Messaging, LIP und Status werden zu diesem Zweck bei der Initialisierung jeder konfigurierten Schnittstelle fr das Routing
  zum TE registriert.

+ Zweck:
  Das Script soll als Hintergrundprozess auf einem Statusmonitor-PC laufen, der mittels RS232-Schnittstellen (auch USB/Seriell-Konverter oder 
  Ethernet-Serial-Device-Server) mit einem PEI-Interface eines TETRA Funkgertes verbunden ist. 
  Die in der MySQL-Datenbank gesammelten SDS knnen so in anderen Anwendungen, z.B. Einsatzfhrungssoftware, ausgewertet werden, um z.B. Status-, 
  Positions- oder Text-Informationen zu verarbeiten.


Systemanforderungen
-------------------

Auf meinem Testsystem mit einer 800 MHZ Via Ezra CPU und 512 MB RAM liegt die Load zwischen 0,02 und 0,5. SDS2DB sollte also auch auf weniger leistungsfhgen Plattformen problemlos laufen.
Durch SDS2DB benutzte Programme, die auf dem System vorhanden sein mssen:
- bash
- mysql
- awk
- inotify
- stty


Installation
------------

1. Erfllung der Abhngigkeiten prfen/herstellen
   - ist eine Bash-Shell vorhanden?
   - sind die von SDS2DB verwendeten Programme (mysql, awk, inotify, stty) vorhanden?

2. MySQL-Datenbank und Tabellen fr SDS2DB anlegen

3. Tgz-Archiv von SDS2DB in das /-Verzeichnis des Zielsystems kopieren

4. Tgz-Archiv als root-User auspacken
   "tar xvpPzf sds2db_....tgz"

5. SDS2DB-Konfiguration an die eigenen Umgebungsbedingungen und Vorlieben anpassen
   - /etc/init.d/sds2db (Required-Start:, Required-Stop:, Default-Start:, Default-Stop:)
   - /usr/local/sds2db/etc/sds2db.conf (Pfade, Device-Namen, Schnittstellen-Parameter)

6. Programm manuell starten, Funktion testen, Programm stoppen
   - starten: "service sds2db start" bzw. "/etc/init.d/sds2db start"
   - Logmeldungen verfolgen: "tail -f /usr/local/sds2db/var/log/sds2db.log" 
   - stoppen: "service sds2db stop" bzw. "/etc/init.d/sds2db stop"

7. Init-Skript mit den Distributions-Werkzeugen in die gewnschten Runlevel verlinken (sofern der Autostart des Programms gewnscht ist)

8. Autostart und Funktion prfen 
