Using Ti's Dlms Cosem Library
Using Ti's Dlms Cosem Library
ABSTRACT
This application report describes in detail the usage of DLMS COSEM library developed by Texas
Instruments for customers who use TIs microcontrollers in metering applications. The library is provided
as object coded with a configuration file for ease of use. The library can be obtained by contacting the
regional sales and marketing offices. The customer will have to sign an SLA before getting access to the
library.
Contents
1 Introduction .................................................................................................................. 1
2 Features ...................................................................................................................... 2
3 Prerequisites ................................................................................................................. 2
4 File Structure ................................................................................................................ 2
5 Object List Tables ........................................................................................................... 3
6 Attribute List Tables ........................................................................................................ 3
7 Handling of Complex Data Types Like Structures and Arrays Through ASN.1BER Encoding ................... 4
8 The Call Back Function .................................................................................................... 4
9 Handling of Multiple Entries in a Profile Generic Class Buffer ........................................................ 4
10 Changing the PDU Size .................................................................................................... 7
11 Methods List Tables and Method Description ........................................................................... 7
12 Handling Associations ...................................................................................................... 9
13 Adding a New Class ........................................................................................................ 9
14 Reference .................................................................................................................... 9
List of Figures
1 Object List Table ........................................................................................................... 3
2 Attribute List Table .......................................................................................................... 3
3 Method List Table ........................................................................................................... 7
1 Introduction
DLMS stands for Device Language Message specification. It is a generalized concept for abstract
modeling of communication entities which, along with the COSEM (COmpanion Specification for Energy
Metering) specification, has been standardized as a set of rules for data exchange with energy meters.
The DLMS specification is developed and maintained by the DLMS User Association and has been
adopted by the IEC TC13 WG14 into the IEC 62056 series of standards.
Texas Instruments has developed a compact and easy to use library that can be integrated into a
metering application on TIs MSP430 microcontrollers. Section 2 describes the various features of this
library.
2 Features
The DLMS Library provided by Texas Instruments supports the following features:
All COSEM classes are supported. The examples of a few commonly used classes are given.
Supports three associations: No Security (NS), Low Security (LS) and High Security (HS). In the HS
association, a four step AES128 based authentication mechanism is used. These three associations
are also referred as Public Client (PC), Meter Reader (MR) and Utility Setting (US) associations,
respectively.
Supports long name addressing
Supports one, two and four byte addressing
Supports GET, SET, GET WITH BLOCK, SET WITH BLOCK, ACTION and Selective Access requests
A special mechanism for handling Profile Generic objects where multiple data entries are required
Supports selective access in Profile Generic Class Buffer
Passes all DLMS CTT V2.0 tests
Code Size - ~24KB
RAM Size ~ 1.8KB
Easy configuration and ease of use
3 Prerequisites
For using this library, it is required that you have a thorough understanding of DLMS Blue Book Classes
and embedded C programming background.
For any development on DLMS library, you need to have DLMS Client software so that the meter can be
tested. There are a few companies like Kalkitech, Gurux, and so forth that provide a semi-functional demo
software, which can be downloaded from the internet. For developing a final product, one would need to
buy a full version of the Kalkitech DLMS Client.
You also need to have a full version of IAR Embedded Workbench for MSP430.
4 File Structure
The following files are available in the library:
iec62056_demo.c: This is the user interface file for system initialization. All the peripherals are
initialized and the HDLC state machine is initialized.
uart_comms.c: This is the configuration file for the UART module. Depending upon the requirement,
the available USCIs can be initialized.
iec62056_link.r43: This file implements HDLC and Mac layer. This file is provided as object coded file.
server_msgs.r43: This file implements COSEM application layer. This file is also provided as object
coded file.
config.c: This file is the main configuration file for the users system. In this file, one can add or remove
parameters from the object list, which is described later in the document
app_server_msgs.c: This file is the one where most of the user code has to be written. Here, one has
to write all the functions, which are used to extract data from the memory and provide it to the DLMS
library.
config.h: Prototype declarations and macro definitions for config.c
cosem.h: Definition of all the constants used in COSEM application layer.
iec_62056_link.h:Prototype declarations and macro definitions for HDLC layer.
Attribute Number: The first entry in this table indicates the serial number of the attribute of this class.
Access Rights: The second column provides the access rights for this attribute depending upon the
type of association that is established between DLMS server and client. The syntax for providing the
access rights is PCXY_MRXY_USXY, where PC, MR, US correspond to the type of association X is
R if a read access is available and _ if no read access is available. Similarly, Y is W if a write access is
available and _ if no write access is available.
Data Type: This column defines a TAG for the data type to which this parameter belongs. The DLMS
documentation (Blue Book, section 4.1.5) specifies a TAG for each data type. There are predefined
macros available for each data type.
Data Pointer: This value gives the pointer to the location where this value is stored.
Call Back Function: If this value is not readily available in the RAM, then the library calls this call-back
function that will execute some C code, which will fill up the actual value at the location specified in
column 4.
7 Handling of Complex Data Types Like Structures and Arrays Through ASN.1BER
Encoding
The DLMS objects require a special encoding of data, which is called ASN.1BER coding. The format of
ASN.1BER coding looks like this:
Tag_Int, Value
Whenever, data is provided as constant, it has to be formatted in the same form as above. There is no
need to put the starting tag as it is taken from the Attribute List Table. But instead, you need to put the
total size of the definition string.
As an example, assume that one has to record the following data in your meter after every 15 minutes.
Parameter Datatype
Date and Time String
Current R Phase Unsigned Long
Current Y Phase Unsigned Long
Current B Phase Unsigned Long
Voltage R Phase Unsigned Integer
Voltage Y Phase Unsigned Integer
Voltage B Phase Unsigned Integer
Active Energy Unsigned Long
Reactive Energy - Lag Unsigned Long
Reactive Energy Lead Unsigned Long
Apparent Energy Unsigned Long
Assume that all currents are 10 Amps, Voltages 240 V and Energies as 100 KWh, then a single entry has
to be encoded in ASN.1 as follows:
TAG_STRUCTURE, 0x0b,
TAG_OCTET_STRING, 12, ITEM_TAG_DATETIME_LP, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, /* Time
& Date */
TAG_UINT32, 0x00,0x00,0x03,0xe8 /* Ir =10.00 A*/
TAG_UINT32, 0x00,0x00,0x03,0xe8 /* Iy =10.00 A*/
TAG_UINT32, 0x00,0x00,0x03,0xe8 /* Ib =10.00A */
TAG_UINT16, 0x09,0x60, /* Vr=240.0V */
TAG_UINT16 ,0x09,0x60, /* Vy=240.0V */
TAG_UINT16, 0x09,0x60, /* Vb=240.0V */
TAG_UINT32, 0x00,0x00,0x27,0x10 /* Active Energy =100.00KWh*/
TAG_UINT320x00,0x00,0x27,0x10 /* Reactive Energy Lag=100.00KVarh */
TAG_UINT32, 0x00,0x00,0x27,0x10 /* Reactive Energy Lead=100.00KVarh */
TAG_UINT32, 0x00,0x00,0x27,0x10 /* Apparent Energy = 100KVAh*/
The ASN.1 encoding above indicates that it is a structure with 11 elements. The first element is an octet
string with 12 characters, the second element is a 32-bit unsigned long and so on. When the above data is
recorded after every 15 minutes for 10 days, there will be 960 entries of the data exemplified above. For
compacting the space required for such data, and for handling multiple entries easily, a template-based
mechanism was put into place. The following is an example of the template for the above data:
In the above template, INJECT32 is a macro, which converts a single long number into byte-wise
characters in the same endianness as per DLMS requirement. In place of the actual data, a user defined
lable is input ( ITEM_TAG_DATETIME above). This label is used as a pointer for the function
Get_Numeric_Item, Get_String_Item, Set_Numeric_Item & Set_String_Item (defined in file
app_server_msgs.c), which is explained in the subsequent section. Each separate parameter has to have
a unique label. Once the template is defined, the next step is to write the call-back function. When the call
back function is called from the library, it carries the Selective Access information in case the DLMS
client wants to read the selective data only. The Selective Access is not supported in case of the SET
command. This data is passed in the following library variables.
In case of Selective access by entry:
SA_From_Entry: This carries the number of the first entry, which the client wants to read.
SA_To_Entry: This carries the number of the last entry.
In case of selective access by range:
SA_Range[0] : This will have the date and time of the first entry, which the client wants to read.
SA_Range[1] : This will have the date and time of the last entry.
Based on the above selective access information and the predefined template, you need to initialize the
following msg_info data structure to pass the relevant information to the library. The following structure is
defined in the library, to which, you have to pass the values.
typedef struct
{
const uint8_t *template;
uint16_t sz_template;
uint16_t start_entry;
uint16_t num_entries;
uint16_t entries_remaining;
const uint16_t *column_szs;
} Msg_Info;
msg_info.template : This element points to the template defined for that particular object.
msg_info.sz_template: This is the size of the template that is explained earlier.
msg_info.start_entry: As there can be a number of entries that have to be transferred, this value
indicates the number of the entry from where to start.
msg_info.num_entries: This element has to be filled with the total number of entries that has to be
transferred.
msg_info.entries_remaining: This element is automatically updated in the library, which tells how many
entries data has been transferred.
msg_info.column_szs: This is an array of cumulative count of bytes in each column of the template.
This parameter is used by the library in case the client needs to apply selective access.
Once you have completed the above steps, then the last step is to insert some code in the function
get_numeric_item(), get_string_item(), set_numeric_item() or set_string_item() in the file
app_server_msgs.c.
These functions are called by the library when it is decoding the profile template and encounters
STUFF_DATA tag. In case of GET command, depending upon the data type of the parameter, either of
get_numeric item() or get_string_item() are called with the corresponding item tag as argument. In these
functions, you have to add a switch case statement and provide the required data into the val variable.
In case of the SET command, again depending upon the data type of the parameter, either of
set_numeric_item() or set_string_item will be called with the data pointer from where data have to be
copied as an argument. The example below explains this in a better way.
void set_numeric_item(uint8_t item, uint8_t *data, uint16_t len)
{
switch(item)
{
________________________
________________________
case ITEM_TAG_DAY_PROFILE_SCRIPT_ID1:
entry_no = msg_info.start_entry+(msg_info.num_entries-msg_info.entries_remaining);
EEPROM_Write(ADDRESS_DAY_ID+entry_no,data)
break;
__________________________
__________________________
}
}
Method Access
Method Function Pointer
Number Rights
Method Number: The first entry in this table indicates the serial number of the method of this class.
Access Rights: The second column provides the access rights for this method depending upon the
type of association that is established between DLMS server and client. The syntax for providing the
access rights is PCXY_MRXY_USXY, where PC, MR, US correspond to the type of association X is
R if a read access is available and _ if no read access is available. Similarly, Y is W if a write access is
available and _ if no write access is available.
Method Function Pointer: This value gives a pointer to the C function that you need to execute in the
meter software. The functions have to be written with predefined arguments. Below is the syntax for
the function:
void Obj_Instant_Profile_reset(uint8_t *data,uint16_t data_len,uint8_t
*response,uint16_t *response_len)
{
// Your code comes here.
}
In the above function definition, data is the pointer to the data (if any) sent by the DLMS Client as
argument for this method, data_len carries the length of this data, response is the data that is to be
returned to the client and response_len is the length of this returned data.
12 Handling Associations
The DLMS library is configured to handle three associations. You do not have access to change the
properties of these associations, except the passwords. Table 1 describes the properties of these
associations:
14 Reference
DLMS UA 1000-1 ed.11, 2013 Blue book, COSEM Identification System and Interface Classes
Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265
Copyright 2013, Texas Instruments Incorporated