Kurzdokumentation zur Reminder Shell:

Autor:      stikx (gendert von DrStoned)
Datum:      08.10.2005
Version:    0.6 gendert von DrStoned, akustische Benachrichtigung eingebaut
Dank:       an terrae fr das Kalender Plugin und die tolle Zusammenarbeit
            an masite fr die unermdliche Ideenlieferung und das Testen
            an Ulli010 fr die Pionierarbeit Dream/Enigma und das Testen
            und speziell Regloh fr alles halt.
            von DrStoned an fernsehass fr die Vorbeit an Version 0.5
            von DrStoned an Nachtvogel fr die Implementierung von bis zu 20 Geburtstagen und Terminen pro Tag
             
Funktionsbeschreibung:

Diese Shell klinkt sich in das Startup des Neutrino oder Enigma der Dbox2 sowie Dreambox.
Sie wird in den Hintergrund geladen und erstmal schlafen gelegt, bis alles andere gestartet ist.
Wenn Sie wirksam wird, durchsucht die Shell die Datei /var/tuxbox/config/tuxcal/tuxcal.list
nach Geburtstagseintrgen und Terminen mit aktuellem Datum (heute) und Datum plus einen Tag (morgen).
Diese Eintrge werden dann in einem Fenster am TV angezeigt, solange bis diese mit 
OK an der Fernbedienung besttigt sind, oder nach einem Timeout (default 120 Sekunden) weggeblendet werden.
Wenn die Datei reminder.wav installiert wurde, erfolgt auch eine akustische Benachrichtigung.
Bei zustzlichem Eintrag des Geburtsdatums wird das Alter zum Namen eingeblendet.
Die Ausgabe ist auf 20 Geburtstage und Termine pro Tag beschrnkt. Es knnen mehr Eintrge in der DB
vorhanden sein, diese werden jedoch ignoriert (Prinzip: First come, first serve). 
Taucht rechts im Ausgabefenster ein Rollbalken auf, so werden weitere Geburtstage und Termine mit der 
Pfeil-nach-unten-Taste angezeigt, ebenso kann mit der Pfeil nach oben-Taste wieder hochgeblttert werden.
Die Shell erkennt den Boxtyp bzw. die GUI automatisch, schlgt das fehl (warum auch immer!)
kann die Shell mit den Parametern -n/e aufgerufen werden um den Type vorzugeben.

-n = Neutrino
-e = Enigma auf Tuxbox oder Dreambox

GUI:    Neutrino
        Enigma

Boxtyp: Tuxbox (Dbox2)
        Dreambox

DB Format:

Das Format der Datei /var/tuxbox/config/tuxcal/tuxcal.list muss wie nachfolgend aufgebaut sein:
Ein Match im Satz erfolgt auf g;xx.yy.zzzz;Vorname Nachname; oder t;xx.yy.zzzz;Termin;
wobei xx fr Tag und yy fr Monat sowie zzzz fr das Geburtsjahr steht  
Beispiel:   g;14.06.1968;Chris Wagner;
            g;23.09.;Jesse James;
            t;13.05.;Reifenwechsel;
            t;12.05.2003;einmaliger Termin;
         
Wie aus dem Beispiel zu ersehen ist, wird das Geburtsjahr im normalen Datumsformat eingegeben.
Ist das Geburtsjahr nicht bekannt, wird es einfach weggelassen (siehe Beispiel Record 2).
Nach dem Semikolon am Ende des Records darf kein Leer- oder sonstiges Zeichen vorkommen,
da sonst die Ausgabe falsch formatiert wrde. Semikolon als Limiter ist zwingend.
Eine Basisdatei ist im Download als Beispiel enthalten. Bitte nur benutzen als Template
und wenn nicht schon vorhanden!
Die Datei tuxcal.list mu im Linux-Format vorliegen!
Das Format dieser Datei und der Standort ist synchron mit terraes Tuxcal v. 0.4 und luft
mit terraes Kalender als auch Standalone. (Kann mit Editor oder einem Remote Frontend 
[sind in Arbeit z.B. von masite]  bearbeitet werden). Das Remote Frontend 'TuxCal-Config'
fr Windows kann bei http://www.tux-box.net/tuxcal/ runtergeladen werden.

ACHTUNG: Das Format hat sich von 0.3 auf 0.4 minimal gendert! Die Datei heit jetzt 
tuxcal.list und befindet sich im Verzeichnis /var/tuxbox/config/tuxcal
Version 0.4 zu 0.4a keine nderung


Aufruf Parameter / Standort:

reminder liegt jetzt unter /var/tuxbox/config/tuxcal. Sollte das Verzeichnis nicht existieren,
so muss es angelegt werden. Zum Test kann reminder ber Telnet manuell gestartet werden.
Aufruf erfolgt mit 'sh reminder' und optional den Parametern -h oder -ns, wobei -h fr Hilfe steht
und -ns fr no sleep. Letzteres verhindert die verzgerte Ausfhrung (120 Sekunden).
Ebenfalls kann mit den Parametern -n/e die Gui bzw. der Boxtyp vorgegeben werden.

*******************************************************************************************
Bitte beachten, da die Box auf einem Sender stehen mu, von der sie ein Zeitsignal erhlt.
Sonst kann das Plugin nicht funktionieren, da die Uhrzeit und somit das Datum nicht stimmt.
*******************************************************************************************

Installation:

Hier ist eine Auflistung der Dateien mit den Speicherorten, Rechten und Zweck.
Je nach Erfordernis und Wunsch die Dateien in die entsprechenden Verzeichnisse kopieren 
und die Rechte vergeben.

Datei                   Verzeichnis                     Rechte  bentigt fr
==========================================================================================================

reminder                /var/tuxbox/config/tuxcal/      755     unbedingt
tuxcal.conf             /var/tuxbox/config/tuxcal/      644     unbedingt
enigma_date             /var/tuxbox/config/tuxcal/      755     Enigma
reminder.wav            /var/tuxbox/config/tuxcal/      644     akustische Benachrichtigung
reminder.so             /var/tuxbox/plugins/            755     Manueller Aufruf ber blaue Taste
reminder.cfg            /var/tuxbox/plugins/            644     Manueller Aufruf ber blaue Taste
standby.off             /var/tuxbox/config/				755     Neutrino    (Aufruf aus Soft-Standby)
enigma_leave_standby.sh /var/etc/						755     Enigma      (Aufruf aus Soft-Standby)
tuxmaild                /var/bin/                       755     akustische Benachrichtigung 
                                                                (nur wenn nicht ab V1.26 auf Box)
                                                                
Nach Download und unzip die Datei reminder per ftp ins Verzeichnis /var/tuxbox/config/tuxcal 
hochladen. Wenn tuxcal nicht vorhanden ist, mit mkdir tuxcal in der ftp session im Verzeichnis 
/var/tuxbox/config anlegen. Wenn reminder hochgeladen ist,  telnet session auf die Dbox starten
und ins Verzeichnis /var/tuxbox/config/tuxcal mit cd tuxbox/config/tuxcal wechseln
und den Befehl chmod 755 reminder ausfhren. Der Befehl ls -l reminder sollte dann -rwxr-xr-x
als permissions bei reminder ausgeben. Anschlieend die Datei tuxcal.list bei Bedarf per ftp
ins Verzeichnis /var/tuxbox/config/tuxcal hochladen (Nur wenn nicht schon vorhanden).
Das ist auch nicht notwendig, wenn bereits tuxcal als Plugin installiert ist.
Anschlieend bzw. vorher die Datei nach euren Wnschen bearbeiten. Die Datei tuxcal.list mu
im Linux-Format vorliegen, nicht mit Windows-Notepad bearbeiten, sonst stimmt die Ausgabe nicht.
Stattdessen vi, Ultraedit oder den Crimson-Editor verwenden. Man kann die Datei auch mit dem 
Tuxbox-Commander-Plugin direkt auf der Box bearbeiten: 
Blaue Taste -> in Verzeichnis /var/tuxbox/config/tuxcal/ wechseln -> auf Datei tuxcal.list gehen -> 
Taste 4 = bearbeiten drcken -> editieren -> Home-Taste -> rote Taste um abzuspeichern.

Eine andere Mglichkeit ist, das Windows-Konfigurationstool Tuxcal Config v 0.4.27 von 
http://www.tux-box.net/tuxcal herunterzuladen und die tuxcal.conf mit diesem Tool zu bearbeiten.

Installation des Autostarts:

Bei aktuellen Jack-the-Grabber-Images ist der Autostart des Reminders schon in der start_neutrino eingebaut. 
Benutzer dieser Images brauchen in der start_neutrino nichts mehr zu ndern. User anderer Images sollten 
nachschauen, ob die Zeile /bin/sh /var/tuxbox/config/tuxcal/reminder & schon in ihrer entsprechenden
Startdatei drin ist.

Es folgt der kritische Teil der Installation. 
Whlt bitte die richtige Methode (1, 2, 3, 4) , Gui und Box aus.
Da auch verschiedene Cramfs und Snapshots unterschiedliche Startshell haben,
kann das bei dem ein oder anderen ein wenig von meiner Version abweichen.

1. Anpassen Startup Neutrino/Tuxbox [Head und Rel]:

Dazu eine Telnet Session auf die Box starten und ins Verzeichnis tuxbox wechseln. 
Dort sind drei Links (ims Head ein Link) auf die Dateien start_neutrino, start_enigma 
und start_lcars gesetzt.Mit dem Befehl rm start_neutrino wird der link gelscht.
Anschlieend sofort den Befehl cp /etc/init.d/start_neutrino start_neutrino aufrufen 
um eine neue Datei zu erstellen.
Dann wird die neue Datei editiert, mit welchem Tool auch immer (z.B. vi ).
Vor der Zeile /bin/sectionsd wird der Aufruf /bin/sh /var/tuxbox/config/tuxcal/reminder & eingetragen. 
Wichtig: Das & nicht vergessen. Speichern und fertig.
Zustzlich gibt es in Neutrino-Images nach dem 16.03.2005 die Mglichkeit, den Reminder auch nach dem 
Verlassen des Standby-Modes zu starten. Dazu ist die Datei standby.off nach /var/tuxbox/config/ zu 
kopieren und per telnet chmod 755 /var/tuxbox/config/standby.off eingeben, um ihr Ausfhrrechte zu 
vergeben.


2. Anpassen Startup Enigma/Tuxbox [zumindest Rel]:

Dazu eine Telnet Session auf die Box starten und ins Verzeichnis tuxbox wechseln.
Dort sind drei Links auf die Dateien start_neutrino, start_enigma  und start_lcars gesetzt.
Mit dem Befehl rm start_enigma wird der link gelscht. Anschlieend sofort den Befehl
cp /etc/init.d/start_enigma start_enigma aufrufen um eine neue Datei zu erstellen.
Dann wird die neue Datei editiert, mit welchem Tool auch immer (z.B. vi ).
In der nchsten (neuen) Zeile hinter /bin/cdkvcinfo -novc Enigma wird der Aufruf
/bin/sh /var/tuxbox/config/tuxcal/reminder & vor der Zeile /bin/camd2 eingetragen.
Wichtig: Das & nicht vergessen. Speichern und fertig.
Um den Reminder bei Enigma auch nach dem Starten der Box aus dem Standby zu starten,
ist die Datei enigma_leave_standby.sh nach /var/etc/ zu kopieren und per telnet 
chmod 755 /var/etc/enigma_leave_standby.sh eingeben, um ihr Ausfhrrechte zu vergeben.
Sollte die Datei enigma_leave_standby.sh schon auf der Box vorhanden sein, so ist ihr Inhalt 
aus der Datei im Archiv herauszukopieren und in enigma_leave_standby.sh auf der Box einzufgen.

3. Anpassen Startup Enigma/Dreambox [alte Firmware vor 1.06.5]:

Dazu eine Telnet Session auf die Box starten und ins Verzeichnis /var/tuxbox wechseln.
Dort fndet Ihr die Datei start_enigma,  die editiert werden muss, mit welchem Tool 
auch immer (z.B. vi ). In der nchsten (neuen) Zeile hinter fi und noch vor 
/bin/initkeys wird der Aufruf /bin/sh /var/tuxbox/config/tuxcal/reminder & eingetragen.
Wichtig: Das & nicht vergessen. Speichern und fertig.

4. Anpassen Startup Enigma/Dreambox [Firmware ab 1.06.5]

Dazu eine Telnet Session auf die Box starten und ins Verzeichnis /var/etc wechseln.
Dort fndet Ihr die Datei init bzw. legt sie an. Nach dem Anlegen muss diese mit chmod +x init
ausfhrbar gemacht werden. Die Datei init muss mit der Zeile /bin/sh /var/tuxbox/config/tuxcal/reminder &
egal an welcher Stelle/Zeile ergnzt werden. Wichtig: Das & nicht vergessen. Speichern und fertig.
Um den Reminder bei Enigma auch nach dem Starten der Box aus dem Standby zu starten,
ist die Datei enigma_leave_standby.sh nach /var/etc/ zu kopieren und per telnet 
chmod 755 /var/etc/enigma_leave_standby.sh eingeben, um ihr Ausfhrrechte zu vergeben.
Sollte die Datei enigma_leave_standby.sh schon auf der Box vorhanden sein, so ist ihr Inhalt 
aus der Datei im Archiv herauszukopieren und in enigma_leave_standby.sh auf der Box einzufgen.

Testen:

Wenn ihr die Installation durchgefhrt habt solltet Ihr zuerst die Funktion manuell testen.
Dazu eine Telnet Session auf der Box aufrufen und ins Verzeichnis /var/tuxbox/config/tuxcal wechseln.
Jetzt sh reminder -ns aufrufen. Wenn ein aktueller Geburtstag oder Termin heute oder morgen
in der tuxcal.conf eingetragen ist, wird das auf dem TV ausgegeben.
Eventuell werden auch Fehlermeldungen ausgegeben (z.B. Datei fehlt).  

Plugin als Add-on: 

Ebenfalls enthalten ist ein "Quick and Dirty" Plugin fr die blaue Taste. 
Zum Installieren die Plugin Dateien tuxrem.so und tuxrem.cfg
in das Verzeichnis /var/tuxbox/plugins kopieren und die Box neu starten.
Reminder kann dann ber die blaue Taste zum Test oder zur erneuten Abfrage aufgerufen werden.
Fr die Bastler liegt der Source (tuxcal.c) bei.

Akustische Benachrichtigung:

Die akkustische Benachrichtigung wird mit Hilfe von tuxmaild ausgefhrt. Der Dmon fr das 
Tuxmail-Plugin bietet ab der Version 1.26 die Mglichkeit, PCM-WAV-Dateien auf der Box abzuspielen.
Der Befehl dazu ist folgender: tuxmaild -play <audio-Datei>
Wer noch eine akustische Benachrichtigung wnscht, bentigt noch folgende Dateien:
reminder.wav nach /var/tuxbox/config/tuxcal/ kopieren.
tuxmaild nach /var/bin/ kopieren, telnet session auf die Dbox starten, ins Verzeichnis 
/var/bin/ mit cd bin/ wechseln und den Befehl chmod 755 tuxmaild ausfhren.
Falls ihr bereits einen tuxmaild ab Version 1.26 auf der Box habt braucht ihr den tuxmaild nicht 
mehr auf die Box zu kopieren und ausfhrbar machen. Um das zu testen, folgendes ausfhren.
Das Plugin Tuxmail ber die blaue Taste 'E-Mail' aufrufen. 
Im Tuxmail-Plugin die ?-Taste drcken. falls dort bei /D eine Version ab 1.26 angezeigt wird,
ist das schon erledigt. Dann funktioniert die akustische Benachrichtigung auf jeden Fall.
Sollte bei D?.?? stehen so ist tuxmaild nicht gestartet worden. 
Dann im Plugin die Standby-Taste drcken, es sollte jetzt eine Meldung 'Autostart aktiviert' 
erscheinen, Plugin verlassen, Box herunterfahren und neu starten. Nachdem die Box hochgelaufen ist,
das Plugin Tuxmail ber die blaue Taste 'E-Mail' aufrufen. 
Im Tuxmail-Plugin die ?-Taste drcken. Falls jetzt bei /D eine Version ab 1.26 angezeigt wird, 
sollte jetzt die akustische Benachrichtigung funktionieren.
Wer das Tuxmail-Plugin nicht benutzt, sollte jetzt den Autostart von tuxmaild wieder ber die 
Standby-Taste wieder ausschalten. Meldung 'Autostart deaktiviert' wird im Fenster angezeigt.

Eigene WAV-Dateien fr die Box erstellen:

Die Box spielt nur Sounddateien in einem speziellen Format ab. Die PCM WAV-Dateien solltet ihr mit dem 
Audiorecorder unter Windows in 8 oder 16 Bit Mono,  12, 24, oder 48 KHz umwandeln. Stereo geht auch, 
die Dateien werden dann halt entsprechend grer. Ich empfehle deswegen 8 Bit Mono, 12 KHz.
Dann noch mit einem Hex-Editor vor der Zeichenfolge 'data' am Anfang der WAV-Datei aus dem Dateiheader 
14 Bytes rauslschen. Ich benutze dazu Ultraedit. 
Die Dateien laufen dann nicht mehr mit dem Windows-Mediaplayer, aber dafr auf der Box.


Abhngigkeiten:

Neutrino http API
Enigma http API (Ausgabe und Datum query)
busybox (grep, expr, wget, echo)
Tuxcal Plugin (oder Standalone File)

Dateien:

reminder                Shell
enigma_date             Datei um das Datum bei Enigma und Dreambox korrekt anzuzeigen.
tuxcal.list             DB Datei (Beispiel)
readme.txt              diese Datei
tuxrem.so               Plugin
tuxrem.cfg              Plugin cfg
tuxrem.c                Plugin source
standby.off             Startdatei, um Reminder nach Aufwachen der Box aus dem Standby zu starten (Neutrino)
enigma_leave_standby.sh Startdatei, um Reminder nach Aufwachen der Box aus dem Standby zu starten (Enigma)
reminder.wav            Sounddatei fr akustische Benachrichtigung
tuxmaild                Tuxmaildmon, wird fr die akustische Benachrichtigung bentigt 
                        (nur wenn nicht schon ab Version 1.26 auf Box vorhanden)
                        
nderungen:

v. 0.6  - Akustische Benachrichtigung mit Hilfe von tuxmaild ab Version 1.26 ermglicht. 
		- Dokumentation angepasst.
v. 0.5c - Dokumentation angepasst wegen der Mglichkeit Reminder unter Enigma 
          (auch Dreambox), jetzt auch nach dem Aufwachen der Box aus dem Standby zu starten.
        - enigma_leave_standby.sh ins Archiv eingefgt.
v. 0.5b - den Parameter '-Y off' bei den wget-Aufrufen eingefgt,
          um Probleme bei Proxy-Usern zu beheben
v. 0.5a - Geburtstage und Termine auf 20 pro Tag erhht (Danke an Nachtvogel)
        - Kleine kosmetische Korrekturen bei der Ausgabe
          (Fr jeden Geburtstag und Termin extra Zeile)
        - Dokumentation angepasst
v. 0.5  - Zustzliche Mglichkeit auch Termine anzeigen zu lassen. 
          (Modifiziert von DrStoned, danke an fernsehass fr die Vorbeit)
        - Dokumentation angepasst wegen der Terminanzeige und der Mglichkeit Reminder
          jetzt auch nach dem Aufwachen der Dbox aus dem Standby zu starten.
          (Geht nur mit Images ab dem 16.03.2005 unter Neutrino)
v. 0.4a - Dokumentation angepasst an neue Images
          Neutrino-Head, Dreambox Firmware ab 1.06.5
        - Korrektur Berechnung Alter bei Geburtstag am 01.01.
          und Geburtstag ist morgen
        - Neutrino(Head und Rel) Plugin fr blaue Taste zum
          Starten des reminders (Test und Aufruf) 
v. 0.4  - Enigma auf Tuxbox und Dreambox supportet
        - neue Startparameter
        - Ausgabe des Alters bei Eintrag von Geburtsdatum
        - Korrektur Ausgabe bei Mehrfacheintrgen an einem Tag
        - Ausgabe am TV leicht umformatiert
        - Standort des Reminders jetzt im neuen Verzeichnis
          /var/tuxbox/config/tuxcal
        - DB Datei heit jetzt tuxcal.list und liegt auch im Verzeichnis
          /var/tuxbox/config/tuxcal
        - DB Datei leicht gendert - Hinzufgen von Geburtsdatum und
          Wegfall des Strings "Geburtstag: " beim Namen
        - Dokumentation jetzt im PDF Format
v. 0.3  - Format der tuxcal.conf gendert
        - Ausgabe jetzt mit Datum
        - Version synchron mit tuxcal
v. 0.2  - nicht released
v. 0.1  - erstes release 

Bekannte Beschrnkungen:

Enigma Datum nur ber http query (date liefert falsches Datum)
Record Format ist zwingend, falsche Formatierung wird nicht korrigiert
Ultralange Namen fhren zu unkorrekter Darstellung vor allem bei Neutrino
busybox grep erforderlich - daher zwischenzeitlich nicht luffhig (AlexW 04.11.)
tuxcal.list mu im Linux-Format vorliegen, sonst stimmt die Ausgabe nicht

Weitere Beschreibung im Header bzw. im Ablauf der eigentlichen Shell

Viel Spass und Erfolg

stikx und DrStoned :-) :-) :-)