1. Intro

jDLMS is a Java implementation of the DLMS [1]/COSEM [2] protocol. It can be used to develop individual DLMS/COSEM client/master or server/slaves applications.

The jDLMS library supports communication over HDLC [3]/serial, HDLC/TCP-IP and Wrapper/TCP-IP.

1.1. Distribution

After extracting the distribution tar file the jDLMS library can be found in the directory build/libs-all/. The Javadoc for jDLMS can be found in the directory build/docs/javadoc/. For license information check the license/ directory 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, https://www.openmuc.org/asn1/

  • jRxTx - This library for serial communication is only needed by jDLMS if communication over HDLC/serial is used. jRxTx is licensed under LGPL(v2 or later). jRxTx 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 jRxTx as explained in our FAQ. jRxTx is located at https://github.com/openmuc/jrxtx.

  • 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-console-client script found in the folder run-scripts/. Executing the script without any parameters will print help information to the screen.

You can find the source code of application in src/main/java/org/openmuc/jdlms/app/. See the README.txt in the run-scripts/ directory to run the demo APP in the console.

Instead of running the application from the terminal you can create Eclipse project files as explained here 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.

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 communication over HDLC/serial, TCP and UDP. The DLMS/COSEM standard is adopted by the IEC TC13 WG 14 into the IEC 62056 standards.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/serial). The entity accessing the meter is called the client or master respectively. In this manual we will always use the terms client and server.

DLMS/COSEM Communication Layers

DLMS/COSEM communication layers

2.1. Physical and 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 0x0000…​0x3FFF. As an example, a meter could consist of one logical device for electricity metering on address 0x12 and another one for a connected gas meter on address 0x43. 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 0x01. 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.

COSEM Physical Device

Physical device.

2.2. Client ID

Both server and client need an address to be uniquely identified. The server ID 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 client ID defines the access level the client is connecting to the Logical Device. The client ID 16 is a special client ID, which refers to the public client, where no authentication or encryption is required. This client ID has the lowest rights.

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 (IC), similar to classes in object oriented programming (OOP) languages. All available classes as well as their exact structure can be found in IEC 62056-6-2.

Objects can be addressed in two ways, depending on the remote meter. The recommended way is using the logical name of an object.

2.3.1. Logical Name Referencing

A logical name, also known as OBIS code or instance ID, is a 6 Byte long number that uniquely identifies a object over in a logical device. For example, the clock of a smart meter is always reachable under the address [0, 0, 1, 0, 0, 255].

OBIS — Object Identification System

The OBIS Code is apostatized in IEC 62056-6-1. The DLMS UA regulates what objects are under what addresses. A list of all possible logical names is published by the DLMS UA as MS Excel sheet. OBIS codes are in the format of A.B.C.D.E.F with following meaning:

A

Medium: Defines the media (energy type) to which the meter is related. Non-media related information is handled as abstract data.

B

Channel: The metering equipment has several inputs for the measurement of energy of the same or different types. This group is independent from group A.

C

Defines the abstract of physical data items, related to the information source.

D

Defines types, or the result of the processing of physical quantities identified with the value groups A and C, according to various specific algorithms.

E

The value group E defines further processing or classification of quantities identified by value groups A to D.

F

Defines the storage of the data, identified by A to E. May be set to 0xFF (255) where this is irrelevant.

2.3.2. Short Name Referencing

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 service and the meter replies with an appropriate response.

Even though the data of the remote device is addressed in an object based fashion, data is accessed attribute based. In order to access an attribute, you may invoke the GET or SET service, which require a set of three addressing parameters:

  • Class ID

  • Instance ID

  • Attribute ID

The class ID of an object can be extracted from the Excel sheet 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-6-2 or the Blue Book from the DLMS UA. As a rule of thumb, the first attribute (attribute ID 1) of an COSEM interface class (IC) is the instance ID (logical name) of the object. Further attributes refer to actual data (see section 4.5 of IEC 62056-6-2).

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)

2.4.1. Selective Access

The xDLMS GET and SET services allow the client to access just a part of a specific attribute. The part is defined by some specific selective access parameters. These selective access parameters are defined as part of the attribute specification.

2.4.2. Example Addresses

Class ID Logical Name Attribute ID Description

SAP_ASSIGNMENT(17)

0.0.41.0.0.255

SAP_assignment_list(2)

Contains the list of all logical devices and their SAP addresses within the physical device.

ASSOCIATION_LN(15)

0.0.40.0.0.255

object_list(2)

Contains the list of visible COSEM objects.

2.5. COSEM Method

A COSEM objects may also offer a number of methods to invoke a procedure in the object the method is associated with. Analogously to COSEM attributes the COSEM methods are addressed in the same manner:

  • Class ID

  • Instance ID

  • Method ID

See IEC 62056-6-2 for a detailed description.

3. Using jDLMS

To get started using jDLMS, create a Gradle project (see the FAQ site how to install Gradle). Add the latest jDLMS version to your project build.gradle:

apply plugin: 'java'
apply plugin: 'eclipse'

buildscript {
  repositories {
    maven {
      url 'https://plugins.gradle.org/m2/'
    }
  }
}

dependency {
	compile group: 'org.openmuc', name: 'jdlms', version: '<latest_version>'
}

See the jDLMS Javadoc for documentation of the stack/API.

A connection can be established in the following manner:

Sample connection from sample source folder.
InetAddress inetAddress = InetAddress.getByName("127.0.0.1");
Authentication authentication = Authentication
        .newPasswordAuthentication("Password".getBytes(StandardCharsets.US_ASCII));

TcpConnectionBuilder connectionBuilder = new TcpConnectionBuilder(inetAddress).setTcpPort(9293)
        .setAuthentication(authentication);

try (DlmsConnection dlmsConnection = connectionBuilder.buildLnConnection();) {

    GetResult result = dlmsConnection
            .get(new AttributeAddress(AssociationLnAttribute.OBJECT_LIST, "0.0.40.0.0.255"));

    if (result.getResultCode() == AccessResultCode.SUCCESS) {
        DataObject resultData = result.getResultData();
        System.out.println(resultData.toString());
    }
} // closes the connection automatically at the end of this block

4. Authors

Developers:

  • Stefan Feuerhahn

  • Dirk Zimmermann

  • Albrecht Schall

Former developers:

  • Karsten Müller-Bier


1. Device Language Meter Specification
2. Companian Specification for Energy Metering
3. High-Level Data Link Control