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.
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.
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:
|
Medium: Defines the media (energy type) to which the meter is related. Non-media related information is handled as abstract data. |
|
Channel: The metering equipment has several inputs for the measurement of energy of the same or different types. This group is independent from group |
|
Defines the abstract of physical data items, related to the information source. |
|
Defines types, or the result of the processing of physical quantities identified with the value groups |
|
The value group E defines further processing or classification of quantities identified by value groups |
|
Defines the storage of the data, identified by |
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 |
---|---|---|---|
|
|
|
Contains the list of all logical devices and their SAP addresses within the physical device. |
|
|
|
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:
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