%
% lprng_power.tex
% Last Update: $Id$
%
%%%%%%%%%%%%%%%%%%%%%%%%%% Kapitel Lprng_power %%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Achtung: Dateien muessen mit latin1-Encoding gespeichert werden!
% Attention: Files must be saved using latin1 encoding!
%

\chapter{Das LPRng\_power-Paket}

\section{Die Einleitung}

    Dieses Paket erm"oglicht das automatisierte Einschalten von Druckern
    beim Eingang eines Druckauftrags und das Ausschalten nach Abschluss des
    Druckauftrags "uber Netzwerkschalter der Firma Allnet vom Typ ALL3075
    oder WLAN-Steckdosen welche mittels HTTP-Kommandos gesteuert werden
    koennen.

\section{Die Funktionen}

    Dieses Paket enth"alt keine externen Programmkomponenten.


\section{Die Voraussetzungen}

    Dieses Paket ben"otigt zur korrekten Funktion ein installiertes LPRng-Paket.


\section{Die Installation}

    Das LPRng\_power-Paket wird "uber das Setup-Men"u installiert. Wird eine
    "altere Paketversion vorgefunden, so wird diese deinstalliert bevor die
    neuen Programmdateien installiert werden. Nach dem Installieren der
    Programmdateien wird direkt der Konfigurations-Editor gestartet um die
    Konfiguration anzupassen. Nach Beendigung dieses Schrittes werden die
    Konfigurationsdateien generiert und alle ben"otigten Programme gestartet.


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

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

    \begin{itemize}
        \item LPRng-Power-Configuration
        \begin{itemize}
            \item View documentation: Anzeigen der Dokumentation
            \item Edit configuration: Bearbeiten der Konfiguration
            \item Show/Toggle device status: Status der Netzwerkschalter anzeigen bzw. umschalten
            \item Advanced configuration file handling: Konfigurationen verwalten
            \item View Logfile: Anzeige der Logdatei
            \item Return: 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 \texttt{/etc/config.d/lprng\_power}.


\section{Die Parameter}
\begin{description}
    \config{START\_LPRNG\_POWER}{START\_LPRNG\_POWER}{STARTLPRNGPOWER}
        Zur Aktivierung der Konfiguration muss dieser Parameter lediglich
        auf den Wert 'yes' gestellt werden. Die Einstellung 'no'
        deaktiviert die Konfiguration.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{START\_LPRNG\_POWER='no'}

    \config{LPRNG\_POWER\_LOAD\_CONTROL\_SCRIPT (optionaler Parameter)}{LPRNG\_POWER\_LOAD\_CONTROL\_SCRIPT}{LPRNGPOWERLOADCONTROLSCRIPT}
        Wird dieser Parameter auf den Wert 'yes' gesetzt, so wird das
        Laden des Kontrollskriptes forciert, welches der "Uberwachung
        der LPR-Warteschlagen dient. Bei Verwendung eines USB-Druckers
        wird das Kontrollskript "ublicherweise automatisch gestartet,
        sodass ein manuelles Laden nicht erforderlich sein sollte.
        Einzig beim direkten LPR-Drucken auf USB-Druckern kann es
        notwendig sein, diesen Parameter zu aktivieren.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{LPRNG\_POWER\_LOAD\_CONTROL\_SCRIPT='no'}

    \config{LPRNG\_POWER\_N}{LPRNG\_POWER\_N}{LPRNGPOWERN}
        "Uber diesen Parameter wird die Anzahl der Netzwerkschalter
        festgelegt welche zum Schalten von Druckern verwendet werden.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{LPRNG\_POWER\_N='0'}

    \config{LPRNG\_POWER\_x\_ACTIVE}{LPRNG\_POWER\_x\_ACTIVE}{LPRNGPOWERxACTIVE}
        Wird dieser Parameter auf den Wert 'yes' gesetzt, so wird der
        zugeh"orige Datensatz aktiviert, 'no' deaktiviert ihn.

        G"ultige Werte: yes oder no

        Standardeinstellung: \texttt{LPRNG\_POWER\_1\_ACTIVE='no'}

    \config{LPRNG\_POWER\_x\_COMMENT}{LPRNG\_POWER\_x\_COMMENT}{LPRNGPOWERxCOMMENT}
        Dies ist ein Kommentarfeld, welches die Identifizierung des
        Datensatzes erleichtern soll.

        G"ultige Werte: beliebiger Text

        Beispiel: \texttt{LPRNG\_POWER\_1\_COMMENT='Dies ist mein Drucker'}

    \config{LPRNG\_POWER\_x\_IPADDR}{LPRNG\_POWER\_x\_IPADDR}{LPRNGPOWERxIPADDR}
        "Uber diesen Parameter legt man die IP-Adresse und TCP-Port
        (optional) fest "uber welchen auf den Netzwerkschalter zugegriffen
        werden kann.

        G"ultige Werte: IP-Adresse und TCP-Port (optional)

        Beispiel: \texttt{LPRNG\_POWER\_1\_IPADDR='192.168.6.40:80'}

    \config{LPRNG\_POWER\_x\_URL\_ON}{LPRNG\_POWER\_x\_URL\_ON}{LPRNGPOWERxURLON}
        "Uber diesen Parameter legt man den URL-Pfad fest, mittels
        welchem das Ger"ate eingeschaltet wird. Siehe auch den Absatz
        \jump{GeraetespezischeURL-Pfade}{Ger"atespezische URL-Pfade} in der Dokumentation.

        G"ultige Werte: URL-Pfad

        Beispiel: \texttt{LPRNG\_POWER\_1\_URL\_ON='/r?b=1\&r=0\&s=1'}

    \config{LPRNG\_POWER\_x\_URL\_OFF}{LPRNG\_POWER\_x\_URL\_OFF}{LPRNGPOWERxURLOFF}
        "Uber diesen Parameter legt man den URL-Pfad fest, mittels
        welchem das Ger"ate ausgeschaltet wird. Siehe auch den Absatz
        \jump{GeraetespezischeURL-Pfade}{Ger"atespezische URL-Pfade}
        in der Dokumentation.

        G"ultige Werte: URL-Pfad

        Beispiel: \texttt{LPRNG\_POWER\_1\_URL\_OFF='/r?b=1\&r=0\&s=0'}

    \config{LPRNG\_POWER\_x\_URL\_STATUS}{LPRNG\_POWER\_x\_URL\_STATUS}{LPRNGPOWERxURLSTATUS}
        "Uber diesen Parameter legt man den URL-Pfad fest, mittels
        welchem der Ger"atetatus abgefragt wird. Siehe auch den Absatz
        \jump{GeraetespezischeURL-Pfade}{Ger"atespezische URL-Pfade}
        in der Dokumentation.

        G"ultige Werte: URL-Pfad

        Beispiel: \texttt{LPRNG\_POWER\_1\_URL\_STATUS='/xml'}

    \config{LPRNG\_POWER\_x\_URL\_STATUS\_FILTER}{LPRNG\_POWER\_x\_URL\_STATUS\_FILTER}{LPRNGPOWERxURLSTATUSFILTER}
        "Uber diesen Parameter legt man die Filterbefehle fest
        mit dessen Hilfe der Ger"atestatus mittels Pipe aus der
        zuvor definierten Statusabfrage extrahiert wird. Aus 
        diesem Grund darf nat"urlich der URL-Pfad selbst NICHT
        den Befehlen vorangestellt werden.\\
        Als Ergebnis muss final das Schaltergebnis `0' (aus)
        oder `1' (an) zur"uck geliefert werden. Andere Ergebnisse
        koennen nicht verarbeitet werden. Siehe auch den Absatz
        \jump{GeraetespezischeURL-Pfade}{Ger"atespezische URL-Pfade}
        in der Dokumentation.
        
        \achtung{Einfache Hochkommata sind in den Befehlen NICHT
            erlaubt, da sie "ublicherweise zum Einfassen der
            Parameterwerte verwendet werden.}

        Beispiel: \texttt{LPRNG\_POWER\_1\_URL\_STATUS\_FILTER='sed -e \grqq{}/<nv0>/!d\grqq{}\\
                  -e \grqq{}s/\textasciicircum.*<nv0>//\grqq{} -e \grqq s/</nv0>.*\$//\grqq{}'}

    \config{LPRNG\_POWER\_x\_PRINTER\_CAPNAME}{LPRNG\_POWER\_x\_PRINTER\_CAPNAME}{LPRNGPOWERxPRINTERCAPNAME}
        "Uber diesen Parameter legt man den eindeutigen Namen des
        Druckers fest welcher beim Eingang eines Druckauftrages
        automatisch eingeschaltet werden soll. Der Name entspricht
        "ublicherweise dem in der Samba-Paketkonfiguration
        festgelegten Wert des Parameters SAMBA\_PRINTER\_x\_CAPNAME.

        G"ultige Werte: Druckername

        Beispiel: \texttt{LPRNG\_POWER\_1\_PRINTER\_CAPNAME='repr1'}

    \config{LPRNG\_POWER\_x\_AUTH}{LPRNG\_POWER\_x\_AUTH}{LPRNGPOWERxAUTH}
        Wird dieser Parameter auf den Wert 'yes' gestellt, so kann
        man einen Benutzernamen und ein Kennwort festlegen welches zur
        Authentifizierung am Netzwerkschalter verwendet werden soll.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{LPRNG\_POWER\_1\_AUTH='no'}

    \config{LPRNG\_POWER\_x\_USER}{LPRNG\_POWER\_x\_USER}{LPRNGPOWERxUSER}
        "Uber diesen Parameter legt man den Benutzernamen fest, welcher
        zur Authentifizierung am Netzwerkschalter verwendet werden
        soll.

        G"ultige Werte: Benutzername

        Standardeinstellung: \texttt{LPRNG\_POWER\_1\_USER='admin'}

    \config{LPRNG\_POWER\_x\_PASS}{LPRNG\_POWER\_x\_PASS}{LPRNGPOWERxPASS}
        "Uber diesen Parameter legt man das Kennwort fest, welches
        zur Authentifizierung am Netzwerkschalter verwendet werden
        soll.

        G"ultige Werte: Kennwort

        Standardeinstellung: \texttt{LPRNG\_POWER\_1\_USER='allnet'}

    \config{LPRNG\_POWER\_x\_TIMEOUT}{LPRNG\_POWER\_x\_TIMEOUT}{LPRNGPOWERxTIMEOUT}
        "Uber diesen Parameter legt man fest nach wie viel Minuten
        der Netzwerkschalter nach dem Einschalten automatisiert
        ausgeschaltet werden soll.

        G"ultige Werte: Zeit in Minuten

        Standardeinstellung: \texttt{LPRNG\_POWER\_1\_TIMEOUT='10'}
\end{description}

\section{Verschiedenes}

\begin{description}
    \config{Ger"atespezische URL-Pfade}{Ger"atespezische URL-Pfade}{GeraetespezischeURL-Pfade}

    \begin{itemize}
        \item{Allnet\textregistered\ ALL3075-Netzwerksteckdose}
            URL: \url{https://www.allnet.de/nc/de/allnet-brand/support/treiber-firmware/download/61844/}
            \begin{verbatim}
LPRNG_POWER_1_URL_ON='/r?b=1&r=0&s=1'
LPRNG_POWER_1_URL_OFF='/r?b=1&r=0&s=0'
LPRNG_POWER_1_URL_STATUS='/xml'
LPRNG_POWER_1_URL_STATUS_FILTER='sed -e "/<nv0>/!d"
                                     -e "s/^.*<nv0>//"
                                     -e "s#</nv0>.*$##"'
            \end{verbatim}

        \item{OBI\textregistered\ WLAN-Steckdose (Tasmota-ROM 5.14.0)}\\
            URL: \url{https://github.com/arendst/Sonoff-Tasmota}
            \begin{verbatim}
LPRNG_POWER_1_URL_ON='/cm?cmnd=Power%20On'
LPRNG_POWER_1_URL_OFF='/cm?cmnd=Power%20Off'
LPRNG_POWER_1_URL_STATUS='/cm?cmnd=Power%20Status'
LPRNG_POWER_1_URL_STATUS_FILTER='grep "{\"POWER\":" |
                                 cut -d\" -f4 |
                                 sed -e "s/ON/1/"
                                     -e "s/OFF/0/"'
            \end{verbatim}

        \item{OBI\textregistered\ WLAN-Steckdose (ESPEasy-ROM)}\\
            URL: \url{https://www.letscontrolit.com/wiki/index.php/ESPEasy}
            \begin{verbatim}
LPRNG_POWER_1_URL_ON='/control?cmd=gpio,5,1'
LPRNG_POWER_1_URL_OFF='/control?cmd=gpio,5,0'
LPRNG_POWER_1_URL_STATUS='/control?cmd=status,gpio,5'
LPRNG_POWER_1_URL_STATUS_FILTER='grep "state" |
                                 cut -d" " -f2'
            \end{verbatim}

        \item{Shelly\textregistered\ Plug S-WLAN-Steckdose}\\
            URL: \url{https://shop.shelly.cloud/shelly-plug-s-wifi-smart-home-automation}
            \begin{verbatim}
LPRNG_POWER_1_URL_ON='/relay/0?turn=on'
LPRNG_POWER_1_URL_OFF='/relay/0?turn=off'
LPRNG_POWER_1_URL_STATUS='/relay/0?'
LPRNG_POWER_1_URL_STATUS_FILTER='cut -d: -f2 | cut -d, -f1 |
                                 sed -e "s/true/1/" -e "s/false/0/"' 
            \end{verbatim}

        \item{FHEM\textregistered\ SmartHome-Server}\\
            URL: \url{https://wiki.fhem.de/}
            \begin{verbatim}
LPRNG_POWER_1_URL_ON='/fhem?cmd=set%20<device-name>
                       %20ON&fwcsrf=<csrf-token>&XHR=1'
LPRNG_POWER_1_URL_OFF='/fhem?cmd=set%20<device-name>
                       %20ON&fwcsrf=<csrf-token>&XHR=0'
LPRNG_POWER_1_URL_STATUS='/fhem?cmd=list%20<device-name>
                          %20state&fwcsrf=<csrf-token>&XHR=1'
LPRNG_POWER_1_URL_STATUS_FILTER='sed -e "s/^.*[ \t]ON$/1/"
                                     -e "s/^.*[ \t]OFF$/0/'
            \end{verbatim}

    \end{itemize}
\end{description}
