Merge remote-tracking branch 'upstream/develop' into thread-1

doc/user/source/beispiele/beispiele.rst

@@ -5,6 +5,8 @@
 .. role:: greensup
 .. role:: blacksup
 
+.. index:: Beispiele
+.. index:: Tipps & Tricks
 
 =========================
 Beispiele, Tipps & Tricks
@@ -16,12 +18,12 @@ Dokumentation des jeweiligen Plugins im Abschnitt  :doc:`Plugins </plugins_all>`
 
 
 .. toctree::
-   :maxdepth: 5
-   :hidden:
-   :titlesonly:
+    :maxdepth: 5
+    :hidden:
+    :titlesonly:
 
-   eval.rst
-   items_tipps_und_tricks.rst
-   logiken/logiken.rst
-   structs.rst
-   knxd.rst
+    items/items.rst
+    logiken/logiken.rst
+    structs/structs.rst
+    plugins/plugins.rst
+    knxd.rst

doc/user/source/beispiele/items/items.rst

@@ -0,0 +1,18 @@
+
+.. index:: Beispiele; Items
+.. index:: Items; Beispiele
+
+=====
+Items
+=====
+
+Hier finden sich einige Beispiele, sowie Tipps & Tricks.
+
+
+.. toctree::
+    :maxdepth: 4
+    :titlesonly:
+
+    items_eval_evaltrigger.rst
+    items_tipps_und_tricks.rst
+

doc/user/source/beispiele/eval.rst → doc/user/source/beispiele/items/items_eval_evaltrigger.rst

@@ -6,8 +6,8 @@
 .. index:: Beispiele; eval
 
 
-Items: eval und eval_trigger
-============================
+eval und eval_trigger
+=====================
 
 Hier finden sich einige Beispiele für die Anwendung von **eval** und **eval_trigger**
 

doc/user/source/beispiele/items_tipps_und_tricks.rst → doc/user/source/beispiele/items/items_tipps_und_tricks.rst

@@ -1,23 +1,25 @@
 :tocdepth: 2
 
-.. index:: Beispiele; Tipps & Tricks
-.. index:: Tipps & Tricks
+.. index:: Items; Tipps & Tricks
+.. index:: Tipps & Tricks; Items
 
 .. role:: redsup
 .. role:: bluesup
 .. role:: greensup
 .. role:: blacksup
 
-=========================================
-Items: Tipps und Tricks :bluesup:`Update`
-=========================================
+==================================
+Tipps und Tricks :bluesup:`Update`
+==================================
 
 
 .. index:: Zeitglied
 .. index:: Timer
 .. index:: Items; Zeitglied
 
 
+.. index:: Tipps & Tricks; Items: Erstellen eines Zeitgiedes
+
 Erstellen eines Zeitgiedes
 ==========================
 
@@ -46,7 +48,7 @@ implementiert.
 |
 
 
-.. index:: Items; Wert invertieren
+.. index:: Tipps & Tricks; Items: Wert Invertieren
 
 Invertieren eines Item Wertes
 =============================
@@ -106,116 +108,7 @@ ein ``eval_trigger`` und ein ``eval`` zufügen.
 
 |
 
-Item Strukturen bequem kopieren
-===============================
-
-Bei Verwendung von relativer Item Adressierung können Teile des Item-Baumes einfach kopiert werden, um sie an
-anderer Stelle im Item-Baum zu verwenden.
-
-Es sollen Fensterkontakte ausgewertet werden (zwei Kontakte je Fenster oder z.B. Hoppe Fenstergriffe). Hierbei
-ergeben zwei Kontakte drei sinnvolle Stati (verschlossen, gekippt, offen). Die Auswertung setzt die
-Informationen der zwei Kontakte auf eigene Items für die drei Stati um.
-
-Diese Lösung soll mit möglichst wenig Aufwand für alle Fenster des Objekts kopiert werden. Mit normaler
-(absoluter) Item Adressierung kann das folgendermaßen gelöst werden:
-
-.. code-block:: yaml
-
-   Test:
-       Buero:
-           Reed1:
-               type: num
-               knx_dpt: 1
-               knx_cache: 4/1/5
-               visu_acl: rw
-
-           Reed2:
-               type: num
-               knx_dpt: 1
-               knx_cache: 4/1/6
-               visu_acl: rw
-
-           zu:
-               type: bool
-               enforce_updates: yes
-               eval: True if sh.Test.Buero.Reed1() == 1 and sh.Test.Buero.Reed2() == 1 else False
-               eval_trigger:
-                 - Test.Buero.Reed1
-                 - Test.Buero.Reed2
-
-           gekippt:
-               type: bool
-               enforce_updates: yes
-               eval: True if sh.Test.Buero.Reed1() == 0 and sh.Test.Buero.Reed2() == 1 else False
-               eval_trigger:
-                 - Test.Buero.Reed1
-                 - Test.Buero.Reed2
-
-           offen:
-               type: bool
-               enforce_updates: yes
-               eval: True if sh.Test.Buero.Reed1() == 0 and sh.Test.Buero.Reed2() == 0 else False
-               eval_trigger:
-                 - Test.Buero.Reed1
-                 - Test.Buero.Reed2
-
-Wenn dieser Block für weitere Fenster kopiert wird, muss jedoch außer der Anpassung der Adressen für
-``Reed1`` und ``Reed2`` auch noch ``Buero`` an diversen Stellen ersetzt werden, was einen gewissen Aufwand
-erfordert und auch noch fehlerträchtig ist.
-
-Mit relativer Item Adressierung kann das einfacher gelöst werden. Dann müssen nach dem Kopieren des Blocks nur
-noch die Adressen für ``Reed1`` und ``Reed2`` angepasst werden:
-
-.. code-block:: yaml
-
-   Test:
-       Buero:
-           Reed1:
-               type: num
-               knx_dpt: 1
-               knx_cache: 4/1/5
-               visu_acl: rw
-
-           Reed2:
-               type: num
-               knx_dpt: 1
-               knx_cache: 4/1/6
-               visu_acl: rw
-
-           zu:
-               type: bool
-               enforce_updates: yes
-               eval: True if sh...Reed1() == 1 and sh...Reed2() == 1 else False
-               eval_trigger:
-                 - ..Reed1
-                 - ..Reed2
-
-           gekippt:
-               type: bool
-               enforce_updates: yes
-               eval: True if sh...Reed1() == 0 and sh...Reed2() == 1 else False
-               eval_trigger:
-                 - ..Reed1
-                 - ..Reed2
-
-           offen:
-               type: bool
-               enforce_updates: yes
-               eval: True if sh...Reed1() == 0 and sh...Reed2() == 0 else False
-               eval_trigger:
-                 - ..Reed1
-                 - ..Reed2
-
-``..<item>`` referenziert hierbei ein Geschwister-Item. Es ist darauf zu achten, dass dort wo Items über
-``sh.<item>()`` angesprochen werden (wie im ``eval`` Attribut) dann drei statt der erwarteten zwei Punkte stehen.
-
-Ausführliche Informationen zur relativen Item Adressierung sind unter
-:doc:`relative Itemreferenzen </referenz/items/attributes_relative_referenzen>` zu finden.
-
-Das Beispiel ließe sich noch weiter vereinfachen, indem die Einträge durch **structs** referenziert werden.
-Detaillierte Informationen hierzu gibt es auf :doc:`structs (Item Strukturen) </konfiguration/item_structs>`
-
-|
+.. index:: Tipps & Tricks; Items: Erstellung von Tag-/Nacht-Items für KNX
 
 Erstellung von Tag-/Nacht-Items für KNX
 =======================================

doc/user/source/beispiele/plugins/plugin_aus_develop.rst

@@ -0,0 +1,104 @@
+
+.. index:: Tipps & Tricks; Plugins: Ein Plugin aus develop installieren
+
+.. _Plugin_aus_develop:
+
+Ein Plugin aus develop installieren
+===================================
+
+Falls in Probleme mit einem Plugin auftreten, kann es hilfreich sein eine neuere Version des Plugins aus dem develop
+Branch auf GitHub zu installieren, ohne deshalb die eigene Installation vollständig auf die (nicht notwendigerweise
+stabile) develop Version von SmartHomeNG zu wechseln.
+
+Im tools Verzeichnis gibt es ein Skript, welches ein gewähltes Plugin aus dem develop branch zusätzlich in die
+aktuelle Installation von SmartHomeNG kopiert. Damit kein Namenskonflikt mit einem bestehenden Plugin entsteht,
+wird an den Plugin Namen der String '_dev' angehängt. Ein Plugin mit dem Namen **xyz** wird also mit dem Namen
+**xyz_dev** in die bestehende SmartHomeNG Installation kopiert.
+
+Das Skript für Installation wird folgendermaßen gestartet:
+
+.. code-block:: bash
+
+    install_plugin_from_develop xyz
+
+Nachdem das Skript erfolgreich endet, ist ein zusätzliches Plugin **xyz_dev** in der Installation vorhanden.
+
+|
+
+Konfiguration anpassen
+----------------------
+
+Um das neue Plugin zu aktivieren, muss noch die Plugin Konfiguration in der Datei ``etc/plugin.yaml`` angepasst werden.
+Dazu muss im Abschnitt in dem das Plugin konfiguriert ist, der Eintrag ``plugin_name: xyz`` durch
+``plugin_name: xyz_dev`` ersetzt werden.
+
+Falls ein Logger für das ursprüngliche Plugin **xyz** konfiguriert ist, muss auch noch in ``etc/logging.yaml`` ein
+Logger für das Plugin **xyz_dev** konfiguriert werden. Dazu einfach den Abschnitt mit dem Logger ``plugins.xyz``
+kopieren und in der Kopie den Namen in ``plugins.xyz_dev`` ändern.
+
+|
+
+Plugin manuell installieren
+---------------------------
+
+Alternativ kann das Plugin manuell installiert werden. Im folgenden wird ein mögliches Vorgehen beschrieben,
+um ein Plugin aus dem develop Branch in eine Release Installation zu installieren. Dazu sind folgende Schritte
+durchzuführen:
+
+Plugins Repository aufrufen
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Im Browser die Seite http://www.github.com/smarthomeng/plugins aufrufen:
+
+.. image:: ../assets/plugin_install_1.jpg
+   :class: screenshot
+
+|
+
+und in den develop Branch wechseln:
+
+.. image:: ../assets/plugin_install_2.jpg
+   :class: screenshot
+
+|
+
+Plugins Repository Download
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Anschließend auf den grünen **Code** Button klicken und **Download ZIP** auswählen:
+
+.. image:: ../assets/plugin_install_3.jpg
+   :class: screenshot
+
+
+|
+
+Falls der Browser das ZIP Archiv nicht bereits entpackt hat, das Archiv ``plugins-develop.zip`` entpacken.
+
+|
+
+Gewünschtes Plugin installieren
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Um zum Beispiel ein Plugin mit dem Namen **xyz** aus dem develop Branch zu installieren, sollte (falls es existiert)
+zuerst das Verzeichnis **xyz_dev** im ``plugins`` Verzeichnis gelöscht werden, damit keine Seiteneffekte durch
+bestehende Dateien auftreten.
+
+Anschließend kann das Verzeichnis **xyz** (mit allen Bestandteilen/Unterordnern) aus dem beim Entpacken entstandenen
+Verzeichnis ``plugins-develop`` in das ``plugins`` Verzeichnis der SmartHomeNG Installation unter dem Namen **xyz_dev**
+kopiert werden.
+
+Nun kann das Archiv ``develop.zip`` und das Verzeichnis ``plugins-develop`` gelöscht werden.
+
+Konfiguration anpassen
+^^^^^^^^^^^^^^^^^^^^^^
+
+Um das neue Plugin zu aktivieren, muss noch die Plugin Konfiguration in der Datei ``etc/plugin.yaml`` angepasst werden.
+Dazu muss im Abschnitt in dem das Plugin konfiguriert ist, der Eintrag ``plugin_name: xyz`` durch
+``plugin_name: xyz_dev`` ersetzt werden.
+
+Falls ein Logger für das ursprüngliche Plugin **xyz** konfiguriert ist, muss auch noch in ``etc/logging.yaml`` ein
+Logger für das Plugin **xyz_dev** konfiguriert werden. Dazu einfach den Abschnitt mit dem Logger ``plugins.xyz``
+kopieren und in der Kopie den Namen in ``plugins.xyz_dev`` ändern.
+
+

doc/user/source/beispiele/plugins/plugins.rst

@@ -0,0 +1,17 @@
+
+.. index:: Tipps & Tricks; Plugins
+.. index:: Plugins; Tipps & Tricks
+
+=======
+Plugins
+=======
+
+Hier finden sich einige Tipps & Tricks zu Plugins.
+
+
+.. toctree::
+    :maxdepth: 4
+    :titlesonly:
+
+    plugin_aus_develop.rst
+