1. Introduction
2. Aim
3. Approach
   1. Device Functionality Overview
      1. Capability
      2. Protocol Information
      3. IP Whitelisting / IP Lookup
      4. API Calls
      5. Historic Packet Tracking
      6. Design Specifications
      7. Routing Key Logic
4. Usage
   1. Device configuration walkthrough
5. Deployment Configuration
   1. Steps on how to deploy and configure the driver
   2. How to set up port forwarding
   3. External HTTP access
6. Release Notes

Introduction

DLMS stands for Device Language Message Specification. DLMS/ COSEM (or IEC 62056) is the main global standard for smart energy metering, control and management. It includes specifications for media-specific communication profiles, an object-oriented data model and an application layer protocol. DLMS/ COSEM smart metering protocol is not specific to electricity metering and can also be used for other utilities such as gas, water and heat.

DLMS/ COSEM consists of three main parts:

1. COSEM (Companion Specification for Energy Metering): describes the general object model and can be used for all kinds of applications.
2. OBIS (Object Identification System): this is the naming system of the objects.
3. DLMS (Device Language Message Specification): this is the application layer protocol that is used to transform the data into messages.

Aim

The objective of DLMS is to provide an interoperable environment for structured modeling and meter data exchange. DLMS supports applications such as remote meter reading, remote control, and value-added services for metering any kind of energy, such as electricity, water, gas or heat. DLMS meters supports both pushing and polling services.

Approach

Old DLMS compatible devices mainly make use of DLMS polling to extract data which involves using a ScheduledReceptor devices to connect to the meters, extract the required xml mapping and then making a subsequent request to map the data according to the xml structure. Newer DLMS devices support a more scalable solution called DLMS Push. DLMS Push allows the device to send its data via TCP to a Receptor device configured with a TCP server. DLMS also supports “DLMS Secured” which is Gurux library defined encryption.

Device Functionality Overview

DLMS PUSH

Figure 1 - DLMS PUSH

Capability

• DLMS Push
• DLMS Poll
• Secured DLMS Push
• Secured DLMS Poll

Protocol Information

The DLMS driver is designed to support 2 different device types namely the Scheduled Receptor and Receptor devices. The Scheduled Receptor device is exclusively used for DLMS polling and it is the least scalable of the two different solutions. The Scheduled Receptor device incorporates the use of the Gurux nuget package to set up a client to be able to connect to a DLMS/COSEM device and extract the data by mapping a xml document with the data structure and then afterwards mapping data according to the XML file. The Receptor device spins up a TCP server that waits for TCP packets from the DLMS devices. These devices usually send data on a schedule and the comms can be secured via a DLMS Secured approach. The Secured Approach encrypts the data that is sent by the devices according to the System Title, Authentication Key, Block Cipher key, Security Type and Security Suite.

IP Whitelisting / IP Lookup

This is a check that is used internally on the driver. IP Whitelisting closely ties into your packet tracking. It will do one of two things, if it is set to true, it will request a user from the database and if it is set to false it will use the config credentials. When a user wants to implement the driver in an environment where each device has its own configuration, then IP Lookup should be enabled. However, if all devices have the same configuration, then there is no need to use the IP Lookup feature. The terms IP Whitelisting and IP Lookup are used interchangeably.

The IP Whitelisting is a security layer that is optional. Ideally, a user can add it in for extra security. If they do not require it, it can be disabled. If the IP Lookup is not used, it will still accept traffic from unverified devices. However that packet that is received will go through a verification process. If it is an invalid DLMS packet, it will just be rejected.

API Calls

It is important to add the Add Users to the database with API calls.

To Add Users/Devices

To add Users/Devices the user can use the following path to use the API: api/Users/Dlms/{DeviceName}/Add.

The above notation must be used exactly as it is.

{
    "users": [
        {
            "Ip": "127.0.0.1",
            "Authentication": "HighGmac",
            "Password" : "12345",
            "ConnectionInterfaceType" : "WRAPPER",
            "UseLogicalNameReferencing" : 1,
            "ClientAddress" : -1,
            "ServerAddress" : -1,
            "SecureClient" : 1,
            "BlockCipherKey" : "000102030405060708090A0B0C0D0E0F",
            "SecureClientSecurity" : "AuthenticationEncryption",
            "SystemTitle" : "45444D6B31304D30",
            "AuthenticationKey" : "000102030405060708090A0B0C0D0E0F",
            "SecuritySuite" : "Suite0"
        },
        {
            "Ip": "127.55.6.1",
            "Authentication": "HighGmac",
            "Password" : "12345",
            "ConnectionInterfaceType" : "WRAPPER",
            "UseLogicalNameReferencing" : 1,
            "ClientAddress" : -1,
            "ServerAddress" : -1,
            "SecureClient" : 1,
            "BlockCipherKey" : "000102030405060708090A0B0C0D0E0F",
            "SecureClientSecurity" : "AuthenticationEncryption",
            "SystemTitle" : "45444D6B31304D30",
            "AuthenticationKey" : "000102030405060708090A0B0C0D0E0F",
            "SecuritySuite" : "Suite0"
        }
    ]
}

To Delete Users/Devices

To delete Users/Devices, the user can use the following path to use the API: api/Users/Dlms/{DeviceName}/Delete.

The above notation must be used exactly as it is.

{
    "ips": [
        "127.0.0.1",
        "127.55.6.1"
    ]
}

All API calls require a sufficient API key with a configurator role. It also requires a service ID which is the name of the deploy driver. See Figure 2

Figure 2 - Service ID Example

Historic Packet Tracking

Historic Packet Tracking is built into the programming layer where it checks the queue, and if it exceeds a certain number, any record or packet that comes in after that exceeded amount is added to a database and it runs on a schedule. That schedule will batch the records. With a batch number, a user can define how many records they want to get out of the database. The historic record batching size and the historic record interval, are both related to a background process. That process is specifically for that historic packet handling. If the load on the driver in general is too high any incoming packets will fall under historic packets and it will be stored in a database for later processing. That way, there will not be any loss of data if there is a massive load. Therefore it is always retainable.

The historic packets have two essential properties and two optional properties. All of them have their own default values. The user does not have to configure the BackgroundProcessBoundedCapacity and the BackgroundProcessMaxDegreeOfParallelism. There are three properties that are important for the historic packets process, i.e. the HandleHistoricRecordInterval, HistoricRecordBatchingSize and the MaxBoundedPacketMultiplier.

Design Specifications

Scheduled Receptor

Device Configuration Options

"LG_Office": {
  "Enabled": false,
  "ActionDelay": 20000,
  "GroupName": "DLMS",
  "GatewayId": "Lan********",
  "DeviceType": "ScheduledDlms",
  "HostName": "17*.**.***.22", 
  "Port": ****,
  "ConnTimeout": 8000,
  "MediaTimeout": 10000,
  "PropertiesDeviceName": "DefaultProperties",
  "Debug": true,
  "ClientAddress": **,
  "ServerAddress": **,
  "Priority": "High", 
  "UseLogicalNameReferencing": false, 
  "StartProtocol": "Idis", 
  "ConnectionInterfaceType": "HDLC", 
  "TxMaxFrameSize": 128,
  "RxMaxFrameSize": 128,
  "SecurityLevel": "None", 
  "Password": null,
  "Authentication": "None", 
  "SecureClient": false
}

PropertyMaps

"DefaultProperties": {
      "DeviceType": "DefaultProperties",
      "GroupName": "DLMS",
      "PropertyMaps": {
        "P3PF": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "P3PF",
          "AttributeIndex": 2
        },
        "P2PF": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "P2PF"
        },
        "P1PF": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "P1PF"
        },
        "TOTALPOWERFACTOR": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "TOTALPOWERFACTOR"
        },
        "ACTIVEPOWER": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "ACTIVEPOWER"
        },
        "FREQUENCY": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "FREQUENCY",
          "TransformSetId": "***0"
        },
        "L0CURRENT": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "L0CURRENT"
        },
        "P3CURRENT": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "P3CURRENT",
          "TransformSetId": "***0"
        }
      }
    }

Receptor (DlmsPushServer)

Device configuration options

"ServerDevice": {
      "Enabled": true,
      "DeviceType": "DlmsPushServer",
      "Debug": true,

      "GroupName": "PushServer",
      "GatewayId": "something",

      "DeviceGatewayIdProperty": "SerialNumber",
      "EnableIpLookup": true,
      "DeviceAuthorization": false,
      "RegisterAsGateway": false,
      "PropertiesDeviceName": "PushProperties",

      "ClientAddress": -1,
      "ServerAddress": -1,
      "Priority": "High",
      "UseLogicalNameReferencing": true,
      "StartProtocol": "DLMS",
      "ConnectionInterfaceType": "WRAPPER",
      "TxMaxFrameSize": 256,
      "RxMaxFrameSize": 256,
      "SecurityLevel": "None",
      "Password": 12345,
      "Authentication": "HighGmac",
      "SecureClient": true,
      "BlockCipherKey": "0001020304050607000H00002G00003D",
      "SystemTitle": "400000E5B13F0000",
      "AuthenticationKey": "000102030405060708090A0B0C0D0E0F",
      "SecuritySuite": "Suite0",
      "SecureClientSecurity": "AuthenticationEncryption",

      "Address": "Any",
      "Port": 9052,
      "Encryption": "None",
      "DroppedClientDetection": "ReadTimeout,DisconnectOtherConnections",
      "DroppedClientTimeoutSecs": 15,
      "CertificatePath": "/etc/ssl/certs/public.rsa.pfx",
      "CertificatePassword": "",

      "HandleHistoricRecordInterval": 30000,
      "HistoricRecordBatchingSize": 100,

      "ProcessBoundedCapacity": 150,
      "ProcessMaxDegreeOfParallelism": 750,

      "BackgroundProcessBoundedCapacity": 500,
      "BackgroundProcessMaxDegreeOfParallelism": 500,

      "MaxBoundedPacketMultiplier": 4,

      "DropDataLength": 120
    },

PropertyMaps

"PushProperties": {
      "DeviceType": "PushDefaultProperties",
      "GroupName": "D********************",
      "PropertyMaps": {
        "TotalPositiveActiveEnergy": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "TotalPositiveActiveEnergy",
          "AttributeIndex": 2,
          "DlmsObjectType": "Register",
          "DataIndex": 0,
          "PushProfileSequenceId": *
        },
        "TotalPositiveActivePower": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "TotalPositiveActivePower",
          "AttributeIndex": 2,
          "DlmsObjectType": "Register",
          "DataIndex": 0,
          "PushProfileSequenceId": *
        },
        "SerialNumber": {
          "ObisCode": "1.*.**.*.*.*55",
          "PropertyName": "SerialNumber",
          "AttributeIndex": 2,
          "DlmsObjectType": "Data",
          "DataIndex": 0,
          "PushProfileSequenceId": *,
          "DataType": "string"
        }
      }
    }

Routing Key Logic

The routing key for these sensors is constructed as follows:

deviceInfo.GatewayId = Options.RegisterAsGateway ? meter.Serial : Options.GatewayId;
deviceInfo.GroupName = meterReading.Measure.ToUpper();
deviceInfo.DeviceType = Options.DeviceType;
deviceInfo.DeviceName = Options.RegisterAsGateway ? DeviceName : meter.Serial;

Meaning you can choose between one of the two configurations for the routing key GatewayID.GroupName:DeviceType|DeviceName

And the available properties are constructed as follows:

CreateProperty("string", nameof(meterReadingData.Id))
CreateProperty("string", nameof(meterReadingData.Serial))
CreateProperty("string", nameof(meterReading.Measure))
CreateProperty("string", nameof(meterReading.Unit))
CreateProperty("string", nameof(meterReading.Direction))
CreateProperty("double", nameof(meterReading.Value))
CreateProperty("DateTime", nameof(meterReading.Date))

Meaning these are the 7 properties to be sent:

Usage

Device configuration walkthrough

• We Create a device called: DLMS
• We want the device to run when deployed, so we must make sure that the Enabled tag is set to true.
• Ideally logging should initially be enabled to ensure that everything is running correctly, therefore Debug should be set to true.
• If we want to include anything relating to IP Lookup, we need to set the EnableIPLookup tag to true. If not, then it will not be used.
• If it should be the case that the IP Lookup is not used, we should set the DLMS device options within the configuration. It will include these essential properties, ClientAddress, ServerAddress, Priority, UseLogicalNameReferencing, StartProtocol, ConnectionInterfaceType, TxMaxFrameSize, RxMaxFrameSize, SecurityLevel, Password, Authentication, SecureClient, BlockCipherKey, SystemTitle, AuthenticationKey, SecuritySuite, and SecureClientSecurity.
• If we want the device to set up authorised users, we can set DeviceAuthorization to true. We can use RegisterAsGateway i.e GatewayID.GroupName:DeviceType|DeviceName.
• Associate a property map with DLMS (a set of properties with the device).
• If we want to customise the historic packet settings, we can set a custom execute interval as well as a custom batching size to pull historic packets from the database.
• With regards to the normal driver flow, we can customise these two properties (ProcessBoundedCapacity, ProcessMaxDegreeOfParallelism) for performance reasons. Determines how many packets can be in the queue as well as how many packets can be handled in parallel. This is a customised way of managing the performance to have a bit more control over the driver, and how much resources it uses. This would also apply to the BackgroundProcessBoundedCapacity, and BackgroundProcessMaxDegreeOfParallelism.
• To be able to receive data we have to configure a TCP server. The TCP server relates to all of these properties: Address, Port, Encryption, DroppedClientDetection, DroppedClientTimeoutSecs, CertficatePath, and CertficatePassword. The most important ones are Address and Port.

Deployment Configuration

Steps on how to deploy and configure the driver

The link below demonstrates the steps to follow when a user deploys and configures a V-Raptor driver:

Deployment Manager Application

How to set up port forwarding

1. Go to the Connection Manager to set up some routing for the driver.
2. Go to Internal Routing.
3. Add an internal rule to the port the driver is configured to initialize the TCP server on. You can call it dlms-tcp-internal.
4. After successfully adding the internal rule, go back to the connection manager main page and click on External Routing.
5. In the External Routing options, this is where you will set up a port that will be used for external connections to the driver.
6. Add the external rule. Within the rule, please make sure to specify your internal rule as a routing point which in this case will be dlms-tcp-internal. You can call the rule dlms-tcp-external.
7. Now your driver should be capable of receiving TCP comms from external devices.

External HTTP access

To access the driver externally e.g. metrics, HTTP requests, Swagger etc

1. Go to the Connection Manager to set up some routing for the driver
2. Go to External Routing
3. Use Virtual Hosting
4. Follow example below

Figure 3 - Add external rule

Release Notes