Dlms Server Ocl User Manual
Dlms Server Ocl User Manual
Dlms Server Ocl User Manual
User Manual
Version 3.0.10
FEBRUARY 2013
Confidential 4
DLMS/COSEM Server Object Library User Manual Version 3.0.10
Ver. Revision Date Revision Description Reason for change Pages affected
No.
1.0.0 12 Mar 2007 Initial version - All
2.1.2 13 Jun 2007 First release of DLMS To add new features 1 - 13
server Cosem wrapper
for IPv4 networks
2.1.3.2 20 Feb 2008 Added new interface To add new features 1 - 15
classes
2.2.3 26 Nov 2009 Added new interface To add new features 1 - 15
classes
3.0.0 10 Nov 2010 Added multi channel To add new features All
support, Porting to new
document template
3.0.2 14 Jul 2011 Changes for library Modifications for library version of All
version server
3.0.5 17 Oct 2011 Increased number of Version change 1–5
objects supported in
the lite version of
library to 50
3.0.9 08/23/12 Bug Fixes Version Change 1-5
3.0.10 18 Feb 2013 Bug Fixes Version change, Added “dayId” to 1 – 5, 23
the arguments of
dataGetAttributeValue function
Confidential 5
DLMS/COSEM Server Object Library User Manual Version 3.0.10
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 step–by–step instruction on how
to use the library in the user application.
Intended Audience
This User's Guide is intended for application developers
Chapter 4 Test Configuration This chapter provides instructions test the configuration
Chapter 5 Implement Data This chapter provides instructions to implement data interface
Interface
Chapter 6 Test Complete Server This chapter provides instructions to test complete server
Implementation implementation
Confidential 6
DLMS/COSEM Server Object Library User Manual Version 3.0.10
Documentation Conventions
The following table shows the conventions used in the document:
Sl.No Item Conventions Used
1 Field Name, Screen Name and Button Arial, Bold face font
2 Note Note:
Confidential 7
DLMS/COSEM Server Object Library User Manual Version 3.0.10
List of Abbreviations
The following table shows the acronyms/abbreviations used in this document:
Acronyms/Abbreviations Description
COSEM Companion Specification for Energy Metering
DLMS Device Language Message Specification
GPRS General Packet Radio Service
IEC International Electro-technical Commission
IP Internet Protocol
LN Logical Name
OBIS Object Identification System
OEM Original Equipment Manufacturer
PDU Protocol Data Unit
PSTN Public Switched Telephone Network
SAP Service Access Point
SMTP Simple Mail Transfer Protocol
SN Short Name
Confidential 8
DLMS/COSEM Server Object Library User Manual Version 3.0.10
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 9
DLMS/COSEM Server Object Library User Manual Version 3.0.10
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.10
1 Introduction
Introduction has the following topics:
▪ Sample implementation.
▪ Key features.
▪ 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
▪ Static information about the data objects (information that does not change at runtime, for eg.
the scaler and unit of a Register object)
Confidential 11
DLMS/COSEM Server Object Library User Manual Version 3.0.10
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.
To provide the actual data from the meter or device, the OEM must implement the functions in the data
interface.
Confidential 12
DLMS/COSEM Server Object Library User Manual Version 3.0.10
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
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.
• 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.10
3 Implementation Procedure
The chapter on Implementation Procedure covers the following topics:
3.1 Overview
For implementing DLMS Server, the user must edit the configuration settings, platform specific
functions and data interface functions.
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.
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.10
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
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.
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.
interOctetTimeout - HDLC inter-octet timeout in milliseconds. The range of this argument is from 20 to
6000.
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.10
Confidential 16
DLMS/COSEM Server Object Library User Manual Version 3.0.10
Confidential 17
DLMS/COSEM Server Object Library User Manual Version 3.0.10
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.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.10
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 value’s scaler and unit)
of that Register is specified in the 7th row (array index 6) of the IC03Register_List[ ] array.
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
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 access-
rights
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 association’s 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 object’s 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.10
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 Profile-
Generic (IC 7) objects in the master-list. A Profile object captures several snapshots of a set of data-
objects 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 profile’s 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.10
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 long-
unsigned. 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-object’s 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 Profile’s 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.
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 meter’s 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.10
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 master-
list.
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.
Confidential 22
DLMS/COSEM Server Object Library User Manual Version 3.0.10
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).
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 *buf_p,
unsigned short *dataLen,
OBISCODE curObis,
unsigned short curIc,
unsigned short curAttrId,
unsigned short curObjIndex,
unsigned char blockTransfer,
unsigned short fromEntry,
unsigned short toEntry,
unsigned short fromDayAction,
unsigned short toDayAction,
unsigned short dayId)
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,
Confidential 23
DLMS/COSEM Server Object Library User Manual Version 3.0.10
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
Confidential 24
DLMS/COSEM Server Object Library User Manual Version 3.0.10
password received is contained in “len” variable. OEM must check the password and return a 0 if the
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.
Confidential 25
DLMS/COSEM Server Object Library User Manual Version 3.0.10
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