updated changelog in preparation of v0.9

CHANGELOG.rst

@@ -1,6 +1,10 @@
 Change Log
 ----------
 
+**0.9** (2017-03-02)
+
+- allow the telegram specification to optionally be autodetected
+
 **0.8** (2017-01-26)
 
 - added support for DSMR v3

README.rst

@@ -8,7 +8,7 @@ DSMR Parser
     :target: https://travis-ci.org/ndokter/dsmr_parser
 
 A library for parsing Dutch Smart Meter Requirements (DSMR) telegram data. It
-also includes a serial client to directly read and parse smart meter data.
+also includes client implementation to directly read and parse smart meter data.
 
 
 Features
@@ -17,41 +17,125 @@ Features
 DSMR Parser supports DSMR versions 2, 3, 4 and 5. It has been tested with Python 3.4, 3.5 and 3.6.
 
 
-Examples
+Client module usage
---------
+-------------------
 
-Using the serial reader to connect to your smart meter and parse it's telegrams:
+**Serial client**
+
+Read the serial port and work with the parsed telegrams. It should be run in a separate
+process because the code is blocking (not asynchronous):
+
+.. code-block:: python
+
+     from dsmr_parser import telegram_specifications
+     from dsmr_parser.clients import SerialReader, SERIAL_SETTINGS_V4
+    
+     serial_reader = SerialReader(
+         device='/dev/ttyUSB0',
+         serial_settings=SERIAL_SETTINGS_V4,
+         telegram_specification=telegram_specifications.V4
+     )
+    
+     for telegram in serial_reader.read():
+         print(telegram)  # see 'Telegram object' docs below
+
+**AsyncIO client**
+
+To be documented.
+
+
+Parsing module usage
+--------------------
+The parsing module accepts complete unaltered telegram strings and parses these
+into a dictionary.
+
+.. code-block:: python
+
+     from dsmr_parser import telegram_specifications
+     from dsmr_parser.parsers import TelegramParser
+
+     telegram_str = (
+         '/ISk5\2MT382-1000\r\n'
+         '\r\n'
+         '0-0:96.1.1(4B384547303034303436333935353037)\r\n'
+         '1-0:1.8.1(12345.678*kWh)\r\n'
+         '1-0:1.8.2(12345.678*kWh)\r\n'
+         '1-0:2.8.1(12345.678*kWh)\r\n'
+         '1-0:2.8.2(12345.678*kWh)\r\n'
+         '0-0:96.14.0(0002)\r\n'
+         '1-0:1.7.0(001.19*kW)\r\n'
+         '1-0:2.7.0(000.00*kW)\r\n'
+         '0-0:17.0.0(016*A)\r\n'
+         '0-0:96.3.10(1)\r\n'
+         '0-0:96.13.1(303132333435363738)\r\n'
+         '0-0:96.13.0(303132333435363738393A3B3C3D3E3F303132333435363738393A3B3C3D3E'
+         '3F303132333435363738393A3B3C3D3E3F303132333435363738393A3B3C3D3E3F30313233'
+         '3435363738393A3B3C3D3E3F)\r\n'
+         '0-1:96.1.0(3232323241424344313233343536373839)\r\n'
+         '0-1:24.1.0(03)\r\n'
+         '0-1:24.3.0(090212160000)(00)(60)(1)(0-1:24.2.1)(m3)\r\n'
+         '(00001.001)\r\n'
+         '0-1:24.4.0(1)\r\n'
+         '!\r\n'
+     )
+
+     parser = TelegramParser(telegram_specifications.V3)
+    
+     telegram = parser.parse(telegram_str)
+     print(telegram)  # see 'Telegram object' docs below
+
+Telegram object
+---------------
+
+A dictionary of which the key indicates the field type. These regex values
+correspond to one of dsmr_parser.obis_reference constants.
+
+The value is either a CosemObject or MBusObject. These have a 'value' and 'unit'
+property. MBusObject's additionally have a 'datetime' property. The 'value' can
+contain any python type (int, str, Decimal) depending on the field. The 'unit'
+contains 'kW', 'A', 'kWh' or 'm3'.
+
+.. code-block:: python
+
+    # Contents of a parsed DSMR v3 telegram
+    {'\\d-\\d:17\\.0\\.0.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fc39eb8>,
+     '\\d-\\d:1\\.7\\.0.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10f916390>,
+     '\\d-\\d:1\\.8\\.1.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fc39e10>,
+     '\\d-\\d:1\\.8\\.2.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fc39ef0>,
+     '\\d-\\d:24\\.1\\.0.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fbaef28>,
+     '\\d-\\d:24\\.3\\.0.+?\\r\\n.+?\\r\\n': <dsmr_parser.objects.MBusObject object at 0x10f9163c8>,
+     '\\d-\\d:24\\.4\\.0.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fc39f60>,
+     '\\d-\\d:2\\.7\\.0.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fc39fd0>,
+     '\\d-\\d:2\\.8\\.1.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fbaee10>,
+     '\\d-\\d:2\\.8\\.2.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fc39e80>,
+     '\\d-\\d:96\\.13\\.0.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fc39d30>,
+     '\\d-\\d:96\\.13\\.1.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fbaeeb8>,
+     '\\d-\\d:96\\.14\\.0.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fbaef98>,
+     '\\d-\\d:96\\.1\\.0.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fbaef60>,
+     '\\d-\\d:96\\.1\\.1.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fc39f98>,
+     '\\d-\\d:96\\.3\\.10.+?\\r\\n': <dsmr_parser.objects.CosemObject object at 0x10fc39dd8>}
+
+Example to get some of the values:
 
 .. code-block:: python
 
-    from dsmr_parser import telegram_specifications
     from dsmr_parser import obis_references
-    from dsmr_parser.clients import SerialReader, SERIAL_SETTINGS_V4
 
-    serial_reader = SerialReader(
+     # The telegram message timestamp.
-        device='/dev/ttyUSB0',
+     message_datetime = telegram[obis_references.P1_MESSAGE_TIMESTAMP]
-        serial_settings=SERIAL_SETTINGS_V4,
-        telegram_specification=telegram_specifications.V4
-    )
 
-    for telegram in serial_reader.read():
+     # Using the active tariff to determine the electricity being used and
+     # delivered for the right tariff.
+     active_tariff = telegram[obis_references.ELECTRICITY_ACTIVE_TARIFF]
+     active_tariff = int(tariff.value)
 
-        # The telegram message timestamp.
+     electricity_used_total = telegram[obis_references.ELECTRICITY_USED_TARIFF_ALL[active_tariff - 1]]
-        message_datetime = telegram[obis_references.P1_MESSAGE_TIMESTAMP]
+     electricity_delivered_total = telegram[obis_references.ELECTRICITY_DELIVERED_TARIFF_ALL[active_tariff - 1]]
 
-        # Using the active tariff to determine the electricity being used and
+     gas_reading = telegram[obis_references.HOURLY_GAS_METER_READING]
-        # delivered for the right tariff.
-        tariff = telegram[obis_references.ELECTRICITY_ACTIVE_TARIFF]
-        tariff = int(tariff.value)
 
-        electricity_used_total \
+    # See dsmr_reader.obis_references for all readable telegram values.
-            = telegram[obis_references.ELECTRICITY_USED_TARIFF_ALL[tariff - 1]]
+    # Note that the avilable values differ per DSMR version.
-        electricity_delivered_total = \
-            telegram[obis_referencesELECTRICITY_DELIVERED_TARIFF_ALL[tariff - 1]]
-
-        gas_reading = telegram[obis_references.HOURLY_GAS_METER_READING]
-
-        # See dsmr_reader.obis_references for all readable telegram values.
 
 
 Installation

dsmr_parser/exceptions.py

@@ -4,3 +4,7 @@ class ParseError(Exception):
 
 class InvalidChecksumError(ParseError):
     pass
+
+
+class TelegramSpecificationMatchError(ParseError):
+    pass

dsmr_parser/objects.py

@@ -1,4 +1,7 @@
 class DSMRObject(object):
+    """
+    Represents all data from a single telegram line.
+    """
 
     def __init__(self, values):
         self.values = values

dsmr_parser/parsers.py

@@ -4,16 +4,18 @@ import re
 from PyCRC.CRC16 import CRC16
 
 from dsmr_parser.objects import MBusObject, CosemObject
-from dsmr_parser.exceptions import ParseError, InvalidChecksumError
+from dsmr_parser.exceptions import ParseError, InvalidChecksumError, \
+    TelegramSpecificationMatchError
 
 logger = logging.getLogger(__name__)
 
 
 class TelegramParser(object):
 
-    def __init__(self, telegram_specification, apply_checksum_validation=True):
+    def __init__(self, telegram_specification=None, apply_checksum_validation=True):
         """
-        :param telegram_specification: determines how the telegram is parsed
+        :param telegram_specification: determines how the telegram is parsed.
+            Will attempt to autodetect if omitted.
         :param apply_checksum_validation: validate checksum if applicable for
             telegram DSMR version (v4 and up).
         :type telegram_specification: dict
@@ -27,8 +29,8 @@ class TelegramParser(object):
 
         The telegram str type makes python 2.x integration easier.
 
-        :param str telegram: full telegram from start ('/') to checksum
+        :param str telegram_data: full telegram from start ('/') to checksum
-            ('!ABCD') including line endings inbetween the telegram's lines
+            ('!ABCD') including line endings in between the telegram's lines
         :rtype: dict
         :returns: Shortened example:
             {
@@ -39,8 +41,10 @@ class TelegramParser(object):
                 ..
             }
         :raises ParseError:
-        :raises InvalidChecksumError:
         """
+        if not self.telegram_specification:
+            self.telegram_specification = \
+                match_telegram_specification(telegram_data)
 
         if self.apply_checksum_validation \
                 and self.telegram_specification['checksum_support']:
@@ -51,8 +55,12 @@ class TelegramParser(object):
         for signature, parser in self.telegram_specification['objects'].items():
             match = re.search(signature, telegram_data, re.DOTALL)
 
-            if match:
+            # All telegram specification lines/signatures are expected to be
-                telegram[signature] = parser.parse(match.group(0))
+            # present.
+            if not match:
+                raise ParseError('Telegram specification does not match '
+                                 'telegram data')
+            telegram[signature] = parser.parse(match.group(0))
 
         return telegram
 
@@ -90,6 +98,36 @@ class TelegramParser(object):
             )
 
 
+def match_telegram_specification(telegram_data):
+    """
+    Find telegram specification that matches the telegram data by trying all
+    specifications.
+
+    Could be further optimized to check the actual 0.2.8 OBIS reference which
+    is available for DSMR version 4 and up.
+
+    :param str telegram_data: full telegram from start ('/') to checksum
+            ('!ABCD') including line endings in between the telegram's lines
+    :return: telegram specification
+    :rtype: dict
+    """
+    # Prevent circular import
+    from dsmr_parser import telegram_specifications
+
+    for specification in telegram_specifications.ALL:
+        try:
+            TelegramParser(specification).parse(telegram_data)
+        except ParseError:
+            pass
+        else:
+            return specification
+
+    raise TelegramSpecificationMatchError(
+        'Could automatically match telegram specification. Make sure the data'
+        'is not corrupt. Alternatively manually specify one.'
+    )
+
+
 class DSMRObjectParser(object):
     """
     Parses an object (can also be see as a 'line') from a telegram.

dsmr_parser/telegram_specifications.py

@@ -42,34 +42,7 @@ V2_2 = {
     }
 }
 
-V3 = {
+V3 = V2_2
-    'checksum_support': False,
-    'objects': {
-        obis.EQUIPMENT_IDENTIFIER: CosemParser(ValueParser(str)),
-        obis.ELECTRICITY_USED_TARIFF_1: CosemParser(ValueParser(Decimal)),
-        obis.ELECTRICITY_USED_TARIFF_2: CosemParser(ValueParser(Decimal)),
-        obis.ELECTRICITY_DELIVERED_TARIFF_1: CosemParser(ValueParser(Decimal)),
-        obis.ELECTRICITY_DELIVERED_TARIFF_2: CosemParser(ValueParser(Decimal)),
-        obis.ELECTRICITY_ACTIVE_TARIFF: CosemParser(ValueParser(str)),
-        obis.CURRENT_ELECTRICITY_USAGE: CosemParser(ValueParser(Decimal)),
-        obis.CURRENT_ELECTRICITY_DELIVERY: CosemParser(ValueParser(Decimal)),
-        obis.ACTUAL_TRESHOLD_ELECTRICITY: CosemParser(ValueParser(Decimal)),
-        obis.ACTUAL_SWITCH_POSITION: CosemParser(ValueParser(str)),
-        obis.TEXT_MESSAGE_CODE: CosemParser(ValueParser(int)),
-        obis.TEXT_MESSAGE: CosemParser(ValueParser(str)),
-        obis.EQUIPMENT_IDENTIFIER_GAS: CosemParser(ValueParser(str)),
-        obis.DEVICE_TYPE: CosemParser(ValueParser(str)),
-        obis.VALVE_POSITION_GAS: CosemParser(ValueParser(str)),
-        obis.GAS_METER_READING: MBusParser(
-            ValueParser(timestamp),
-            ValueParser(int),
-            ValueParser(int),
-            ValueParser(int),
-            ValueParser(str),
-            ValueParser(Decimal),
-        ),
-    }
-}
 
 V4 = {
     'checksum_support': True,
@@ -145,3 +118,5 @@ V5 = {
         )
     }
 }
+
+ALL = (V2_2, V3, V4, V5)

setup.py

@@ -6,7 +6,7 @@ setup(
     author='Nigel Dokter',
     author_email='nigeldokter@gmail.com',
     url='https://github.com/ndokter/dsmr_parser',
-    version='0.8',
+    version='0.9',
     packages=find_packages(),
     install_requires=[
         'pyserial>=3,<4',

test/test_match_telegram_specification.py

@@ -0,0 +1,29 @@
+import unittest
+
+from dsmr_parser.exceptions import TelegramSpecificationMatchError
+from dsmr_parser.parsers import match_telegram_specification
+from dsmr_parser import telegram_specifications
+from test import example_telegrams
+
+
+class MatchTelegramSpecificationTest(unittest.TestCase):
+
+    def test_v2_2(self):
+        assert match_telegram_specification(example_telegrams.TELEGRAM_V2_2) \
+           == telegram_specifications.V2_2
+
+    def test_v3(self):
+        assert match_telegram_specification(example_telegrams.TELEGRAM_V3) \
+           == telegram_specifications.V3
+
+    def test_v4_2(self):
+        assert match_telegram_specification(example_telegrams.TELEGRAM_V4_2) \
+           == telegram_specifications.V4
+
+    def test_v5(self):
+        assert match_telegram_specification(example_telegrams.TELEGRAM_V5) \
+           == telegram_specifications.V5
+
+    def test_malformed_telegram(self):
+        with self.assertRaises(TelegramSpecificationMatchError):
+            match_telegram_specification(example_telegrams.TELEGRAM_V5[:-4])

test/test_parse_v2_2.py

@@ -12,6 +12,15 @@ from test.example_telegrams import TELEGRAM_V2_2
 class TelegramParserV2_2Test(unittest.TestCase):
     """ Test parsing of a DSMR v2.2 telegram. """
 
+    def test_telegram_specification_matching(self):
+        parser = TelegramParser()
+        parser.parse(TELEGRAM_V2_2)
+
+        self.assertEqual(
+            parser.telegram_specification,
+            telegram_specifications.V2_2
+        )
+
     def test_parse(self):
         parser = TelegramParser(telegram_specifications.V2_2)
         result = parser.parse(TELEGRAM_V2_2)

test/test_parse_v3.py

@@ -12,6 +12,15 @@ from test.example_telegrams import TELEGRAM_V3
 class TelegramParserV3Test(unittest.TestCase):
     """ Test parsing of a DSMR v3 telegram. """
 
+    def test_telegram_specification_matching(self):
+        parser = TelegramParser()
+        parser.parse(TELEGRAM_V3)
+
+        self.assertEqual(
+            parser.telegram_specification,
+            telegram_specifications.V3
+        )
+
     def test_parse(self):
         parser = TelegramParser(telegram_specifications.V3)
         result = parser.parse(TELEGRAM_V3)

test/test_parse_v4_2.py

@@ -15,6 +15,15 @@ from test.example_telegrams import TELEGRAM_V4_2
 class TelegramParserV4_2Test(unittest.TestCase):
     """ Test parsing of a DSMR v4.2 telegram. """
 
+    def test_telegram_specification_matching(self):
+        parser = TelegramParser()
+        parser.parse(TELEGRAM_V4_2)
+
+        self.assertEqual(
+            parser.telegram_specification,
+            telegram_specifications.V4
+        )
+
     def test_parse(self):
         parser = TelegramParser(telegram_specifications.V4)
         result = parser.parse(TELEGRAM_V4_2)

test/test_parse_v5.py

@@ -16,6 +16,15 @@ from test.example_telegrams import TELEGRAM_V5
 class TelegramParserV5Test(unittest.TestCase):
     """ Test parsing of a DSMR v5.x telegram. """
 
+    def test_telegram_specification_matching(self):
+        parser = TelegramParser()
+        parser.parse(TELEGRAM_V5)
+
+        self.assertEqual(
+            parser.telegram_specification,
+            telegram_specifications.V5
+        )
+
     def test_parse(self):
         parser = TelegramParser(telegram_specifications.V5)
         result = parser.parse(TELEGRAM_V5)