1. Intro

jDLMS is a Java implementation of the DLMS/COSEM protocol. It can be used to develop individual DLMS/COSEM client/master applications that access server/slave devices. The jDLMS library supports communication over HDLC/serial and TCP/IP.

1.1. Distribution

After extracting the distribution tar file the jDLMS library can be found in the folder "build/libs-all/". The javadoc for jDLMS can be found in the folder "build/docs/javadoc/". For license information check the "license/" folder in the distribution.

1.1.1. Dependencies

Besides the jDLMS library the folder "build/libs-all/" contains the following external libraries:

  • jasn1 - a library for ASN.1 BER encoding/decoding, LGPLv2.1 or later, http://www.openmuc.org

  • RXTX - This library for serial communication is only needed by jDLMS if communication over HDLC/serial is used. RXTX is licensed under LGPL(v2 or later). RXTX consists of a Java part located in the dependencies folder of the distribution and a native part. Note that you have to install the native part of RXTX as explained in our FAQs: http://www.openmuc.org/index.php?id=72#faq_rxtx

  • Bouncy Castle (bcprov) - A library needed for security algorithms. It is only needed if jDLMS is used with encryption or authentication enabled.

The "dependencies/" folder in the distribution contains more detailed license and copyright information about these dependencies.

1.1.2. Command Line Application

A command line application is part of the library that can be used to connect, read, write and scan DLMS devices. You can execute it using the "jdlms-clientapp" script found in the folder run-scripts/. Executing the script without any parameters will print help information to the screen.

Instead of running the application from the terminal you can create Eclipse project files as explained here: http://www.openmuc.org/index.php?id=72#faq_gradle and run it from within Eclipse.

1.1.3. Build Scripts

We use the Gradle build automation tool. The distribution contains a fully functional gradle build file ("build.gradle"). Thus if you changed code and want to rebuild a library you can do it easily with Gradle. Also if you want to import our software into Eclipse you can easily create Eclipse project files using Gradle. Just follow the instructions on our FAQ site: http://www.openmuc.org/index.php?id=72#faq_gradle

1.1.4. A-XDR Compiler

Besides the jDLMS project the distribution contains a subproject named A-XDR Compiler. It is an application developed to automatically compile the DLMS/COSEM ASN.1 data structures and generate classes that can be used to encode/decode A-XDR messages. The generated classes are part of jDLMS. You will not need this application if you simply want to use the jDLMS library.

2. How DLMS/COSEM Works

DLMS/COSEM is an application layer protocol specifically designed for communication with smart meters over multiple lower layer protocols. DLMS/COSEM supports communication over HDLC/serial, TCP and UDP. Recently DLMS/COSEM is also being used over power line protocols such as G3.

In DLMS/COSEM the meter is called the server (when used over IP) or slave (when accessed over HDLC). The entity accessing the meter is called the client or master respectively. In this manual we will always use the terms client and server.

2.1. Logical Devices

In DLMS/COSEM, a physical smart meter device can host several so called logical devices. Each logical device has an address in the range from 1 to 65536. As an example, a meter could consist of one logical device for electricity metering on address 18 and another one for a connected gas meter on address 67. No matter what type of smart meter it is, a DLMS/COSEM device must contain a special logical device called the management logical device at address 1. The content of this device may vary, but it must at least have a list of all logical devices inside the physical smart meter. You are always connecting to a single logical device with DLMS/COSEM.

2.2. Client Address

Both server and client need an address to be uniquely identified. The server address that identifies a device consists of the physical address of the device (e.g. an IP address + port), as well as the address of the logical device (e.g. 1 for the management logical device).

On the other hand, the address of the client depends on the communication protocol being used but always consists at least of one Byte to identify the nature of the client. In most cases, this Byte determines what objects you can read or write and what form of authentication is necessary to connect to the device. A special identifier is the number 16, which refers to the public client. This client address has the lowest rights and doesn’t need any authentication in most cases.

If HDLC is used as communication layer, the client address only consists of this single byte. Using TCP or UDP, the address additionaly consists of the IP and port of the client application.

2.3. Object Addresses

As previously mentioned, DLMS/COSEM is an object based protocol. That means that the data of a device is grouped in objects. These objects are always instances of clearly defined interface classes, similar to classes in object oriented programming languages. All available classes as well as their exact structure can be found in IEC 62056-62.

Objects can be addressed in two ways, depending on the connected smart meter. The recommended way is using the logical name of an object. A logical name, also known as OBIS code, is a 6 Byte long number that uniquely addresses a certain object over all smart meters. For example, the clock of a smart meter is always reachable under the address [0, 0, 1, 0, 0, 255]. The DLMS UA regulates what objects are under what addresses. A list of all possible logical names is published by the DLMS UA under the following site as an Excel sheet.

The other way to address an object is by means of the so called short address. Short addresses are used for small devices and should only be used if the connected smart meter cannot communicate using logical names. The short address is a simple 2 Byte long number, instead of the 6 Byte long OBIS code mentioned above. The address space of short addresses is not regulated like the logical names, meaning that the same address can lead to different objects on different devices.

2.4. Accessing Data

After the connection to a logical device has been established, communication occurs using the request-response model, meaning that the client requests a specific action and the device sends the appropriate response back to the client.

Even though the data of the remote device is addressed in an object based fashion, data is accessed attribute based. So, in order to send a request, you have to send 3 parameters for uniquely identify the data and access it:

  • Class ID

  • Address of the object

  • Attribute ID

The class ID of an object can be extracted from the list mentioned earlier, while the exact attribute ID depends on the class ID and can be extracted the best way by consulting the document IEC 62056-62 or the Blue Book from the DLMS UA. As a rule of thumb, the first attribute of an object is its logical name, while the second attribute is the actual data. Further attributes usually include metadata like unit and scaling factor.

As an example that is used through the rest of this document, to access the current time on a smart meter you have to use the following parameters:

  • Class ID: 8 (Clock class)

  • Logical Name: [0, 0, 1, 0, 0, 255] (Current time)

  • Attribute ID: 2 (Data)

3. Using jDLMS

The library includes a console application that can be used to connect to and read a given meter. This application can also be used as an example on how to use the the library. You can find the source code of application in src/main/java/org/openmuc/jdlms/app/ .

4. Authors

Developers:

  • Stefan Feuerhahn

  • Dirk Zimmermann

  • Albrecht Schall

Former developers:

  • Karsten Müller-Bier