The IEC 62056-21 plugin

PRINTED MANUAL

© 2018-2019 AGG Software

IEC 62056-21 plugin

© 2018-2019 AGG Software

All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or
mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the
written permission of the publisher.

Products that are referred to in this document may be either trademarks and/or registered trademarks of the
respective owners. The publisher and the author make no claim to these trademarks.

While every precaution has been taken in the preparation of this document, the publisher and the author assume no
responsibility for errors or omissions, or for damages resulting from the use of information contained in this
document or from the use of programs and source code that may accompany it. In no event shall the publisher and
the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused
directly or indirectly by this document.

Printed: 8/6/2019

Publisher
AGG Software

Production
© 2018-2019 AGG Software
http://www.aggsoft.com
 Contents I

Table of Contents

Part 1 Introduction 1

Part 2 System requirements 1

Part 3 Installing IEC 62056-21 2

Part 4 Glossary 3

Part 5 Requests queue 3

Part 6 Request method 5

Part 7 "Cron" time format 6

Part 8 Response items 7

Part 9 How to configure the logger 8

Part 10 Troubles? 12
1 Possible
...................................................................................................................................
problems 12

© 2018-2019 AGG Software

1 IEC 62056-21 plugin

1 Introduction
The "IEC 62056-21" module is designed to read data from IEC 62056-21 compatible devices through
RS232 or RS485 data interfaces (you need the Opto-to-RS232 converter to read data from optical
probes). The module can poll all listed devices and their measured values at regular intervals. The
received values are passed to the main program, where they can be, for example, logged or written to
a database.

For example, the following devices can send data using this communication protocol:
Satec EM720
Iskra Emeco MT174, MT371, MT372, MT860, MT880
Elgama-Elektronika GAMA 300
DSS1088
Landis+Gyr

The plugin supports modes A, B, C and D. The plugin does not support the mode E. The plugin
executes the "Readout" command to get all values at once.

2 System requirements
The following requirements must be met for "IEC 62056-21" to be installed:

Operating system: Windows 2000 SP4 and above, including both x86 and x64 workstations and
servers. A latest service pack for the corresponding OS is required.
Free disk space: Not less than 5 MB of free disk space is recommended.
Special access requirements: You should log on as a user with Administrator rights in order to
install this module.

The main application (core) must be installed, for example, Advanced Serial Data Logger.

Notes for Microsoft Vista and above:

Since our software saves data to the registry and installs to the Program Files folder, the following
requirements must be met:

1. You need Administrator rights to run and install our software

2. The shortcut icon of our software will be located on the desktop;
3. Windows Vista will ask for your confirmation to continue the installation.

NOTE: You can configure the user account only once in order not to see the above dialog box any
more. Search Google for the solution of this problem.

© 2018-2019 AGG Software

 Installing IEC 62056-21 2

3 Installing IEC 62056-21

1. Close the main application (for example, Advanced Serial Data Logger) if it is running;
2. Copy the program to your hard drive;
3. Run the module installation file with a double click on the file name in Windows Explorer;
4. Follow the instructions of the installation software. Usually, it is enough just to click the "Next"
button several times;
5. Start the main application. The name of the module will appear on the "Modules" tab of the
"Settings" window if it is successfully installed.

If the module is compatible with the program, its name and version will be displayed in the module
list. You can see examples of installed modules on fig.1-2. Some types of modules require additional
configuration. To do it, just select a module from the list and click the "Setup" button next to the list.
The configuration of the module is described below.

You can see some types of modules on the "Log file" tab. To configure such a module, you should
select it from the "File type" list and click the "Advanced" button.

Fig.1. Exam ple of installed m odule

© 2018-2019 AGG Software

3 IEC 62056-21 plugin

4 Glossary
Main program – the main executable of the application. For example: Advanced Serial Data Logger
and asdlog.exe. It allows creating several configuration. Each configuration may use many plugins.

Plug-in - the additional plugin module for the main program. The plugin module extend the
functionality of the main program.

Parser – the plugin module that processes the data flow, singling out data packets from it, and then
variables from data packets. These variables are used in data export modules after that.

Core - see "Main program".

5 Requests queue
For the module to work, you need to make a request list. Each request may be addressed to one or
more devices. All requests in the queue are performed one by one, top to bottom.

To add a new request, click the "Action" button and select "Add a request." A dialog box will open
(Figure 1). Enter a request description, which can include any characters, and click the "OK" button.

Figure 1: Request description entry dialog box

The new request will appear in the request list (Figure 2). Each request includes a few important
options that need to be configured:

· Send requests, otherwise only process responses: Turn on this option if you want the
module to poll devices at regular intervals. This option should be enabled in most cases.
· Device: A unique identifier of a device in the RS485 network. To specify multiple addresses,
use the semicolon as a delimiter (for example, 1;2;3).
· Request timeout (ms): The time to wait for a device’s response after sending a request. If this
time expires, the module will automatically cancel the current request and proceed to the next
request in the queue. If any data are received from that device after the time has expired, they
will be ignored. Response waiting time depends on the network and on the performance of the
devices.
· Change baud rate - the standard states that a device may use two different baud rates while
communicating with a host computer. The baud rate "300" is used for establishing the
connection and for basic information exchange between the device and the computer. Then the
device "proposes" a new baud rate, and the computer have to change to the new baud rate.

© 2018-2019 AGG Software

 Requests queue 4

Despite the fact that the standard defines the first speed as 300, some devices may be
configured in order to use another initial baud rate.

Figure 2: Request queue

Next chapters explain parameters in the "Request method" and "Response items" groups.

© 2018-2019 AGG Software

5 IEC 62056-21 plugin

6 Request method
The plugin can send requests in the following mode:

Once, on program startup - the program will send request once, when the program starts.

Polling - the program will be sending request periodically based on an interval specified. The interval
between requests depends on the network on which master (program) and slave (device) is running. If
the network is slow then time for each request will be larger and vice versa. Because, the program
are executing all requests in the queue one by one, then time between requests depends on the
number of requests in the queue.

At specified time - the time of the day using the 24hr format (e.g. 18:00:00). You may specify
several time points separated by a semicolon (e.g. 11:00:00;11:20:00;11:40:00).

Time using Unix Cron schedule - a flexible schedule format that allows to send requests
periodically or at the specified time. You can find the detailed information about this format and see
examples in the "Cron time format" section. The default is 0 0 12 * * *, which means "every week,
every day at 12:00:00".

Event - the program executes the corresponding request when the plugin receives an external event.
These events can be g generates by our plugins, like "Event generator", "Script execute",
"Expressions".

Fig.3. Request m ethods

If you have added several requests to the queue, you can move them up or down. To do it, select a
request, click the "Action" button, and select an action ("Move up" or "Move down").

You can also click this button to change the description of a request, or to remove a request from the
queue.

You can also perform the same actions by using the context menu that pops up when you right-click
items in the request tree.

© 2018-2019 AGG Software

 "Cron" time format 6

7 "Cron" time format

The cron format is a simple yet powerful way to describe time and operation periodicity. The
traditional (inherited from the Unix world) cron format consists of five fields separated with spaces:

<Second> <Minutes> <Hours> <Month days> <Months> <Weekdays>

Any of the five fields can contain the * (asterisk) character as its value. It stands for the entire range
of possible values. For example, every minute, every hours and so on. You can also use the
"nonstandard" ? character in the first four fields. See its description below.

Any field can contain a list of comma-separated values (for example, 1,3,7) or an interval (subrange)
of values defined by a hyphen (for example, 1-5).

You can use the / character after the asterisk (*) character or after an interval to specify the value
increment. For example, you can use 0-23/2 in the "Hours" field to specify that the operation should
be carried out every two hours (old version analog: 0,2,4,6,8,10,12,14,16,18,20,22). The value */4 in
the "Minutes" field means that the operations must be carried out every four minutes. 1-30/3 is the
same as 1,4,7,10,13,16,19,22,25,28.

You can use three-word abbreviations in the "Months" (Jan, Feb, ... , Dec) and "Weekdays" (Mon,
Tue, ... , Sun) fields instead of numbers.

Examples

Note: the <Second> field equal 0 in all examples

Format Description
***** every minute
59 23 31 12 5 one minute before the end of the year if the last
day in the year is Friday
59 23 31 Dec Fri one minute before the end of the year if the last
day in the year is Friday (one more variant)
45 17 7 6 * every year on the 7th of June at 17:45
0,15,30,45 0,6,12,18 1,15,31 * 1-5 * 00:00, 00:15, 00:30, 00:45, 06:00, 06:15, 06:30,
06:45, 12:00, 12:15, 12:30, 12:45, 18:00, 18:15,
18:30, 18:45, if it is the 1st, 15th or 31st of any
month and only on workdays
*/15 */6 1,15,31 * 1-5 00:00, 00:15, 00:30, 00:45, 06:00, 06:15, 06:30,
06:45, 12:00, 12:15, 12:30, 12:45, 18:00, 18:15,
18:30, 18:45, if it is the 1st, 15th or 31st of any
month and only on workdays (one more variant)
0 12 * * 1-5 (0 12 * * Mon-Fri) at noon on workdays
* * * 1,3,5,7,9,11 * every minute in January, March, May, July,
September and November
1,2,3,5,20-25,30-35,59 23 31 12 * on the last day in the year at 23:01, 23:02, 23:03,
23:05, 23:20, 23:21, 23:22, 23:23, 23:24, 23:25,
23:30, 23:31, 23:32, 23:33, 23:34, 23:35, 23:59

© 2018-2019 AGG Software

7 IEC 62056-21 plugin

0 9 1-7 * 1 on the first Monday of every month at 9 in the

morning
001** at midnight on the 1st of every month
* 0-11 * * every minute till noon
* * * 1,2,3 * every minute in January, February and March
* * * Jan,Feb,Mar * every minute in January, February and March
00*** every day at midnight
00**3 every Wednesday at midnight

You can use the nonstandard "?" character in the first four fields of the cron format. It stands for the
start time, i.e. the question mark will be replaced with the start time during the field processing:
minute for the minute field, hour for the hours field, month day for the month day field and month for
the month field.

For example, if you specify:

??***

the task will be run at the moment of startup and will continue being run at the same time (if the user
does not restart the program again, of course) – the question marks are replaced with the time the
program was started at. For example, if you start the program at 8:25, the questions marks will be
replaced like this:

25 8 * * * *

Here are some more examples:

· ? ? ? ? * - run _only_ at startup;

· ? * * * * - run at startup (for example, at 10:15) and continue being run in exactly one hour: at
11:15, 12:15, 13:15 and so on;
· * ? * * * - run every minute during the startup hour;
· */5 ? * * * - run on the next day (if the cron is not restarted) at the same hour every minute and so
on every day, once in five minutes, during the startup hour.

8 Response items
The "Response items" node contains a list of parsed values.

If this list is empty, the plugin will extract and export all possible values returned by the "Readout"
command. In this case, the name of an exported variable is an OBIS code.

To add more variables to a request, click the "Action" button, and select "Add a response." Before
doing that, you need to select the request from the queue. The new variable will appear in the
"Response items" group (Figure 2).

Each response item has the following options:

© 2018-2019 AGG Software

 Response items 8

· Name: The name of the variable. The value of the variable is passed under that name to the
main program and used in the data export modules. You must give a unique name to each
response item in the request. However, variable names in different requests may coincide.
· OBIS code: You should select the OBIS code of the necessary value. The list contains all
supported codes. Your device may have a limited set of values from this list.

9 How to configure the logger

This module implements data communication based on the IEC 62056-21 protocol through RS232 or
RS485 connections. For this reason, the module can be used with the following products only:

· Advanced Serial Data Logger

· Data Logger Suite

To configure a connection, you need to create a new configuration in the program by clicking the
"Green Plus" button in the main window. In the COM port settings, select the correct COM port
number (Figure 1). The standard COM port parameters are:

Baud rate: 300 (some devices allow configuring the standard baud rate in the device settings)
Data bits: 7
Parity: Even
Stop bits: 1

© 2018-2019 AGG Software

9 IEC 62056-21 plugin

Figure 1: Configuring the COM connection

After that, you can select the recommended data view mode (Figure 2), so that the received values
are displayed in the main window.

© 2018-2019 AGG Software

 How to configure the logger 10

Figure 2: Data display m ode

On the "Query Parse Filter" tab, select "IEC 62056-21" in the "Data query" and "Data parser" fields
(Figure 3). The list of active filter modules and export modules depends on the specific task. Then
click the "Setup" button, and configure the requests queue for your device.

© 2018-2019 AGG Software

11 IEC 62056-21 plugin

\
Figure 3: Selecting m odules

In the result, you should see outgoing requests (yellow) and incoming data (Figure 4). If the device is
offline, you'll see the "Timeout" message in the drop-down box with program messages.

© 2018-2019 AGG Software

 How to configure the logger 12

\
Figure 4: Outgoing and incom ing data

10 Troubles?
10.1 Possible problems
No data for publication/exporting – no data is passed for exporting. Solution: configure the
parser, make sure that one or more variables are declared in the parser.

Error on binding variable with name %s [%s] – the error usually occurs if data does not
correspond to the specified format. For example, the date and time format does not correspond to
the data.

Unable to disconnect from the database [%s] and Unable to connect to a database [%s] – it is
impossible to connect/disconnect to/form the database. You should check the parameters of the
database connection. The analysis of the additional information will help you locate the error.

Database access error [%s]. Stop operations with the database? – the message appears if an error
occurs during an attempt to execute an SQL query if the second variant of reacting to errors is
selected. The message implies a "Yes" or "No" answer. The analysis of the additional information
will help you locate the error.

Unable to verify your SQL script [%s] – the message appears when an attempt to analyze your
SQL query fails. Check if the syntax of your SQL query is correct.

Tested successfully – the message appears if your database connection is successfully tested. It
requires no additional actions.

Database isn't used – the message appears if the module is temporarily disabled (the "Temporarily
disabled" check box is selected) or the database name field is empty. Check the connection
parameters.

© 2018-2019 AGG Software

13 IEC 62056-21 plugin

Database isn't selected - the message appears if the database type is not selected. Check the
connection parameters.

Database: %s – %s contains the database name. The message appears if the database connection
is successful. Usually, you see it when you call the module for the first time. It requires no additional
actions.

Invalid data block length (columns=%d,length=%d) – an internal application error. It means that
the data sent by the parser is in an invalid format. Perhaps, you are using the module incompatible
with the version of the Advanced Serial Data Logger kernel. Update the versions of both the kernel
and the module.

The time of connection is not due yet (%d,%d) – the message appears during an attempt to
connect to the database after the connection to it has been lost and the "Reconnect after" option is
enabled. No additional actions are required.

Invalid procedure call. Bad arguments –an attempt to call the module using invalid parameters.
Perhaps, you are using the module incompatible with the version of the Advanced Serial Data Logger
kernel. Update the versions of both the kernel and the module.

Writing to the database is complete - the message appears if your queue of SQL queries is
successfully executed. It requires no additional actions.

Writing to the database is complete with errors – the message appears if the executing your
queue of SQL queries was interrupted by an error. It requires no additional actions.

Your SQL is empty. Please, specify some SQL text first – the message appears if you do not
enter the text for your SQL query. Check if the options on the "SQL queue" tab are configured
correctly.

Invalid temporary path – the path to the temporary file specified by you does not exist. Enter a
new path in the "Temporary folder" field on the "Errors handling" tab.

%s, %d – will be replaced by additional information.

© 2018-2019 AGG Software