rrd plugin: translate Readme into userdoc, update requirements

rrd/plugin.yaml

@@ -38,8 +38,21 @@ item_attributes:
         type: str
         valid_list: ['', 'yes', 'init']
         description:
-            de: "Wenn auf 'yes' gesetzt, werden die Werte des Items in die rrd Datenbank geschrieben. Wenn auf 'init' gesetzt, wird zusätzlich beim Start von SmartHomeNG der Wert aus rrd gelesen."
-            en: "This attribute enables the database logging when set (just use value 'yes'). If value 'init' is used, an item will be initalized from rrd after SmartHomeNG is restarted."
+            de: >
+                Wenn auf 'yes' gesetzt, werden die Werte des Items in die rrd Datenbank geschrieben. 
+                Wenn auf 'init' gesetzt, wird zusätzlich beim Start von SmartHomeNG der Wert aus rrd gelesen.
+                
+                Wenn für dieses Item ebenfalls ein Attribut 'sqlite' oder 'database' gesetzt ist, 
+                so ist die Wahrscheinlichkeit groß, das eines der Plugins nicht funktioniert.
+                Um dieses Problem zum umgehen kann das Attribut 'rrd_no_series' gesetzt werden.
+                
+            en: >
+                This attribute enables the database logging when set (just use value 'yes'). 
+                If value 'init' is used, an item will be initalized from rrd after SmartHomeNG is restarted.
+                
+                If this same item has the attribute ‘sqlite’ or ‘database’ it is likely
+                that one of the plugins will not work. To prevent this problem there is
+                the attribute ``rrd_no_series``
 
     rrd_step:
         type: int
@@ -59,13 +72,17 @@ item_attributes:
         valid_list: ['', 'gauge', 'counter' ]
         description:
             de: "Gibt die Art der Datenreihe in der Datenbank an: gauge für Temperaturen, counter für Zähler"
-            en: "Set the type of data samples in rrd: gauge for temperatures etc. and counter for continuous smartmeter readings"
+            en: >
+                Set the type of data source. Default ist ``gauge``. \* ``gauge`` -
+                should be used for things like temperatures. \* ``counter`` - should be
+                used for continuous incrementing counters like the Powermeter (kWh),
+                watercounter (m^3), pellets (kg).
 
     rrd_ds_name:
         type: str
         description:
             de: 'Alternativen Datenquellennamen festlegen. Wird dieser Name festgelegt, so wird nicht der Item Name für den Datenquellennamen verwendet'
-            en: 'alternative data source name. If set then the item`s name will not be used for data source but this name instead.'
+            en: 'Alternative data source name. If set then the item`s name will not be used for data source but this name instead.'
 
     rrd_min:
         type: bool

rrd/requirements.txt

@@ -1 +1 @@
-rrdtool>=0.1.15
+rrdtool>=0.1.16

rrd/user_doc.rst

@@ -0,0 +1,145 @@
+.. index:: Plugins; rrd
+.. index:: rrd
+
+
+===
+rrd
+===
+
+
+Das `RRDTool <https://oss.oetiker.ch/rrdtool/>`_  ist ein weitverbreitetes Tool um Zeitreihen von Messdaten aufzuzeichnen. 
+Dieses Plugin stellt die Möglichkeit bereit Itemwerte an das RRDTool weiterzugeben.
+
+
+
+Anforderungen
+=============
+
+Notwendige Software
+-------------------
+
+Das Paket Rrdtool und die entsprechenden Python Libraries müssen installiert sein.
+
+.. code:: bash
+
+    sudo apt-get install librrd-dev libpython3-dev
+
+
+Vergleich zwischen Datenbank-Plugin und rrdtool:
+------------------------------------------------
+
+Das RRD-Plugin und das Datenbank-Plugin können nicht zusammen für ein einzelnes Element verwendet werden.
+
+RRD
++ ein stabiles, zuverlässiges Werkzeug
++ wird in vielen Datenprotokollierungs- und Grafiktools verwendet
+- Die Entwicklung hat in den letzten Jahren nicht stattgefunden
+
+Datenbank-Plugin
++ Unterstützung für viele verschiedene Datenbanken wie SQLite, MySQL/MariaDB usw.
++ genaue Protokollierung der Änderungszeiten
++ mehr Analysefunktionalität
+
+Konfiguration
+=============
+
+Die Plugin Parameter und die Informationen zur Item-spezifischen Konfiguration des Plugins sind
+unter :doc:`/plugins_doc/config/rrd` beschrieben.
+
+
+plugin.yaml
+-----------
+
+Zu den Informationen, welche Parameter in der ../etc/plugin.yaml konfiguriert werden können bzw. müssen, bitte
+bitte die Dokumentation :doc:`Dokumentation </plugins_doc/config/rrd>` lesen, die aus
+den Metadaten der plugin.yaml erzeugt wurde (siehe oben).
+
+
+items.yaml
+----------
+
+Zu den Informationen, welche Attribute in der Item Konfiguration verwendet werden können bzw. müssen, bitte
+bitte die Dokumentation :doc:`Dokumentation </plugins_doc/config/rrd>` lesen, die aus
+den Metadaten der plugin.yaml erzeugt wurde (siehe oben).
+
+
+logic.yaml
+----------
+
+Zu den Informationen, welche Konfigurationsmöglichkeiten für Logiken bestehen, bitte
+bitte die Dokumentation :doc:`Dokumentation </plugins_doc/config/rrd>` lesen, die aus
+den Metadaten der plugin.yaml erzeugt wurde (siehe oben).
+
+Funktionen
+----------
+
+Zu den Informationen, welche Funktionen das Plugin bereitstellt (z.B. zur Nutzung in Logiken), bitte
+bitte die Dokumentation :doc:`Dokumentation </plugins_doc/config/rrd>` lesen, die aus
+den Metadaten der plugin.yaml erzeugt wurde (siehe oben).
+
+Das Plugin stellt für jedes Item das für die Verwendung mit dem Plugin konfiguriert wurde eine Datenbankfunktion bereit.
+
+``sh.item.db(function, start, end='now')``
+
+Diese Funktion liefert Werte unter Berücksichtigung der nachfolgend erläuterten Funktion und dem Zeitrahmen ``start`` und ``end``.
+
+Unterstützte Funktionen für die Datenaufbereitung sind:
+
+   * `avg`: Durchschnittswert
+   * `max`: Maximalwert
+   * `min`: Minimalwert
+   * `last`: Letzter eingetragener Wert
+
+Für das Zeitintervall müssen *relative* Anfangs- und Endzeitpunkte zum aktuellen Zeitpunkt angegeben werde.
+Der Vorgabewert für das Ende ist ``now`` was einer relativen Verschiebung um ``0`` entspricht.
+
+Die relativen Start- und Endzeitpunkte werden definiert durch ``<Nummer><Intervalleinheit>``
+Für die Intervalleinheit können folgende Kennzeichnungen verwendet werden:
+
+   * `i`: minute
+   * `h`: hour
+   * `d`: day
+   * `w`: week
+   + `m`: month
+   * `y`: year
+
+Beispiele
+=========
+
+.. code-block:: yaml
+
+    Aussen:
+        name: Aussen
+        Temperatur:
+            type: num
+            rrd: init
+            rrd_min: 'yes'
+            rrd_max: 'yes'
+
+    Wohnzimmer:
+        Temperatur:
+            type: num
+            rrd: 'yes'
+
+    Versorgung
+        Wasser:
+            type: num
+            rrd_type: counter
+
+Um das Minimum der letzten 24 Stunden zu ermitteln:
+
+.. code-block:: python
+
+    sh.Aussen.Temperatur.db('min', '1d')
+
+Um die Durchschnittstemperatur einer Woche zu ermitteln die vor genau 7 Tagen endete:
+
+.. code-block:: python
+    
+    sh.Aussen.Temperatur.db('avg', '2w', '1w')
+
+
+Web Interface
+=============
+
+Aktuell hat das Plugin kein Webinterface