%
% Achtung: Dateien muessen mit latin1-Encoding gespeichert werden!
% Attention: Files must be saved using latin1 encoding!
%

\chapter{Das owswitch-Paket}

\section{Die Einleitung}

   Das owwitch-Paket erm"oglicht die "Uberwachung und das Steuern
   von 1-wire Sensoren und Aktoren die z.B. an einem DS2413-Modul
   angeschlossen wurden. "Andert sich der Status eines Ports, so
   k"onnen auf Wunsch externe Programme aufgerufen werden um z.B.
   Warnungen etc. zu versenden.

\section{Die Voraussetzungen}

   Das owswitch-Paket ben"otigt ein installiertes owfs-Paket um
   funktionieren zu k"onnen.

\section{Die Installation}

   Das owswitch-Paket wird "uber das Setup-Men"u installiert. Wird
   eine "altere Paketversion vorgefunden, so wird diese deinstalliert
   bevor die neuen Programmdateien installiert werden.

\section{Das Men"u im Setup-Programm}

   Das Men"u im Setup-Programm ist wie folgt aufgebaut:

    \begin{itemize}
        \item owswitch administration
        \begin{itemize}
            \item View documentation: Anzeigen der Dokumentation
            \item Edit configuration: Bearbeiten der Konfiguration
            \item Advanced configuration file handling: Konfigurationen
                  verwalten
            \item Show status: Status des owswitch-Monitors anzeigen
            \item Start service: Starten des owswitch-Monitors
            \item Stop service: Stoppen des owswitch-Monitors
            \item Restart service: Neustarten des owswitch-Monitors
            \item Show sensor status: Aktuellen Sensorstatus
                  anzeigen
            \item View log file: Die Logmeldungen anzeigen
            \item Exit: Untermen"u verlassen
        \end{itemize}
    \end{itemize}

   Die Men"upunkte d"urften selbsterkl"arend sein, da sie keinerlei
   weitere Eingaben erwarten. Aus diesem Grund wird auf deren Funktion
   nicht weiter eingegangen.

\section{Die "Anderung der Konfiguration}

   Die Konfiguration kann "uber den Men"upunkt 'Edit configuration'
   ge"andert werden. Standardm"a"sig wird der Editor aufgerufen, der in
   der Environment-Konfiguration "uber die Variable 'EDITOR' festgelegt
   wurde. Nachdem der Editor beendet wurde wird abgefragt, ob die
   Konfiguration aktiviert werden soll. Wird dies best"atigt, werden "uber
   ein Skript die Anpassungen umgehend wirksam gemacht.

\section{Die Konfigurationsdatei}

   In der Konfigurationsdatei, die "uber das Men"u zug"anglich ist, sind
   folgende Parameter vorhanden; wer sie von Hand editieren will findet
   sie unter /etc/config.d/owswitch.

\section{Die Parameter}

\begin{description}
%% JED - show this description only in the help file
 % \config{OWSWITCH\_DO\_DEBUG (Optionaler Parameter)}{OWSWITCH\_DO\_DEBUG}{OWSWITCHDODEBUG}
 %      Um den Debug-Modus zu aktivieren muss diese Parameter
 %      lediglich auf den Wert `yes' gestellt werden, die Einstellung
 %      `no' deaktiviert den Debug-Modus.
 %
 %      G"ultige Werte: yes, no
 %
 %      Standardeinstellung: \texttt{OWSWITCH\_DO\_DEBUG='no'}

   \config{START\_OWSWITCH}{START\_OWSWITCH}{STARTOWSWITCH}
        F"ur die Aktivierung des owswitch-Paketes muss diese Variable
        lediglich auf den Wert `yes' gestellt werden. Die Einstellung
        'no' deaktiviert das owswitch-Paket.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{START\_OWSWITCH='no'}

    \config{OWSWITCH\_SOURCE (Optionaler Parameter)}{OWSWITCH\_SOURCE}{OWSWITCHSOURCE}
        "Uber diesen Parameter wird auf Wunsch festgelegt, welches
        Programm zum Abruf der 1-Wire-Sensordaten verwendet werden
        soll. Zur Auswahl stehen zur Zeit `owread' (Standard) f"ur
        den lokalen Datenabruf und `owhttp' f"ur den Datenabruf
        von einem entfernten Rechner mittels http-Protokoll.

        G"ultige Werte: owread, owhttp

        Standardeinstellung: \texttt{OWSWITCH\_SOURCE=$''$}

    \config{OWSWITCH\_OWFS\_HOSTNAME (Optionaler Parameter)}{OWSWITCH\_OWFS\_HOSTNAME}{OWSWITCHOWFSHOSTNAME}
        Wurde "uber den Parameter \jump{OWSWITCHSOURCE}{OWSWITCH\_SOURCE}
        als Datenquelle das Programm `owhttp' festgelegt, so wird
        "uber diesen Parameter der Hostname des entfernten Rechners
        festgelegt, von dem die 1-Wire-Sensordaten abgerufen werden
        sollen.

        G"ultige Werte: FQDN-Name eines Servers, IP-Adresse

        Standardeinstellung: \texttt{OWSWITCH\_OWFS\_HOSTNAME=$''$}

    \config{OWSWITCH\_OWFS\_PORT (Optionaler Parameter)}{OWSWITCH\_OWFS\_PORT}{OWSWITCHOWFSPORT}
        Wurde "uber den Parameter \jump{OWSWITCHSOURCE}{OWSWITCH\_SOURCE}
        als Datenquelle das Programm `owhttp' festgelegt, so wird
        "uber diesen Parameter der TCP-Port des entfernten Rechners
        festgelegt, von dem die 1-Wire-Sensordaten abgerufen werden
        sollen. Standardm"a"sig wird sonst der Port 2121/tcp verwendet.

        G"ultige Werte: TCP-Port

        Standardeinstellung: \texttt{OWSWITCH\_OWFS\_PORT=$''$}


    \config{OWSWITCH\_N}{OWSWITCH\_N}{OWSWITCHN}
        "Uber diesen Parameter wird die Anzahl der am 1-Wire-Bus 
        angeschlossenen DS2413 PIO-Sensoren festgelegt.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{OWSWITCH\_N='1'}

    \config{OWSWITCH\_x\_ID}{OWSWITCH\_x\_ID}{OWSWITCHxID}
        "Uber diesen Parameter wird die Sensor-ID eines am 1-Wire-Bus
        angeschlossenen DS2413 PIO-Sensors festgelegt/ausgew"ahlt.

        G"ultige Werte: g"ultige Sensor-ID

        Standardeinstellung: \texttt{OWSWITCH\_1\_ID='3A.67C6697351FF'}

    \config{OWSWITCH\_x\_NAME (Optionaler Parameter)}{OWSWITCH\_x\_NAME}{OWSWITCHxNAME}
        "Uber diesen Parameter kann einem 1-Wire-Sensor ein eindeutiger
        Name zugewiesen werden, "uber den er sich im owfs-Dateisystem
        einfacher identifizieren l"asst. Wird kein Name vergeben, so
        l"asst sich ein Sensor immer noch "uber dessen ID ansprechen.

        Beispiel:\\
        \texttt{Parameter: OWSWITCH\_1\_NAME='Tueroeffner'\\
                \\
                Programmaufruf: owread Tueroeffner/type}

        G"ultige Werte: eindeutiger Name ohne Umlaute

         Standardeinstellung: \texttt{OWSWITCH\_1\_NAME=$''$}

    \config{OWSWITCH\_x\_ACTIVE}{OWSWITCH\_x\_ACTIVE}{OWSWITCHxACTIVE}
        Wird dieser Parameter auf den Wert 'yes' gesetzt, so wird dieser
        1-Wire-Sensor aktiviert, 'no' deaktiviert ihn, sodass dessen
        Status nicht "uberwacht wird.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{OWSWITCH\_1\_ACTIVE='no'}

    \config{OWSWITCH\_x\_PIO\_N}{OWSWITCH\_x\_PIO\_N}{OWSWITCHxPION}
        "Uber diesen Parameter wird die Anzahl der PIO-Ports festgelegt,
        die von dem ausgew"ahlten 1-Wire-Sensor unterst"utzt werden.
        Ein DS2413-Sensor unterst"utzt "ublicherweise insgesamt 2
        PIO-Ports.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{OWSWITCH\_1\_PIO\_N='2'}

    \config{OWSWITCH\_x\_PIO\_y\_NAME (Optionaler Parameter)}{OWSWITCH\_x\_PIO\_y\_NAME}{OWSWITCHxPIOyNAME}
        "Uber diesen Parameter kann einem PIO-Port eines 1-Wire-Sensors
        ein Name zugewiesen werden, um diesen einfacher identifizieren
        zu k"onnen.

        G"ultige Werte: Text

        Standardeinstellung: \texttt{OWSWITCH\_1\_PIO\_1\_NAME=$''$}

    \config{OWSWITCH\_x\_PIO\_y\_FUNC}{OWSWITCH\_x\_PIO\_y\_FUNC}{OWSWITCHxPIOyFUNC}
        "Uber diesen Parameter stellt man die Funktion des PIO-Ports ein.
        Soll der PIO-Portstatus nicht aus dem OWFS-Cache gelesen werden,
        um schnelle Statuswechsel zu erkennen, so muss `input-uncached'
        bzw.  `output-uncached' ausgew"ahlt werden.\\
        \hinweis{Standardm"a"sig wird der PIO-Portstatus aus dem OWFS-Cache 
            gelesen um den 1-Wire-Bus nicht "uberm"a"sig stark zu belasten.
            Das Lesen des ungepufferten Status sollte somit m"oglichst 
            vermieden werden.}
        
        Folgende Werte k"onnen eingestellt werden:
        \begin{itemize}
            \item none: Der PIO-Port wird nicht benutzt.
            \item input: Der PIO-Port wird als Eingang verwendet.
            \item input-uncached: Der PIO-Port wird als Eingang verwendet
                und der Status soll nicht aus dem Cache gelesen werden.
            \item output: Der PIO-Port wird als Ausgang verwendet.
            \item output-uncached: Der PIO-Port wird als Ausgang verwendet
                und der Status soll nicht aus dem Cache gelesen werden.
        \end{itemize}

        G"ultige Werte: none, input, input-uncached, output, output-uncached

        Standardeinstellung: \texttt{OWSWITCH\_1\_PIO\_1\_FUNC='input'}

    \config{OWSWITCH\_x\_PIO\_y\_INPUT\_DEFAULT}{OWSWITCH\_x\_PIO\_y\_INPUT\_DEFAULT}{OWSWITCHxPIOyINPUTDEFAULT}
        "Uber diesen Parameter wird der Standardwert f"ur einen PIO-Port,
        welcher als Eingang (input) konfiguriert wurde, festgelegt werden.

        \begin{itemize}
            \item 0: Kontakt geschlossen.
            \item 1: Kontakt ge"offnet.
        \end{itemize}

        G"ultige Werte: 0, 1

        Standardeinstellung: \texttt{OWSWITCH\_1\_PIO\_1\_INPUT\_DEFAULT='0'}

    \config{OWSWITCH\_x\_PIO\_y\_ON\_EXEC\_ACTIVE}{OWSWITCH\_x\_PIO\_y\_ON\_EXEC\_ACTIVE}{OWSWITCHxPIOyONEXECACTIVE}
        Wird dieser Parameter auf den Wert 'yes' gesetzt, so wird der
        "uber den Parameter \jump{OWSWITCHxPIOyONEXEC}{OWSWITCH\_x\_PIO\_y\_ON\_EXEC}
        festgelegt Befehl ausgef"uhrt, sobald sich der Status des PIO-Ports
        auf `1' "andert (0->1).

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{OWSWITCH\_1\_PIO\_1\_ON\_EXEC\_ACTIVE='no'}

    \config{OWSWITCH\_x\_PIO\_y\_ON\_EXEC}{OWSWITCH\_x\_PIO\_y\_ON\_EXEC}{OWSWITCHxPIOyONEXEC}
        "Uber diesen Parameter wird der Befehl festgelegt, welcher ausgef"uhrt
        wird sobald sich der Status des PIO-Ports auf `1' "andert (0->1).

        G"ultige Werte: g"ultiger Shell-Befehl

        Standardeinstellung: \texttt{OWSWITCH\_1\_PIO\_1\_ON\_EXEC=$''$}

    \config{OWSWITCH\_x\_PIO\_y\_OFF\_EXEC\_ACTIVE}{OWSWITCH\_x\_PIO\_y\_OFF\_EXEC\_ACTIVE}{OWSWITCHxPIOyOFFEXECACTIVE}
        Wird dieser Parameter auf den Wert 'yes' gesetzt, so wird der
        "uber den Parameter \jump{OWSWITCHxPIOyOFFEXEC}{OWSWITCH\_x\_PIO\_y\_OFF\_EXEC}
        festgelegt Befehl ausgef"uhrt, sobald sich der Status des PIO-Ports
        auf `0' "andert (1->0).

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{OWSWITCH\_1\_PIO\_1\_OFF\_EXEC\_ACTIVE='no'}

    \config{OWSWITCH\_x\_PIO\_y\_OFF\_EXEC}{OWSWITCH\_x\_PIO\_y\_OFF\_EXEC}{OWSWITCHxPIOyOFFEXEC}
        "Uber diesen Parameter wird der Befehl festgelegt, welcher ausgef"uhrt
        wird sobald sich der Status des PIO-Ports auf `0' "andert (1->0).

        G"ultige Werte: g"ultiger Shell-Befehl

        Standardeinstellung: \texttt{OWSWITCH\_1\_PIO\_1\_OFF\_EXEC=$''$}
\end{description}

\section{Verschiedenes}

\begin{description}
    \config{Setzen eines PIO-Ausgangs}{Setzen eines PIO-Ausgangs}{SetzeneinesPIO-Ausgangs}
        Hat man den PIO-Port eines 1-Wire-Moduls als Ausgang (output)
        konfiguriert, so kann man dessen Status "uber das Kommandozeilenskript
        `owswitch-set-output' abfragen und setzen. Das Skript kann
        dabei in unterschiedlicher Weise aufgerufen werden.
        
        Wird es z.B. ohne weitere Optionen aufgerufen, so werden
        alle 1-Wire Module die mindestens einen PIO-Port als Ausgang
        konfiguriert haben angezeigt. Die Ausg"ange werden dabei
        durch ein \texttt{FUNC:out} kenntlich gemacht.
        Der Status wird dabei als \texttt{STATUS:0|1}
        ausgegeben.\\
        Bei eine, DS2413 1-Wire Modul entsprechend z.B. die PIO-Stati
        folgenden Schaltzust"anden:

        \begin{itemize}
            \item 0: ON, geschlossener Kontakt.
            \item 1: OFF, ge"offneter Kontakt
        \end{itemize}

        Beispiel:
\begin{verbatim}
/usr/bin/owswitch-set-output
OWFS server has been enabled ...
checking sensor stati ...
- all sensors reachable.
- all available sensors configured.
sensor status/stati:
ID:3A.3CF813000000 PIO:1 FUNC:in   DEF:0 STATUS:0 (on)
                   PIO:2 FUNC:out  DEF:o STATUS:1 (off)
\end{verbatim}

        Soll der Ausgang 2 (PIO-Port) des Moduls mit der ID
        `3A.3CF813000000' auf `1' (on) gesetzt werden, so kann
        man dies durch folgenden Befehl veranlassen:

        Beispiel:
\begin{verbatim}
/usr/bin/owswitch-set-output --seton 3A.3CF813000000:2
OWFS server has been enabled ...
checking sensor stati ...
- all sensors reachable.
- all available sensors configured.
set sensor status ...
- ID:3A.3CF813000000 PIO:2 STATUS:0 (on)
  status changed 0->1
\end{verbatim}

        Soll der Ausgang 2 (PIO-Port) des Moduls mit der ID
        `3A.3CF813000000' auf `0' (off) gesetzt werden, so kann
        man dies durch folgenden Befehl veranlassen:
        
        Beispiel:
\begin{verbatim}
/usr/bin/owswitch-set-output --setoff 3A.3CF813000000:2
OWFS server has been enabled ...
checking sensor stati ...
- all sensors reachable.
- all available sensors configured.
set sensor status ...
- ID:3A.3CF813000000 PIO:2 STATUS:1 (off)
  status changed 1->0
\end{verbatim}

        Soll der Ausgang 2 (PIO-Port) des Moduls mit der ID
        `3A.3CF813000000' umgeschaltet werden, d.h. wenn dessen
        aktueller Status `0' (off) ist, soll er auf `1' (on),
        bzw. wenn dessen aktueller Status `1' (on) ist, soll
        dieser auf `0' (off) gesetzt werden, so kann man dies
        durch folgenden Befehl bewerkstelligen:

        Beispiel:
\begin{verbatim}
/usr/bin/owswitch-set-output --toggle 3A.3CF813000000:2
OWFS server has been enabled ...
checking sensor stati ...
- all sensors reachable.
- all available sensors configured.
set sensor status ...
- ID:3A.3CF813000000 PIO:2 STATUS:1 (off)
  status changed 1->0
\end{verbatim}

        Sollen mehrere Ausg"ange (PIO-Ports) eines Moduls mit
        einem Programmaufruf gesetzt werden, so f"ugt man diese,
        getrennt durch einen Doppelpunkt, aneinander.

        Beispiel:
\begin{verbatim}
/usr/bin/owswitch-set-output --toggle 3A.3CF813000000:1:2
\end{verbatim}

        Sollen mehrere Ausg"ange (PIO-Ports) unterschiedlicher
        Module mit einem Programmaufruf gesetzt werden, so f"ugt
        man diese, getrennt durch ein Leerzeichen, aneinander
        und setzt diese zus"atzlich in Hochkomma.

        Beispiel:
\begin{verbatim}
/usr/bin/owswitch-set-output --toggle "3A.3CF813000000:1 3A.3BB813000000:1"
\end{verbatim}

        Will man die Bildschirmausgabe unterdr"ucken, so reicht
        es dem Befehl ein \texttt{--quiet} voran zu stellen.
\end{description}
