# A Python library for DLMS/COSEM.
[](https://codecov.io/gh/pwitab/dlms-cosem)
<img src="dlms-logo.png" alt="dlms_logo" width="200"/>
# Installation
```
pip install dlms-cosem
```
# Documentation
Full documentation can be found at [www.dlms.dev](https://www.dlms.dev)
# About
`dlms-cosem` is designed to be a tool with a simple API for working with DLMS/COSEM
enabled energy meters. It provides the lowest level function, as protocol state
management, APDU encoding/decoding, APDU encryption/decryption.
The library aims to provide a [sans-io](https://sans-io.readthedocs.io/) implementation
of the DLMS/COSEM protocol so that the protocol code can be reused with several
io-paradigms. As of now we provide a simple client implementation based on
blocking I/O. This can be used over either a serial interface with HDLC or over TCP.
We have not implemented full support to be able to build a server (meter) emulator. If
this is a use-case you need, consider sponsoring the development and contact us.
# Supported features
* AssociationRequest and AssociationRelease
* GET, GET.WITH_BLOCK, GET.WITH_LIST
* SET
* ACTION
* DataNotification
* GlobalCiphering - Authenticated and Encrypted.
* HLS-GMAC, LLS, HLS-Common auth
* Selective access via RangeDescriptor
* Parsing of ProfileGeneric buffers
# Example use:
A simple example of reading invocation counters using a public client:
```python
from dlms_cosem.client import DlmsClient
from dlms_cosem.io import TcpTransport, BlockingTcpIO
from dlms_cosem.security import NoSecurityAuthentication
from dlms_cosem import enumerations, cosem
tcp_io = BlockingTcpIO(host="localhost", port=4059)
tcp_transport = TcpTransport(io=tcp_io, server_logical_address=1, client_logical_address=16)
client = DlmsClient(transport=tcp_transport, authentication=NoSecurityAuthentication())
with client.session() as dlms_client:
data = dlms_client.get(
cosem.CosemAttribute(interface=enumerations.CosemInterface.DATA,
instance=cosem.Obis(0, 0, 0x2B, 1, 0), attribute=2, ))
```
Look at the different files in the `examples` folder get a better feel on how to fully
use the library.
# Supported meters
Technically we aim to support any DLMS enabled meter. The library is implementing all
the low level DLMS, and you might need an abstraction layer to support everything in
your meter.
DLMS/COSEM specifies many ways of performing tasks on a meter. It is
customary that a meter also adheres to a companion standard. In the companion standard
it is defined exactly how certain use-cases are to be performed and how data is modeled.
Examples of companion standards are:
* DSMR (Netherlands)
* IDIS (all Europe)
* UNI/TS 11291 (Italy)
On top of it all your DSO (Distribution Service Operator) might have ordered their
meters with extra functionality or reduced functionality from one of the companion
standards.
We have some meters we have run tests on or know the library is used for in production
* Pietro Fiorentini RSE 1,2 LA N1. Italian gas meter
* Iskraemeco AM550. IDIS compliant electricity meter.
* Itron SL7000
* Hexing HXF300
# License
*The `dlms-cosem` library is released under the Business Source License 1.1 .
It is not a fully Open Source License but will eventually be made available under an Open Source License
(Apache License, Version 2.0), as stated in the license document.*
Our goal with this licence is to provide enough freedom for you to use and learn from the software without
[harmful free-riding](https://en.wikipedia.org/wiki/Free-rider_problem).
---
You may make use of the Licensed Work for any Permitted Purpose other than a Competing Use.
A Competing Use means use of the Licensed Work in or for a commercial product or service that
competes with the Licensed Work or any other product or service we offer using the Licensed Work
as of the date we make the Software available.
Competing Uses specifically include using the Licensed Work:
1. as a substitute for any of our products or services;
2. in a way that exposes the APIs of the Licensed Work; and
3. in a product or service that offers the same or substantially similar
functionality to the Licensed Work.
Permitted Purposes specifically include using the Software:
1. for your internal use and access;
2. for non-commercial education; and
3. for non-commercial research.
For information about alternative licensing arrangements or questions about permitted use of the library,
please contact us at `info(at)pwit.se`.
# Development
This library is developed by Palmlund Wahlgren Innovative Technology AB. We are
based in Sweden and are members of the DLMS User Association.
If you find a bug please raise an issue on Github.
We add features depending on our own, and our clients use cases. If you
need a feature implemented please contact us.
# Training / Consultancy / Commercial Support / Services
We offer consultancy service and training services around this library and general DLMS/COSEM.
If you are interested in our services just reach at `ìnfo(at)pwit.se`
The library is an important part of our [Smart meter platform Utilitarian, https://utilitarian.io](https://utilitarian.io). If you need to
collect data from a lot of DLMS devices or meters, deploying Utilitarian might be the smoothest
solution for you.
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Calendar Versioning](https://calver.org/)
## Unreleased
### Added
### Changed
### Deprecated
### Removed
### Fixed
### Security
## 24.1.0 - 2024-01-22
### Added
* Support for HDLC over TCP via composition of IO-implementation separate from
transport implementation.
* Support for LLS (Low Level Security)
* Support for HLS (method 2) using common method of AES128-ECB.
* Structlog logging.
* Implemented VisibleStringData.
* DlmsConnectionSettings to handle manufacturer specific quirks in communication.
### Changed
* Changed License from MIT to BSL v1.1
* Refactor of authentication to make it simpler support more authentication types. And make
it possible to supply manufacturer specific implementations.
### Removed
* Shorthand class methods to create DlmsClients. Now composition has to be used.
### Fixed
* Error in DataArray dlms data type
## [21.3.2] - 2021-11-07
## Changed
Updated dependencies and made it a bit more lenient so installing in other environments
will allow for more versions.
## [21.3.1] - 2021-06-14
### Added
* To handle the more complicated parsing problem of GET.WITH_LIST with compound data
elements a new parser, DlmsDataParser, was added that focuses on only A-XDR DLMS data.
Hopefully this can be be used instead of the A-XDR Parser when the parsing of ACSE
services APDUs is built away
## [21.3.0] - 2021-06-08
### Added
* Added HDLC UnnumberedInformationFrame.
* Ability to set timeout of transport layer at client level.
* A simpler way to change client address and invocation counter of a `DlmsClient` to
that reuseing a connection goes smoother
* Added `from_string` on `Obis`that can parse any viable string as OBIS.
* Added GET.WITH_LIST service.
### Changed
* Renamed classes to exclude `Apdu` in class names. To have it consistent over the
project.
* Simplified DataNotification
* Improved handling of pre-established associations
* Using the wrong data to decrypt now raises `DecryptionError` instead of InvalidTag
* The `to_string` method on `Obis` now returns in the format `1-8:1.8.0.255` with a
possible override of the separator.
### Removed
* Removed the `from_dotted`, `dotted_repr` and `verbose_repr` from `Obis`
### Fixed
* Some DLMS over TCP implementations will return partial data. The
`BlockingTcpTransport` now keeps on trying to read the data until all data is
received. Fixes [#35](https://github.com/pwitab/dlms-cosem/issues/35).
* Fixed a bug in the HDLC layer that prevented correct sending of segmented information
frames.
## [21.2.2] - 2021-03-02
### Fixed
* Fixed missing state management for general ACTION usage
## [21.2.1] - 2021-02-18
### Fixed
* Fixed [#23](https://github.com/pwitab/dlms-cosem/issues/23). Typo in A-XDR Parser.
Just referenced the function and did not call it. Now DLMS data is interpreted
correctly.
* Fixed [#20](https://github.com/pwitab/dlms-cosem/issues/20). It was possible that not
calling the .shutdown() on socket before disconnecting made remote modems on meters,
that have an embedded TCP/IP stack, keep the socket open and blocking subsequent calls.
## [21.2.0] - 2021-01-28
### Added
* Support for basic SET service. No support for WITH_LIST or service specific block
transfer
## [21.1.2] - 2021-01-22
### Fixed
* The standard DLMS way of dealing with timezones in datetime are via UTC offset. But
the offset is the deviation from normal time to UTC not deviation from UTC. This
results in -60 min deviation for UTC+01:00 for example. Previous solution assumed
60 min for UTC+01:00. Solved by negating all values for offset.
Note that some DLMS companion standards handles the offset the previous way and in
the future there will be need to handle both ways correctly.
* Included typing-extensions in required packages.
## [21.1.1] - 2021-01-13
### Added
* Better handling of TCP errors in `BlockingTcpTransport`
### Changed
* It is now explicitly possible to connect and disconnect a transport in the
`DlmsClient` instead of it being done automatically in `.associate()` and
`.release_association()`. Context manager `.session()` works the same.
* Client to server challenge of DlmsConnection is always created independent of auth
method. But only used if needed.
### Removed
* Removed conformance validation in DlmsConnection. It seems like meters don't always
follow it so better to leave it up to the client.
## [21.1.0] - 2021-01-12
### Added
* HDLC transport implementation
* TCP transport implementation
* DlMS client implementation
* Support for Get service including service specific block transfer
* Support for selective access via range descriptor
* Support for HLS authentication using HLS-GMAC.
* Support for GlobalCiphering
* Parsing of ProfileGeneric buffer
### Changed
* Changed project versioning scheme to Calendar versioning
## v0.0.2
### Changed
- UDP messages are now based WrapperProtocolDataUnit to be able to reuse
WrapperHeader for TCP messages.
- Parsing of DLMS APDUs
### v0.0.1
Initial implementation.
Raw data
{
"_id": null,
"home_page": "https://github.com/pwitab/dlms-cosem",
"name": "dlms-cosem",
"maintainer": "Henrik Palmlund Wahlgren @ Palmlund Wahlgren Innovative Technology AB",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "henrik@pwit.se",
"keywords": "AMR,Metering,smart meters,MDM,dlms,cosem",
"author": "Henrik Palmlund Wahlgren @ Palmlund Wahlgren Innovative Technology AB",
"author_email": "henrik@pwit.se",
"download_url": "https://files.pythonhosted.org/packages/42/56/9c01ffad667aa39e011a80eba1a4e7160c4f07a430af0114958519b56c3c/dlms-cosem-24.1.0.tar.gz",
"platform": null,
"description": "\n# A Python library for DLMS/COSEM.\n\n[](https://codecov.io/gh/pwitab/dlms-cosem)\n\n\n\n<img src=\"dlms-logo.png\" alt=\"dlms_logo\" width=\"200\"/>\n\n# Installation\n\n```\npip install dlms-cosem\n```\n\n# Documentation\n\nFull documentation can be found at [www.dlms.dev](https://www.dlms.dev)\n\n# About\n\n`dlms-cosem` is designed to be a tool with a simple API for working with DLMS/COSEM\nenabled energy meters. It provides the lowest level function, as protocol state\nmanagement, APDU encoding/decoding, APDU encryption/decryption.\n\nThe library aims to provide a [sans-io](https://sans-io.readthedocs.io/) implementation\nof the DLMS/COSEM protocol so that the protocol code can be reused with several\nio-paradigms. As of now we provide a simple client implementation based on\nblocking I/O. This can be used over either a serial interface with HDLC or over TCP.\n\nWe have not implemented full support to be able to build a server (meter) emulator. If\nthis is a use-case you need, consider sponsoring the development and contact us.\n\n# Supported features\n\n* AssociationRequest and AssociationRelease\n* GET, GET.WITH_BLOCK, GET.WITH_LIST\n* SET\n* ACTION\n* DataNotification\n* GlobalCiphering - Authenticated and Encrypted.\n* HLS-GMAC, LLS, HLS-Common auth\n* Selective access via RangeDescriptor\n* Parsing of ProfileGeneric buffers\n\n# Example use:\n\nA simple example of reading invocation counters using a public client:\n\n```python\nfrom dlms_cosem.client import DlmsClient\nfrom dlms_cosem.io import TcpTransport, BlockingTcpIO\nfrom dlms_cosem.security import NoSecurityAuthentication\nfrom dlms_cosem import enumerations, cosem\n\ntcp_io = BlockingTcpIO(host=\"localhost\", port=4059)\ntcp_transport = TcpTransport(io=tcp_io, server_logical_address=1, client_logical_address=16)\nclient = DlmsClient(transport=tcp_transport, authentication=NoSecurityAuthentication())\nwith client.session() as dlms_client:\n data = dlms_client.get(\n cosem.CosemAttribute(interface=enumerations.CosemInterface.DATA,\n instance=cosem.Obis(0, 0, 0x2B, 1, 0), attribute=2, ))\n```\n\n\nLook at the different files in the `examples` folder get a better feel on how to fully\nuse the library.\n\n# Supported meters\n\nTechnically we aim to support any DLMS enabled meter. The library is implementing all\nthe low level DLMS, and you might need an abstraction layer to support everything in\nyour meter.\n\nDLMS/COSEM specifies many ways of performing tasks on a meter. It is\ncustomary that a meter also adheres to a companion standard. In the companion standard\nit is defined exactly how certain use-cases are to be performed and how data is modeled.\n\nExamples of companion standards are:\n* DSMR (Netherlands)\n* IDIS (all Europe)\n* UNI/TS 11291 (Italy)\n\nOn top of it all your DSO (Distribution Service Operator) might have ordered their\nmeters with extra functionality or reduced functionality from one of the companion\nstandards.\n\nWe have some meters we have run tests on or know the library is used for in production\n\n* Pietro Fiorentini RSE 1,2 LA N1. Italian gas meter\n* Iskraemeco AM550. IDIS compliant electricity meter.\n* Itron SL7000\n* Hexing HXF300\n\n\n# License\n\n\n*The `dlms-cosem` library is released under the Business Source License 1.1 .\nIt is not a fully Open Source License but will eventually be made available under an Open Source License \n(Apache License, Version 2.0), as stated in the license document.*\n\nOur goal with this licence is to provide enough freedom for you to use and learn from the software without\n[harmful free-riding](https://en.wikipedia.org/wiki/Free-rider_problem).\n\n---\n\nYou may make use of the Licensed Work for any Permitted Purpose other than a Competing Use.\nA Competing Use means use of the Licensed Work in or for a commercial product or service that\ncompetes with the Licensed Work or any other product or service we offer using the Licensed Work \nas of the date we make the Software available.\n\nCompeting Uses specifically include using the Licensed Work:\n\n1. as a substitute for any of our products or services;\n\n2. in a way that exposes the APIs of the Licensed Work; and\n\n3. in a product or service that offers the same or substantially similar\nfunctionality to the Licensed Work.\n\nPermitted Purposes specifically include using the Software:\n\n1. for your internal use and access;\n\n2. for non-commercial education; and\n\n3. for non-commercial research.\n\nFor information about alternative licensing arrangements or questions about permitted use of the library,\nplease contact us at `info(at)pwit.se`. \n\n# Development\n\nThis library is developed by Palmlund Wahlgren Innovative Technology AB. We are\nbased in Sweden and are members of the DLMS User Association.\n\nIf you find a bug please raise an issue on Github.\n\nWe add features depending on our own, and our clients use cases. If you\nneed a feature implemented please contact us.\n\n# Training / Consultancy / Commercial Support / Services\n\nWe offer consultancy service and training services around this library and general DLMS/COSEM.\nIf you are interested in our services just reach at `\u00ecnfo(at)pwit.se`\n\nThe library is an important part of our [Smart meter platform Utilitarian, https://utilitarian.io](https://utilitarian.io). If you need to \ncollect data from a lot of DLMS devices or meters, deploying Utilitarian might be the smoothest \nsolution for you.\n\n\n\n\n# Changelog\nAll notable changes to this project will be documented in this file.\n\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Calendar Versioning](https://calver.org/)\n\n## Unreleased\n\n\n### Added\n\n### Changed\n\n### Deprecated\n\n### Removed\n\n### Fixed\n\n### Security\n\n\n## 24.1.0 - 2024-01-22\n\n### Added\n* Support for HDLC over TCP via composition of IO-implementation separate from\n transport implementation.\n* Support for LLS (Low Level Security)\n* Support for HLS (method 2) using common method of AES128-ECB.\n* Structlog logging.\n* Implemented VisibleStringData.\n* DlmsConnectionSettings to handle manufacturer specific quirks in communication.\n\n### Changed\n* Changed License from MIT to BSL v1.1\n* Refactor of authentication to make it simpler support more authentication types. And make\n it possible to supply manufacturer specific implementations.\n\n### Removed\n* Shorthand class methods to create DlmsClients. Now composition has to be used.\n\n### Fixed\n* Error in DataArray dlms data type \n\n\n## [21.3.2] - 2021-11-07\n\n## Changed\n\nUpdated dependencies and made it a bit more lenient so installing in other environments\nwill allow for more versions.\n\n## [21.3.1] - 2021-06-14\n\n### Added\n\n* To handle the more complicated parsing problem of GET.WITH_LIST with compound data\n elements a new parser, DlmsDataParser, was added that focuses on only A-XDR DLMS data.\n Hopefully this can be be used instead of the A-XDR Parser when the parsing of ACSE\n services APDUs is built away\n\n## [21.3.0] - 2021-06-08\n\n\n### Added\n\n* Added HDLC UnnumberedInformationFrame.\n* Ability to set timeout of transport layer at client level.\n* A simpler way to change client address and invocation counter of a `DlmsClient` to\n that reuseing a connection goes smoother\n* Added `from_string` on `Obis`that can parse any viable string as OBIS.\n* Added GET.WITH_LIST service.\n\n### Changed\n\n* Renamed classes to exclude `Apdu` in class names. To have it consistent over the\n project.\n* Simplified DataNotification\n* Improved handling of pre-established associations\n* Using the wrong data to decrypt now raises `DecryptionError` instead of InvalidTag\n* The `to_string` method on `Obis` now returns in the format `1-8:1.8.0.255` with a\n possible override of the separator.\n\n### Removed\n\n* Removed the `from_dotted`, `dotted_repr` and `verbose_repr` from `Obis`\n\n\n### Fixed\n\n* Some DLMS over TCP implementations will return partial data. The\n `BlockingTcpTransport` now keeps on trying to read the data until all data is\n received. Fixes [#35](https://github.com/pwitab/dlms-cosem/issues/35).\n* Fixed a bug in the HDLC layer that prevented correct sending of segmented information\n frames.\n\n\n## [21.2.2] - 2021-03-02\n\n### Fixed\n\n* Fixed missing state management for general ACTION usage\n\n## [21.2.1] - 2021-02-18\n\n### Fixed\n\n* Fixed [#23](https://github.com/pwitab/dlms-cosem/issues/23). Typo in A-XDR Parser.\n Just referenced the function and did not call it. Now DLMS data is interpreted\n correctly.\n\n* Fixed [#20](https://github.com/pwitab/dlms-cosem/issues/20). It was possible that not\n calling the .shutdown() on socket before disconnecting made remote modems on meters,\n that have an embedded TCP/IP stack, keep the socket open and blocking subsequent calls.\n\n## [21.2.0] - 2021-01-28\n\n### Added\n\n* Support for basic SET service. No support for WITH_LIST or service specific block\n transfer\n\n## [21.1.2] - 2021-01-22\n\n### Fixed\n\n* The standard DLMS way of dealing with timezones in datetime are via UTC offset. But\n the offset is the deviation from normal time to UTC not deviation from UTC. This\n results in -60 min deviation for UTC+01:00 for example. Previous solution assumed\n 60 min for UTC+01:00. Solved by negating all values for offset.\n Note that some DLMS companion standards handles the offset the previous way and in\n the future there will be need to handle both ways correctly.\n\n* Included typing-extensions in required packages.\n\n## [21.1.1] - 2021-01-13\n\n### Added\n\n* Better handling of TCP errors in `BlockingTcpTransport`\n\n### Changed\n\n* It is now explicitly possible to connect and disconnect a transport in the\n `DlmsClient` instead of it being done automatically in `.associate()` and\n `.release_association()`. Context manager `.session()` works the same.\n\n* Client to server challenge of DlmsConnection is always created independent of auth\n method. But only used if needed.\n\n### Removed\n\n* Removed conformance validation in DlmsConnection. It seems like meters don't always\n follow it so better to leave it up to the client.\n\n\n\n## [21.1.0] - 2021-01-12\n\n### Added\n\n* HDLC transport implementation\n* TCP transport implementation\n* DlMS client implementation\n* Support for Get service including service specific block transfer\n* Support for selective access via range descriptor\n* Support for HLS authentication using HLS-GMAC.\n* Support for GlobalCiphering\n* Parsing of ProfileGeneric buffer\n\n### Changed\n\n* Changed project versioning scheme to Calendar versioning\n\n\n## v0.0.2\n\n\n### Changed\n\n- UDP messages are now based WrapperProtocolDataUnit to be able to reuse\n WrapperHeader for TCP messages.\n- Parsing of DLMS APDUs\n\n\n### v0.0.1\n\n\nInitial implementation.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for DLMS/COSEM",
"version": "24.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/pwitab/dlms-cosem/issues",
"Documentation": "https://www.dlms.dev/",
"Homepage": "https://github.com/pwitab/dlms-cosem",
"Source Code": "https://github.com/pwitab/dlms-cosem"
},
"split_keywords": [
"amr",
"metering",
"smart meters",
"mdm",
"dlms",
"cosem"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea1fc53d1f240cb2d02d05dbec5604efdcb899518185a878c94e5aefd8598853",
"md5": "9d8695ebb58e1312498da2fa061770b8",
"sha256": "11b790e40033c0b096e482ebe54589965e4e436a85ee3a6f4bff0649fb4d62ee"
},
"downloads": -1,
"filename": "dlms_cosem-24.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d8695ebb58e1312498da2fa061770b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 116096,
"upload_time": "2024-01-22T15:29:17",
"upload_time_iso_8601": "2024-01-22T15:29:17.231917Z",
"url": "https://files.pythonhosted.org/packages/ea/1f/c53d1f240cb2d02d05dbec5604efdcb899518185a878c94e5aefd8598853/dlms_cosem-24.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "42569c01ffad667aa39e011a80eba1a4e7160c4f07a430af0114958519b56c3c",
"md5": "e5931609d297b797a77786684ddd5fbe",
"sha256": "9718dc57f68fba4ea58bb288b6da0546a59720ee6ee3d70863a95dc65c069070"
},
"downloads": -1,
"filename": "dlms-cosem-24.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e5931609d297b797a77786684ddd5fbe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 102234,
"upload_time": "2024-01-22T15:29:20",
"upload_time_iso_8601": "2024-01-22T15:29:20.996249Z",
"url": "https://files.pythonhosted.org/packages/42/56/9c01ffad667aa39e011a80eba1a4e7160c4f07a430af0114958519b56c3c/dlms-cosem-24.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-22 15:29:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pwitab",
"github_project": "dlms-cosem",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dlms-cosem"
}
JSON
