DLMS/COSEM Server Object Library

User Manual
Version 3.0.0
JUNE 2011

Kalki Communication Technologies Limited

DLMS/COSEM Server Object Library

User Manual
Version 3.0.0
JUNE 2011

Kalki Communication Technologies Limited

Anantha Pushpa Building,#147, 5th Main road,HSR lay Out 7th sector, Bangalore 560 102, India. Ph: 91 80 25721263/64 Web Site: www.kalkitech.com

Disclaimer
Copyright 2011 KALKITECH Kalki Communication Technologies assumes no responsibility for any inaccuracies that may be contained in this document. Kalki Communication Technologies makes no commitment to update or keep current the information contained in this manual. Kalki Communication Technologies reserves the right to make improvements to this document and/or product at any time and without notice.

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

Document Release Note

The details of the document is given as follows. Document Release Number Document Release Date 3.0.0 06/17/11 Table 1: Document Details

Created By Reviewed By Project Name

Aneesh Jose Pradeep Joseph DLMS Server Object Library Table 2: Document Authoring Details

Version Number 3.0.0

Confidential

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

Document Revision History

The document revision history is given as follows. Ver. No. 1.0.0 2.1.2 Revision Date Revision Description 12 Mar 2007 13 Jun 2007 Initial version Reason for change Pages affected All 1 - 13

First release of DLMS To add new features server Cosem wrapper for IPv4 networks Added new interface classes Added new interface classes To add new features To add new features

2.1.3.2 20 Feb 2008 2.2.3 3.0.0 26 Nov 2009 10 Nov 2010

1 - 15 1 - 15 All

Added multi channel To add new features support, Porting to new document template Changes for library version Modifications for library version of server

3.0.0a

17 Jun 2011

All

Table 3: Document Revision History

Confidential

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

About the Document

Purpose
This manual serves as a guide for using DLMS/COSEM Server Object Library for microchip PIC MCUs. This manual familiarizes the user with the object library and provides a stepbystep instruction on how to use the library in the user application.

Intended Audience
This User's Guide is intended for application developers

Organization of the Document

This document is organized in to three parts as follows: Chapter Chapter 1 Chapter 2 Chapter 3 Chapter Name Introduction Getting Started Implementation procedure Test Configuration Implement Data Interface Test Complete Server Implementation Description The chapter provides an introduction to the DLMS Server Library This chapter provides instructions on getting started with the DLMS Server Library This chapter provides instructions for the Implementation procedure This chapter provides instructions test the configuration This chapter provides instructions to implement data interface This chapter provides instructions to test complete server implementation

Chapter 4 Chapter 5 Chapter 6

Table 4: Organization of the document

Confidential

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

Documentation Conventions
The following table shows the conventions used in the document: Sl.No 1 2 3 Item Field Name, Screen Name and Button Note Each step in the task is numbered Conventions Used Arial, Bold face font Note: Identified by numbered list 1. First Step 2. Second Step Table 5: Document Conventions

Confidential

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

List of Abbreviations
The following table shows the acronyms/abbreviations used in this document: Acronyms/Abbreviations COSEM DLMS GPRS IEC IP LN OBIS OEM PDU PSTN SAP SMTP SN Description Companion Specification for Energy Metering Device Language Message Specification General Packet Radio Service International Electro-technical Commission Internet Protocol Logical Name Object Identification System Original Equipment Manufacturer Protocol Data Unit Public Switched Telephone Network Service Access Point Simple Mail Transfer Protocol Short Name Table 6: List of abbreviations

Confidential

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

Contents
1. Introduction................................................................................................................................................11 1.1. Protocol Stack Overview..............................................................................................................11 1.2. Sample Implementation................................................................................................................12 1.3. Key Features................................................................................................................................12 2. Getting Started..........................................................................................................................................13 2.1. Meter Data....................................................................................................................................13 2.2. DLMS Protocol features...............................................................................................................13 3. Implementation Procedure........................................................................................................................14 3.1. Overview......................................................................................................................................14 3.2. DLMS Server API Reference.......................................................................................................14 3.3. Build the DLMS Server in your application...................................................................................16 3.4. Implement Platform Interface.......................................................................................................17 3.5. Test Platform implementation.......................................................................................................18 3.6. Edit Configuration Interface..........................................................................................................18 4. Test Configuration.....................................................................................................................................23 5. Implement Data Interface..........................................................................................................................23 6. Test Complete Server Implementation......................................................................................................25

Confidential

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

Index of Tables
Table 1: Document Details...............................................................................................................................4 Table 2: Document Authoring Details...............................................................................................................4 Table 3: Document Revision History................................................................................................................5 Table 4: Organization of the document............................................................................................................6 Table 5: Document Conventions......................................................................................................................7 Table 6: List of abbreviations............................................................................................................................8

Confidential

10

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

1 Introduction
Introduction has the following topics:

Overview of the protocol stack. Sample implementation. Key features.

1.1 Protocol Stack Overview

The DLMS/COSEM Server Object Library provides meter manufacturers and other OEMs a complete implementation of the 62056 COSEM/HDLC protocol stack to enable DLMS support in their meters and devices using Microchip PIC MCUs. The stack is based on the following specifications

IEC-62056-42: Physical Layer IEC-62056-46: HDLC Data Link Layer IEC-62056-53: COSEM Application Layer IEC-62056-61: OBIS (Object Identification System) IEC-62056-62: Interface Classes

1.1.1 Platform Interface

The platform interface is used by the library to perform functions that can be only be provided in a platform-specific manner. These functions include millisecond timers and communication port handling. During runtime, the library makes calls to these functions and expects them to perform the documented purpose of the function. The OEM must implement these functions.

1.1.2 Configuration interface

The DLMS Object Library should be configured properly according to the requirements of the OEM. The configuration includes the following

Complete list of data to be served by the meter (with their OBIS codes, short names, interface classes etc.) Division of access to these data objects into multiple association views. The same data object may be accessed under different association views with different access privileges Configuration of the associations Static information about the data objects (information that does not change at runtime, for eg. the scaler and unit of a Register object) Capture-object lists for Profile objects Inter layer buffer sizes

Confidential

11

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

The above mentioned parameters are configured by editing two header files (obis.h and picconfig.h). Note that all the configuration parameters must be assigned properly before compilation.

1.1.3 Data interface

Once the application is compiled after platform and configuration interfaces are implemented, it will run and serve data to a DLMS Client. Without any further configuration, the server application can provide all the static information that is available for each object in the meter,. However when requested for dynamic values (for eg. the value attribute of a Register object), it will return zeros or invalid data. To provide the actual data from the meter or device, the OEM must implement the functions in the data interface.

1.2 Sample Implementation

The library ships with a sample application that is already configured with many objects from supported interface classes. It also has a a number of association views that exercise the LN and SN referencing with different levels of security. This sample also implements the platform interface, providing sample implementations of the communication port routines. The OEM can use this sample configuration as a base for further development.

1.3 Key Features

DLMS UA attested stack Support for IEC 62056-21 Mode-E Implementation requires no detailed protocol knowledge Memory constraints for embedded system are taken care of

Confidential

12

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

2 Getting Started
The getting started section provides information on the tasks that are to be performed in-order to use the library. The following topics are covered:

Meter Data DLMS Protocol features

2.1 Meter Data

OEM must build a master list of meter data and map these to the standard DLMS interface classes and OBIS codes. Examine the header file obis.h closely. The AllOBIS_List[ ] array contains the default configuration and models various objects of several interface classes. For example, energy values can be modeled by a Data (IC 1), Register (IC 3) or an Extended Register (IC 4) class object. If you only require the value you can use a Data object. If you also want to model the scaler and unit of the value, you must use a Register object. Additionally, if you require to store the times tamp of the Energy-Value you can use an Extended Register object. A full description of the interface classes is beyond the scope of this document. Please refer to IEC-62056-62 for further details. OBIS codes for each object follow a standard specification as described in IEC-62056-61. Note that the library does not verify the OBIS codes against the standard and accepts all configured OBIS. If you are planning to use SN (Short Name) referencing, you must also map each object to a short base name (2 bytes) which will be the attribute address of the first attribute of the object. The library calculate the base-names of all other attributes of the object automatically.

2.2 DLMS Protocol features

OEM must decide if they want to use LN (Logical Name) or SN (Short Name) referencing or both OEM must decide which subset of the interface classes they want to support. For example if the master-list of meter data objects does not contain any Extended Register objects, they can exclude this interface class completely. This can save considerable code-space.

Confidential

13

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

3 Implementation Procedure
The chapter on Implementation Procedure covers the following topics:

Overview of the implementation procedure. DLMS server API reference. Build the DLMS server in your application. Implement platform interface. Test platform implementation. Edit configuration interface.

3.1 Overview
For implementing DLMS Server, the user must edit the configuration settings, platform specific functions and data interface functions.

3.2 DLMS Server API Reference

The following APIs are available with DLMS object library. int initServer(unsigned short intBufSz, unsigned short apduRcv, unsigned short apduSnd, unsigned short infoSzSnd, unsigned short infoSzRcv, unsigned char winSzSnd, unsigned char winSzRcv, unsigned char noOfChannels, char *timerName unsigned char maxHlsChallengeLen, char *hlsKey) This function initialize the DLMS server library with the inter layer buffer sizes and a bunch of other parameters that are common for all the server channels. The arguments for this function are as follows intBufSz This is the data interface buffer size, that is the maximum length of data that can be exchanged between COSEM application layer and data interface at a time. This value should be slightly lesser than the maximum APDU size receive and maximum APDU size send. apduRcv This is the size of COSEM application layer input buffer. Typical value will be 128 bytes. apduSnd This is the size of COSEM application layer output buffer. Typical value will be 150 bytes or higher. infoSzSnd - This is the maximum length of send HDLC information field. infoSzRcv - This is the maximum length of receive HDLC information field. winSzSnd Window size send is the maximum number of consecutive HDLC frames that can be sent. Range of this parameter is from 1 to 7

Confidential

14

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

winSzRcv Window size receive is the maximum number of consecutive HDLC frames that can be received. Range of this parameter is from 1 to 7 noOfChannels This is the total number of channels supported by the meter. timerName This is the timer name that will be passed on to the init_timer() function. Library won't process this string in any manner. maxHlsChallengeLen - Maximum HLS challenge length hlsKey High level security key

char hdlcInit( unsigned char channelNo, char *portName, long baud, unsigned short inactivityTimeout, unsigned short interOctetTimeout, unsigned short deviceAddress, char enableModeE, long modeEopeningBaud, char *modeEidentString, char *modeExxx, char *modeEdevAddr) This function initialize the HDLC layer. This function should be called once for each channel used. The arguments of this function are as follows. channelNo The channel number which uniquely identifies the channel. Channel number should start from 0 for the first channel. baud - This name is used to identify the communication port used by the channel. The library won't process this string in any manner, instead it will be passed to the port_open() function. inactivityTimeout - This is the baud rate of the channel to be opened. interOctetTimeout - HDLC inactivity timeout in seconds. interOctetTimeout - HDLC inter-octet timeout in milliseconds. The range of this argument is from 20 to 6000. deviceAddress - This is the HDLC physical device address of the meter. enableModeE - This is to indicate that whether mode-E support is enabled for the channel. If this argument is 0, mode-E support will be disabled for the channel. If this is 1, mode-E will be enabled in the channel. modeEopeningBaud - This is the mode-E opening baud rate. This is processed only when mode-E support is enabled. modeEidentString - This is manufacturer specific, and can have 16 printable characters except / and !. modeExxx This is manufacturer specific, and should have three upper case characters. ModeEdevAddr This is the mode-E device address. This can be a string of maximum size 16 charecters.

Confidential

15

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

void hdlcProcess( KDEFS_UCHAR channelNo ) This routine performs the HDLC layer functions of the DLMS server. This should be called from the main processing loop within the application. The only argument to this function is channel number which uniquely identifies the communication channel.

void cosemInit( KDEFS_UCHAR channelNo) This function initialize the COSEM layer. This function should be once called for each channel used. The only argument to this function is channel number which uniquely identifies the communication channel.

void cosemProcess( KDEFS_UCHAR channelNo ) This routine performs the COSEM layer functions of the DLMS server. This should be called from the main processing loop within the application. The only argument to this function is channel number which uniquely identifies the communication channel.

void phys_read( KDEFS_UCHAR channelNo ) This function performs a read operation from the physical channel. This will invoke the function port_read() and copy the received data to the HDLC input buffer. This function can be called from the main processing loop. It can also be called from an interrupt handler function if the reading scheme is interrupt based.

3.3 Build the DLMS Server in your application

The first step in implementation is to write the main function from which DLMS API's are called. The library supports multiple channels. Write a main() method (task entry point) and call the DLMS library functions as shown in the sample below. #include "dlms.h" void main(void) /* Entry point function */ { int i, maxChannels = 1; initServer(96,128,150,96,96,1,1,maxChannels,"timer1",16, "wwwwwwwwwwwwwwww","abcdefghijklmnop" ); for( i=0; i < maxChannels; i++ ) { hdlcInit(i,"uartname",9600,120,1000,100,0,0,0,0,0); cosemInit(i); } /*Infinite while Loop*/ while(1) { for( i = 0; i < maxChannels; i++ ) { hdlcProcess(i); cosemProcess(i); } } return 0;

Confidential

16

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

3.4 Implement Platform Interface

The next step is to implement the functions in the platform interface. The functions are declared in picfunc.h and defined with empty bodies in pincfunc.c. void *port_open (char *portName, long baudRate, unsigned char parity, unsigned char stopBits) This function is called by the library when it requires open a communication channel. This function should open a communication port specified by the argument portName with the the specified baud rate, parity and stopbits. The value for the argument parity can be 0 no parity, 1-odd parity, 2-even parity. The function should return a handle(void pointer) to the opened port. The handle shall be passed as an argument for subsequent calls that access the port.

char

port_read (void *portHandle, unsigned char *buf_p, unsigned char length)

This function is called by the library when it requires to read bytes from the communication channel. The argument portHandle uniquely identifies the port, and is the pointer value returned by port_open() function. Maximum bytes it can read is specified by the argument length. The function should return the number of bytes read. It can be any number less than or equal to the argument length.

void port_write (void *portHandle, unsigned char *buf_p, unsigned short length) This function is called by the library when it requires to transmit data to the communication port. The argument portHandle uniquely identifies the port, and is the pointer value returned by port_open() function. The data to be transmitted is stored in buf_p, and the length of data to be transmitted is provided in the argument length.

void port_setbaud (void *portHandle, long baudRate) This function should set the baud rate of the communication port specified by the portHandle to the value specified in argument baudrate.

void port_setparity_bytesize (void *portHandle, unsigned char parity, unsigned char dataBits) This function should set the parity and data bits of the communication port specified by the port handle to the values specified in the arguments. The value for the argument parity can be 0 no parity, 1-odd parity, 2-even parity.

void init_timer ( char *timerName); If any sort of timer initialization is required, it can be done in this function. The argument timerName is the same as the one which is passed to initServer() function.

Confidential

17

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

void get_time (void *timer_p) This function must return a timer value with millisecond precision, which can be of any form (even a user-defined struct) with size not exceeding 10 bytes. User must fill the location pointed by timer_p with the timer value. The DLMS library will not process the value stored in this pointer in any way. It simply passes back the pointer to the user-code in is_timer_expired() function as the initial value to be compared against the current value.

int is_timer_expired (void *initial_val, unsigned long timeout) This function is called by the library to check for expiry of timeouts. It sends as an argument the same pointer that was filled-in in the get_time() function and also sends a timeout value in milliseconds. This function must compare the present time to the initial value provided and check whether the provided timeout has elapsed. The function should return 1 if the timer has expired and 0 if not.

3.5 Test Platform implementation

At this stage the application contains a default configuration and a fully-implemented platform-interface. It is now possible to test the DLMS server with a DLMS client program or DLMS/COSEM OPC server. The default configuration contains multiple associations including the standard Public-Client association. This association is defined by a client-id of 16 (0x10). This association is set to use logical name referencing and uses lowest level of security (no password). Using these details OEM can establish a link-layer connection and associate to the server (AARQ/AARE exchange). OEM can then proceed to read/write parameters to the server. A useful test at this stage is to read the object-list of the association. The default configuration configures all objects in the meter with full access to this association. Please note however that several attributes of DLMS/COSEM objects are not writable by default. For example the LN (Logical Name) attribute of every object is not writable. Even though the association grants full read-write access, an attempt to write to this value will return a READ_WRITE_DENIED error.

3.6 Edit Configuration Interface

At this stage, the server implementation has been running with a default configuration. OEM must edit the configuration in the header files obis.h and picconfig.h to specify the actual configuration of the meter. All the objects supported by the meter and the related configuration are to be specified in the obis.h. Pre-compiler directives related to configuration settings and communication should be specified in picconfig.h. Variables and precompiler directives to be modified are as follows.

3.6.1 AllOBIS_List[ ]
This is an array defined in obis.h holding master-list of all meter data objects. Each entry in this list fully qualifies a meter data object by specifying its OBIS code, SN, IC number, IC version, number of historical stored values (for past billing periods) for that object. This table must be filled in ascending order of OBIS codes. This is because the library uses an optimized binary search to locate an OBIS code when it receives a request. Care must also be taken in assigning short names to ensure that there is no overlap across objects. The SN of an object is the SN of its first attribute. SNs of successive attributes are obtained by adding 8 to the previous attributes SN. Confidential
18

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

However the SNs of methods are not always sequential. Please refer to the IEC-62056-61 specification for more details. Other entries in the list are as follows. Table Index this parameter identifies the index of a record in another IC specific table which contains static-information for that object. For example, if a Register (IC 3) object has a tableIndex value of 6, this means that the static information (data type of the value, length of the value, the values scaler and unit) of that Register is specified in the 7th row (array index 6) of the IC03Register_List[ ] array. Access Privileges - A notable parameter in this master-table is a pointer to an array of access-privileges to access this object for each configured association. For example if you have configured 6 associations, this array will contain 6 unsigned longs. The first ulong will contain the access-privileges for this object in the first association. A value of zero means that object is not included in the object-list of that association. Access privileges are bit-wise encoded inside the unsigned long. Access to each attribute of the object is encoded in 2 bits 00 No access 01 Read access 10 Write access 11 Read-Write access Access to each method of the object is encoded in 1 bit 0 No access 1 Execute access Accesses to all the attributes and methods of an object are encoded in a single unsigned long. The access to the first attribute is encoded in the least-significant 2 bits, the next attribute in the next 2 bits going upwards. When all attributes are accounted for, method accesses are added as 1 bit each. For example a Register object has 3 attributes and 1 method. If you wish to specify the following accessrights Attr 1: Logical Name Attr 2: Value Attr 3: Scaler-Unit Meth 1: Reset Read access 01 Read-Write access 11 Read access 01 Execute access 1

The access-rights unsigned long will contain the binary value 1011101 = 0x5D The same object can have different access-rights in different associations. It can even be excluded from an associations object-list by specifying a value of zero for the access-rights.

3.6.2 IC01Data_List
This array defined in obis.h is an IC-specific table that configures the static information for all Data (IC 1) objects in the master-list. OEM must configure the data-type of the Data objects value attribute and optionally its length (if the data-type is non-primitive, for eg. An Octet-String ). Data-types are specified using the DLMS standard ASN1 notations as listed in IEC-62056-53. The data-types are also defined in datastructs.h with named defines for your convenience. Each entry in this table is linked to the object in the master-list via the tableIndex parameter in the Confidential

19

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

master-list

3.6.3 IC03Register_List[ ]
This array defined in obis.h is an IC-specific table that configures the static information for all Register (IC 3) objects in the master-list. The configurable static information for a Register object is similar to the one specified in the Data class above. The additional attribute here is the Scaler and Unit of the Value attribute. OEM must configure the scaler and unit as per the standard values in IEC-62056-62. A value of zero for the scaler means No-Scaling and a value of 255 for the unit means No-Unit (pulse-counts) Each entry in this table is linked to the object in the master-list via the tableIndex parameter in the master-list

3.6.4 IC04XRegister_List[ ]
This array defined in obis.h is an IC-specific table that configures the static information for all ExtendedRegister (IC 4) objects in the master-list. The static information for this object includes all the information for the above Register class and additionally also configures the data-type of the status attribute and optionally its length (for non-primitive data-types) Each entry in this table is linked to the object in the master-list via the tableIndex parameter in the master-list

3.6.5 IC05DRegister_List[ ]
This array defined in obis.h is an IC-specific table that configures the static information for all DemandRegister (IC 5) objects in the master-list. It has the same static-information as for the ExtendedRegister class above. Note that the data-type and length of the Value attribute applies to both the Current-Average-Value as well as the Previous-Average-Value attributes of the object. Each entry in this table is linked to the object in the master-list via the tableIndex parameter in the master-list

3.6.6 IC07Profile_List[ ]
This array defined in obis.h is an IC-specific table that configures the static information for all ProfileGeneric (IC 7) objects in the master-list. A Profile object captures several snapshots of a set of dataobjects at various intervals of time. For example a Load-profile object may capture the values of Active and Reactive energies, say, every 15 minutes. The 15 minutes duration is called the Capture-Period and the set of objects that it captures is called the Capture-Objects. Each profile will have a maximum number of snapshots that it can capture. When the maximum number of entries is exceeded, oldest entry is removed from the buffer. Static Information - This table is used to configure the Capture-Objects, capture-period, sort-method, sort-object (if not default sort-method) and max-entries of the Profiles. This list also must contain the encoded-size of each snapshot. The encoded size of each snapshot (called entry) is the sum of the encoded-sizes of each capture-value (see below) in the capture-objects list. Capture Objects - Capture objects must be configured in a separate table as shown in the default configuration and the address of the cap-objects table must be provided in the profiles static information. OEM must create a separate Capture-Objects table for each Profile object. The default configuration only creates one Capture-Objects table and assigns the same table to all Profiles. A Capture-Objects table configures the OBIS-code, IC number, attribute and data-indices of each

Confidential

20

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

captured object. In addition it also specifies the encoded-size of each value and the ASN1 code for that value. For example if one of the Capture-Objects is an Energy Register and its value is of data-type longunsigned. The DLMS type-code for this is 18 and its length is 2 bytes. The value will be sent as 18xxyy which meas that the encoded size is 3 bytes and the ASN1 code is just 18. The ASN1 code does not require a length since the data-type is a primitive value. Consider another example. If the data-type of a capture-objects value is of type Octet-String of length 5 characters, its value will be sent as 09 05 aa bb cc dd ee. This means the encoded-size of the value is 7 bytes and its ASN1 code is 09,05 Note: The Library does not actually capture the values or store the profile data in any way. The OEM code inside the meter must capture the data and store the different snapshots of data. If the OEM configures the Profiles sort method, it must perform the sorting inside the meter and return the sorted values when requested through the Data Interface.

3.6.7 IC08Clock_List[ ]
This array defined in obis.h is an IC-specific table that configures the static information for all Clock (IC 8) objects in the master-list. The only static attribute of a Clock object is its Clock-base attribute. OEM can configure this value from the standard defines in datastructs.h

3.6.8 IC09ScriptTable_List[ ]
This array defined in obis.h is an IC-specific table that configures the information for all ScriptTable (IC 9) objects in the master-list. A ScriptTable object is used to model Actions that can be triggered from the client. A ScriptTable contains a number of Scripts. Each script is identified by a script-identifier and contains an array of actions. The actions specify which attribute of which object must be written to and with what data, or which method of which object must be executed and with what data. The information of a ScriptTable object contains the number of scripts in the object as well as the number of actions in each script. In addition, if the script actions require a parameter (Write data or Execute argument), this table must list the ASN1 code and length of the parameter.

3.6.9 IC11SpecialDaysTable_List[ ]
This array defined in obis.h is an IC-specific table that configures the information for all SpecialDaysTable (IC 11) objects in the master-list. A SpecialDaysTable object is used to list all special days that can over-ride the default Tariffication schedules as defined in Activity Calendar objects. Each entry in this object defines a special day (date) linked to a Tariffication day-profile ID in the ActivityCalendar. The only information in this object is the number of Special days.

3.6.10 IC20ActivityCalendar_List[ ]
This is an IC-specific table that configures the information for all Activity Calendar (IC 20) objects in the master-list. An Activity Calendar object specifies the meters Tariffication schedule in the forms of Seasons, Weeks and Day profiles. Each Day Profile defines a number of time-switches which indicate the start-times at which specific scripts are activated. The scripts associated with each time-switch refer to ScriptTable objects and specific script-selectors in those objects. A Day Profile is identified by a DayID and is linked to one or Confidential
21

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

more Week-profiles. Each Week-profile is linked to one or more Seasons. The static information of an ActivityCalendar object includes the lengths of the Calendar, Season and week names and the number of Seasons, Weeks, Days and Time-switches in each Day.

3.6.11 IC22SingleActionSchedule_List[ ]
This is an IC-specific table that configures the information for all SingleActionSchedule (IC 22) objects in the master-list. A SingleActionSchedule object is used to trigger specific Scripts (from a ScriptTable object with a script-selector). These scripts typically are not related to Tariffication. The information of this object contains only the number of execution-times for all the scripts.

3.6.12 IC1215Association_List[ ]
This is an IC-specific table that configures the static information for all Associations (IC 12 as well as IC 15) objects in the master-list. This table thus includes both LN and SN associations. The associations are entirely static in nature and include the referencing used (LN or SN), authentication mechanism, the associated Client-ID and Server-ID, the DLMS conformance block (specifies the functions supported in that association) and the DLMS version (always 6, currently) The number of entries in this table must match the array-length of the access-rights array in the masterlist. Note: There should be at least one entry for this list in the configuration. This is because at least one association is required for the client to connect to the server.

3.6.13 IC27PSTNModemConfig_List[ ]
This is an IC-specific table that configures the information for all PSTNModemConfiguration (IC 27) objects in the master-list. A PSTNModemConfiguration object describes the configuration to handle an attached PSTN modem. The information includes the number of modem initialization strings, the length of the request and response init-strings and the maximum length of the modem-profile as described in IEC-62056-62

3.6.14 IC28PSTNAutoAnswer_List[ ]
This is an IC-specific table that configures the information for all PSTNAutoAnswer (IC 28) objects in the master-list. A PSTNAutoAnswer object defines the configuration of the Auto-answer functionality of an attached PSTN modem. The information includes the number of configured listening-windows

3.6.15 Pre-compiler directives

OEM must set the parameters related to configuration and communication in picconfig.h. This configuration file contains various pre-compiler directives, the purpose of which are described in code comments. User is advised to understand each pre-compiler directive and edit the values as required. The config.h header file also contains #SUPPORT_IC_XX macros to conditionally compile-in support for required Interface Classes only. This can be used to exclude unnecessary classes from the code during build and thus can help reduce code size.

Confidential

22

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

4 Test Configuration
At this stage OEM will have a library with their specific configuration and platform interface fully defined. OEM can test the implementation so far by connecting to the server with a client and testing the associations, object-lists and reads of static-information. OEM can also perform reads of dynamic values but will receive junk-bytes (containing whatever is available in buf_p).

5 Implement Data Interface

Data Interface connects the library with Meters data. For each DLMS service that needs access to Meters data, separate Data Interface function is made. The functions are declared in data.h and defined with empty bodies in data.c. OEM must fill these functions, to suitably pass data between Meter and library. In all the data interface functions the buffer buf_p[ ] is used as an intermediate data buffer for exchange of data between the library and meter code. When the library receives a GET or READ request, the meter code must fill data into the buf_p[] and when the library receives a SET or WRITE or ACTION request, the meter code must extract the data from the buf_p[]. Data interface functions are as follows. unsigned char dataGetAttributeValue( unsigned char unsigned OBISCODE unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned *buf_p, short *dataLen, curObis, short curIc, short curAttrId, short curObjIndex, char blockTransfer, short fromEntry, short toEntry, short fromDayAction, short toDayAction )

The function is used when server receives a remote request for Getting Meter data (Note that the original request may be a LN GET request or a SN Read request). Cosem Attribute Descriptor variables in data.c (curObis, curIc, curAttrId) helps OEM to identify the Attribute of Object Instance to be accessed. OEM must write requested Meter data into buf_p[ ] and return the status of operation(success/error code). Please note that only the raw data bytes should be written into buf_p[ ]. The library will automatically encode the type and length information into the response from the configuration interface data. For long data Get (data to be encoded as array), OEM must return the exact number of entries as requested by library using variables fromEntry and toEntry. Note: The mechanism of long data Get using variables fromEntry and toEntry is applicable for all Interface Class attributes except for Passive and Active Day Profile attributes of an Activity Calendar object (Attributes 5 and 9 of an IC: 20 object). For these attributes OEM must always return day ID as first byte following information of timeswitch (day action). Variables fromDayAction and toDayAction informs OEM about the from and to index of day action information that it must pass to library. unsigned char dataSetAttributeValue( unsigned char *buf_p, unsigned short dataLen, OBISCODE curObis, unsigned short curIc, unsigned short curAttrId, Confidential

23

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

unsigned unsigned unsigned unsigned

short curObjIndex, char blockTransfer, short fromEntry, short toEntry )

The function is used when server receives a remote request to Set Meter data. Cosem Attribute Descriptor in data.c (curObis, curIc, curAttrId) helps OEM to identify the Attribute of Object Instance to be written. OEM must Set Meter with data stored buf_p[ ]. If the Attribute to be written stores array data, library will indicate the From and To array index of data in buf_p[ ] using variables fromEntry and toEntry respectively. The function should return a 0 on success or 1 on failure. Once again the buf_p[ ] will contain only the raw data. The encoding information will already have been verified and stripped away by the library. Note: All Interface Class attributes will be written using this interface function except for the Passive and Active Day Profile attributes of an Activity Calendar object (Attributes 5 and 9 of an IC:20 object). For these attributes a separate interface function is defined below, since the set-data contains 2 levels of nesting. For this special function, user does not need to use the fromEntry and toEntry variables. unsigned char dataSetDayProfile( unsigned char *buf_p, unsigned short dataLen, OBISCODE curObis, unsigned short curIc, unsigned short curAttrId, unsigned short curObjIndex, unsigned short fromDayAction, unsigned short toDayAction, unsigned short dayId, unsigned short fromEntry, unsigned short toEntry ) The function is used when server receives a remote request to Set Day Profile Table of Activity Calendar. Cosem Attribute Descriptors in data.c (curObis, curIc, curAttrId) helps OEM to identify the Attribute of Object Instance to be accessed. The Day ID of data to set is indicated by variable dayId. From and To index of Day profile Action contained in the specific Day ID is indicated by variables fromDayAction and toDayAction respectively. The function should return a 0 on success or 1 on failure. Note that if a SET or WRITE request packet contains data for multiple DayProfiles, the library will call this function repeatedly, passing in the values for an individual DayProfile each time unsigned char dataActionAttributeValue( unsigned char *buf_p, unsigned short dataLen, OBISCODE curObis, unsigned short curIc, unsigned short curMethIndex, unsigned short curObjIndex) The function is used when server receives a remote request to Execute Meter method. CosemMethod Descriptors in data.c (curObis, curIc, curMethIndex) helps OEM to identify the Method of Object Instance to be executed. Argument Data (if any) required to execute Method will be contained in buf_p[ ]. OEM must execute specified Method and return a 0 on success or 1 on failure. unsigned char dataCheckPassword( unsigned char *passwd_p, unsigned char len, unsigned short curAssoc ) The function is used to verify Authentication password during Association establishment phase. The password received from remote client is contained in passwd_p[ ], the number of character in the password received is contained in len variable. OEM must check the password and return a 0 if the Confidential
24

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

password is correct or 1 if not. The Association for which the password-check is being performed is indicated by the value of the variable curAssoc. This value indicates the index of the current association in the IC1215Association_List[ ] array.

6 Test Complete Server Implementation

Now the Server Implementation is complete. OEM can test the Server Implementation at Data Link Level, Application Level and Data Interface (Accessing Meter Data) Level.

Confidential

25

DLMS/COSEM Server Object Library

User Manual

Version 3.0.0

Alphabetical Index
API Reference................................................................................................................................................14 Configuration interface...................................................................................................................................11 Data interface.................................................................................................................................................12 DLMS Protocol features.................................................................................................................................13 Edit Configuration Interface............................................................................................................................18 Getting Started...............................................................................................................................................13 Implement Data Interface...............................................................................................................................23 Implement Platform Interface.........................................................................................................................17 Implementation Procedure.............................................................................................................................14 Introduction.....................................................................................................................................................11 Key Features..................................................................................................................................................12 Meter Data.....................................................................................................................................................13 Platform Interface...........................................................................................................................................11 Protocol Stack Overview................................................................................................................................11 Sample Implementation.................................................................................................................................12 Test Configuration..........................................................................................................................................23 Test Platform implementation.........................................................................................................................18

Confidential

26