Merged branch 'development' into default for v1.3!

docs/api.rst

@@ -0,0 +1,100 @@
+API
+===
+The application has a simple, one-command API for remote dataloggers.
+
+
+Configuration
+-------------
+
+Enable API
+^^^^^^^^^^
+
+By default the API is disabled in the application. You may enable it in your configuration or admin settings.
+
+.. image:: _static/screenshots/admin_api_settings.png
+    :target: _static/screenshots/admin_api_settings.png
+    :alt: API admin settings
+
+Authentication
+^^^^^^^^^^^^^^
+Besides allowing the API to listen for requests, you will also need use the generated API Auth Key. 
+It can be found on the same page as in the screenshot above. The configuration page will also display it, but only partly.
+Feel free to alter the API Auth Key when required. The application randomly generates one initially for you. 
+
+You should pass it in the header of every API call. The header should be defined as ``X-AUTHKEY``. See below for an example. 
+
+Examples
+^^^^^^^^
+
+Using ``cURL``::
+
+   curl http://YOUR-DSMR-URL/api/v1/endpointX \
+        -d 'telegram=xxxxx' \
+        -H 'X-AUTHKEY: YOUR-DSMR-API-AUTHKEY'
+        
+Using ``requests``::
+
+   requests.post(
+        'http://YOUR-DSMR-URL/api/v1/datalogger/dsmrreading',
+        headers={'X-AUTHKEY': 'YOUR-DSMR-API-AUTHKEY'},
+        data={'telegram': 'xxxxx'},
+    )
+
+
+API calls
+---------
+
+POST ``/api/v1`` ``/datalogger/dsmrreading``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This allows you to insert a raw telegram, read from your meter remotely, into the application as if it was read locally using the serial cable.
+
+- Method: ``POST``
+- Data: ``telegram`` (as raw string containing all linefeeds ``\n``, and carriage returns ``\r``, as well!)
+- Status code returned: ``HTTP 200`` on success, any other on failure.
+
+Example
+~~~~~~~
+
+(using the ``requests`` library available on PIP)::
+
+    import requests  # Tested with requests==2.9.1
+    
+    # Fake buffer.
+    telegram_string = ''.join([
+        "/KFM5KAIFA-METER\r\n",
+        "\r\n",
+        "1-3:0.2.8(42)\r\n",
+        "0-0:1.0.0(160303164347W)\r\n",
+        "0-0:96.1.1(*******************************)\r\n",
+        "1-0:1.8.1(001073.079*kWh)\r\n",
+        "1-0:1.8.2(001263.199*kWh)\r\n",
+        "1-0:2.8.1(000000.000*kWh)\r\n",
+        "1-0:2.8.2(000000.000*kWh)\r\n",
+        "0-0:96.14.0(0002)\r\n",
+        "1-0:1.7.0(00.143*kW)\r\n",
+        "1-0:2.7.0(00.000*kW)\r\n",
+        "0-0:96.7.21(00006)\r\n",
+        "0-0:96.7.9(00003)\r\n",
+        "1-0:99.97.0(1)(0-0:96.7.19)(000101000001W)(2147483647*s)\r\n",
+        "1-0:32.32.0(00000)\r\n",
+        "1-0:32.36.0(00000)\r\n",
+        "0-0:96.13.1()\r\n",
+        "0-0:96.13.0()\r\n",
+        "1-0:31.7.0(000*A)\r\n",
+        "1-0:21.7.0(00.143*kW)\r\n",
+        "1-0:22.7.0(00.000*kW)\r\n",
+        "!74B0\n",
+    ])
+    
+    # Register telegram by simply sending it to the application with a POST request.
+    response = requests.post(
+        'http://YOUR-DSMR-URL/api/v1/datalogger/dsmrreading',
+        headers={'X-AUTHKEY': 'YOUR-DSMR-API-AUTHKEY'},
+        data={'telegram': telegram_string},
+    )
+       
+    # You will receive a status 200 when successful.
+    if response.status_code != 200:
+        # Or you will find the error (hint) in the reponse body on failure.
+        print('Error: {}'.format(response.text))
+    

docs/changelog.rst

@@ -2,6 +2,15 @@ Changelog
 =========
 
 
+v1.3.0 - 2016-07-15
+^^^^^^^^^^^^^^^^^^^
+- API endpoint for datalogger (`#140 <https://github.com/dennissiemensma/dsmr-reader/issues/140>`_).
+- Colors for charts (`#137 <https://github.com/dennissiemensma/dsmr-reader/issues/137>`_).
+- Data export: Mindergas.nl (`#10 <https://github.com/dennissiemensma/dsmr-reader/issues/10>`_).
+- Requirement upgrade (`#143 <https://github.com/dennissiemensma/dsmr-reader/issues/143>`_).
+- Installation wizard for first time use (`#139 <https://github.com/dennissiemensma/dsmr-reader/issues/139>`_).
+
+
 v1.2.0 - 2016-05-18
 ^^^^^^^^^^^^^^^^^^^
 - Energy supplier prices does not indicate tariff type (Django admin) (`#126 <https://github.com/dennissiemensma/dsmr-reader/issues/126>`_).

docs/credits.rst

@@ -13,6 +13,8 @@ Software
 
 - `Django Solo <https://github.com/lazybird/django-solo>`_
 
+- `Django Colorfield <https://github.com/jaredly/django-colorfield>`_
+
 - `Supervisor <http://supervisord.org/>`_
 
 - `MySQL <https://www.mysql.com/>`_
@@ -39,6 +41,8 @@ Software
 
 - `Full Page Screen Capture <https://chrome.google.com/webstore/detail/full-page-screen-capture/fdpohaocaechififmbbbbbknoalclacl?>`_
 
+- `Twitter Bootstrap Wizard <https://github.com/VinceG/twitter-bootstrap-wizard>`_
+
 
 Testers & contributors
 ----------------------

docs/faq.rst

@@ -1,18 +1,64 @@
 Frequently Asked Questions (FAQ)
 ================================
 
-Feature/bug report
-------------------
-**How can I propose a feature or report a bug I've found?**
+Dropbox: Automated backup sync
+------------------------------
+*How can I link my Dropbox account for backups?*
+
+Make sure you have a Dropbox-account or sign up for one. 
+Now go to `Dropbox Apps <https://www.dropbox.com/developers/apps>`_ and click **"Create app"** in top right corner.
+
+.. image:: _static/faq/dropbox_apps_overview.png
+    :target: _static/faq/dropbox_apps_overview.png
+    :alt: Dropbox Apps
+
+Choose the following options: (1) **Dropbox API** and (2) **App folder**. 
+Then enter a name for your app (3), this will also be used as directory name within the Apps-folder of your Dropbox. 
+
+.. image:: _static/faq/dropbox_create_app.png
+    :target: _static/faq/dropbox_create_app.png
+    :alt: Dropbox Apps
+
+The app should be created in developer-mode. You can generate an access token for yourself by clicking the **"Generate"** button somewhere below.
+
+.. image:: _static/faq/dropbox_app_token.png
+    :target: _static/faq/dropbox_app_token.png
+    :alt: Dropbox Apps
+
+Copy the generated access token to the DSMR-reader settings for the Dropbox-configuration. The DSMR-reader application should sync any backups created shortly.
+
+
+Mindergas.nl: Automated gas meter position export
+-------------------------------------------------
+*How can I link my mindergas.nl account?*
+
+Make sure you have a Mindergas.nl-account or `signup for one <https://www.mindergas.nl/users/sign_up>`_. 
+Now go to "`Meterstand API <https://www.mindergas.nl/member/api>`_" and click on the button located below **"Authenticatietoken"**.
+
+.. image:: _static/faq/mindergas_api.png
+    :target: _static/faq/mindergas_api.png
+    :alt: Mindergas API
+
+Copy the authentication token generated and paste in into the DSMR-reader settings for the Mindergas.nl-configuration.
+Obviously the export only works when there are any gas readings at all and you have ticked the 'export' checkbox in the Mindergas.nl-configuration as well.
+
+Please note that due to policies of mindergas.nl it's not allowed to retroactively upload meter positions using the API. 
+Therefor this is not supported by the application. You can however, enter them manually on their website. 
 
-`Just create a ticket at Github <https://github.com/dennissiemensma/dsmr-reader/issues/new>`_
 
 Recalculate prices
 ------------------
-**I've adjusted my energy prices but there are no changes! How can I regenerate them with my new prices?**
+*I've adjusted my energy prices but there are no changes! How can I regenerate them with my new prices?*
 
-*You can flush your statistics by executing:*
+You can flush your statistics by executing:
 
 ``./manage.py dsmr_stats_clear_statistics --ack-to-delete-my-data``
 
-*The application will delete all statistics and (slowly) regenerate them in the background. Just make sure the source data is still there.*
+The application will delete all statistics and (slowly) regenerate them in the background. Just make sure the source data is still there.
+
+
+Feature/bug report
+------------------
+*How can I propose a feature or report a bug I've found?*
+
+`Just create a ticket at Github <https://github.com/dennissiemensma/dsmr-reader/issues/new>`_

docs/index.rst

@@ -8,6 +8,7 @@ DSMR Reader's documentation
    screenshots
    installation
    application
+   api
    faq
    changelog
    contributing

docs/locale/nl/LC_MESSAGES/api.po

@@ -0,0 +1,126 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2016, Dennis Siemensma
+# This file is distributed under the same license as the DSMR Reader
+# package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2016.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: DSMR Reader 1.0\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2016-05-19 22:24+0200\n"
+"PO-Revision-Date: 2016-05-19 22:32+0100\n"
+"Last-Translator: Dennis Siemensma <dsmr@dennissiemensma.nl>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.2.0\n"
+"X-Generator: Poedit 1.5.4\n"
+
+#: ../../api.rst:2
+msgid "API"
+msgstr "API"
+
+#: ../../api.rst:3
+msgid "The application has a simple, one-command API for remote dataloggers."
+msgstr ""
+"De applicatie heeft een eenvoudige, enkele API-call voor dataloggers op "
+"afstand."
+
+#: ../../api.rst:7
+msgid "Configuration"
+msgstr "Configuratie"
+
+#: ../../api.rst:10
+msgid "Enable API"
+msgstr "API inschakelen"
+
+#: ../../api.rst:12
+msgid ""
+"By default the API is disabled in the application. You may enable it in your "
+"configuration or admin settings."
+msgstr ""
+"Standaard is de API in de applicatie uitgeschakeld. Je kunt deze inschakelen "
+"in het configuratiescherm of beheerderpaneel."
+
+#: ../../api.rst:19
+msgid "Authentication"
+msgstr "Autorisatie"
+
+#: ../../api.rst:20
+msgid ""
+"Besides allowing the API to listen for requests, you will also need use the "
+"generated API Auth Key. It can be found on the same page as in the "
+"screenshot above. The configuration page will also display it, but only "
+"partly. Feel free to alter the API Auth Key when required. The application "
+"randomly generates one initially for you."
+msgstr ""
+"Naast het inschakelen van de API zul je ook een (automatisch) gegenereerde "
+"API autorisatiesleutel moeten gebruiken. Deze kun je terugvinden op dezelfde "
+"pagina als in bovenstaand screenshot. Op de configuratiepagina staat de "
+"sleutel ook, maar slechts ten delete. Pas overigens gerust de API "
+"autorisatiesleutel naar wens aan. De applicatie genereert eenmalig initieel "
+"een voor je."
+
+#: ../../api.rst:24
+msgid ""
+"You should pass it in the header of every API call. The header should be "
+"defined as ``X-AUTHKEY``. See below for an example."
+msgstr ""
+"Je moet deze gebruiken voor elke API call die je uitvoert. De header heet "
+"``X-AUTHKEY``. Zie hieronder voor een voorbeeld."
+
+#: ../../api.rst:27
+msgid "Examples"
+msgstr "Voorbeelden"
+
+#: ../../api.rst:29
+msgid "Using ``cURL``::"
+msgstr "Met ``cURL``::"
+
+#: ../../api.rst:35
+msgid "Using ``requests``::"
+msgstr "Met ``requests``::"
+
+#: ../../api.rst:45
+msgid "API calls"
+msgstr "API calls"
+
+#: ../../api.rst:48
+msgid "POST ``/api/v1`` ``/datalogger/dsmrreading``"
+msgstr "POST ``/api/v1`` ``/datalogger/dsmrreading``"
+
+#: ../../api.rst:49
+msgid ""
+"This allows you to insert a raw telegram, read from your meter remotely, "
+"into the application as if it was read locally using the serial cable."
+msgstr ""
+"Dit staat je toe om een ruwe telegram aan de applicatie door te geven, "
+"wanneer je deze op afstand uitleest."
+
+#: ../../api.rst:51
+msgid "Method: ``POST``"
+msgstr "Methode: ``POST``"
+
+#: ../../api.rst:52
+msgid ""
+"Data: ``telegram`` (as raw string containing all linefeeds ``\\n``, and "
+"carriage returns ``\\r``, as well!)"
+msgstr ""
+"Data: ``telegram`` (als een ruwe tekenreeks inclusief zowel alle regeleindes "
+"``\\n`` als 'carriage returns' ``\\r``)"
+
+#: ../../api.rst:53
+msgid "Status code returned: ``HTTP 200`` on success, any other on failure."
+msgstr ""
+"Status code resultaat: ``HTTP 200`` wanneer succesvol, elke andere code bij "
+"falen."
+
+#: ../../api.rst:56
+msgid "Example"
+msgstr "Voorbeeld"
+
+#: ../../api.rst:58
+msgid "(using the ``requests`` library available on PIP)::"
+msgstr "(met de ``requests`` tool beschikbaar in PIP)::"