Plugin documentation #486

Author: dennissiemensma

docs/changelog.rst

@@ -26,6 +26,7 @@ v1.20.0 - 2018-xx-xx
 - [`#484 <https://github.com/dennissiemensma/dsmr-reader/issues/484>`_] API call om huidige versie terug te geven
 - [`#291 <https://github.com/dennissiemensma/dsmr-reader/issues/291>`_] API option to get status info
 - [`#485 <https://github.com/dennissiemensma/dsmr-reader/issues/485>`_] Retrieve the current energycontract for the statistics page - helmo
+- [`#486 <https://github.com/dennissiemensma/dsmr-reader/issues/486>`_] Plugin documentation
 
 
 

docs/credits.rst

@@ -75,7 +75,7 @@ Please note and respect their licences as well, if any. Credits to the following
 - `MySQL <https://www.mysql.com/>`_
 - `MariaDB <https://mariadb.org/>`_
 - `PostgreSQL <http://www.postgresql.org/>`_
-- `Director Responsive Admin <http://web-apps.ninja/director-free-responsive-admin-template/>`_
+- Director Responsive Admin template (website is offline) 
 - Favicon made by `Freepik <http://www.freepik.com/>`_ from `flaticon.com <http://www.flaticon.com/free-icon/eco-energy_25013>`_
 - `Real Favicon Generator <http://realfavicongenerator.net>`_
 - `Bootstrap-datepicker <http://bootstrap-datepicker.readthedocs.org/>`_
@@ -87,7 +87,6 @@ Please note and respect their licences as well, if any. Credits to the following
 - `Full Page Screen Capture <https://chrome.google.com/webstore/detail/full-page-screen-capture/fdpohaocaechififmbbbbbknoalclacl?>`_
 - `Buienradar <http://www.buienradar.nl>`_
 - `Django REST Framework <http://www.django-rest-framework.org>`_
-- `Swagger UI Themes <http://meostrander.com/swagger-ui-themes/>`_
 
 
 Misc

docs/index.rst

@@ -12,6 +12,7 @@ DSMR Reader's documentation
    settings
    retention
    api
+   plugins
    mqtt
    mindergas
    pvoutput

docs/locale/nl/LC_MESSAGES/api.mo

@@ -276,9 +276,7 @@ msgid "`PostgreSQL <http://www.postgresql.org/>`_"
 msgstr ""
 
 #: ../../credits.rst:78
-msgid ""
-"`Director Responsive Admin <http://web-apps.ninja/director-free-"
-"responsive-admin-template/>`_"
+msgid "Director Responsive Admin template (website is offline)"
 msgstr ""
 
 #: ../../credits.rst:79
@@ -329,33 +327,29 @@ msgstr ""
 msgid "`Django REST Framework <http://www.django-rest-framework.org>`_"
 msgstr ""
 
-#: ../../credits.rst:90
-msgid "`Swagger UI Themes <http://meostrander.com/swagger-ui-themes/>`_"
-msgstr ""
-
-#: ../../credits.rst:94
+#: ../../credits.rst:93
 msgid "Misc"
 msgstr "Overig"
 
-#: ../../credits.rst:96
+#: ../../credits.rst:95
 msgid "Dutch Smart Meter reading specifications, data cables, examples and hints:"
 msgstr "Dutch Smart Meter reading specifications, data cables, examples and hints:"
 
-#: ../../credits.rst:98
+#: ../../credits.rst:97
 msgid "`Gé Janssen <http://gejanssen.com/howto/Slimme-meter-uitlezen/>`_"
 msgstr ""
 
-#: ../../credits.rst:100
+#: ../../credits.rst:99
 msgid ""
 "`Joost van der Linde (smartmeterdashboard) "
 "<http://www.smartmeterdashboard.nl/>`_"
 msgstr ""
 
-#: ../../credits.rst:102
+#: ../../credits.rst:101
 msgid "`SOS Solutions <https://www.sossolutions.nl/>`_"
 msgstr ""
 
-#: ../../credits.rst:104
+#: ../../credits.rst:103
 msgid "`Nico Di Rocco <http://nrocco.github.io/>`_"
 msgstr ""
 
@@ -368,3 +362,12 @@ msgstr ""
 #~ msgid "`raoulteeuwen <https://github.com/raoulteeuwen >`_"
 #~ msgstr ""
 
+#~ msgid ""
+#~ "`Director Responsive Admin <http://web-"
+#~ "apps.ninja/director-free-responsive-admin-"
+#~ "template/>`_"
+#~ msgstr ""
+
+#~ msgid "`Swagger UI Themes <http://meostrander.com/swagger-ui-themes/>`_"
+#~ msgstr ""
+

docs/locale/nl/LC_MESSAGES/changelog.mo

@@ -0,0 +1,196 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2015 - 2018, Dennis Siemensma
+# This file is distributed under the same license as the DSMR Reader
+# package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2018.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: DSMR Reader 1.x\n"
+"Report-Msgid-Bugs-To: \n"
+"Last-Translator: \n"
+"Language: nl\n"
+"Language-Team: \n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.5.1\n"
+"X-Generator: Poedit 1.8.7.1\n"
+
+#: ../../plugins.rst:2
+msgid "Plugins/hooks (Do It Yourself)"
+msgstr "Plugins/hooks (Doe-Het-Zelf)"
+
+#: ../../plugins.rst:3
+msgid ""
+"The application allows you to create and add plugins, hooking on certain "
+"events triggered."
+msgstr ""
+"De applicatie staat je toe om plugins te maken en te koppelen, op bepaalde "
+"gebeurtenissen."
+
+#: ../../plugins.rst:6
+msgid "Contents"
+msgstr "Inhoudsopgave"
+
+#: ../../plugins.rst:9
+msgid "Configuration"
+msgstr "Configuratie"
+
+#: ../../plugins.rst:11
+msgid ""
+"You can create plugins in their own file in ``dsmr_plugins/modules/"
+"plugin_name.py``, where ``plugin_name`` is the name of your plugin."
+msgstr ""
+"Je kan plugins maken in hun eigen bestand in ``dsmr_plugins/modules/"
+"plugin_naam.py``, waar ``plugin_naam`` de naam van je plugin is."
+
+#: ../../plugins.rst:14
+msgid "Please make sure the ``plugin_name``,"
+msgstr "Zorg er voor dat ``plugin_naam``,"
+
+#: ../../plugins.rst:16
+msgid "is lowercase (``plugin_name`` and **not** ``PLUGIN_NAME``),"
+msgstr "zonder hoofdletters is (``plugin_naam`` en **niet** ``PLUGIN_NAAM``),"
+
+#: ../../plugins.rst:17
+msgid ""
+"does not contains spaces or dashes, just use underscores and do not start "
+"the name with a digit."
+msgstr ""
+"geen spaties of koppeltekens bevat, gebruik daarvoor underscores en begin "
+"de naam niet met een cijfer."
+
+#: ../../plugins.rst:20
+msgid ""
+"Add the **dotted** path to the end of your ``dsmrreader/settings.py`` file::"
+msgstr ""
+"Voeg het **dotted** pad toe aan het einde van je ``dsmrreader/settings.py`` "
+"bestand::"
+
+#: ../../plugins.rst:27
+msgid ""
+"Your plugin file is imported once, so you should make sure to hook any "
+"events you want."
+msgstr ""
+"Je plugin-bestand wordt eenmalig geimporteerd, dus zorg ervoor dat je "
+"gebeurtenissen koppelt die je wilt volgen."
+
+#: ../../plugins.rst:29
+msgid ""
+"And finally, make sure to **reload the application** by deploying it again. "
+"You can do that by simply executing the ``post-deploy.sh`` script in the "
+"root of the project."
+msgstr ""
+"En tot slot, zorg ervoor dat je **de applicatie herlaadt** door opnieuw te "
+"deployen. Je kunt dat doen door simpelweg ``post-deploy.sh`` uit te voeren, "
+"het script in de root van het project."
+
+#: ../../plugins.rst:33
+msgid "Events / Signals"
+msgstr "Gebeurtenissen / Signalen"
+
+#: ../../plugins.rst:34
+msgid ""
+"These are either dispatched by the Django framework or the application at "
+"some point."
+msgstr ""
+"Deze worden verstuurd door ofwel het Django framework ofwel de applicatie "
+"zelf."
+
+#: ../../plugins.rst:37
+msgid "``dsmr_backend.signals.backend_called``"
+msgstr "``dsmr_backend.signals.backend_called``"
+
+#: ../../plugins.rst:39
+msgid ""
+"Called by each iteration of the backend. Please use with caution, as it may "
+"block all backend operations when used improperly."
+msgstr ""
+"Aangeroepen bij elke iteratie van de backend. Gebruik dit terughoudend, "
+"gezien het alle backend-acties kan blokkeren wanneer het verkeerd gebruikt "
+"wordt."
+
+#: ../../plugins.rst:43
+msgid "``dsmr_pvoutput.signals.pvoutput_upload``"
+msgstr "``dsmr_pvoutput.signals.pvoutput_upload``"
+
+#: ../../plugins.rst:44
+msgid ""
+"Called by dsmr_pvoutput just before uploading data to PVOutput. The "
+"``data`` kwarg contains the data to be sent."
+msgstr ""
+"Aangeroepen door dsmr_pvoutput vlak voor het uploaden van gegevens naar "
+"PVOutput. De ``data`` kwarg bevat de gegevens die verstuurd worden."
+
+#: ../../plugins.rst:48
+msgid "``dsmr_datalogger.signals.raw_telegram``"
+msgstr "``dsmr_datalogger.signals.raw_telegram``"
+
+#: ../../plugins.rst:49
+msgid ""
+"Called by dsmr_datalogger when receiving or reading a telegram string. The "
+"``data`` kwarg contains the raw telegram string."
+msgstr ""
+"Aangeroepen door dsmr_datalogger wanneer er een telegram ontvangen of "
+"uitgelezen wordt. De ``data`` kwarg bevat de ruwe string met het telegram."
+
+#: ../../plugins.rst:53
+msgid "``django.db.models.signals.post_save``"
+msgstr "``django.db.models.signals.post_save``"
+
+#: ../../plugins.rst:54
+msgid ""
+"Called by Django after saving new records to the database. Can be bound to "
+"the ``DayStatistics`` model for example, to process daily statistics "
+"elsewhere."
+msgstr ""
+"Aangeroepen door Django bij het opslaan van nieuwe databaserecords. Kan "
+"gekoppeld worden aan bijvoorbeeld het ``DayStatistics`` model, om "
+"dagelijkse statistieken ergens anders te verwerken."
+
+#: ../../plugins.rst:58
+msgid "Other"
+msgstr "Overige"
+
+#: ../../plugins.rst:59
+msgid ""
+"More signals may be available for use, please be careful when binding "
+"Django save-signals as it may impact performance. :doc:`If you need any "
+"help or information, please seek contact via Github<contributing>`."
+msgstr ""
+"Meer signalen/gebeurtenissen zijn beschikbaar voor gebruik, echter wees "
+"voorzichtig bij het gebruiken van Django save-signalen, aangezien het de "
+"performance kan beïnvloeden.  :doc:`Mocht je hulp of informatie nodig "
+"hebben, zoek dan contact via Github<contributing>`."
+
+#: ../../plugins.rst:64
+msgid "Example: Upload data to second PVOutput account"
+msgstr "Voorbeeld: Upload gegevens naar een tweede PVOutput-account"
+
+#: ../../plugins.rst:65
+msgid ""
+"This is an example of issue `#407 <https://github.com/dennissiemensma/dsmr-"
+"reader/issues/407>`_, requesting the feature to upload data to a second "
+"PVOuput account."
+msgstr ""
+"Dit is een voorbeeld van issue `#407 <https://github.com/dennissiemensma/"
+"dsmr-reader/issues/407>`_, met het verzoek om gegevens te uploaden naar een "
+"tweede PVOutput-account."
+
+#: ../../plugins.rst:68
+msgid "Settings file ``dsmrreader/settings.py`` (addition)::"
+msgstr "Settings bestand ``dsmrreader/settings.py`` (toevoeging)::"
+
+#: ../../plugins.rst:75
+msgid "Plugin file ``dsmr_plugins/modules/pvoutput.py``::"
+msgstr "Plugin bestand ``dsmr_plugins/modules/pvoutput.py``::"
+
+#: ../../plugins.rst:101
+msgid ""
+"Note that the ``XXXXX`` and ``YYYYY`` variables should be replace by your "
+"second set of PVOutput API credentials."
+msgstr ""
+"N.B.: De variablen ``XXXXX`` en ``YYYYY`` zouden vervangen moeten worden "
+"met de API-credentials van je tweede PVOutput-account."

docs/locale/nl/LC_MESSAGES/credits.mo

@@ -0,0 +1,101 @@
+Plugins/hooks (Do It Yourself)
+==============================
+The application allows you to create and add plugins, hooking on certain events triggered.
+
+
+.. contents::
+
+Configuration
+~~~~~~~~~~~~~
+
+You can create plugins in their own file in ``dsmr_plugins/modules/plugin_name.py``, 
+where ``plugin_name`` is the name of your plugin. 
+
+Please make sure the ``plugin_name``,
+
+* is lowercase (``plugin_name`` and **not** ``PLUGIN_NAME``),
+* does not contains spaces or dashes, just use underscores and do not start the name with a digit.
+
+
+Add the **dotted** path to the end of your ``dsmrreader/settings.py`` file::
+
+    DSMRREADER_PLUGINS = [
+        'dsmr_plugins.modules.plugin_name1',
+        'dsmr_plugins.modules.plugin_name2',
+    ]
+
+Your plugin file is imported once, so you should make sure to hook any events you want.
+
+And finally, make sure to **reload the application** by deploying it again. You can do that by simply executing the ``post-deploy.sh`` script in the root of the project.
+
+
+Events / Signals
+----------------
+These are either dispatched by the Django framework or the application at some point.
+
+``dsmr_backend.signals.backend_called``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Called by each iteration of the backend. Please use with caution, as it may block all backend operations when used improperly.
+
+
+``dsmr_pvoutput.signals.pvoutput_upload``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Called by dsmr_pvoutput just before uploading data to PVOutput. The ``data`` kwarg contains the data to be sent.
+
+
+``dsmr_datalogger.signals.raw_telegram``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Called by dsmr_datalogger when receiving or reading a telegram string. The ``data`` kwarg contains the raw telegram string.
+
+
+``django.db.models.signals.post_save``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Called by Django after saving new records to the database. Can be bound to the ``DayStatistics`` model for example, to process daily statistics elsewhere.
+
+
+Other
+^^^^^
+More signals may be available for use, please be careful when binding Django save-signals as it may impact performance.
+:doc:`If you need any help or information, please seek contact via Github<contributing>`.
+
+
+Example: Upload data to second PVOutput account
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This is an example of issue `#407 <https://github.com/dennissiemensma/dsmr-reader/issues/407>`_, requesting the feature to upload data to a second PVOuput account.
+
+
+Settings file ``dsmrreader/settings.py`` (addition)::
+
+    DSMRREADER_PLUGINS = [
+        'dsmr_plugins.modules.pvoutput',
+    ]
+
+
+Plugin file ``dsmr_plugins/modules/pvoutput.py``::
+
+    import requests
+    
+    from dsmr_pvoutput.models.settings import PVOutputAddStatusSettings
+    from dsmr_pvoutput.signals import pvoutput_upload
+    
+    def handle_pvoutput_upload(sender, **kwargs):
+        print(' - Uploading the same data to PVOutput using plugin: {}'.format(kwargs['data']))
+    
+        response = requests.post(
+            PVOutputAddStatusSettings.API_URL,
+            headers={
+                'X-Pvoutput-Apikey': 'XXXXX',
+                'X-Pvoutput-SystemId': 'YYYYY',
+            },
+            data=kwargs['data']
+        )
+    
+        if response.status_code != 200:
+            print(' [!] PVOutput upload failed (HTTP {}): {}'.format(response.status_code, response.text))
+    
+    
+    pvoutput_upload.connect(receiver=handle_pvoutput_upload)
+
+
+Note that the ``XXXXX`` and ``YYYYY`` variables should be replace by your second set of PVOutput API credentials.