Merge for v1.6 release!

dsmrreader · Mar 18, 2017 · f0d635e · f0d635e
1 parent 5d1918b
commit f0d635e
Show file tree

Hide file tree

Showing 116 changed files with 4,180 additions and 2,051 deletions.
diff --git a/README.md b/README.md
@@ -1,25 +1,29 @@
 [![Build Status](https://travis-ci.org/dennissiemensma/dsmr-reader.svg?branch=master)](https://travis-ci.org/dennissiemensma/dsmr-reader)
 [![Coverage](https://codecov.io/github/dennissiemensma/dsmr-reader/coverage.svg?branch=master)](https://codecov.io/gh/dennissiemensma/dsmr-reader/branch/master)
-[![Requirements Status](https://requires.io/github/dennissiemensma/dsmr-reader/requirements.svg?branch=master)](https://requires.io/github/dennissiemensma/dsmr-reader/requirements/?branch=master)
 [![Documentation Status](https://readthedocs.org/projects/dsmr-reader/badge/?version=latest)](https://dsmr-reader.readthedocs.io/en/latest/?badge=latest)
+[![Requirements Status](https://requires.io/github/dennissiemensma/dsmr-reader/requirements.svg?branch=master)](https://requires.io/github/dennissiemensma/dsmr-reader/requirements/?branch=master)
 
+# DSMR Reader Datalogger/GUI
 
-# Documentation (English & Dutch / Nederlands)
-
-**English**
-
-See [Read The Docs, in English](https://dsmr-reader.readthedocs.io/en/latest/). Installation guide can be found there as well.
+## Project mission & goals
+- Have fun by reading your smart meter at home yourself!
+- Provide an easy to use setup for logging your own energy consumption.
+- Keeping your data for yourself (all data is stored locally and untracked as well).
+- Always free to use (and open source).
 
-**Dutch / Nederlands**
 
-Zie [Read The Docs, in het Nederlands](https://dsmr-reader.readthedocs.io/nl/latest/). Je kunt daar ook alle installatieinstructies vinden.
+## Documentation (`English` & `Nederlands`)
+- `English`: See [Read The Docs, in English](https://dsmr-reader.readthedocs.io/en/latest/). Installation guide can be found there as well.
+- `Nederlands`: Zie [Read The Docs, in het Nederlands](https://dsmr-reader.readthedocs.io/nl/latest/). Je kunt daar ook alle installatieinstructies vinden.
 
 
-# Screenshots
+## Screenshots
 More screenshots can be found in the documentation at [Read The Docs](https://dsmr-reader.readthedocs.io/en/latest/screenshots.html).
 
-## Dashboard
+
+### Dashboard
 ![Dashboard](docs/_static/screenshots/dashboard.png)
 
-## Archive
+
+### Archive
 ![Archive](docs/_static/screenshots/archive.png)
diff --git a/docs/api.rst b/docs/api.rst
@@ -58,9 +58,14 @@ This allows you to insert a raw telegram, read from your meter remotely, into th
 
 Parameters
 ~~~~~~~~~~
+
+.. note::
+
+    Since ``v1.6`` this call now returns ``HTTP 201`` instead of ``HTTP 200`` when successful.
+
 - 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.
+- Status code returned: ``HTTP 201`` on success, any other on failure.
 
 Example
 ~~~~~~~
@@ -103,8 +108,8 @@ Example
         data={'telegram': telegram_string},
     )
 
-    # You will receive a status 200 when successful.
-    if response.status_code != 200:
+    # You will receive a status 201 when successful.
+    if response.status_code != 201:
         # Or you will find the error (hint) in the reponse body on failure.
         print('Error: {}'.format(response.text))
 
@@ -151,14 +156,15 @@ Client file in ``/home/dsmr/dsmr_datalogger_api_client.py``::
     def main():
         print ('Starting...')
 
-        while True:
-            telegram = read_telegram()
-            print('Read telegram', telegram)
+        for telegram in read_telegram():
+            print('Telegram read')
+            print(telegram)
 
             for current_server in API_SERVERS:
                 api_url, api_key = current_server
+
+                print('Sending telegram to:', api_url)
                 send_telegram(telegram, api_url, api_key)
-                print('Sent telegram to:', api_url)
 
             sleep(1)
 
@@ -179,7 +185,7 @@ Client file in ``/home/dsmr/dsmr_datalogger_api_client.py``::
         serial_handle.open()
 
         telegram_start_seen = False
-        telegram = ''
+        buffer = ''
 
         # Just keep fetching data until we got what we were looking for.
         while True:
@@ -188,7 +194,7 @@ Client file in ``/home/dsmr/dsmr_datalogger_api_client.py``::
             except SerialException as error:
                 # Something else and unexpected failed.
                 print('Serial connection failed:', error)
-                return
+                raise StopIteration()  # Break out of yield.
 
             try:
                 # Make sure weird characters are converted properly.
@@ -205,12 +211,15 @@ Client file in ``/home/dsmr/dsmr_datalogger_api_client.py``::
 
             # Delay any logging until we've seen the start of a telegram.
             if telegram_start_seen:
-                telegram += data
+                buffer += data
 
             # Telegrams ends with '!' AND we saw the start. We should have a complete telegram now.
             if data.startswith('!') and telegram_start_seen:
-                serial_handle.close()
-                return telegram
+                yield buffer
+
+                # Reset the flow again.
+                telegram_start_seen = False
+                buffer = ''
 
 
     def send_telegram(telegram, api_url, api_key):
@@ -221,16 +230,16 @@ Client file in ``/home/dsmr/dsmr_datalogger_api_client.py``::
             data={'telegram': telegram},
         )
 
-        # You will receive a status 200 when successful.
-        if response.status_code != 200:
-            # Or you will find the error (hint) in the response body on failure.
-            print('[!] Error: {}'.format(response.text))
-
+        # Old versions of DSMR-reader return 200, new ones 201.
+        if response.status_code not in (200, 201):
+            # Or you will find the error (hint) in the reponse body on failure.
+            print('API error: {}'.format(response.text))
 
     if __name__ == '__main__':
         main()
 
 
+
 Supervisor config in ``/etc/supervisor/conf.d/dsmr-client.conf``::
 
     [program:dsmr_client_datalogger]

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -18,6 +18,56 @@ Please make sure you have a fresh **database backup** before upgrading! Upgradin
 
 
 
+v1.6.0 - 2017-03-18
+^^^^^^^^^^^^^^^^^^^
+
+.. warning::
+
+    Support for ``MySQL`` has been **deprecated** since ``DSMR-reader v1.6`` and will be discontinued completely in a later release.
+    Please use a PostgreSQL database instead. Users already running MySQL will be supported in easily migrating to PostgreSQL in the future.
+
+.. note::
+
+    **Change in API:**
+    The telegram creation API now returns an ``HTTP 201`` response when successful.
+    An ``HTTP 200`` was returned in former versions.
+    :doc:`View API docs<api>`.
+
+
+**Tickets resolved in this release:**
+
+- [`#221 <https://github.com/dennissiemensma/dsmr-reader/issues/221>`_] Support for DSMR-firmware v5.0.
+- [`#237 <https://github.com/dennissiemensma/dsmr-reader/issues/237>`_] Redesign: Status page.
+- [`#249 <https://github.com/dennissiemensma/dsmr-reader/issues/249>`_] Req: Add iOS icon for Bookmark.
+- [`#232 <https://github.com/dennissiemensma/dsmr-reader/issues/232>`_] Docs: Explain settings/options.
+- [`#260 <https://github.com/dennissiemensma/dsmr-reader/issues/260>`_] Add link to readthedocs in Django for Dropbox instructions.
+- [`#211 <https://github.com/dennissiemensma/dsmr-reader/issues/211>`_] API request should return HTTP 201 instead of HTTP 200.
+- [`#191 <https://github.com/dennissiemensma/dsmr-reader/issues/191>`_] Deprecate MySQL support.
+- [`#251 <https://github.com/dennissiemensma/dsmr-reader/issues/251>`_] Buienradar Uncaught exception.
+- [`#257 <https://github.com/dennissiemensma/dsmr-reader/issues/257>`_] Requirements update (February 2017).
+- [`#274 <https://github.com/dennissiemensma/dsmr-reader/issues/274>`_] Requirements update (March 2017).
+
+
+
+v1.5.5 - 2017-01-19
+^^^^^^^^^^^^^^^^^^^
+
+**Tickets resolved in this release:**
+
+- Remove readonly restriction for editing statistics in admin interface (`#242 <https://github.com/dennissiemensma/dsmr-reader/issues/242>`_).
+
+
+
+v1.5.4 - 2017-01-12
+^^^^^^^^^^^^^^^^^^^
+
+**Tickets resolved in this release:**
+
+- Improve datalogger for DSMR v5.0 (`#212 <https://github.com/dennissiemensma/dsmr-reader/issues/212>`_).
+- Fixed another bug in MinderGas API client implementation (`#228 <https://github.com/dennissiemensma/dsmr-reader/issues/228>`_).
+
+
+
 v1.5.5 - 2017-01-19
 ^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -56,9 +56,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.5'
+version = '1.x'
 # The full version, including alpha/beta/rc tags.
-release = '1.5.0'
+release = '1.x'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -298,4 +298,4 @@
 #texinfo_no_detailmenu = False
 
 locale_dirs = ['locale/']   # path is example but recommended.
-gettext_compact = True
+gettext_compact = False
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -3,10 +3,10 @@ Contributing
 Would you like to contribute or help this project in any way?
 
 
-Feedback
---------
-All feedback and any input is, as always, very much appreciated! 
-It doesn't matter whether you run into problems getting started in this guide or just want to get in touch, just fire away!
+Feedback / Bugs / Contact
+-------------------------
+Any feedback or input is appreciated. 
+It doesn't matter whether you run into problems or just want to get in touch, just fire away!
 
 .. seealso::
 

diff --git a/docs/credits.rst b/docs/credits.rst
@@ -1,5 +1,5 @@
-Credits
-=======
+Credits / Hall of Fame
+======================
 
 
 Special thanks for supplying code contributions
@@ -25,9 +25,9 @@ Listed in any order, sorted by name.
 - "`WatskeBart <https://github.com/WatskeBart>`_"
 
 
-Software
---------
-Please note and respect their licences, if any, as well.
+Software used
+-------------
+Please note and respect their licences as well, if any. Credits to the following software and projects:
 
 - `Raspbian <https://www.raspbian.org/>`_
 
@@ -47,7 +47,9 @@ Please note and respect their licences, if any, as well.
 
 - `Director Responsive Admin <http://web-apps.ninja/director-free-responsive-admin-template/>`_
 
-- `Favicon <http://www.flaticon.com/free-icon/eco-energy_25013>`_
+- 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/>`_
 

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -15,10 +15,10 @@ Every once in a while there may be updates. Since ``v1.5`` you can also easily c
 
     Before updating, **please make sure you have a recent backup of your database**! :doc:`More information about backups can be found here<application>`.
 
-You can update your application to the latest version by executing **deploy.sh**, located in the root of the project. 
+You can update your application to the latest version by executing **upgrade.sh**, located in the root of the project. 
 Make sure to execute it while logged in as the ``dsmr`` user::
 
-   ./deploy.sh
+   ./upgrade.sh
 
 It will make sure to check, fetch and apply any changes released. Summary of deployment script steps:
 
@@ -189,6 +189,8 @@ Only want to restore the database?
 
 - Stop the application first with ``sudo supervisorctl stop all``. This will disconnect it from the database as well.
 
+- Importing the data could take a long time. It took MySQL 15 minutes to import nearly 3 million readings, from a compressed backup, on a RaspberryPi 3. 
+
 For **PostgreSQL** restores::
 
     sudo sudo -u postgres dropdb dsmrreader
@@ -209,12 +211,12 @@ For **MySQL** restores::
     sudo mysqladmin drop dsmrreader
     
     # Either restore an uncompressed (.sql) backup:
-    cat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+    cat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql --defaults-file=/etc/mysql/debian.cnf -D dsmrreader
     
     # OR
     
     # Restore a compressed (.gz) backup with:
-    zcat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+    zcat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql --defaults-file=/etc/mysql/debian.cnf -D dsmrreader
 
 
 - Start the application again with ``sudo supervisorctl start all``.

diff --git a/docs/index.rst b/docs/index.rst
@@ -8,7 +8,9 @@ DSMR Reader's documentation
    screenshots
    installation
    application
+   settings
    api
+   troubleshooting
    faq
    changelog
    contributing