********************************************************************************


                      Kelvin Serverraum Temperaturberwachung
                                Hochschule Mnchen

   Version                           Autor                          Datum                 
     1.4                         Mike Niedermayr                  27.03.2012

********************************************************************************


           TS2 TS4 TS6 TS8      kelvin.ini               potter.ini  gnuplot.ini
            |   |   |   |           |                            |       |
Data <---- +-------------+     +--------+     +-----------+     +---------+
    RS-232 |    Kelvin   |<--->| kelvin |---->|   mySQL   |<--->| plotter |
           |    Board    | TCP |        | TCP | Datenbank | TCP |         |
Data <---- +-------------+     +--------+     +-----------+     +---------+
   Browser |   |   |   |            |                                |
          TS1 TS3 TS5 TS7       error.log                       +---------+  
                                    |                           | gnuplot |
                             +-------------+                    +---------+  
                             | errortomail |-> Mail                  |
                             +-------------+                      plot.png


Kurzbeschreibung:

Dieses Projekt ermglicht die berwachung eines Serverraums mithilfe von bis zu 
acht Temperatursensoren, deren Daten in eine mySQL-Datenbank abgespeichert 
werden knnen. Aus den Messwerten lassen sich bersichtliche Grafiken 
anfertigen, die den Temperaturverlauf der Sensoren ber der Zeit wiedergeben.

Hauptbestandteil ist das "Kelvin Board", an das die acht Temperatursensoren 
angeschlossen werden knnen und somit im Serverraum zu installieren ist. 
Das Board liest die Temperaturen ein und bietet diese ber Netzwerk via TCP/IP 
in Textform an oder als Webpage fr die Ansicht in einem Browser.

Das Kommandozeilen basierte Linux-Programm "kelvin" fragt die Daten periodisch
beim "Kelvin Board" ab und speichert diese mit Timestamp in eine 
mySQL-Datenbank. 

Um den Temperaturverlauf in eine Grafik zu berfhren kann das ebenfalls 
Kommandozeilen basierte Linux-Programm "plotter" verwendet werden, dass als 
Plotterengine das Programm "gnuplot" verwendet.

Das Shellscript "errortomail" schickt die Fehlerausgabe von "kelvin" 
gegebenenfalls an eine E-Mailadresse. Damit knnen Temperaturberschreitungen 
und Fehler rechtzeitig erkannt werden.

Da das "Kelvin Board" und die Programme "kelvin", "plotter" ber TCP/IP 
kommunizieren, knnen diese beliebig ber mehrere Rechner verteilt sein.
Voraussetzung ist lediglich das auf dem Linux-Rechner auf dem "plotter" 
betrieben wird, das Programm "gnuplot" installiert ist. Informationen zur 
Installation finden sich unter  www.gnuplot.info.

Um die Daten zu speichern wird die mySQL-Datenbank bentigt, die unter 
www.mysql.de dokumentiert ist. Die Datenbank kann auch auf einem anderen 
Rechner laufen als die restlichen Programme, aber es muss ein Login, 
bestehend aus Nutzername und Passwort eingerichtet werden, damit sich
"kelvin" und "plotter" mit der Datenbank verbinden knnen.

Mit entsprechenden Eintrgen im "Cronjob" knnen die Temperaturen periodisch
abgefragt werden.


********************************************************************************
Wichtige Dateien und Verzeichnisstruktur:
********************************************************************************

Kelvin Board Firmware 
  Code                # Ordner mit dem Sourcecode vom "Kelvin-Board" 
  Config              # Ordner mit Konfigurationsdateien
  Webpage             # Webpage vom "Kelvin-Board"

Plotter and Kelvin        
  plots               # Ordner in den die fertigen Plots gespeichert werden
  scr                 # Ordner mit dem Sourcecode von "kelvin" und "plotter"
  temp                # Ordner fr temporre Daten
	
  kelvin              # Programm zum speichern der Temperaturdaten in mySQL
  kelvin.ini          # Konfigurationsdatei von "kelvin"
  error.log           # Fehler-Log-Datei von "kelvin"
  errortomail         # Shellscript um "error.log" an ein E-Mail zu schicken
  plotter             # Programm zur Erzeugung von Grafiken
  plotter.ini         # Konfigurationsdatei von "plotter"         
  gnuplot.ini         # Zustzliche Einstellungen von "gnuplot"
	


********************************************************************************
Kelvin Board:
********************************************************************************

Funktionsweise:

Die Temperaturwerte der acht Sensoren werden jeweils in kurzen Zeitabstnden
mit einer Auflsung von 0.1 C eingelesen und knnen ber eine TCP/IP, RS-232 
oder einer Webpage abgerufen werden. Whrend des Betriebs knnen neue Sensoren 
angesteckt oder entfernt werden, die selbststndig erkannt werden. Da die 
Temperatur digital vom Sensor zum Board bertragen wird, verflscht die 
Lnge des Kabels den Messwert nicht.


Anzeige ber die Webpage:

Um die Daten ber die Board-interne Webpage abzufragen, kann die IP-Adresse 
des Boards in die Adresszeile eines Browsers eingeben werden. Diese Webseite
wird direkt vom Board erzeugt und zeigt die Temperaturwerte in Echtzeit an.


Datenabfrage ber TCP/IP:

Das Board lauscht auf einem einstellbaren Port auf Verbindungsanfragen ber 
TCP/IP. Geht eine SYN Paket ein, so werden die Temperaturdaten in folgendem 
Format zurckgeschickt. Danach wird die Verbindung wieder geschlossen.

Beispiel einer Abfrage ber TCP:

TS1:  50.2 C\r\nTS2:  83.5 C\r\nTS3: ---.- C\r\nTS4: ---.- C\r\nTS5:  23.0 C\r\n
TS6:  10.2 C\r\nTS7: ---.- C\r\nTS8: 123.0 C\r\nda8236889a61139e3da\r\n'

Die Signatur am Ende der Nachricht ist ein MD5-Hashwert ber die gesendeten 
Daten und ein einstellbares Passwort. Dieser hexadezimale Hashwert ist immer 
16 Zeichen lang und erlaubt es die Integritt der Nachricht und die 
Authentizitt des Absenders zu berprfen.
Um eine Verbindungsanfrage an das Board zu schicken kann der Befehl
"telnet <Board IP-Adresse> <Port>" aus der Kommandozeile aus verwendet werden.


Datenabfrage ber RS-232:

Wenn ber die serielle Schnittstelle RS-232 der Kelvin-Boards ein beliebiges
Zeichen empfangen wird, dann werden die Netzwerkadresse, der Listenport,
die Subnet Mask und das Gateway, sowie alle Temperaturen der Sensoren
zurckgesendet. Die einstellbare Baudrate betrgt standardmig 19200; 
8 Datenbits, 1 Stopbit und keine Flusssteuerung.
Zur Abfrage eignet sich beispielsweise das Programm "PuttY".

Beispiel einer Abfrage ber RS-232:

'\r\nIP Address: 192.168.1.187 : 666
 \r\nSubnetMask: 255.255.255.0
 \r\nGateway   : 192.168.1.1
 \r\n\n
 TS1:  24.0 C\r\n
 TS2:  21.7 C\r\n
 TS3:  23.9 C\r\n
 TS4: ---.- C\r\n
 TS5:  27.6 C\r\n
 TS6:  28.2 C\r\n
 TS7:  27.6 C\r\n
 TS8: ---.- C\r\n\n\n'


Anbindung an ein Netzwerk:

Die IP Adresse vom Kelvin-Board kann entweder statisch vergeben werden oder 
es kann ein DHCP Client aktiviert werden, um die Adresse dynamisch zu erhalten.
Die Wahl wird in der Datei "Kelvin Board Firmware/Config/ProjectConfig.h"
getroffen und muss extra kompiliert und ins Board geflasht werden.
Auerdem kann festgelegt werden, ob das Board auf Ping-Anfragen reagiert. 
Die MAC Adresse kann beliebig eingestellt werden, wobei darauf zu achten ist,
dass eine einmalige Adresse verwendet wird.


Hardware des Boards:

Als Hardware des Sensor-Boards kommt das Development-Board "PIC-WEB REVISION-B" 
der Firma Olimex (www.olimex.com) zum Einsatz, das den Mikrocontroller 
"PIC18F67J60" von Microchip verwendet.
Das Projekt kann auf andere Hardware portiert werden, wenn die entsprechenden 
Einstellungen in der Datei "Kelvin Board Firmware/Config/HardwareProfile.h"
vorgenommen werden. 

Alle Konfigurationen vom "Kelvin-Board" knnen in der Datei
"Kelvin Board Firmware/Config/ProjectConfig.h" gettigt werden.

Um das Projekt zu kompilieren und ins Board flashen zu knnen, eignet sich die 
kostenlose Entwicklungsumgebung "MPLAB IDE" von Microchip, die von 
www.microchip.com heruntergeladen werden kann. 
Dort findet sich ebenfalls der bentigte Compiler "mplabc18" der in einer 
Testversion bezogen werden kann, die nach 60 Tagen lediglich die Optimierung
des Codes abschaltet. 
Nachdem das Projekt kompiliert wurde kann es direkt mit einem Programmer ins 
Board bertragen werden. Dazu kann beispielsweise das "ICD 3" oder "PICkit 3"
benutzt werden. Die ntigen Anleitungen sind unter www.microchip.com zu
finden.

Hochladen einer eigenen Webpage:

Eine eigene Webpage kann individuell gestaltet werden, und in das EEPROM 
des Boards geladen werden. Die Templates im HTML Code der Form "~TS(1)~" von 1 
bis 8 werden durch die jeweiligen Temperaturwerte ersetzt.
Wenn das JavaScript von Microchip verwendet wird, knnen auch nur bestimmte 
Teile nachgeladen werde die in einer XML Datei aktualisiert werden. 
Die fertige Webpage muss anschlieend in das MPFS Filesystem der Firma Microchip 
gebracht werden. Dazu kann das mitgelieferte Tool 
"Kelvin Board Firmware/Tools/MPFS2.exe" verwendet werden. 
Whlen Sie als Source den Ordner aus, der die von Ihnen gestaltete Webpage und 
sonstige Daten enthlt.
Als Output markieren Sie "BIN Image" und geben den Pfad 
".../Server Temperature/Code" an. 
Der Name des Images kann beliebig gewhlt werden. 
Der Upload ins Board erfolgt entweder direkt aus dem Tool oder per http. 
Geben Sie dazu die IP Adresse des Boards in eine Browser ein, gefolgt von 
"/httpupload".
Sie werden nach einem einstellbaren Nutzernamen und Passwort gefragt und knnen
dann die zuvor erstellte *.bin Datei ins Board laden. Diese knnen in der
Datei "Kelvin Board Firmware/Config/ProjectConfig.h" gendert werden.


Belegung der Pinleiste des PIC-WEB-Boards:

+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|   |   |TS6|   |   |TS1|TS3|RST|VDD|   |LE1|   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|   |   |TS5|TS7|   |   |TS2|TS4|   |GND|TS8|LE2|   |   |   |   |   |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
<-- Power Stecker                                        RS-232 -->

TSx = Datenpins der einzelnen Temperatur Sensoren (1-8).
VDD = Versorgungsspannung 3,3 V der Sensoren.
GND = Masse
RST = Low-aktiver Anschluss fr einen Resetknopf.
LE1 = LED1 Pin, der durch blinken den Normalbetrieb anzeigt.
LE2 = LED2 Pin, der aufblinkt, wenn Daten ber TCP abgefragt werden.


Hardware und Anschluss der Temperatur-Sensoren:

Es werden bis zu acht digitale Temperatursensoren "DS18S20" der Firma Maxim 
untersttzt, die ber das 1-Wire Protokoll mit dem Kelvin Board kommunizieren.
Diese werden jeweils ber einen eigenen Datenpin angesprochen und bentigen
zudem jeweils eine Versorgungsspannung VDD von 3,3 V sowie einen
Masseanschluss GND. 

Ansicht des Temperatursensors DS18S20 von unten:

 ---------------
|               |
|  1    2    3  |
 \             /
  \           /
   -----------

 GND  Data  VDD


Pinbelegung fr XLR Steckverbindung und DS18S20:

PIN 1 = GND
PIN 2 = Data
PIN 3 = VDD

Als Anschluss kommt die dreiadrige XLR-Steckverbindung zum Einsatz, wobei fr
jeden der acht Sensoren ein eigener XLR-Anschluss verwendet wird.
Der weibliche Part des Steckers ist ins Gehuse vom "Kelvin Board" eingebaut 
wobei jeweils Pin 1 mit dem GND Anschluss der Pinleiste des Boards verbunden 
wird, sowie VDD mit Pin 3. Der individuelle Datenpin jedes Sensors wird an den 
Pin 2 angeschlossen. Zwischen dem Datenpin und der Versorgungsspannung VDD
muss zudem jeweils ein 4,7k Ohm Widerstand vorhanden sein, der direkt auf die
Rckseite des Steckers geltet werden kann.


Ansicht der Rckseite XLR-Stecker weiblich:

  GND                     Data
   1                       2
                  +-----+ / 
                 /| 4k7 |/
                / +-----+   
               /     
              3
             VDD


Der mnnlich Part des XLR-Steckers ist direkt mit den Temperatursensoren
"DS18S20" verbunden, wobei die Pinbezeichnungen bereinstimmen.



********************************************************************************
Programm "kelvin":
********************************************************************************

Mit dem kommandozeilen basierte Linux-Programm "kelvin" knnen die 
Temperaturdaten vom Kelvin-Board abgefragt werden, die zusammen mit einem 
Timestamp in eine mySQL-Datenbank gespeichert werden. 

Um eine periodische Abfrage der Daten zu erreichen, kann man entweder einen 
Cronjob einrichten, der das Programm jeweils einmal aufruft oder man stellt
ein Update-Intervall in Sekunden ein. Dann beendet sich das Programm nicht
nach der Ausfhrung sondern wartet die Intervall-Zeit ab und fhrt danach das
Programm in einer Endlosschleife aus. Zum Beenden dient die Tastenkombination
[Strg] + [C]. 

Bei der Abfrage der Daten wird auch der vom Kelvin-Board mitgesendete Hashwert 
der Daten berprft, um die Integritt der Daten und die Authentizitt des 
Absenders festzustellen. Das Hash-Passwort muss mit dem Hash-Passwort im 
Kelvin-Board bereinstimmen. Falls das Programm einen anderen abweichenden 
Hashwert errechnet, dann wird eine Fehlermeldung ausgegeben und die nicht 
vertrauenswrdigen Daten werden nicht in die mySQL-Datenbank aufgenommen.

Immer wenn ein Fehler auftritt, wird dieser mit einer Zeitangabe auf der
Standard-Fehlerausgabe ausgegeben. Es ist zu empfehlen, die Fehlerausgabe
mit"./kelvin 2>>/home/kelvin/error.log" auf eine Log-Datei umzulenken, um
somit alle Fehler zu protokollieren. Die Datei "error.log" wird im Shellscript 
"errortomail" verwendet, um den Administrator ber aufgetretene 
Fehler zu informieren.

Alle Einstellungen, wie zum Beispiel das Passwort fr mySQL, knnen in 
der Konfigurationsdatei "kelvin.ini" vorgenommen werden, und/oder als 
Kommandozeilenparameter bergeben werden.

Beim Programmstart wird im aktuellen Verzeichnis nach der Datei "kelvin.ini"
gesucht und gegebenenfalls als Grundeinstellungen geladen. Als erster  
Kommandozeilenparameter kann mit "-load Dateiname" auch eine alternative
Konfigurationsdatei mit absolutem Pfad geladen werden.
Danach werden die Kommandozeilenparameter ausgewertet, die die in der
Konfigurationsdatei getroffene Einstellungen gegebenenfalls berschreiben.

Die Syntax bestehen immer aus zwei Teilen: Dem Befehl, eingeleitet mit 
einem "-" und dem bergabewert der vom Befehl durch mindestens ein 
Leerzeichen getrennt sein muss. 

In der Konfigurationsdatei werden leere Zeilen und Zeilen die mit einem 
"#"-Zeichen anfangen bersprungen. In jeder Zeile darf nur ein Befehl 
stehlen und muss vom bergabewert durch mindestens ein Leer- oder 
Tabulatorzeichen abgetrennt sein.


Inhalt der "kelvin.ini" mit Standardwerten:

# [-l],  [--load]         Lade Config Datei
# [-i],  [--interval]     Update Intervall in Sekunden

# [-mu], [--user]         mySQL User

# [-p],  [--password]     mySQL Passwort
# [-d],  [--database]     mySQL Database
# [-tb], [--table]        mySQL Table
# [-mh], [--sqlhost]      mySQL Host

# [-mp], [--sqlport]      mySQL Port
#
 [-kh], [--boardhost]    Kelvin Board Hostname
# [-kp], [--boardport]    Kelvin Board Port

# [-hp], [--hashpassword] MD5-Hash Passwort
# [-at], [--alarm]        Alarm Temperatur in C



--interval       5

--user           root
--p
assword       1234

--database       Kelvin

--table          Temperatur
-
-sqlhost        localhost

--sqlport        3306

--boardhost      192.168.1.187
--boardport      666

--hashpassword   1234567
--alarm          50.0


Befehlserluterung fr "kelvin":

"-l Dateiname" oder "load Dateiname"
Die angegebene Datei z.B "kelvin.ini" wird geladen und die darin 
befindlichen Einstellungen werden gelesen. Dieser Befehl kann nur als erster
Kommandozeilenparameter aufgerufen werden.


"-i Zahl" oder "--interval Zahl"
Wenn eine Zahl grer Null angegeben wird, so wird diese als Update-Intervall 
in Sekunden interpretiert. Dann wird das Programm nach einem Durchlauf nicht 
beendet, sondern suspendiert bis die gewhlte Wartezeit abgelaufen ist. 
Wird der Wert "0" bergeben, luft das Programm genau einmal durch und beendet
sich dann selber.


"-mu Name" oder "--user Name"
Um sich mit einer mySQL-Datenbank verbinden zu knnen muss man sich als User 
mit Passwort einloggen. Der bergebene Name ist der Username fr mySQL.


"-p Zeichenkette" oder "--password Zeichenkette"
Die Zeichenkette ist das Passwort fr die mySQL-Datenbank.


"-d Name" oder "--database Name"
Der Name der Datenbank innerhalb von mySQL. Wenn diese Datenbank nicht 
vorhanden ist, so wird sie neu angelegt.


"-tb Name" oder "--table Name"
Der Name der Tabelle innerhalb von mySQL unter der die Daten gespeichert
werden sollen.


"-mh Hostname" oder "--sqlhost Hostname"
Die IP-Adresse unter der die mySQL-Datenbank zu erreichen ist. 
"localhost" adressiert den lokalen Rechner.


"-mp Nummer" oder "--sqlport Nummer"
Die Portnummer unter der die mySQL-Datenbank zu erreichen ist.
3306 ist der Standerdport fr mySQL.


"-kh Adresse" oder "--boardhost Adresse"
Die IP-Adresse vom Kelvin-Board. Wenn diese per DHCP zugeteilt wurde, 
kann die Adresse ber RS-232 eingesehen werden.


"-kp Nummer" oder "--boardport Nummer"
Die Portnummer unter der das Kelvin-Board zu erreichen ist.

"-hp Passwort" oder "--hashpassword Passwort"
Das Passwort, dass in den MD5 Hash der Daten bei der bertragung eingerechnet
wird. Dieses muss gleich dem Passwort vom Kelvin-Board sein, dass in der Datei 
"Kelvin Board Firmware/Config/ProjectConfig.h" gendert werden kann.


"-at Zahl" oder "--alarm Zahl"
Die Zahl wird als Temperaturwert interpretiert. berschreitet ein Sensor 
diese Temperatur, so wird eine entsprechende Warnung mit Zeitangabe auf der 
Standard-Fehlerausgabe ausgegeben. 


********************************************************************************
Shellscript "errortomail":
********************************************************************************

Das Skript "errortomail" prft, ob die Datei "Error.log" existiert und Inhalt 
hat. Gegebenenfalls wird dann der Inhalt dieser Datei an eine einstellbare 
E-Mail Adresse gesendet und danach wird die Log-Datei gelscht.
Sinnvollerweise muss das Skript in regelmigen Abstnden per "Cronjob" 
aufgerufen werden, um einen Administrator rechtzeitig ber einen 
Temperaturanstieg oder den Ausfall des Kelvin-Boards informieren zu knnen. 
Im Skript selber mssen die folgenden beiden Variablen entsprechend 
angepasst werden.

ERRORLOG="/home/kelvin/error.log"   # Die zu berwachende Log-Datei
MAILADDRESS="kelvin@test.de"        # Die Ziel-Mailadresse


********************************************************************************
Programm "plotter":
********************************************************************************

Um den Temperaturverlauf in eine Grafik zu berfhren kann das ebenfalls
kommandozeilen basierte Linux-Programm "plotter" verwendet werden, dass seine 
Einstellungen aus der Datei "plotter.ini" oder aus den Kommandozeilenparameter 
analog zu "kelvin" ausliest. Dabei lassen sich gezielt Zeitbereiche auswhlen, 
die der zu erstellenden Grafik zugrunde liegen. Als Plotterengine wird "gnuplot"
verwendet das ber die Datei "gnuplot.ini" konfiguriert werden kann.
Deshalb muss "gnuplot" auf dem System installiert sein, auf dem das Programm 
"plotter" ausgefhrt werden soll.

Die Temperaturen aus der mySQL-Datenbank werden ber der Zeitachse fr die 
ausgewhlten Sensoren angezeigt. 
Um den Zeitbereich einzuschrnken knnen ein Start- und ein Endzeitpunkt 
festgelegt werden. Dies geschieht zum Beispiel durch
"-start '2012-12-24 18:00:00'" und "-end '2013-01-01 00:00:00'". Zustzlich 
kann auch ein Zeitbereich mit Range festgelegt werden. Dazu wird eine Zahl und
eine Einheit verwendet, die zusammen Range ergeben wie zum Beispiel 
"-range 2 -unit day". Es sind fnf verschiedene Kombinationen zulssig, um den
Zeitbereich anzugeben.
Start, End und Range knnen nicht alle gleichzeitig definiert werden.

Bedeutung der Kombinationen von Start, End und Range:

       1.             2.              3.              4.              5.
  Start, End     Start, Range     End, Range        Range
   
Start     End   Start                     End            Last   First    Last
 |---------|     |---------|     |---------|     |---------|     |---------|
                  <-Range->       <-Range->       <-Range->

1. Wenn nur Start und End gesetzt sind, 
   dann wird der Zeitraum dazwischen ausgewhlt.

2. Wenn nur Start und Range gesetzt sind, 
   dann wird der Zeitraum ab Start bis Start plus Range ausgewhlt.

3. Wenn nur End und Range gesetzt sind,
   dann wird der Zeitraum von End minus Range bis Range ausgewhlt.

4. Wenn nur Range gesetzt ist,
   dann wird als End Zeitpunkt der letzte bzw aktuellste Datensatz gewhlt.

5. Wenn keine Angabe gemacht wird,
   dann wird der gesamte Datensatz zugrunde gelegt. 


Inhalt der "kelvin.ini" mit Standardwerten:

# [-l],  [--load]       Lade Config Datei

# [-mu], [--user]       mySQL User
# [-p],  [--password]   mySQL Passwort
# [-d],  [--database]   mySQL Database
# [-tb], [--table]      mySQL Table
# [-h],  [--host]       mySQL Host
# [-mp], [--port]       mySQL Port
# [-mo], [--sqlout]     Zielort der SQL Output Datei
# [-go], [--gnuout]     Zielort der SQL Gnuplot Output Datei
# [-i],  [--gnuini]     Ort der Gnuplot.ini Datei, die mit geladen wird
# [-gp], [--gnupic]     Zielort der zu erzeugenden Grafik Datei

# [-s],  [--start]      Start Zeitpunkt im SQL Datumsformat

# [-e],  [--end]        End Zeitpunkt im SQL Datumsformat
# [-r],  [--range]      Anzahl des Umfangs
# [-u],  [--unit]       Einheit von Range
# [-x],  [--sensors]    Auswahl der Sensoren [all, ts1,ts2,ts3...]
# [-o],  [--smooth]     Interpolation "smooth csplines", "smooth bezier",
#                       "smooth acsplines"
# [-t1], [--nameTS1]    Name in Grafik fuer TS1 bis TS8
# [-c1], [--colourTS1]  Farbe der Linie fuer TS1 bis TS8
# [-w1], [--styleTS1]   Darstellung der fuer TS1 bis TS8 z.B "lines", 
#                       "points", "linespoints"



--user         root

--password     1234

--database     Kelvin
--table        Temperatur

--host         localhost

--port         3306

--sqlout       /home/kelvin/temp/sqloutput

--gnuout       /home/kelvin/temp/gnuoutput
--gnuini       /home/kelvin/gnuplot.ini

--gnupic       /home/kelvin/plots/plot.png

--sensors      all
--nameTS1      Server 1
--colourTS1    black

--styleTS1     lines


--nameTS2      Server 2

--colourTS2    green

--styleTS2     lines
--nameTS3      Server 3

--colourTS3    blue

--styleTS3     lines
--nameTS4      Server 4
--colourTS4    magenta
--styleTS4     lines
--nameTS5      Server 5
--colourTS5    light-blue
--styleTS5     lines
--nameTS6      Server 6
--colourTS6    red

--styleTS6     lines


--nameTS7      Server 7

--colourTS7    grey
--styleTS7     lines
--nameTS8      Server 8

--colourTS8    orange
--styleTS8     lines


Befehlserluterung fr "plotter":

"-l Dateiname" oder "load Dateiname"
Die angegebene Datei z.B "plotter.ini" wird geladen und die darin 
befindlichen Einstellungen werden gelesen. Dieser Befehl kann nur als 
erster Kommandozeilenparameter aufgerufen werden.

"-mu Name" oder "--user Name"
Um sich mit einer mySQL-Datenbank verbinden zu knnen muss man sich als 
User mit Passwort einloggen. Der bergebene Name ist der Username fr mySQL.


"-p Zeichenkette" oder "--password Zeichenkette"
Die Zeichenkette ist das Passwort fr die mySQL-Datenbank.


"-d Name" oder "--database Name"
Der Name der Datenbank innerhalb von mySQL. Wenn diese Datenbank nicht 
vorhanden ist, so wird sie neu angelegt.


"-tb Name" oder "--table Name"
Der Name der Tabelle innerhalb von mySQL unter der die Daten gespeichert 
werden sollen.


"-h Hostname" oder "--host Hostname"
Die IP-Adresse unter der die mySQL-Datenbank zu erreichen ist. 
"localhost" adressiert den lokalen Rechner.


"-mp Nummer" oder "--port Nummer"
Die Portnummer unter der die mySQL-Datenbank zu erreichen ist.
3306 ist der Standerdport fr mySQL.


"-mo Dateiname" oder "--sqlout Dateiname"
In diese Datei wird die Ausgabe der mySQL-Datenbank nach der individuellen 
Abfrage geschrieben. Sie enthlt die Daten, aus denen die Grafik 
erzeugt wird, danach kann sie gelscht werden.

"-go Dateiname" oder "--gnuout Dateiname"
In diese Datei werden die Anweisungen geschrieben, die dann von gnuplot 
ausgefhrt werden. Innerhalb dieser Anweisungen wird die 
"gnuplot.ini" geladen.


"-i Dateiname" oder "--gnuini Dateiname"
In dieser Datei knnen Einstellungen fr gnuplot vorgenommen werden, 
die bei der Erstellung der Grafik mit bercksichtigt werden.


"-gp Dateiname" oder "--gnupic Dateiname"
Der Zielort und der Name der zu erzeugenden Gnuplot-Grafik


"-s Datum/Uhrzeit" oder "--start Datum/Uhrzeit"
Der Startzeitpunkt beispielsweise im Format "YYYY-MM-DD hh:mm:ss" 
ab dem die Daten fr die Erzeugung der Grafik verwendet werden. 
Jedes mySQL Datumsformat ist gltig.

"-e Datum/Uhrzeit" oder "--end Datum/Uhrzeit"
Der Endzeitpunkt beispielsweise im Format "YYYY-MM-DD hh:mm:ss" bis zu dem
die Daten fr die Erzeugung der Grafik verwendet werden. 
Jedes mySQL Datumsformat ist gltig.


"-r Zahl" oder "--range Zahl"
Die Zahl ergibt zusammen mit der Einheit einen Zeitraum wie zum
Beispiel "-r 1 -u day"


"-u Einheit" "--unit Einheit"
Die Einheit in der der Zeitraum definiert werden soll. Gltig sind alle
mySQL-Einheiten wie zum Beispiel:
"MINUTE", "HOUR", "DAY", "WEEK", "MONTH" oder "YEAR"


"-x Auswahl" oder "--sensors"
Die Auswahl der Sensoren, die angezeigt werden sollen. 
Es ist eine beliebige Kombination aus den Sensoren "ts1" bis "ts8" mglich,
die durch ein Komma aber ohne Leerzeichen getrennt werden. Bsp: "ts1,ts4,ts3"
Mit "all" werden alle Sensoren ausgewhlt.


"-o Text" oder "--smooth Text"
Mit Text kann eine Interpolations- oder Approximationsfunktion ausgewhlt
werden, die fr alle Sensoren gilt. Dadurch knnen sehr zackige Kurve 
geglttet dargestellt werden. Es sind alle gnuplot Funktionen gltig wie 
zum Beispiel: "smooth csplines", "smooth bezier" oder "smooth acsplines".


"-t1 Name" oder "--nameTS1 Name"
Der Name des jeweiligen Sensors, wie er in der Legende der Grafik angezeigt
werden soll. Gltig analog fr alle Sensoren TS1 bis TS8.


"-c1 Farbe" oder "--colourTS1 Farbe"
Die Farbe des jeweiligen Graphen. Gltig sind alle Farbbezeichnungen von 
gnuplot als Text oder als RGB Farbcode. 
Bsp: "#CCCCCC". Analog fr alle Sensoren TS1 bis TS8.


"-w1 Text" oder  "--styleTS1 Text"
Mit Text kann fr jeden Sensor eine individuelle Darstellung gewhlt werden. 
Gltig sind alle Bezeichnungen von gnuplot wie "lines", "points" 
oder "linespoints". Analog fr alle Sensoren TS1 bis TS8.



********************************************************************************
Cronjob Eintrge:
********************************************************************************

Vorausgesetzt der Inhalt des Ordners "Plotter and Kelvin" befindet sich unter 
"/home/kelvin" kann ein Cronjob folgendermaen aussehen und mit
"crontab -e" hinzugefgt werden. Wenn fr "kelvin.ini" und "plotter.ini" nur 
der Besitzer Leserechte besitzt, werden die Passwrter fr andere Nutzer 
verborgen.


Beispiel fr einen Cronjob Eintrag:

# Minute Stunde Tag  Monat Wochentag
# 0-59   0-23   1-31 1-12  0-6 (0=So)

# Alle 10 Minuten werden die Temperaturwerte der Server im Serverraum abgerufen
# und in die mySQL Datenbank gespeichert. 

0,10,20,30,40,50 * * * * /home/kelvin/kelvin -l /home/kelvin/kelvin.ini
  >/dev/null 2>>/home/kelvin/error.log

# Immer um ca Mitternacht wird ein Plot ber den letzten Tag erstellt 

55 23 * * * /home/kelvin/plotter -l /home/kelvin/plotter.ini 
  -r 1 -u day -gp /home/kelvin/plots/lastday.png >/dev/null 2>&1


# Immer Sonntags um ca Mitternacht wird ein Plot ber die letzte Woche erstellt 

56 23 * * 0 /home/kelvin/plotter -l /home/kelvin/plotter.ini 
  -r 1 -u week -gp /home/kelvin/plots/lastweek.png >/dev/null 2>&1

# Immer am ersten des Monats um ca Mitternacht wird ein Plot ber
# den letzten Monat erstellt 

57 23 1 * * /home/kelvin/plotter -l /home/kelvin/plotter.ini 
 -r 1 -u month -gp /home/kelvin/plots/lastmonth.png -o "smooth bezier"
 >/dev/null 2>&1

# Jede Stunde wird ein Skript gestartet, dass ueberprueft ob Daten in der
# Error.log vorhanden sind und diese dann an eine Mailadresse schickt.

5 * * * * /home/kelvin/errortomail
