[](https://github.com/toreamun/amshan/releases)
[](https://lgtm.com/projects/g/toreamun/amshan/context:python)
[](LICENSE)
[](https://www.buymeacoffee.com/toreamun)
# AMSHAN
Package to help decode smart power meter data stream of IEC 62056-21 Mode D P1 or DLMS/Cosem HDLC frames used by MBUS (Meter Bus). The package can both help reading frames of meter data and/or decoding them.
The package has special support for DLMS formats used by Aidon, Kaifa and Kamstrup smart meteres (HAN) in Norway (See https://www.nek.no/info-ams-han-utviklere/) and Sweden. The Swedish P1 format format is also supported.
## Reading asynchronous from a stream of data
SmartMeterMessagePayloadProtocol can be used to read smart meter P1 date readout (ascii) or MBUS HDLC (binary) frames asynchronous. The content of each mdssage (no headers and control characters) is passed as bytes to a Queue. Headers are checked and checksum validated, and only content from non empty frames with expected length (only DLMS) and checksum is passed to the queue.
SmartMeterMessageProtocol can be used to read smart meter P1 data readout (ascii) or MBUS HDLC frames asynchronous. The complete message is sent to a Queue as an instance of as subclass of MeterReaderBase. Frames are not validated. This class is a more low level alternative to SmartMeterMessagePayloadProtocol. This type has to be used to get the meter type from P1 readouts as this is part of the message "header".
Both SmartMeterMessagePayloadProtocol and SmartMeterMessageProtocol is a [Python asyncio protocol](https://docs.python.org/3/library/asyncio-protocol.html#protocols). Protocols support different types of transports like network and serial.
It is recommended to use provided ConnectionManager and connection factories to read the data stream.
### Create protocol using transport
Pass a factory for the selected protocol (SmartMeterMessagePayloadProtocol or SmartMeterMessageProtocol) to a utility function of your selected transport (e.g., EventLoop.create_connection() for TCP/IP or serial_asyncio.create_serial_connection() for serial).
Serial example:
```python
transport, protocol = await serial_asyncio.create_serial_connection(loop, lambda: SmartMeterMessagePayloadProtocol(queue, [ModeDReader]), url = "/dev/tty01")
```
Serial example:
```python
transport, protocol = await serial_asyncio.create_serial_connection(loop, lambda: SmartMeterMessagePayloadProtocol(queue, [ModeDReader]), url = "/dev/tty01")
```
### Create protocol using provided factories
Multiple factories are provided to create a protocol as an alternative to using selected transports create function as above. Use [serial_connection_factory](serial_connection_factory.py) for serial and [tcp_connection_factory](tcp_connection_factory) for TCP/IP.
| Factory module | SmartMeterMessageProtocol | SmartMeterMessagePayloadProtocol |
| ------------------------- | ------------------------------------------ | --------------------------------------- |
| serial_connection_factory | create_serial_message_payload_connection() | create_serial_message_connection() |
| tcp_connection_factory | create_tcp_message_connection() | create_tcp_message_payload_connection() |
Example of creating a SmartMeterMessagePayloadProtocol serial connection on device /dev/ttyUSB0:
```python
queue = Queue()
loop = asyncio.get_event_loop()
transport, protocol = await create_serial_frame_content_connection(queue, loop, None, url="/dev/ttyUSB0", baudrate=2400, parity=N)
```
Example of creating a SmartMeterMessageProtocol protocol TCP/IP connection to host 192.168.1.1 on port 1234:
```python
queue = Queue()
loop = asyncio.get_event_loop()
transport, protocol = await create_tcp_frame_connection(queue, loop, None, "192.168.1.1", 1234)
```
See [reader_async.py](reader_async.py) for a complete example.
### Create resilient connection with ConnectionManager
ConnectionManager maintain connection and reconnect if connection is lost. A back-off retry strategy is used when reconnecting, and a simple circuit breaker is used for lost connection.
```python
queue = Queue()
loop = asyncio.get_event_loop()
connection_manager = ConnectionManager(lambda: create_serial_message_connection(queue, loop, None, url="/dev/ttyUSB0", baudrate=2400, parity=N))
await connection_manager.connect_loop()
```
See [reader_async.py](amshan/reader_async.py) for a complete example.
## Parse P1 readouts directly from raw bytes
dlde.ModeDReader can be used to read readout by readout from bytes. Call read() to read readouts as more bytes become available. The function takes bytes as an argument and returns a list of DataReadout (the list can be empty). The function can receive incomplete readout in the buffer input and add incomplete data to an internal buffer. The buffer is schrinked when complete readout are found and returned. You should check if returned readouts are valid with readout.is_valid before using them.
## Parse frames directly from raw bytes
hdlc.HdlcFrameReader can be used to read frame by frame from bytes. Call read() to read frames as more bytes become available. The function takes bytes as an argument and returns a list of HdlcFrame (the list can be empty). The function can receive incomplete frames in the buffer input and add incomplete data to an internal buffer. The buffer is schrinked when complete frames are found and returned. You should check if returned frames are valid with frame.is_valid before using them.
# Decode norwegian and swedish messages
P1 readout and MBUS frames using the norwegian or swedish DMLS AMS format can be parsed into meter specific objects or decoded into a common dictionary. Modules exists for P1 (generic format), Aidon, Kaifa and Kamstrup meters, but the easiest is to use [autodecoder.AutoDecode](han/autodecode.py) to automatically detect meter type and decode the frame into a dictionary. The dictionay content is as far as possible common between meters. Possible dictionary keys kan be found as constants in [obis_map.py](han/obis_map.py).
Example:
```python
decoder = AutoDecoder()
frame = bytes.fromhex("e6e700" "0f" "40000000" "00" "0101" "020309060100010700ff060000011802020f00161b")
decoded = decoder.decode_frame_content(frame)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/toreamun/amshan",
"name": "amshan",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "meter,han,ams,p1,mbus,aidon,kaifa,kamstrup,dlms,cosem,hdlc,fast frame check",
"author": "Tore Amundsen",
"author_email": "tore@amundsen.org",
"download_url": "https://files.pythonhosted.org/packages/08/bc/abecc4d9de3603fc3c7d68abae22677114e6c15f51a49006a6ba85bc01aa/amshan-2.1.1.tar.gz",
"platform": "POSIX",
"description": "[](https://github.com/toreamun/amshan/releases)\n[](https://lgtm.com/projects/g/toreamun/amshan/context:python)\n[](LICENSE)\n\n\n[](https://www.buymeacoffee.com/toreamun)\n\n# AMSHAN\n\nPackage to help decode smart power meter data stream of IEC 62056-21 Mode D P1 or DLMS/Cosem HDLC frames used by MBUS (Meter Bus). The package can both help reading frames of meter data and/or decoding them.\n\nThe package has special support for DLMS formats used by Aidon, Kaifa and Kamstrup smart meteres (HAN) in Norway (See https://www.nek.no/info-ams-han-utviklere/) and Sweden. The Swedish P1 format format is also supported.\n\n## Reading asynchronous from a stream of data\n\nSmartMeterMessagePayloadProtocol can be used to read smart meter P1 date readout (ascii) or MBUS HDLC (binary) frames asynchronous. The content of each mdssage (no headers and control characters) is passed as bytes to a Queue. Headers are checked and checksum validated, and only content from non empty frames with expected length (only DLMS) and checksum is passed to the queue.\n\nSmartMeterMessageProtocol can be used to read smart meter P1 data readout (ascii) or MBUS HDLC frames asynchronous. The complete message is sent to a Queue as an instance of as subclass of MeterReaderBase. Frames are not validated. This class is a more low level alternative to SmartMeterMessagePayloadProtocol. This type has to be used to get the meter type from P1 readouts as this is part of the message \"header\".\n\nBoth SmartMeterMessagePayloadProtocol and SmartMeterMessageProtocol is a [Python asyncio protocol](https://docs.python.org/3/library/asyncio-protocol.html#protocols). Protocols support different types of transports like network and serial.\n\nIt is recommended to use provided ConnectionManager and connection factories to read the data stream.\n\n### Create protocol using transport\n\nPass a factory for the selected protocol (SmartMeterMessagePayloadProtocol or SmartMeterMessageProtocol) to a utility function of your selected transport (e.g., EventLoop.create_connection() for TCP/IP or serial_asyncio.create_serial_connection() for serial).\n\nSerial example:\n\n```python\ntransport, protocol = await serial_asyncio.create_serial_connection(loop, lambda: SmartMeterMessagePayloadProtocol(queue, [ModeDReader]), url = \"/dev/tty01\")\n```\n\nSerial example:\n\n```python\ntransport, protocol = await serial_asyncio.create_serial_connection(loop, lambda: SmartMeterMessagePayloadProtocol(queue, [ModeDReader]), url = \"/dev/tty01\")\n```\n\n### Create protocol using provided factories\n\nMultiple factories are provided to create a protocol as an alternative to using selected transports create function as above. Use [serial_connection_factory](serial_connection_factory.py) for serial and [tcp_connection_factory](tcp_connection_factory) for TCP/IP.\n\n| Factory module | SmartMeterMessageProtocol | SmartMeterMessagePayloadProtocol |\n| ------------------------- | ------------------------------------------ | --------------------------------------- |\n| serial_connection_factory | create_serial_message_payload_connection() | create_serial_message_connection() |\n| tcp_connection_factory | create_tcp_message_connection() | create_tcp_message_payload_connection() |\n\nExample of creating a SmartMeterMessagePayloadProtocol serial connection on device /dev/ttyUSB0:\n\n```python\nqueue = Queue()\nloop = asyncio.get_event_loop()\ntransport, protocol = await create_serial_frame_content_connection(queue, loop, None, url=\"/dev/ttyUSB0\", baudrate=2400, parity=N)\n```\n\nExample of creating a SmartMeterMessageProtocol protocol TCP/IP connection to host 192.168.1.1 on port 1234:\n\n```python\nqueue = Queue()\nloop = asyncio.get_event_loop()\ntransport, protocol = await create_tcp_frame_connection(queue, loop, None, \"192.168.1.1\", 1234)\n```\n\nSee [reader_async.py](reader_async.py) for a complete example.\n\n### Create resilient connection with ConnectionManager\n\nConnectionManager maintain connection and reconnect if connection is lost. A back-off retry strategy is used when reconnecting, and a simple circuit breaker is used for lost connection.\n\n```python\nqueue = Queue()\nloop = asyncio.get_event_loop()\nconnection_manager = ConnectionManager(lambda: create_serial_message_connection(queue, loop, None, url=\"/dev/ttyUSB0\", baudrate=2400, parity=N))\nawait connection_manager.connect_loop()\n```\n\nSee [reader_async.py](amshan/reader_async.py) for a complete example.\n\n## Parse P1 readouts directly from raw bytes\n\ndlde.ModeDReader can be used to read readout by readout from bytes. Call read() to read readouts as more bytes become available. The function takes bytes as an argument and returns a list of DataReadout (the list can be empty). The function can receive incomplete readout in the buffer input and add incomplete data to an internal buffer. The buffer is schrinked when complete readout are found and returned. You should check if returned readouts are valid with readout.is_valid before using them.\n\n## Parse frames directly from raw bytes\n\nhdlc.HdlcFrameReader can be used to read frame by frame from bytes. Call read() to read frames as more bytes become available. The function takes bytes as an argument and returns a list of HdlcFrame (the list can be empty). The function can receive incomplete frames in the buffer input and add incomplete data to an internal buffer. The buffer is schrinked when complete frames are found and returned. You should check if returned frames are valid with frame.is_valid before using them.\n\n# Decode norwegian and swedish messages\n\nP1 readout and MBUS frames using the norwegian or swedish DMLS AMS format can be parsed into meter specific objects or decoded into a common dictionary. Modules exists for P1 (generic format), Aidon, Kaifa and Kamstrup meters, but the easiest is to use [autodecoder.AutoDecode](han/autodecode.py) to automatically detect meter type and decode the frame into a dictionary. The dictionay content is as far as possible common between meters. Possible dictionary keys kan be found as constants in [obis_map.py](han/obis_map.py).\n\nExample:\n\n```python\ndecoder = AutoDecoder()\nframe = bytes.fromhex(\"e6e700\" \"0f\" \"40000000\" \"00\" \"0101\" \"020309060100010700ff060000011802020f00161b\")\ndecoded = decoder.decode_frame_content(frame)\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Decode P1 and MBUS (Meter Bus) DLMS data. Special support for norwegian and swedish meters.",
"version": "2.1.1",
"project_urls": {
"Homepage": "https://github.com/toreamun/amshan"
},
"split_keywords": [
"meter",
"han",
"ams",
"p1",
"mbus",
"aidon",
"kaifa",
"kamstrup",
"dlms",
"cosem",
"hdlc",
"fast frame check"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aad4883b6d951f4b7ea3c04bd45e751726e78dcc0beac6a7201431a3119cdd9b",
"md5": "eafe27618dfcd800b73d073320fe4b7c",
"sha256": "e868e8bfe1431b8ed22e1902136ff92da5f986fc24c5b3d6cd6e891c5baf7f29"
},
"downloads": -1,
"filename": "amshan-2.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eafe27618dfcd800b73d073320fe4b7c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 32611,
"upload_time": "2023-06-14T20:39:27",
"upload_time_iso_8601": "2023-06-14T20:39:27.948036Z",
"url": "https://files.pythonhosted.org/packages/aa/d4/883b6d951f4b7ea3c04bd45e751726e78dcc0beac6a7201431a3119cdd9b/amshan-2.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "08bcabecc4d9de3603fc3c7d68abae22677114e6c15f51a49006a6ba85bc01aa",
"md5": "b71cd52f519f6cc1c5e0804dd8168c4a",
"sha256": "fe5edf37ed400a48248c23b2360167ff47d0e86b2d69ee4c5af363a5fb737405"
},
"downloads": -1,
"filename": "amshan-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "b71cd52f519f6cc1c5e0804dd8168c4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26823,
"upload_time": "2023-06-14T20:39:29",
"upload_time_iso_8601": "2023-06-14T20:39:29.719542Z",
"url": "https://files.pythonhosted.org/packages/08/bc/abecc4d9de3603fc3c7d68abae22677114e6c15f51a49006a6ba85bc01aa/amshan-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-14 20:39:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "toreamun",
"github_project": "amshan",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "amshan"
}
JSON
