Citect Pty Ltd ABN 88 001 158 854

3 Fitzsimons Lane Gordon 2072 NSW Australia

PO Box 174 Pymble 2073 NSW Australia
Tel 61 2 9496 7300 Fax 61 2 9496 7399 www.citect.com

DNPr Driver
User Information and Design

CitectSCADA DNPr Driver Page 1 of 85

Citect Pty Ltd Driver User Guide

Revision History

Date Comment
3/3/97 As per first Beta (to be extended)
19/4/98
25/5/98
27/05/98 Removed need to specify number of IO points
17/06/98 Mods as per Beta8
07/10/98 Mods for Beta9
25/11/98 As per Beta9
14/04/99 As per Beta10
09/06/99 As per Beta11
20/07/99 As per Release V1.2 (V1.02)
08/11/99 As per Release V1.03
15/02/00 Testing for Remote I/O
02/06/00 Updates due to additional functionality
26/11/02 Updates for V2.0 of driver – redundancy support
09/12/02 Update DnpR to as-built status, and again 12/12/02
08/01/03 Updates for new ini parameters
13/02/03 Add new option to UnitUsurpMode[Default] parameters
25/02/03 Added new INI PollPeriodOffset. For Build 183 on.
14/03/03 Added new mode to UseFeedBackPoll
19/03/03 Added retry to peer coms for 187 build
22/07/03 Updated to as built status for version 192
24/07/03 Megawatt updates. Calculated Variables and new tag types.
Updates to as-built status v3.00.00.003 B1
27/08/03 Adding missing data types
24/10/03 To as built status for version v3.00.01.01 B1, features :

17/11/03 Update to version 3.00.02.06 status

03/12/03 Update to version 3.01.00.006 – DNP changed to DNPR
22/01/04 Update to version 3.01.05.001 – Time updates, new tags
17/05/04 Update to version 3.01.07.xxxx – Mainly event related

CitectSCADA DNPr Driver 18/08/2005 Page 2 of 85

Citect Pty Ltd Driver User Guide

Contents

1. INTRODUCTION 6
1.1 Scope. 6
1.2 Outline. 6
1.3 Terms 7

2. TARGET DEVICE(S) AND PROTOCOL 8

2.1 Introduction 8
2.2 Device Manufacturer 8
2.3 Device Definition 8
2.4 Communications Method 8
2.5 Communications/Hardware Configuration 8
2.5.1 I/O Device Settings 9
2.5.2 Software Setup 9
2.6 Redundancy Features of DNP-R 9
2.6.1 Redundancy level 10
2.6.2 Enabling redundancy 10
2.6.3 Peer Driver Settings 10
2.6.4 Active driver state 10
2.6.5 Off-line Standby 10
2.6.6 User control of redundancy 10
2.6.7 Level of redundancy 11
2.6.8 Port level redundancy 11
2.6.9 Driver cache replication 11
2.6.10 Trend and alarm backfilling 11
2.6.11 Value writes 12
2.6.12 Action on becoming active (usurp) 12
2.6.13 Virtual Units 12
2.6.14 SELECT and OPERATE 12
2.7 Calculated Variables 13
2.7.1 Configuring Calculated Variable CSV Files 13
2.8 Event Polls 14
2.9 Special Requirements 14
2.10 Maximum Request Length 14

3. USER INTERFACE 15
3.1 Introduction 15

CitectSCADA DNPr Driver 18/08/2005 Page 3 of 85

Citect Pty Ltd Driver User Guide

3.2 Driver Name 15

3.3 Boards Form 15
3.4 Ports Form 15
3.5 IO Devices Form 16
3.5.1 Address 16
3.6 Pulldown lists Help 17
3.7 IO Device Variable Types 18
3.7.1 Formats and types 18
3.7.2 driver.dbf Entries 44
3.8 PROTDIR.DBF 45
3.9 Parameters and INI options 45
3.9.1 General Parameters 45
3.9.2 Standard Driver Parameters 45
3.9.3 Driver Specific Parameters 46
3.10 Driver Specific Errors 60
3.11 Driver Error Help 63
3.12 Debug Messages 65
3.12.1 SCADA Debugging 65
3.12.2 Protocol Debugging 66
3.12.3 Peer State Machine Debugging 67
3.12.4 Useful Debugging Tips 67
3.13 Stats Special Counters 68
3.14 Processing of Timestamped Event Data 69
3.14.1 Driver Ordinals 71
3.14.2 DNPR_LOGGER.TXT Format 72
3.15 Hints and Tips 73
3.15.1 DNP Protocol 73
3.15.2 Data Acquisition within DNP 73
3.15.3 Blocking Issues 74
3.15.4 Citect forms and Citect tag databases 76
3.15.5 Startup considerations 76
3.15.6 Useful INI parameters for debugging 76

4. PROTOCOL REQUIREMENTS 77
4.1 Introduction 77
4.2 Initialising the Board 77
4.3 Initialising the Port 77
4.4 Initialising the IO Device 77
4.5 IO Device Online Test 77
4.6 State Flow Description 78
4.7 Message Structure 78

CitectSCADA DNPr Driver 18/08/2005 Page 4 of 85

Citect Pty Ltd Driver User Guide

4.8 Data Format 78

4.9 Check Sum 78
4.10 Error Handling 78
4.11 Special Citect.INI Values 79

5. DESIGN 80
5.1 Active Arbitration 80

6. BASIC TESTING 82
6.1 Introduction 82
6.2 Procedure 82
6.3 Start of Testing 82
6.3.1 Test 1: Basic Communication Test 82
6.3.2 Test 2: Read/Write of each data type 82
6.3.3 Test 3: Break in communication and recovery 82
6.3.4 Test 4: Bulk Test 82
6.3.5 Test 5: Check all types read/write to the correct address 82
6.3.6 Test 6: Test all Parameters and INI options. 82
6.3.7 Test 6: Basic Remote I/O testing. 82
6.4 Faults Found. 82

7. PERFORMANCE TESTINGINTRODUCTION 83
7.1 Calculating the Blocking Constant 83

8. REFERENCES AND CONTACTS 84

8.1 References 84
8.2 Contacts 84

9. QA 85
9.1 Developers Guidelines 85
9.1.1 Accredited Drivers. 85
9.1.2 Independent Drivers. 85
9.2 Accreditation process 85

CitectSCADA DNPr Driver 18/08/2005 Page 5 of 85

Citect Pty Ltd Driver User Guide

1. Introduction

1.1 Scope.

This document follows the development of the new driver. It serves as a functional specification,
design specification and test specification.

1.2 Outline.

The specification is broken down into the following sections:

Section 1 – Introduction.
This section defines the scope of a board driver specification and outlines the items
addressed by the specification.

Section 2 – Physical Communication Method.

The Physical Communication Method section defines the physical communication method
supported, hardware/software suppliers, how the method is setup, any wiring diagrams
involved etc.

Section 3 – Protocol Requirements.

The Protocol Requirements section details the technical considerations required or
incorporated by the driver.

Section 4 – User Interface.

The User Interface section defines how the user will see and setup the driver in Citect.

Section 5 – Basic Testing.

The Basic Testing section defines the items which should be addressed in Basic testing by
the developer.

Section 6 – Performance Testing.

The Performance Testing section is used in full testing of the driver by the Citect Testing
Department of CiT. Once complete, this will provide details on the reliability and stability of
the driver, and point out where the driver needs to be improved.

Section 7 – References and Contacts.

The References and Contacts section should be used as a record of reference materials and
contacts used in developing this driver.

Section 8 – Quality Assurance.

The QA section defines the requirements and procedures for Quality Assurance
Accreditation. It is important you read this if you want your driver integrated into Citect.

CitectSCADA DNPr Driver 18/08/2005 Page 6 of 85

Citect Pty Ltd Driver User Guide

1.3 Terms

Term Definition
Active unit The ONLINE unit which is actively being used for Reads and Writes
Class 0 Data All objects defined in the device
Class 1,2,3 Data Optional classes a data object can be associated with, this is used
to restrict the traffic volume for these polls to specific items.
Event Poll A poll to the device from the driver to return and new events (data
changes) since the last poll (for the class)
Inactive unit The ONLINE unit which is not being used for Reads and Writes.
However, this unit is available for these if the IOServer choses.
Integrity Poll A poll to the device from the driver to return the status of all data
points (for the class),
OFFLINE Offline means the unit cannot talk to the device.
ONLINE Online means we can communicate to the device.
PRIMARY unit The unit is configured to be the primary or master unit for use
STANDBY unit The unit is configured to be the unit to use when the PRIMARY is
not available
USURP When a unit is forced offline to allow its peer driver unit to take over

CitectSCADA DNPr Driver 18/08/2005 Page 7 of 85

Citect Pty Ltd Driver User Guide

2. Target Device(s) and Protocol

2.1 Introduction
This section defines the types of I/O Devices that are targeted by this driver. This specification covers
the scope of version 3.0 of the driver which supports redundancy of driver information (data values,
events) at a per unit level,calculated varaiables, dial up support, and new data types.

It is strongly recommended that the reader study Section 3.15 Hints and Tips, to gain an overview of
the protocol and driver, before reading the remainder of this specification.

It is assumed the reader is familiar with the terms and issues involved with configuring RTU type
devices using the DNP3 protocol. . The term DNP3 is referring to the commonly known protocol name
used in the Citect DNPr driver.

This spec has been updated to functionality in v3.01.07.029 of the driver. Prior to this the driver has
the DNPr driver.

2.2 Device Manufacturer

As this is an open protocol, acting as a pseudo standard for the utility industries, there are numerous
vendors manufacturing devices that support this protocol. Many device manufacturers are also
modifying their existing devices to support the DNP protocol.

2.3 Device Definition

Any device that supports the DNP3 protocol subsets Level 1 or Level 2.
Devices that support DNP Level 3 will be partially supported by the driver.

2.4 Communications Method

The communication methods are RS-232, TCP/IP or UDP. E.g. utilising the standard PC COM port, or
a digiboard, or an Ethernet card.
The RS-232 communications may then be placed through an adaptor of a type determined by the
DNP network that Citect is interfacing with.

2.5 Communications/Hardware Configuration

CitectSCADA DNPr Driver 18/08/2005 Page 8 of 85

Citect Pty Ltd Driver User Guide

serial or IP

Citect
Ethernet

Controllogix with Controllogix with Controllogix with Controllogix with

ENET Module ENET Module ENET Module EthenNet Module

2.5.1 I/O Device Settings

If the device supports multiple protocols, then the device should be set for the DNP protocol.
DNP Subsets Level 1 and Level 2 are supported by this driver.

2.5.2 Software Setup

The device should be configured so that all static data required by Citect is allocated to Class 0.
Allocating points to Class 0 of a device additional to Citect’s requirements will place an extra
communication burden on the system during the regular integrity polling.

Event data corresponding to the above mentioned static data should be assigned to Classes 1,2 or 3.

2.6 Redundancy Features of DNP-R

DNP-R has non standard Citect redundancy features. Typically, the IOServer controls unit
redundancy where the PRIMARY device is used unless it has failed, then the STANDBY unit is used.
In DNP-R you can lock the behaviour so that a STANDBY unit is NOT made inactive (USURPed)
when PRIMARY unit is available again. In DNP-R you can also toggle which unit is active by using
virtual tags.

CitectSCADA DNPr Driver 18/08/2005 Page 9 of 85

Citect Pty Ltd Driver User Guide

2.6.1 Redundancy level

The driver supports single level redundancy only. That is, a unit can only have one peer (redundant)
unit. This unit must live on the other IOServer. A Unit cannot have a redundant unit within the same
IOServer.

2.6.2 Enabling redundancy

Via an CITECT.INI parameter.

2.6.3 Peer Driver Settings

Via CITECT.INI parameters. The default is NO peer redundancy.

2.6.4 Active driver state

The driver only communicates with a device if the unit is in the active state on that driver. Two
redundant drivers arbitrate to ensure that the unit is only active on one peer driver at one time.
A unit becomes active if either:
• Communications between the peer drivers fails.
• No redundant unit is found on the peer driver (does not exist or is disabled).
• Is forced to active by the user writing to one of the new unit control tags.
When a unit is active on a driver, the driver reports the current communications on-line / off-line state
to the Citect I/O server. This is normal driver behaviour. If the unit is not active it appear as off-line to
the Citect I/O server unless transitioning to the active state in which case it reports the peer’s last
known communication state.
Hence the Citect I/O server can only be active if its driver has an active unit as Citect I/O servers use
the unit on-line state to arbitrate which is active.

2.6.5 Off-line Standby

If the unit is not active on a driver then that driver does not communicate with the device. If not active
it does not send any DNP3 frames to the device and does not process any frames received from the
device.

2.6.6 User control of redundancy

The user can control on which driver (I/O server) a unit is active by the following special tags:
Unit<n>.RequestUnitActive.Primary
Unit<n>.RequestUnitActive.Standby
Writing a 1 to the a primary request tag (Unit<n>.RequestUnitActive.Primary) causes the unit
to be active on the driver on the primary I/O server. Writing 0 causes the unit to be active on the
driver on the standby I/O server.
Writing a 1 to the a standby request tag (Unit<n>.RequestUnitActive.Standby) causes the unit
to be active on the driver on the standby I/O server. Writing 0 causes the unit to be active on the
driver on the primary I/O server.
The request tags can be read at any time and return the value last written to the tag.
The user can monitor on which driver (I/O server) the unit is active by the following tags:
Unit<n>.UnitActiveState.Primary
Unit<n>.UnitActiveState.Standby
If the unit is active on the primary I/O server driver then the Primary tags return 1 and the Standby
tags return 0. If the unit is active on the standby I/O server driver then the standby tags return 1 and
the primary tags return 0.
v3.01.05.01 introduced two more addresses to identfy the Port's online status for diagnostics.
Unit<n>.UnitPortState.Primary
Unit<n>.UnitPortState.Standby
This online status is the TRUE online status. This is important when using ExclusiveAccess mode for
Ports. Please note, the Port reported is the one which matches your tag, as you can in you wish have
units on one port being PRIMARY, STANDBY, PRIMARY etc.

CitectSCADA DNPr Driver 18/08/2005 Page 10 of 85

Citect Pty Ltd Driver User Guide

2.6.7 Level of redundancy

The driver natively provides unit level redundancy for I/O server failure. The unit control tags also
allow the user to control on which I/O server the driver unit is active.
User application can control cluster level redundancy (failure of a critical unit requiring usurp of one or
more other units) using the unit control tags.

2.6.8 Port level redundancy

Normal Citect Port control is to open the port at startup and close it at shutdown (when a Port is not
used in a scheduled device or dialup context) . Thus if the RTU supports multiple IP connections, it
will normally get a connection from the primary AND secondary port (normal Citect redundancy). This
may be an issue for your RTU. A new mode called ExclusiveAccess mode was introduced into the
series 3.1.7.x driver which can resolve this issue for you.

Exclusive Port Access - When connecting to devices like terminal servers, which only support one
connection at a time, port control is needed. An INI setting has been provided to sets a Ports mode to
"ExclusiveAccess". In this mode when any unit on a Port is Usurped from being active to being
inactive, the Port connection is dropped. This then allows the Port on the other server access to the
device(s) and for units on the other side to become active.

Thus when using ExclusiveAccess mode, ports on BOTH sides need to have the INI setting set.

Also in exclusive mode, the virtual unit on the PORT follows the active port. The virtual unit is
essentially following the active unit as the physical port may not be online (e.g. the RTU is offline) .

If possible, any hardware which only allows one connection, should have an inactivity timer set so the
connection is droppped if it is not used. This is to allow access to the unit from another server if the
current connection dies. If the hardware doesn't support this, you may want to consider using the –K
option on the TCPIP driver combined with registry "Keep Alive" changes (see KB article or the TCPIP
help).

2.6.9 Driver cache replication

The driver maintains a database of values received from devices known as the cache. The cache is
updated by both event and static data. When updating this cache with values received from the
device, the active unit replicates these values to the non-active unit on a peer driver over the TCP link
between the peer drivers. In order to send the DNP3 acknowledge to the device AFTER all received
values have been replicated to the peer, use SyncReplicationDefault and SyncReplication INI
parameters. This behaviour is preferable (but not default) as it guarantees that no data will be lost in
case the active server dies in the instant straight after it acknowledges the transaction to the RTU but
before the values are replicated to the peer. Also, the DNP3 acknowledge will be sent straight away
on peer TCP link failure.
On cold start-up, if there is a running peer driver, the cache is synchronised from the running peer’s
cache prior to the unit, on the starting driver, being allowed to become active. If no peer driver is
found, or there is no redundant unit, the cache is cleared.
The cache value replication throughput is faster than 100 values per second provided that the
underlying Windows operating system and TCP network does not introduce delays. This rate can be
expected on a reliable 10Mbit network that is not congested.
There is no disk file image of the driver cache. On cold start after a total system shutdown (shutdown
of both peer drivers) the cache is empty.

2.6.10 Trend and alarm backfilling

The trend and alarm backfilling use event queues that hold events until they are back filled into the
Citect trend and alarm systems. The queue of events waiting to be processed for backfilling will be
replicated between the drivers using the same TCP communications link that the cache replication
uses.
The event queues in peer drivers are kept synchronised in the same manner as the driver cache is
kept synchronised. That is, the image is copied on unit start-up, if there is a peer, and is kept
synchronised by replication on queue state change.

CitectSCADA DNPr Driver 18/08/2005 Page 11 of 85

Citect Pty Ltd Driver User Guide

There is no disk file image of the event queue. On cold start after a total system shutdown (shutdown
of both peer drivers) the queue is empty.

2.6.11 Value writes

Tag writes, resulting in a DNP3 transaction such as controls, are not replicated between peer drivers.
The write failed and write pending flags are always zero in an inactive driver’s database. Hence if a
usurp occurs during a control write then the write pending and write failed flags will both be zero
regardless of if the write was completed.

2.6.12 Action on becoming active (usurp)

On a unit becoming active, the driver will be configurable by the user to either:
• Send DNP3 link reset and then integrity poll the device. The polling sequence is reset to start
from the time the unit became active. Or,
• Send DNP3 link reset and then read the RTU time. The polling sequence is not changed and
continues as if nothing happened.
Note: The driver may perform additional DNP3 transactions depending on the states of the
IIN bits. In particular if the IIN restart bit is set the driver will perform and integrity poll. If any
of the class 1, 2, or 3 event flags are set the driver will perform an event poll if the reset bit is
not set.

2.6.13 Virtual Units

To enable control over offline units and to read information about an offline unit, each PORT can have
a virtual unit which never goes offline unless the PORT itself has gone offline. This pretend unit can
be used to read/write information on specific TAGS on other units on the PORT whether these units
are online or offline. This virtual unit has an address of 65534. However, this virtual unit is NOT
available if the PORT is offline (non exclusive mode).

A global virtual unit with address 65535 was introduced in v3.01.05.01 which allows virtual unit
access globally over all channels. i.e. you define a dummy port which can never go offline and add a
virtual unit with a number of 65535. This global access to certain unit info (irrsepective of whether the
channel the units are on is in fact online) relies on unique Device (Unit) Address'es throughout the
site.

2.6.14 SELECT and OPERATE

From version v2.00.00.193, it is possible to have separate select and operate operations for BOs and
AOs. New address types exist. The timeout value for how soon an operate is needed after a select is
set in the RTU. Thus the default parameters MaxOperateDelayDefault & MaxOperateDelay (per unit)
needs to be changed to match this time. This is essential because this time is used to stall any polls
for the unit while a SELECT[_ONLY] is pending. That is because the DNP protocol requires that the
next request after a SELECT[_ONLY] IS an OPERATE.
Note that only ONE SELECT/OPERATE sequence can be done at a time on a single RTU. Multiple
SELECTs cannot be done at once. This is a DNP3 limitation.
An OPERATE cannot be guaranteed if the SELECT[_ONLY] failed or if the OPERATE failed, or due
to bad timing, unsolicted messages are still on the wire. Users should always display the WRITE
PENDING bit and the WRITE FAIL bit to verify correct operation. Typically if you send an OPERATE
after the max. delay time, you will see the WRITE FAIL tag light up.

A SELECT can be manually cancelled by writing to the BO/AOx.CancelSel . This will clear all other
status bits for SELECT/OPERATE.

Forced Integrity or Event polls should NOT be done while a SELECT[_ONLY] command is pending.
The software automatically will delay regular scheduled polling to ensure no poll occurs while a
SELECT[_ONLY] is pending.

CitectSCADA DNPr Driver 18/08/2005 Page 12 of 85

Citect Pty Ltd Driver User Guide

Status bits BO/AOx.<WrtPend,WrtFail,SelPend> are available to provide user feedback on the

SELECT/OPERATE sequence.

NB: The existing SELECT command was effectively a SELECT & OPERATE (automatic). This
remains unchanged. Where you see an address with “.Select.” this is a select & operate. To get a
pure select only, the address needs to be “.SelectOnly.” .

2.7 Calculated Variables

This driver supports the configuration of calculated variables that are triggered from changes in the
drivers back-end cache. These calculations may return results that are placed back into a virtual tag
in the driver cache. The calculations are configured in a CSV file using a defined syntax. Each
calculation can have an associated timestamp and quality. The calculation will inherit the latest
timestamp of all the arguments and the worst quality of all the arguments. For example given the
calculation

RealPower = Voltage x Current x PowerFactor (where Power factor is 0.85)

We would like to perform this calculation every time that the voltage or current changed value. The
following tags would need to be configured in Citect

RealPower : Virtual0.Val.Float
Voltage : AI_3.Val.Float
Current : AI_7.Val.Float

The CSV file would have a row as follows

RealPower, @CalculateRealPower, Voltage, Current, #0.85

A cicode function called CalculateRealPower needs to exist which performs the actual calculation.

When either Voltage or Current acquire a new value from the field the above calculation will be
triggered and the result placed into the RealPower tag.

Engineering scaling note: When the TAG has no engineering scaling defined, then the TAGs raw
value is used in the calculations. If the TAG has engineering scaling values defined, e.g. 0, 32000
equals 0.0 to 120.0 then the scaled value is used in the calculations.

On top of this, meta tags for timestamps and quality can be defined and if the values coming in from
the field provide these the timestamps and quality for RealPower will be derived from these.

2.7.1 Configuring Calculated Variable CSV Files

The configuration file can either be global to a driver or specified per unit. If a configuration file
contains items that are for another driver these items will not trigger. The configuration file syntax is
as follows

! Comments
<VirtualTag>,<@|+><CicodeFunction>,[#][“]<Argument1>[“],…,[#][“]<Argument8>[“]

VirtualTag The name of a valid virtual tag in the driver cache to store the result of the
calculation. If <none> is specified then the cicode function is assumed to not
return a value.

CicodeFunction The name of a valid cicode function to call as the calculation. Must be prefixed
with either a ‘@’ or ‘+’ symbol.

CitectSCADA DNPr Driver 18/08/2005 Page 13 of 85

 The ‘@’ denotes a synchronous cicode function that will be invoked directly.
The ‘+’ denotes an asynchronous cicode function that will be invoked via a
TaskNew() cicode call. The cicode function will only accept up to eight arguments.

ArgumentN Either the name of a valid tag in the driver cache, a constant string or a numeric
constant.
The ‘#’ denotes that the argument is a pure parameter. If placed before a tag
name that exists in the driver cache then this argument will be used in the
calculation but not used as a trigger for the calculation. All numeric values must be
prefixed with ’#’.
All constant strings should be surrounded by quotes, e.g. “My dog has fleas”. It is
valid to have a virtual tag as a trigger or parameter but care must be taken to avoid
recursion.

If a line is prefixed with a ‘!’ then the line will be considered a comment. Any empty lines or lines that
consist of only blank spaces will be ignored. Any leading or trailing blank spaces will be ignored.

The following is a sample configuration file.

!
! Sample Configuration File
!

! Simple synchronous calculation with two triggers

Virtual_Tag_1, @FunctionOne, Real_Tag_1, Real_Tag_2

! Simple asynchronous calculation with three triggers

<none>, +FunctionTwo, Real_Tag_2, Real_Tag_3, Real_Tag_4

! Example of a constant numeric value as an argument

Virtual_Tag_2, @FunctionThree, Virtual_Tag_1,#3.14

! Example of how an argument can be passed in but not used as a trigger

Virtual_Tag_3, @FunctionFour, Real_Tag_5, #Virtual_Tag_3

! Simple synchronous calculation that does not return a result

<none>, @FunctionFive, Real_Tag_6

! Example of using a constant string, Note spaces and commas allowed within quotes
<none>, @Logcurrentvalues, Power_Total, “Current value of Power_total, in MegaWatts”

See section 3.9.3.5 for INI parameter details.

2.8 Event Polls

INI parameters exist to allow event polls to be isolated into classes. The default behaviour is that all
event classes are polled each event poll. The EventPollRatioClassX INIs control the ratio for each class to
the event poll. A value of zero will turn event polls off for that class. A value of 2 would mean that this
event class happens every 2nd poll period.

Note: The integrity poll always asks for the static data for all event classes.

2.9 Special Requirements

Due to the many facets of configuring a redundant DNP system, many tuning Citect.ini parameters
exist. These are discussed in the next chapter “User Interface”.

2.10 Maximum Request Length

256 Bytes.

Digital Reads are always blocked by Citect to a minimum of 8 bits. A DNP device can configure points
in a non continuous fashion, .e.g. Points 0 to 4, then 10 to 14 etc. Thus non-digital Citect requests are
not blocked so as to avoid the situation where a blocked request may also include a point in cache
that is not part of the pre-defined DNP3 group.

CitectSCADA DNPr Driver Page 14 of 85

Citect Pty Ltd Driver User Guide

3. User Interface

3.1 Introduction
This section defines how the user will see the driver. This relates directly to how the Citect forms
need to be filled out and any special INI options. For the kernel, the debug trace messages and the
Stats.Special counters are documented.

3.2 Driver Name

DNPR

3.3 Boards Form

This driver uses standard serial communications (ie communication is achieved via a
standard PC COM port or a dedicated serial board)

Boards form for COMX

Field Default Allowable values
Board Name This field is user defined, and is not used by the driver.
Board Type COMX
Address 0
I/O Port
Interrupt
Special Opt
Comment This field is user defined and is not used by the driver.

Boards form for TCP/IP

Field Default Allowable values

Board Name This field is user defined, and is not used by the driver.
Board Type TCP/IP
Address 0
I/O Port
Interrupt
Special Opt
Comment This field is user defined and is not used by the driver.

3.4 Ports Form

Ports form for COMX

Field Default Allowable values
Port Name This field is user defined and is not used by the driver.
Port number

CitectSCADA DNPr Driver 18/08/2005 Page 15 of 85

Citect Pty Ltd Driver User Guide

Board name Refers to the board previously defined in ‘boards’ form.

Baud rate 9600 2400 – 38400
Data bits 8
Stop bits 1
Parity None
Special Opt Leave this field blank
Comment This field is user defined and is not used by the driver.

Ports form for TCP/IP

Field Default Allowable values
Port Name This field is user defined and is not used by the driver.
Port number
Board name Refers to the board previously defined in ‘boards’ form.
Baud rate Leave this field blank
Data bits Leave this field blank
Stop bits Leave this field blank
Parity Leave this field blank
Special Opt -Iaaa.bbb.ccc.ddd –Pe -U –FC (v2.2.5.0+ TCPIP driver feature)
Comment This field is user defined and is not used by the driver.

Where:
• “aaa.bbb.ccc.ddd” is the RTU’s IP address.
“e” is the port number of the RTU.

-U for use when UDP being used. TCP is the default.

-FC can be used for the global virtual port to host the global virtual unit. FC stands for
Fake Connection so this pretends that the port is connected to keep citect happy. No
real connection is made.

3.5 IO Devices Form

I/O Devices form

Field Default Allowable values
Name This field is user defined, and is not used by the driver.
Number Must be unique. Your redundant unit will use the same number.
Address RTU_address_number citect.ini_section_name
Protocol DNPR
Port name Refers to the port previously defined in ‘ports’ form.
Comment This field is user defined and is not used by the driver.

3.5.1 Address
DNP_Address Device_Group
e.g 128 SITERTU
where
128 The DNP address of this device.
(valid addresses are in the range 0...65,533)
SITERTU Name of the section heading in Citect.ini under which all the
parameters related to SITERTU will be held.

CitectSCADA DNPr Driver 18/08/2005 Page 16 of 85

Citect Pty Ltd Driver User Guide

If no 2nd argument is given, (i.e. SITERTU) the default name of "Unit_x" is used where
x is the IODevice "Number", e.g. "Unit_10"
65534 is reserved for a virtual unit per channel.

Virtual Units

Each Port allows a virtual unit with an IODevice Address of 65534

This allows a pretend unit to come online permanently per port.

What use is this ?

This allows address items like :

Unit10.ForceIntegrityPoll
Unit10.ForceEventPoll

to be used when Unit10 is OFFLINE. When a unit is offline, naturally you can’t
write or read tags. The virtual unit never goes offline so allows you to
read/write to these special TAG types

A global virtual unit is allowed with an IODevice Address of 65535 . Only one of these should
exist of a dummy port which is always online.

3.6 Pulldown lists Help

The following entries should be included in the Citect HELP.DBF spec file.

TYPE DATA FILTER

PROTOCOL DNPR

CitectSCADA DNPr Driver 18/08/2005 Page 17 of 85

 Citect Pty Ltd Driver User Guide

3.7 IO Device Variable Types

3.7.1 Formats and types

3.7.1.1 Monitoring Types

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Binary Input Value Bin.Val DIGITAL R/O. Current state of Binary Input
(This is Bit 7 of Status Byte)

Object 01 Variations
1,2
Object 02 Variations
1,2,3
Binary Input Status Bin.Stat BYTE R/O. Status data related to Value
Bit 7 (State bit) not included – always zero.
Status byte (excluding
state)
Object 01 Variation 2
Object 02 Variations
1,2,3
Binary Input Status Bin.Stat.Online DIGITAL R/O. Bit 0 of Status byte
If Offline, command will not be successful.
Online bit 0=Offline,1=Online
Object 01 Variation 2
Object 02 Variations
1,2,3
Binary Input Status Bin.Stat.Restart DIGITAL R/O. Bit 1 of Status byte
Originating field device has been restarted.
Restart bit 0=normal,1=Restart
Object 01 Variation 2
Object 02 Variations
1,2,3
Binary Input Status Bin.Stat.CommLost DIGITAL R/O. Bit 2 of Status byte
If comms lost, command will not be successful
Communication Lost 0=normal,1=Lost
bit
Object 01 Variation 2
Object 02 Variations
1,2,3
Binary Input Status Bin.Stat.RemForced DIGITAL R/O. Bit 3 of Status byte
Originating field device is in control
Remote Forced Data 0=normal,1=Forced
bit
Object 01 Variation 2
Object 02 Variations
1,2,3
Binary Input Status Bin.Stat.LocalForced DIGITAL R/O. Bit 4 of Status byte

CitectSCADA DNPr Driver 18/08/2005 Page 18 of 85

 Citect Pty Ltd Driver User Guide

Local Forced Data bit This device is in control

0=normal,1=Forced
Object 01 Variation 2
Object 02 Variations
1,2,3
Binary Input Status Bin.Stat.ChatFilter DIGITAL R/O. Bit 5 of Status byte
Low Pass Filter for filtering unwanted transitions
ChatterFilter bit 0=normal,1=Filter on
Object 01 Variation 2
Object 02 Variations
1,2,3
Binary Input Time Bin.Val.TS LONG UTC time when value last changed or when the
value was acquired from the initial integrity poll
Stamp (seconds since
1970)
Binary Input Time Bin.Val.TMS LONG Milliseconds since midnight when value last
changed or when the value was acquired from the
Stamp (milliseconds initial integrity poll
since midnight)
Binary Input Quality Bin.Val.QUAL LONG OPC quality of point converted from value of flags.

CitectSCADA DNPr Driver 18/08/2005 Page 19 of 85

 Citect Pty Ltd Driver User Guide

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Binary Output Value Bon.Val DIGITAL R/O. Current state of Binary Output

Object 10 Variation 2
Binary Output Status Bon.Stat BYTE R/O. Status data related to Value.
Bit 7 (State bit) not included – always zero.
Status Byte (excluding
state)
Object 10 Variation 2
Binary Output Status Bon.Stat.Online DIGITAL R/O. Bit 0 of Status byte
If Offline, command will not be successful.
Online bit 0=Offline,1=Online
Object 10 Variation 2
Binary Output Status Bon.Stat.Restart DIGITAL R/O. Bit 1 of Status byte
Originating field device has been restarted.
Restart bit 0=normal,1=Restart
Object 10 Variation 2
Binary Output Status Bon.Stat.CommLost DIGITAL R/O. Bit 2 of Status byte
If comms lost, command will not be successful
Communication Lost 0=normal,1=Lost
bit
Object 10 Variation 2
Binary Output Status Bon.Stat.RemForced DIGITAL R/O. Bit 3 of Status byte
Originating field device is in control
Remote Forced Data 0=normal,1=Forced
bit
Object 10 Variation 2
Binary Output Status Bon.Stat.LocalForced DIGITAL R/O. Bit 4 of Status byte
This device is in control
Local Forced Data bit 0=normal,1=Forced
Object 10 Variation 2
Bon.Stat.SelPend
Bon.Stat.LocalForced DIGITAL
DIGITAL R/O.
R/O.BitBit
5 4ofofStatus
Statusbyte
byte
Binary Output Status
This
Thisdevice
deviceis isinincontrol
control
Citect – Object 0=not selected,1=Selected, waiting on OPERATE
0=normal,1=Forced
Selected in RTU
Binary Output Status Bon.Stat.WrtPend DIGITAL R/O. Bit 6 of Status byte
This device is in control
Citect – Select Initated 0=not initatedl,1=SELECT started
in RTU
Binary Output Status Bon.Stat.WrtFail DIGITAL R/O. Bit 7 of Status byte
This device is in control
Citect – Problem in 0=normal,1=Write Fail
SELECT/OPERATE
sequence
Binary Output Control Bon.CtrlStat BYTE R/O. Status of Control Operation.
0=Request accepted, initiated or queued
Status 1= Request rejected – OPERATE received after
Status Byte SELECT had already timed-out
2= Request rejected – OPERATE received without
Object 12 receiving matching SELECT
Variation(s) 1,2 3= Request rejected – Formatting errors in control
request (Select, Operate or Doperate)
4= Request rejected – Control Operation not
supported for this bit
5= Request rejected – Queue full or point already

CitectSCADA DNPr Driver 18/08/2005 Page 20 of 85

 Citect Pty Ltd Driver User Guide

active
6= Request rejected – Control
hardware problems
7-127=Undefined.
Binary Output Quality Bon.Val.QUAL LONG OPC quality of point converted from value of flags.

CitectSCADA DNPr Driver 18/08/2005 Page 21 of 85

 Citect Pty Ltd Driver User Guide

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Counter Value (16/32 bit) Cn.Val LONG R/O. Accumulated transitions of a SW or HW point
(16bit or 32bit value)
Object 20 Variations
1,2,5,6
Object 22 Variations
1,2
Counter Value Quality Cn.Val.Qual LONG R/O

Counter Status Cn.Stat BYTE R/O. Status data related to Value.

Status byte
Object 20 Variations
1,2
Object 22 Variations
1,2
Counter Status Cn.Stat.Online DIGITAL R/O. Bit 0 of Status byte
If Offline, command will not be successful
Online bit 0=Offline,1=Online
Object 20 Variations
1,2
Object 22 Variations
1,2
Counter Status Cn.Stat.Restart DIGITAL R/O. Bit 1 of Status byte
Originating field device has been restarted
Restart bit 0=normal,1=Restart
Object 20 Variations
1,2
Object 22 Variations
1,2
Counter Status Cn.Stat.CommLost DIGITAL R/O. Bit 2 of Status byte
If comms lost, command will not be successful
Communication Lost 0=normal,1=Lost
bit
Object 20 Variations
1,2
Object 22 Variations
1,2
Counter Status Cn.Stat.RemForced DIGITAL R/O. Bit 3 of Status byte
Originating field device is in control
Remote Forced Data 0=normal,1=Forced
bit
Object 20 Variations
1,2
Object 22 Variations
1,2
Counter Status Cn.Stat.LocalForced DIGITAL R/O. Bit 4 of Status byte
This device is in control
Local Forced Data bit 0=normal,1=Forced
Object 20 Variations
1,2

CitectSCADA DNPr Driver 18/08/2005 Page 22 of 85

 Citect Pty Ltd Driver User Guide

Object 22 Variations
1,2
Counter Status Cn.Stat.RollOver DIGITAL R/O. Bit 5 of Status byte
Counter has reached limit and reset to 0
Roll Over bit 0=normal,1=Rollover
Object 20 Variations
1,2
Object 22 Variations
1,2
Delta Counter Value Cn.DeltaVal LONG R/O. Accumulated transitions of a SW or HW point
(16/32 bit) This value is reset to 0 after each read.
(16bit or 32bit value)
Object 20 Variations
3,4,7,8
Delta Counter Status Cn.DeltaStat BYTE R/O. Status data related to Value

Status byte
Object 20 Variations
3,4
Delta Counter Status Cn.DeltaStat.Online DIGITAL R/O. Bit 0 of Status byte
If Offline, command will not be successful
Online bit 0=Offline,1=Online
Object 20 Variations
3,4
Delta Counter Status Cn.DeltaStat.Restart DIGITAL R/O. Bit 1 of Status byte
Originating field device has been restarted
Restart bit 0=normal,1=Restart
Object 20 Variations
3,4
Delta Counter Status Cn.DeltaStat.CommLost DIGITAL R/O. Bit 2 of Status byte
If comms lost, command will not be successful
Communication Lost 0=normal,1=Lost
bit
Object 20 Variations
3,4
Delta Counter Status Cn.DeltaStat.RemForced DIGITAL R/O. Bit 3 of Status byte
Originating field device is in control
Remote Forced Data 0=normal,1=Forced
bit
Object 20 Variations
3,4
Delta Counter Status Cn.DeltaStat.LocalForced DIGITAL R/O. Bit 4 of Status byte
This device is in control
Local Forced Data bit 0=normal,1=Forced
Object 20 Variations
3,4
Delta Counter Status Cn.DeltaStat.RollOver DIGITAL R/O. Bit 5 of Status byte
Counter has reached limit and reset to 0
Roll Over bit 0=normal,1=Rollover
Object 20 Variations
3,4
Counter Quality Cn. QUAL LONG OPC quality of point converted from value of flags.

CitectSCADA DNPr Driver 18/08/2005 Page 23 of 85

 Citect Pty Ltd Driver User Guide

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Frozen Counter Value FCn.Val LONG R/O. Counter value when last freeze
(16/32 bit)
performed.
(16bit or 32bit value)
Object 21 Variations
1,2,9,10
Frozen Counter Value FCn.Val.Qual LONG R/O

Quality
Frozen Counter Status FCn.Stat BYTE R/O. Status data related to Value

Status byte
Object 21 Variations
1,2
Frozen Counter Status FCn.Stat.Online DIGITAL R/O. Bit 0 of Status byte
If Offline, command will not be successful
Online bit 0=Offline,1=Online
Object 21 Variations
1,2
Frozen Counter Status FCn.Stat.Restart DIGITAL R/O. Bit 1 of Status byte
Originating field device has been restarted
Restart bit 0=normal,1=Restart
Object 21 Variations
1,2
Frozen Counter Status FCn.Stat.CommLost DIGITAL R/O. Bit 2 of Status byte
If comms lost, command will not be successful
Communication Lost 0=normal,1=Lost
bit
Object 21 Variations
1,2
Frozen Counter Status FCn.Stat.RemForced DIGITAL R/O. Bit 3 of Status byte
Originating field device is in control
Remote Forced Data 0=normal,1=Forced
bit
Object 21 Variations
1,2
Frozen Counter Status FCn.Stat.LocalForced DIGITAL R/O. Bit 4 of Status byte
This device is in control
Local Forced Data bit 0=normal,1=Forced
Object 21 Variations
1,2
Frozen Counter Status FCn.Stat.RollOver DIGITAL R/O. Bit 5 of Status byte
Counter has reached limit and reset to 0
Roll Over bit 0=normal,1=Rollover
Object 21 Variations
1,2
Frozen Delta Counter FCn.DeltaVal LONG R/O. Counter delta value when last freeze
performed.
Value (16/32 bit)
(16bit or 32bit value)

Object 21 Variations 3,4

Frozen Delta Counter FCn.DeltaStat BYTE R/O. Status data related to value.
Status
Status byte

CitectSCADA DNPr Driver 18/08/2005 Page 24 of 85

 Citect Pty Ltd Driver User Guide

Object 21 Variations 3,4

Frozen Delta Counter FCn.DeltaStat.Online DIGITAL R/O. Bit 0 of Status byte
Status If Offline, command will not be successful
0=Offline,1=Online
Online bit
Object 21 Variations 3,4
Frozen Delta Counter FCn.DeltaStat.Restart DIGITAL R/O. Bit 1 of Status byte
Status Originating field device has been restarted
0=normal,1=Restart
Restart bit
Object 21 Variations 3,4
Frozen Delta Counter FCn.DeltaStat.CommLost DIGITAL R/O. Bit 2 of Status byte
Status If comms lost, command will not be successful
0=normal,1=Lost
Communication Lost bit
Object 21 Variations 3,4
Frozen Delta Counter FCn.DeltaStat.RemForced DIGITAL R/O. Bit 3 of Status byte
Status Originating field device is in control
0=normal,1=Forced
Remote Forced Data bit
Object 21 Variations 3,4
Frozen Delta Counter FCn.DeltaStat.LocalForced DIGITAL R/O. Bit 4 of Status byte
Status This device is in control
0=normal,1=Forced
Local Forced Data bit
Object 21 Variations 3,4
Frozen Delta Counter FCn.DeltaStat.RollOver DIGITAL R/O. Bit 5 of Status byte
Status Counter has reached limit and reset to 0
0=normal,1=Rollover
Roll Over bit
Object 21 Variations 3,4
Frozen Counter FCn. QUAL LONG OPC quality of point converted from value of flags.

Quality

CitectSCADA DNPr Driver 18/08/2005 Page 25 of 85

 Citect Pty Ltd Driver User Guide

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Analog Input Value Ain.Val LONG R/O. Current value of Analog Input
(16/32 bit) (16bit or 32bit value)

Object 30 Var(s)
1,2,3,4
Object 32 Var(s)
1,2,3,4
Analog Input Value Ain.Val.Float REAL R/O. Current value of Analog Input
(float) (float value)

Object 30 Var(s) 5
Object 32 Var(s) 5,7
Analog Input Status Ain.Stat BYTE R/O. Status data related to Value

Status byte
Object 30 Variations
1,2,5
Object 32 Var(s)
1,2,3,4,5,7
Analog Input Status Ain.Stat.Online DIGITAL R/O. Bit 0 of Status byte
If Offline, command will not be successful
Online bit 0=Offline,1=Online
Object 30 Variations
1,2,5
Object 32 Var(s)
1,2,3,4,5,7
Analog Input Status Ain.Stat.Restart DIGITAL R/O. Bit 1 of Status byte
Originating field device has been restarted.
Restart bit 0=normal,1=Restart
Object 30 Variations
1,2,5
Object 32 Var(s)
1,2,3,4,5,7
Analog Input Status Ain.Stat.CommLost DIGITAL R/O. Bit 2 of Status byte
If comms lost, command will not be successful
Communication Lost 0=normal,1=Lost
bit
Object 30 Variations
1,2,5
Object 32 Var(s)
1,2,3,4,5,7
Analog Input Status Ain.Stat.RemForced DIGITAL R/O. Bit 3 of Status byte
Originating field device is in control
Remote Forced Data 0=normal,1=Forced
bit
Object 30 Variations
1,2,5
Object 32 Var(s)

CitectSCADA DNPr Driver 18/08/2005 Page 26 of 85

 Citect Pty Ltd Driver User Guide

1,2,3,4,5,7
Analog Input Status Ain.Stat.LocalForced DIGITAL R/O. Bit 4 of Status byte
This device is in control
Local Forced Data bit 0=normal,1=Forced
Object 30 Variations
1,2,5
Object 32 Var(s)
1,2,3,4,5,7
Analog Input Status Ain.Stat.OverRange DIGITAL R/O. Bit 5 of Status byte
Analog is over/under range and has been clipped
Over Range bit 0=normal,1=Over Range
Object 30 Variations
1,2,5
Object 32 Var(s)
1,2,3,4,5,7
Analog Input Status Ain.Stat.RefCheck DIGITAL R/O. Bit 6 of Status byte
A/D reference signal unreliable. Value is unreliable
Reference Check bit 0=normal,1=Error
Object 30 Variations
1,2,5
Object 32 Var(s)
1,2,3,4,5,7
Analog Input Time Ain.Val.TS LONG UTC time when value last changed or when the
value was acquired from the initial integrity poll
Stamp (seconds since
1970)
Analog Input Time Ain.Val.TMS LONG Milliseconds since midnight when value last
changed or when the value was acquired from the
Stamp (milliseconds initial integrity poll
since midnight)
Analog Input Quality Ain.Val.QUAL LONG OPC quality of point converted from value of flags.

CitectSCADA DNPr Driver 18/08/2005 Page 27 of 85

 Citect Pty Ltd Driver User Guide

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Analog Output Value Aon.Val OR LONG R/O Current value of Analog Output.
(32 bit) Aon.Val.Long (32bit value)

Object 40 Variation 1
Analog Output Value Aon.Val LONG R/O Current value of Analog Output.
(16 bit) (16bit value)

Object 40 Variation 2
Analog Output Value Aon.Val.Float REAL R/O Current value of Analog Output.
(float) (float value)

Object 40 Variation 3
Analog Output Status Aon.Stat BYTE R/O. Status data related to Value

Status byte
Object 40 Variations
1,2,3
Analog Output Status Aon.Stat.Online DIGITAL R/O. Bit 0 of Status byte
If Offline, command will not be successful
Online bit 0=Offline,1=Online
Object 40 Variations
1,2,3
Analog Output Status Aon.Stat.Restart DIGITAL R/O. Bit 1 of Status byte
Originating field device has been restarted.
Restart bit 0=normal,1=Restart
Object 40 Variations
1,2,3
Analog Output Status Aon.Stat.CommLost DIGITAL R/O. Bit 2 of Status byte
If comms lost, command will not be successful
Communication Lost 0=normal,1=Lost
bit
Object 40 Variations
1,2,3
Analog Output Status Aon.Stat.RemForced DIGITAL R/O. Bit 3 of Status byte
Originating field device is in control
Remote Forced Data 0=normal,1=Forced
bit
Object 40 Variations
1,2,3
Aon.Stat.SelPend
Bon.Stat.LocalForced DIGITAL
DIGITAL R/O.
R/O.BitBit
5 4ofofStatus
Statusbyte
byte
Analog Output Status
This
Thisdevice
deviceis isinincontrol
control
Citect – Object 0=not selected,1=Selected, waiting on OPERATE
0=normal,1=Forced
Selected in RTU
Analog Output Status Aon.Stat.WrtPend DIGITAL R/O. Bit 6 of Status byte
This device is in control
Citect – Select Initated 0=not initatedl,1=SELECT started
in RTU
Analog Output Status Aon.Stat.WrtFail DIGITAL R/O. Bit 7 of Status byte
This device is in control
Citect – Problem in 0=normal,1=Write Fail
SELECT/OPERATE

CitectSCADA DNPr Driver 18/08/2005 Page 28 of 85

 Citect Pty Ltd Driver User Guide

sequence
Analog Output Aon.CtrlStat BYTE R/O. Status of Control Operation.
0=Request accepted, initiated or queued
Control Status 1= Request rejected – OPERATE received after
Status Byte SELECT had already timed-out
2= Request rejected – OPERATE received without
Object 41 Variations receiving matching SELECT
1,2,3 3= Request rejected – Formatting errors in control
request (Select, Operate or Doperate)
4= Request rejected – Control Operation not
supported for this bit
5= Request rejected – Queue full or point already
active
6= Request rejected – Control hardware problems
7-127=Undefined.
Analog Output Aon.Val.QUAL LONG OPC quality of point converted from value of flags.

Quality

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
RTU Time & Date ReadTime LONG R/W
– Read RTU time from driver cache
– Write RTU time to driver cache

Object 50 Variation 1

CitectSCADA DNPr Driver 18/08/2005 Page 29 of 85

 Citect Pty Ltd Driver User Guide

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
IIN INTEGER R/O
The value of the
Internal Indication bits
retrieved from the last (Virtual Address)
response (see note 6).
No Object
Bit 0 of Byte 2 of the IIN.BadFunction DIGITAL R/O

Internal Indication bits

(see note 6). Function (Virtual Address)
code not implemented.
No Object
Bit 1 of Byte 2 of the IIN.ObjectUnknown DIGITAL R/O

Internal Indication bits (Virtual Address)

(see note 6). Request
object unknown.
No Object
Bit 2 of Byte 2 of the IIN. OutOfRange DIGITAL R/O

Internal Indication bits

(see note 6).
Parameters in (Virtual Address)
qualifier, range or data
fields are not valid or
out of range.
No Object
Bit 3 of Byte 2 of the IIN. BufferOvfl DIGITAL R/O

Internal Indication bits

(see note 6). Event or (Virtual Address)
other buffers
overflowed.
No Object
Bit 4 of Byte 2 of the IIN.ExecutingIIN DIGITAL R/O

Internal Indication bits

(see note 6)
Request understood (Virtual Address)

but requested
operation already
executing.
No Object
Bit 5 of Byte 2 of the IIN.ConfigIIN DIGITAL R/O

Internal Indication bits

(see note 6) (Virtual Address)
Configuration in
outstation corrupt.
No Object

CitectSCADA DNPr Driver 18/08/2005 Page 30 of 85

 Citect Pty Ltd Driver User Guide

Bit 0 of Byte 1 of the IIN.AllStations DIGITAL R/O

Internal Indication bits (Virtual Address)

(see note 6).
All stations message
received.
No Object
Bit 1 of Byte 1 of the IIN.Class1 DIGITAL R/O

Internal Indication bits (Virtual Address)

(see note 6). Class 1
data available.
No Object
Bit 2 of Byte 1 of the IIN.Class2 DIGITAL R/O

Internal Indication bits (Virtual Address)

(see note 6).
Class 2 data available.
No Object
Bit 3 of Byte 1 of the IIN.Class3 DIGITAL R/O

Internal Indication bits (Virtual Address)

(see note 6). Class 3
data available.
No Object
Bit 4 of Byte 1 of the IIN.TimeIIN DIGITAL R/O

Internal Indication bits

(see note 6). Time (Virtual Address)
uccessful tion
required from the
master.
No Object

CitectSCADA DNPr Driver 18/08/2005 Page 31 of 85

 Citect Pty Ltd Driver User Guide

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Bit 5 of Byte 1 of the IIN.LocalIIN DIGITAL R/O

Internal Indication bits

(see note 6). Some or
all of the outstations (Virtual Address)
digital output points
are in local state.
No Object
Bit 6 of Byte 1 of the IIN.TroubleIIN DIGITAL R/O

Internal Indication bits

(see note 6) (Virtual Address)
Abnormal condition
exists in the
outstation.
No Object
Bit 7 of Byte 1 of the IIN.Restart DIGITAL R/O

Internal Indication bits (Virtual Address)

(see note 6). Device
restart.
No Object
Virtual Address –This address does not relate to I/O data internal to the device, but relates to data internal to the driver, or an
action to be to be performed by the driver.

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Count of all successful Polls INTEGER R/W. Count of successful Integrity, Event, Class1,
Class2 and Class 3 polls of the device.
polls (Virtual Address) Write ‘1’ to reset counter.
(Forced and periodic)
No Object
Count of all failed FailedPolls INTEGER R/W. Count of failed Integrity, Event, Class1,
Class2 and Class3 polls of the device. (ie failure of
polls (Virtual Address) full timeout sequence)
Write ‘1’ to reset counter.
(Forced and periodic)
No Object
Count of successful Ipolls INTEGER R/W. Count of successful Integrity polls of the
device.
Integrity polls (Forced (Virtual Address) Write ‘1’ to reset counter.
and periodic)
No Object
Count of failed FailedIPolls INTEGER R/W. Count of failed Integrity polls of the device.
(ie failure of full timeout sequence)
Integrity polls (Virtual Address) Write ‘1’ to reset counter.
(Forced and periodic)
No Object
Count of successful Epolls INTEGER R/W. Count of successful Event polls of the device.
Write ‘1’ to reset counter.
Event polls (Forced (Virtual Address)
and periodic)

CitectSCADA DNPr Driver 18/08/2005 Page 32 of 85

 Citect Pty Ltd Driver User Guide

No Object
Count of failed Event FailedEPolls INTEGER R/W. Count of failed Event polls of the device.
(ie failure of full timeout sequence)
polls (Virtual Address) Write ‘1’ to reset counter.
(Forced and periodic)
No Object
Count of Unsoliciteds UnsolicitedRxd INTEGER R/W. Count of valid Unsolicited Responses
received by the device.
received (Virtual Address) Write ‘1’ to reset counter.

No Object
Late cache refresh for LateRefresh DIGITAL R/O. Indicates when a device poll has been
delayed, resulting in a late cache refresh.
device (Virtual Address) Refer to INI parameter DataLag for further details.

No Object
RTU Online status RTUStatus DIGITAL R/O Internal online status of a unit. Of limited use
as a tag on a unit as if the unit was offline, you
could not read the tag anyway. This tag has been
suberceeded by the UnitActiveState.X tags.

RTU Events received RTUEvents LONG R/O RTU events PER PORT received from the field
(Virtual address) device. Available as a virtual tag as well.

Calculated variable CalcEvents LONG R/O Calculated variable events PER PORT
received from internal calculation engine. This is
events (Virtual address) equivalent to changed LEFT hand side variables
due to calculations. Available as a virtual tag as
well
Virtual Address –This address does not relate to I/O data internal to the device, but relates to data internal to the driver, or an
action to be to be performed by the driver.

CitectSCADA DNPr Driver 18/08/2005 Page 33 of 85

 Citect Pty Ltd Driver User Guide

3.7.1.2 Control Types

The driver can support multiple writes per Citect request for Binary Output and Analog Output control.

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Binary Output Control Bon.Select.Latch DIGITAL W/O. Selects point and mode of operation.
Maintains output in specified state
Select (Latch Mode)
Object 12 Variation 1
Binary Output Control Bon.Select.Pulse DIGITAL W/O. Selects point and mode of
Select (Pulse Mode) operation
Object 12 Variation 1 Only Pulse ON supported
Pulse OFF may be supported in future release
Binary Output Control Bon.Select.TC DIGITAL W/O. Selects point and mode of operation
Trip and Close both use the ONTIME parameter.
Select (TC Mode)
0=Trip breaker, 1=Close breaker
Object 12 Variation 1
Binary Output Control Bon.Operate.Latch DIGITAL W/O. Activates previously selected operation.
(Tag Type currently not Maintains output in specified state.
Operate (Latch Mode) supported, Refer to Note1)
Object 12 Variation 1
Binary Output Control Bon.Operate.Pulse DIGITAL W/O. Activates previously selected
(Tag Type currently not
Operate (Pulse Mode) supported, Refer to Note1) operation
Object 12 Variation 1 Only Pulse ON supported
Pulse OFF may be supported in future release
Binary Output Control Bon.Operate.TC DIGITAL W/O. Activates previously selected operation
(Tag Type currently not Trip and Close both use the ONTIME parameter.
Operate (TC Mode) supported, Refer to Note1) 1=Close breaker, 0=Trip breaker
Object 12 Variation 1
Binary Output Control Bon.Doperate.Latch DIGITAL W/O. Selects and activates point operation.

Direct Operate (Latch Maintains output in specified state

(Refer to Note2)
Mode)
Object 12 Variations
1,2,3
Binary Output Control Bon.Doperate.Pulse DIGITAL W/O. Selects and activates point
Direct Operate (Pulse (Refer to Note2)
operation
Mode) Only Pulse ON supported
Object 12 Variations Pulse OFF may be supported in future release

1,2,3
Binary Output Control Bon.Doperate.TC DIGITAL W/O. Selects and activates point operation

Direct Operate (TC Trip and Close both use the

(Refer to Note2)
Mode) ONTIME parameter.
1=Close breaker, 0=Trip breaker
Object 12 Variations
1,2,3
Binary Output Control Bon.Configure.Ontime LONG R/W. Time in milliseconds of momentary contact
closure (used in Pulse ON, Trip and Close modes)
Configure Ontime

CitectSCADA DNPr Driver 18/08/2005 Page 34 of 85

 Citect Pty Ltd Driver User Guide

Object 12 Variations
1,2
Binary Output Control Bon.CancelSel DIGITAL W/O. Clear OPERATE status bits and cancel the
SELECT operation to the RTU.
Cancel Current
.SelectOnly
Binary Output Control Bon.Configure.Offtime LONG R/W. Time in milliseconds of momentary contact
opening (used in Pulse OFF)
Configure Offtime
Object 12 Variations 1,2
Binary Output Control Bon.Configure.Queue DIGITAL R/W

Configure Queue
Object 12 Variations 1,2
Binary Output Control Bon.Configure.Clear DIGITAL R/W
Configure Clear
Object 12 Variations 1,2
Binary Output Control Bon.Configure.Count DIGITAL R/W
Configure Count
Object 12 Variations 1,2

CitectSCADA DNPr Driver 18/08/2005 Page 35 of 85

 Citect Pty Ltd Driver User Guide

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Counter Freeze C.Freeze DIGITAL W/O. Copy all counters to a freeze buffer.

Command (Refer to Note3)

Object 20 Variations
1..8
Counter Freeze and C.FreezeClear DIGITAL W/O. Copy all counter to a freeze buffer, and then
clear all counters to 0.
Clear (Refer to Note4)
Command
Object 20 Variations
1..8

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Analog Output Aon.Select.Long LONG W/O. Selects point to be controlled.
(32bit value)
Control (32bit)
Select
Object 41 Variation 1
Analog Output Aon.Select INT W/O. Selects point to be controlled.
(16bit value)
Control (16bit)
Select
Object 41 Variation 2
Analog Output Aon.Select.Float REAL W/O. Selects point to be controlled.
(float value)
Control (float)
Select
Object 41 Variation 3
Analog Output Aon.Operate.Long LONG W/O. Activates control operation on previously
(Tag Type currently not selected point. (32bit value)
Control (32bit) supported, Refer to Note1)
Operate
Object 41 Variation 1
Analog Output Aon.Operate INT W/O. Activates control operation on previously
(Tag Type currently not selected point. (16bit value)
Control (16bit) supported, Refer to Note1)
Operate
Object 41 Variation 2
Analog Output Aon.Operate.Float REAL W/O. Activates control operation on previously
(Tag Type currently not selected point. (float value)
Control (float) supported, Refer to Note1)
Operate
Object 41 Variation 3
Analog Output Aon.Doperate.Long LONG W/O. Selects and activates control
Control (32bit) (Refer to Note2)
operation on point. (32bit value)
Direct Operate
Object 41 Variation 1
Analog Output Aon.Doperate INT W/O. Selects and activates control

CitectSCADA DNPr Driver 18/08/2005 Page 36 of 85

 Citect Pty Ltd Driver User Guide

Control (16bit) operation on point. (16bit value)

(Refer to Note2)
Direct Operate
Object 41 Variation 2
Analog Output Aon.Doperate.Float REAL W/O. Selects and activates control
Control (float) (Refer to Note2)
operation on point. (float value)
Direct Operate
Object 41 Variation 3
Analog Output Aon.CancelSel DIGITAL W/O. Clear OPERATE status bits
Control Cancel and cancel the SELECT operation to
Current .SelectOnly the RTU.

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
RTU Time & Date WriteTime DIGITAL W/O.
Write ‘1’ to synchronise RTU time with Citect time

Object 50 Variation 1

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Cold Restart ColdRestart DIGITAL W/O. Instruct the Outstation to perform a complete
restart of the user application. The only valid value
Command (Virtual Address) to write is 1.

No Object
Warm Restart WarmRestart DIGITAL W/O.

Command

No Object

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
File commands TBA TBA TBA

Object 70

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Force an Integrity Poll ForceIntegrityPoll DIGITAL W/O. Writing a ‘1’ to this tag will force the driver to
execute an Integrity poll of the device (in addition
Object 60 Variation 1 to the routine polling that it automatically
undertakes).
Object 60 Variation 2
(Virtual Address)
Object 60 Variation 3
Object 60 Variation 4
Force an Event Poll ForceEventPoll DIGITAL W/O. Writing a ‘1’ to this tag will
Object 60 Variation 2 force the driver to execute an Event

CitectSCADA DNPr Driver 18/08/2005 Page 37 of 85

 Citect Pty Ltd Driver User Guide

Object 60 Variation 3 poll of the device (in addition to the

(Virtual Address)
Object 60 Variation 4 routine polling that it automatically
undertakes).
ForceClass1Poll DIGITAL W/O. Writing a ‘1’ to this tag will force the driver to
Force a Class1 Poll execute a poll for Class1 data from the device (in
Object 60 addition to the routine polling that it automatically
undertakes
Variation 2
ForceClass2Poll DIGITAL W/O. Writing a ‘1’ to this tag will force the driver to
Force a Class2 Poll execute a poll for Class2 data from the device (in
Object 60 addition to the routine polling that it automatically
undertakes
Variation 3
ForceClass3Poll DIGITAL W/O. Writing a ‘1’ to this tag will force the driver to
Force a Class1 Poll execute a poll for Class3 data from the device (in
Object 60 addition to the routine polling that it automatically
undertakes
Variation 4
DisableUnsolicited DIGITAL W/O. Writing a ‘1’ to this tag will instruct the unit not
Disable all to broadcast any more unsolicited responses.
Unsoliciteds Must be W/O, as there is no way of determining if
unsoliciteds were disabled before Citect startup.
Object 60 Variation 2 (Virtual Address) N.B. This a Level 3 feature.
Object 60 Variation 3
Object 60 Variation 4
EnableUnsolicited DIGITAL W/O. Writing a ‘1’ to this tag will allow the unit not
Enable all to broadcast unsolicited responses. The Classes
Unsoliciteds enabled are determined by the INI parameter
[DNPR] AutoUnsolicitedEnableDefault or [<unit.]
Object 60 Variation 2 (Virtual Address) AutoUnsolicitedEnable.
Object 60 Variation 3 Must be W/O, as there is no way of determining if
Object 60 Variation 4 unsoliciteds were disabled before Citect startup.
N.B. This a Level 3 feature.
Virtual Address –This address does not relate to I/O data internal to the device, but relates to data internal to the driver, or an
action to be to be performed by the driver.

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Adjust the Polling PollPeriod LONG R/W. If the INI parameter ‘EnablePollPeriodWrites’
is set to TRUE (1), then this tag can be used to
Period adjust the Event Polling Period. This tag can be
used to display the current Event Polling Period
(Virtual Address) regardless of the state of ‘EnablePollPeriodWrites’.

No Object
Returns if Polling EnablePoll INTEGER R/W. Returns if the unit has polling
enabled for reads enabled. A write of ‘0’ will turn
polling off, ‘1’ will re-enable polling.
Time to go to next poll TimeToNextPoll LONG R/O. Seconds. Will count down from the set
poll time, and may go –ve if the poll has
been delayed.
Virtual Address –This address does not relate to I/O data internal to the device, but relates to data internal to the driver, or an
action to be to be performed by the driver.

3.7.1.3 Virtual Usurp Types

CitectSCADA DNPr Driver 18/08/2005 Page 38 of 85

 Citect Pty Ltd Driver User Guide

Request unit active on Unitx.RequestUnitActive.Pr DIGITAL R/W. Writing a ‘1’ to this tag will
imary
primary force the unit be active on the
(Virtual Address) primary I/O server. Writing ‘0’ will
force the unit be active on the
standby I/O server. A read returns
the last value written to the tag.
Request unit active on Unitx.RequestUnitActive.St DIGITAL R/W. Writing a ‘1’ to this tag will
andby
standby force the unit be active on the
(Virtual Address) standby I/O server. Writing ‘0’ will
force the unit be active on the
primary I/O server. A read returns
the last value written to the tag.
Unit active state on Unitx.UnitActiveState.Prim DIGITAL R/O. Returns 1 if the unit is active
ary
primary on the primary I/O server and 0 if
(Virtual Address) active on the standby I/O server.
Unit active state on Unitx.UnitActiveState.Stan DIGITAL R/O. Returns 1 if the unit is active
dby
standby on the standby I/O server and 0 if
(Virtual Address) active on the primary I/O server.

CitectSCADA DNPr Driver 18/08/2005 Page 39 of 85

Citect Pty Ltd Driver User Guide

Where:

n Point index number

R/O Read Only.
W/O Write Only
R/W Read or Write
text Not currently supported

Notes:

1 The driver will automatically issue a (high priority) ‘Operate’ command upon the
successful completion of a ‘Select’ command. ‘Operate’ is a DNP (Subset level 1)
command and is supported internally by the driver, even though the user can not
currently create ‘Operate’ tag types to manually force an ‘Operate’ command.
2 DNP (Subset level 1) supports a ‘Direct Operate without
acknowledgment’, but as this does not verify the success of
the command, only ‘Direct Operate’ is currently
implemented.
3 DNP (Subset level 2) supports an ‘Immediate Freeze without acknowledgment’, but
as this does not verify the success of the command, only ‘Immediate Freeze’ is
currently implemented.
4 DNP (Subset level 2) supports a ‘Freeze and Clear without acknowledgment’, but as
this does not verify the success of the command, only ‘Freeze and Clear’ is currently
implemented.
5 For types Binary Output Control Status and Analog Output
Control Status, see section 3.9.3 Driver Specific Parameters
regarding the use of the RetZeroOnCROBInvalid and
RetZeroOnAOOBInvalid parameters.
6 Note that not every transition of the IIN will be visible using
this tag since the driver reacts to the IIN bits. Also IIN error
onsistent reflect the response to a single request therefore
may only be briefly stored. For instance if the IIN bits
indicate time uccessful tion is required, and the driver is
configured to do so, then the uccessful tion will occur, and
the time uccessful tion bit become zero before it can be
displayed. The IIN tag is useful for viewing IIN conditions
that are global to the device (not specific to a request) and are
not being responded to by the driver (for instance, the Local
bit).

CitectSCADA DNPr Driver 18/08/2005 Page 40 of 85

 Citect Pty Ltd Driver User Guide

3.7.1.4 Virtual Unit Types

Virtual types allow tags to be implemented on one Citect unit but work on another. This is particularly
useful with Virtual units to allow writes to tags on units that are off-line.

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Force an Integrity Poll UNITn.ForceIntegrityPoll DIGITAL W/O. Writing a ‘1’ to this tag will force the driver to
execute an Integrity poll of the device n (in addition
Object 60 Variation 1 to the routine polling that it automatically
undertakes).
Object 60 Variation 2
(Virtual Address)
Object 60 Variation 3
Object 60 Variation 4
Force an Event Poll UNITn.ForceEventPoll DIGITAL W/O. Writing a ‘1’ to this tag will
Object 60 Variation 2 force the driver to execute an Event
Object 60 Variation 3 (Virtual Address) poll of the device n (in addition to the
Object 60 Variation 4 routine polling that it automatically
undertakes).
Request unit active on UNITn.RequestUnitActive. DIGITAL R/W. Writing a ‘1’ to this tag will
Primary
primary force the unit n be active on the
primary I/O server. Writing ‘0’ will
force the unit be active on the
standby I/O server. A read returns
the last value written to the tag.
Request unit active on UNITn.RequestUnitActive. DIGITAL R/W. Writing a ‘1’ to this tag will
Standby
standby force the unit n be active on the
standby I/O server. Writing ‘0’ will
force the unit be active on the
primary I/O server. A read returns
the last value written to the tag.
Unit active state on UNITn.UnitActiveState.Pri DIGITAL R/O. Returns 1 if the unit n is active
mary
primary on the primary I/O server and 0 of
active on the standby I/O server.
Unit active state on UNITn.UnitActiveState.Sta DIGITAL R/O. Returns 1 if the unit n is active
ndby
standby on the standby I/O server and 0 of
active on the primary I/O server.
Count of all successful UNITn.Polls INTEGER R/W. Count of successful Integrity,
polls Event, Class1, Class2 and Class 3
(Forced and periodic) polls of the device.
Write ‘1’ to reset counter.
Count of all failed UNITn.FailedPolls INTEGER R/W. Count of failed Integrity,
polls Event, Class1, Class2 and Class3
(Forced and periodic) polls of the device. (ie failure of full
timeout sequence)
Write ‘1’ to reset counter.

CitectSCADA DNPr Driver 18/08/2005 Page 41 of 85

 Citect Pty Ltd Driver User Guide

Count of successful UNITn.Ipolls INTEGER R/W. Count of successful Integrity

Integrity polls (Forced polls of the device.
and periodic) Write ‘1’ to reset counter.
Count of failed UNITn.FailedIPolls INTEGER R/W. Count of failed Integrity polls
Integrity polls of the device.
(Forced and periodic) (ie failure of full timeout sequence)
Write ‘1’ to reset counter.
Count of successful UNITn.Epolls INTEGER R/W. Count of successful Event polls
Event polls (Forced of the device.
and periodic) Write ‘1’ to reset counter.
Count of failed Event UNITn.FailedEPolls INTEGER R/W. Count of failed Event polls of
polls the device.
(Forced and periodic) (ie failure of full timeout sequence)
Write ‘1’ to reset counter.
Count of Unsoliciteds UNITn.UnsolicitedRxd INTEGER R/W. Count of valid Unsolicited
received Responses received by the device.
Write ‘1’ to reset counter.
Returns if Polling UNITn. EnablePoll INTEGER R/W. Returns if the unit has polling
enabled for reads enabled. A write of ‘0’ will turn
polling off, ‘1’ will re-enable polling.
Time to go to next poll UNITn.TimeToNextPoll LONG Will count down from the srt poll time, and
may go –ve if the poll has been delayed.
True port connection UNITn.UnitPortState.Prima INTEGER R/O. Useful to check if the port a unit is on
ry is connected.
state off primary unit
True port connection Unitn.UnitPortState.Standb INTEGER R/O. Useful to check if the port a unit is on
y is connected.
state off standby unit
Virtual Address –This address does not relate to I/O data internal to the device, but relates to data internal to the driver, or an
action to be to be performed by the driver.

Virtual units are devices that always appear on-line to Citect. Any unit with an address of 65534 is a
virtual unit. A virtual unit does not send any DNP3 frames and the driver will not process any received
frames from a device with an address of 65534. This the address to use when a virtual unit is on a
real port.
One global virtual unit is allowed (on a dummy port which never goes offline) with an address of
65535. The global unit is the best way to get high level items like the port status as virtual units on
ports are not available if the unit is offline. Suggest a TCPIP port is configured with settings of "-
i127.0.0.1 –u".
The Citect I/O server will not write to any tags on an off-line unit. Virtual units are useful to implement
virtual tags that write to other units on the same port. They provide a way to write to some tags on
units regardless of if the unit is on-line or off-line.
For example with the following project units and tags:

Unit 42
Tag1 address: ForceIntegrityPoll

Virtual unit (65534)

Tag2 address: UNIT42. ForceIntegrityPoll

If unit 42 is off-line it is not possible to write to Tag1. However as the virtual unit always on-line it is
possible to write to the virtual tag Tag2 and this will cause the driver to do an integrity poll to unit 42
even if unit 42 is off-line.

CitectSCADA DNPr Driver 18/08/2005 Page 42 of 85

 Citect Pty Ltd Driver User Guide

3.7.1.5 Virtual Tag Types

These types are primarily intended to be used with the calculated variables. They are points that can
be used to store values that do not reside on the RTU.

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
Long Virtual Tag Virtualn.Val LONG Long virtual tag type primarily intended to be used
with calculated variables

Real Virtual Tag Virtualn.Val.Float REAL Float virtual tag type primarily intended to be used
with calculated variables

Digital Virtual tag Virtualn.Val.Binary DIGITAL Uses LONG internally, set to 0 or 1

Virtual Tag Time Virtualn.Val.TS LONG UTC time associated with value

Stamp (seconds since

1970)
Virtual Tag Time Virtualn.Val.TS LONG Milliseconds since midnight associated with value

Stamp (milliseconds
since midnight)
Virtual Tag Quality Virtualn.Val.QUAL LONG OPC quality associated with value.

3.7.1.6 Global Types

These are global variables in the DNPr driver.

IO Device Type Citect data format Citect data Description/Special Usage/Limitations/ Valid
Ranges
types
N/A EventQueSize LONG Current size of the event que. Should be accessed
via a virtual unit.

N/A DelayEventQueSize LONG Current size of the delay event que. Should be
accessed via a virtual unit.

Where:

n Device address as specified in the IODevice form address field.

R/O Read Only.
W/O Write Only
R/W Read or Write
text Not currently supported
Bold These tags read global values and can be used on any unit or virtual unit. A virtual
unit is the best choice.

CitectSCADA DNPr Driver 18/08/2005 Page 43 of 85

Citect Pty Ltd Driver User Guide

3.7.2 driver.dbf Entries

Driver.dbf table removed due to the difficulty in keeping in up to date. The accurate picture of this is
the dnp.txt or its dnpr.dbf file.

CitectSCADA DNPr Driver 18/08/2005 Page 44 of 85

Citect Pty Ltd Driver User Guide

3.8 PROTDIR.DBF
TAG FILE BIT_BLOCK MAX_LENGTH OPTIONS
DNPR DNPR 8 Bits * 8 Bits * 0x1010cb
0 Adjustable by user to 2048 bits
The driver code has been written to support blocked requests. However as an RTU’s configuration is
infinitely variable, users must ensure the blocking of a data type makes sense. I.e. asking the driver
for a point that does not exist will cause the whole request to be flagged as an error. If this entry is
adjusted, then the equivalent [DNPR]Block=x value needed to be adjusted to the byte count
equivalent.

3.9 Parameters and INI options

3.9.1 General Parameters

Citect v5.40+ on
[IOSERVER]WatchdogPrimary=1

Should be set when peer redundancy is in use. This ensures that the check that your unit is still online
occurs for all units. Not only does this enable the unit’s offline to be noticed if NO reads are
happening to that unit, but enables the driver to minimise #COMs on changeover by reporting offline
in this check, and not on actual read requests.

NOTE: The following INI values will need to be set uniquely on any system using DNP:

- SCADAAddress=xxx
- EnablePeerRedundancy=0 ! if enabled then ‘PeerAddress=xxx’ needs to be set

Failure tp provide a [DNPR]SCADAAddress entry will cause a popup box to occur at startup.
It is also likely that these will also need adjustment for your specific network hardware :

AppLayerTimeout=xxx
DataLinkTimeout=xx
Retry=x
Timeout=xx
RapidOfflineDetection=xx

3.9.2 Standard Driver Parameters

Block 1 Byte (Note 1)
Delay 20 mSec
MaxPending 16 Request
Polltime 200 mSec
Timeout 5000 mSec (range 500 – 32000 mSec)
Retry 1 NB: A per unit Retry INI is available.
WatchTime 10 Sec

Note 1 – Dynamic IOServer Blocking is adjustable by the user up to 256 bytes.

e.g. [DNPR]Block=256
This allows DCBs to be blocked together in the IOServer and make fewer requests down to the driver.

CitectSCADA DNPr Driver 18/08/2005 Page 45 of 85

 Citect Pty Ltd Driver User Guide

3.9.3 Driver Specific Parameters

3.9.3.1 Parameters that apply in scope to the entire driver

Many of these values can be over-ridden by a unique value for each individual unit. Section 3.9.3.3
has these details. If a unit does not have one of these INIs, the global [DNPR] value is used. E.g.
[DNPR]EventPollPeriodDefault=30 will set all units to use 30s, however if say
[unit_123]EventPollPeriod=10 existed, then unit “unit_123” would use 10.

Section Function Range Default Comments

[DNPR] ConnectionTimeout 1000 to 8000 The maximum amount of time to allow the low level
65534mSec transport for the driver to attempt a connection.
[DNPR] ScadaAddress 0 to 65,534 3 Citect DNP Address

[DNPR] TimeoutExtensionDefault 0 to 0 mSec Default extension to be added to the standard ‘Timeout’

2,000,000,000 parameter. This extension is only required if a timeout
mSec greater than 32,000 milliseconds is needed.
[DNPR] EventPollPeriodDefault 0 to 60 Sec Default period to poll devices for event class data.
4,000,000 Sec Integrity poll will poll for all classes (event and static
data), and occurs after every EventPollRatioDefault event
polls.

[DNPR] EventPollRatioDefault 0 to 65,535 10 Default number of event class polls for every integrity poll.
Integrity poll will poll for all classes (event and static
data). Note that a value of zero implies that only integrity
polls are conducted.

[DNPR] ResponseModeDefault 1 to 15 11 Default Response Mode, composed from a

Combination of: 1=Polled, 2=Unsolicited enabled, 4=Use
Delay Measurement,
8 = perform time synch when requested.

[DNPR] DataLinkConfirmDefault 0 to 2 0 Default Data Link Confirm mode:

0 = Never, 1 = Sometimes, 2 = Always
[Sometimes = Multiframe only]

[DNPR] DataLinkTimeOutDefault 1 to 2000 mSec Default waiting period since last frame for a data link
65,5 confirm –only if confirm requested
35
mSec
[DNPR] DataLinkRetrysDefault 0 to 255 3 Default number of attempts to retransmit after a data link
timeout

[DNPR] DataLinkNoRetriesOnControlsDe 0 to 1 0 If set to 1 then there are no data link layer retries when
fault sending control messages such as direct operate, or
select/operate. If set to 0 then normal retries apply.
Note: The data link layer will only retry if data link layer
confirmations are used, see DataLinkConfirmDefault.
[DNPR] OnTimeBODNPDefault 0 to 1000 mSec Default value to be used by all OnTimeBODeviceDefault
2,000,000,000 device level INI parameters. The
mSec OnTimeBODeviceDefault in turn defines the default value
for all momentary Binary Output closure times for that
device (unit). Each Binary Output can have its closure
time individually configured.
[DNPR] OffTimeBODNPDefault 0 to 1000 mSec Default value to be used by all OffTimeBODeviceDefault
2,000,000,000 device level INI parameters. The
mSec OffTimeBODeviceDefault in turn defines the default value
for all momentary Binary Output opening times for that
device (unit). Each Binary Output can have its opening
time individually configured
[DNPR] QueueBODNPDefault 0 to 1 0 Default value to be used by all QueueBODeviceDefault
device level INI parameters. The QueueBODeviceDefault
in turn defines the default ‘queue’ setting value for all
momentary Binary Output operations for that device
(unit). Each Binary Output can have its ‘queue’ setting
value individually configured
[DNPR] ClearBODNPDefault 0 to 1 0 Default value to be used by all ClearBODeviceDefault
device level INI parameters. The ClearBODeviceDefault
in turn defines the default ‘clear’ setting value for all
momentary Binary Output operations for that device

CitectSCADA DNPr Driver 18/08/2005 Page 46 of 85

 Citect Pty Ltd Driver User Guide

(unit). Each Binary Output can have its ‘clear’ setting

value individually configured
[DNPR] CountBODNPDefault 0 to 255 1 Default value to be used by all CountBODeviceDefault
device level INI parameters. The CountBODeviceDefault
in turn defines the default ‘count’ setting value for all
momentary Binary Output operations for that device
(unit). Each Binary Output can have its ‘count’ setting
value individually configured
[DNPR] DataLagDefault 0 to 0 Sec Data in cache is only considered fresh if it is no older than
2,000,000,000 the combined periods of :
Sec - Period between Integrity Polls AND
- Period of complete timeout sequence (ie initial and
retried timeouts) AND
- DataLagDefault period (tolerated poll delay)
The first time data is retrieved from cache for a unit and
the data is not fresh, error 0x61 is generated and a tag
read with virtual address LateRefresh will return TRUE.
This condition is reset when the late poll for the device is
eventually received.
[DNPR] DataInvalidationFactorDefault 0 to 65535 2 As explained in DataLagDefault, data in cache is only
considered to be fresh for a certain amount of time. When
this time has been exceeded, the data is considered to be
valid, but not fresh. If the data in cache is still not
refreshed after a further ‘n’ Event periods of time (where
‘n’ = DataInvalidationFactorDefault), then the data in
cache is no longer considered valid, and all data retrieved
from cache in this state will be marked with error 0x54
[DNPR] TransDelay 0 to 65,535 0 mSec Transmission Delay for use in RS485 networks
mSec

[DNPR] MaxDNPTimeOuts 0 to 65535 1 Number of unit timeout errors before returning a ‘unit
offline’ reply. Unit timeout errors can result from both
Citect requests and driver polls. (timeout error may result
from Citect request or driver poll). Refer also to parameter
[DNPR] RapidOfflineDetectionDefault
[DNPR] ReqDelay 0 to 65535 60 mSec Delay used when servicing a read request by reading
mSec from cache.

[DNPR] EnablePollPeriodWritesDefault 0 to 1 0 Enable the adjustment of the device’s poll period via
writing to a tag of address ‘PollPeriod’. This is a security
feature to ensure that an operator is not inadvertently
given access to adjust the poll period.
0 = FALSE
1 = TRUE
[DNPR] RapidOfflineDetectionDefault 0 to 1 1 If RapidOfflineDetectionDefault is set to 0 (false), then a
unit will only be placed offline due to a comms failure
detected in regular polling requests. Failure of other
Citect requests (eg Tag Writes), will not be taken into
account when determining a units on-line status. This
parameter allows the driver to be configured to either
provide rapid detection of offline status, or to provide a
consistent interval of time before a unit is marked as
offline.
0 = FALSE
1 = TRUE
[DNPR] AutoUnsolicitedEnableDefault 0 to 7 7 This provides the ability to explicitly specify the classes to
be enabled for unsoliciteds at start-up. Currently when a
device is brought on-line, the driver will send a command
to enable unsolicited responses for all classes. An
additional INI Parameter [DNPR]
AutoUnsolicitedEnableDefault has been added to allow
the user to specify which classes are to be enabled
automatically. Acceptable values for this parameter are ‘1’
for Class1, ‘2’ for Class2, ‘4’ for Class3, or a combination
thereof. A value of zero (0) will result in NO classes being
enabled for unsoliciteds. The onsist value is to enable
all classes (value of ‘7’). To provide configuration down to
the device level, a corresponding INI parameter[<unit>]
AutoUnsolicitedEnable has also been implemented. The
default value for this INI parameter is the value from
[DNPR] AutoUnsolicitedEnableDefault. Note that the
driver also has a ‘virtual’ data type for enabling/disabling
unsolicited responses in a unit. The classes enabled will
be as specified by this parameter.

CitectSCADA DNPr Driver 18/08/2005 Page 47 of 85

 Citect Pty Ltd Driver User Guide

[DNPR] SyncReplicationDefault 0 to 1 0 This provides the ability to stop all transmissions at the
data-link layer level to DNP Devices while waiting for data
to be replicated to the peer. This is to ensure that the
device does not receive an acknowledgement until the
data has been safely replicated.
[DNPR] DataLinkFrameSize 28 to 292 292 For DNP devices that have small data link layer frames,
then for the same size application layer buffer, more data
link layer frames will be produced. The library that the
DNPr driver utilises was previously assuming that the
DNP device would have a maximum data link layer frame
size of 292 bytes, and an application layer fragment
maximum size of 2048 bytes. This combination would
result in a maximum of 9 frames per fragment. The library
has been modified such that it will allow up to 64 frames
per fragment, however the main practical restriction
introduced is that the resulting application layer data from
the combined frames will not overflow the application
layer buffer. Now DNP devices with maximum data link
layer frame size of less than 292 bytes are also
supported.
Similarly, the INI parameter “[DNPR] DataLinkFrameSize”
allows the specification of the Max data link layer transmit
frame size. The default value is 292 bytes. The parameter
value is upper limited to 292 bytes, and lower limited to 28
bytes.
[DNPR] AddressPaddingWidth 0 to 64 0 When the driver receives a time-stamped event, it needs
to determine the tag(s) associated with the event. It does
this by determining the address field of the tag that would
be associated with this event, from the Object, Variation
and Index. This algorithm assumes that the address does
not use any leading zeros for the point index (eg BI1.Val
not BI00001.Val). If you wish to use leading zeros, then
you must onsistently use the same padding width for all
relevant addresses, and you must also define this
padding width with the INI parameter “[DNPR]
AddressPaddingWidth”. The default is 0 (ie no padding).
This mechanism will not truncate the index to the
specified digits, it will only pad leading zeros if required.
Eg for a point index of 12 : 0 => 12, 1 =>12, 2 =>12, 3
=> 012, 4 => 0012, etc.
This INI parameter is available in version 1.03.02 of the
driver (or later).
DNP AlarmScanTime 0 to 60,000 [ALARM]Sc This provides the ability to explicitly specify the alarm
(ms) antime padding delay used in the processing of time-stamped
alarms. If the project has the alarm server resident on a
separate machine to the I/O server, then the new INI
parameter [DNPR] AlarmScanTime must be set to the
scan time used by the alarm server, as the [ALARM]
ScanTime parameter will be be used by the I/O server. As
the [DNPR] AlarmScanTime defaults to the value of
[ALARM] ScanTime, only the [ALARM] ScanTime needs
to be adjusted when the I/O server and the alarm server
reside on the same machine. Refer to Processing of
Timestamped Event Data in the help file for more
information on time-stamped alarm.
[DNPR] StartupDelay 0 to 0 Allows the unit initialisation (and subsequent online
‘WatchTime’ check) to be delayed. This INI parameter can be used, in
Seconds conjunction with a Cicode IODeviceControl() call at start-
up, to disable units before they transmit an online check
for unit initialisation.
A delay of a couple of seconds should suffice. Do not
delay more than the WatchTime.
[DNPR] DnpProtocolFilter 0 to 0xFFFF 0xFFFF Bitmask indicating detail required for protocol diagnostic
reporting. The bitmask is the logical OR of the following.
TRANSACTIONS 0x8000
ERRORS 0x4000
LINK DATA 0x0001
TRANSPORT DATA 0x0002
APPLICATION DATA 0x0004
STATIC OBJECTS 0x0008
COS OBJECTS 0x0200
SOE OBJECTS 0x0400
APPL TRANSMIT DELAYS 0x0800
STATIC DBASE 0x0010
COS DBASE 0x0080

CitectSCADA DNPr Driver 18/08/2005 Page 48 of 85

 Citect Pty Ltd Driver User Guide

SOE DBASE 0x0100

USER DATA 0x0020
SCADA MMI 0x0040
Setting bitmask to 0x8000 is invalid, TRANSACTIONS
must be used in conjunction with other option(s).
Default of 0xFFFF selects everything.
[DNPR] RetZeroOnCROBInvalid 0 to 1 0 Flag indicating whether Binary Output Control Status data
is to be tested for validity (before a Binary Output Control
Status point can be valid, a value must be written to the
corresponding binary point). If not tested for validity, then
if an invalid Binary Output Control Status point is read,
then a zero will be displayed. If the type IS to be tested
for validity, then if any point within a Citect multiple point
request is invalid, then the response to the request
indicate an error condition. A solution in this case might
be to write to all Binary points at startup.
0=Test validity of Binary Output Control Status data
1= Do not test validity of Binary Output Control Status
data.
[DNPR] RetZeroOnAOOBInvalid 0 to 1 0 Flag indicating whether Analog Output Control Status
data is to be tested for validity in the same manner as for
RetZeroOnCROBInvalid above.
0=Test validity of Analog Output Control Status data
1= Do not test validity of Analog Output Control Status
data.
[DNPR] UseFeedBackPoll 0 to 3 1 0=Use Integrity poll instead of Feedback Poll
to update cache after control action.
1=Use Feedback poll to update cache after counter
freeze or analogue or binary writes (Feedback Poll
requires devices to support reads to Binary Output Status,
Analog Output Status, Binary Inputs, Analog Inputs,
Counters and Frozen Counters) . This mode requires
Level 3 DNP support in the RTU.
2= Do not perform any type of immediate poll after a
control write. This mode will been implemented for
devices that can provide an unsolicted update of any
feedback changes (caused by control writes).
3= Use an individual point read to update the cache after
analogue or binary writes. NOTE: This option still does
the Level 3 option from mode 1 for counters and frozen
counters.
[DNPR] MinorIINSelectFilter Refer to 0xFFFF This parameter allows the user to turn on the ability of the
description driver to generate a driver error
(CDNP_WARN_IIN_ERROR) to notify the user of several
IIN (Internal indications bits) errors. These IIN errors are
normally not considered serious, and are usually only
treated as warnings.
Any combination of the following IIN errors can be
detected by OR-ing the selected IIN error bits together to
create the MinorIINSelectFilter value. It should be noted
that the errors are only notified under certain conditions.
The conditions are noted in the Driver Specific errors
section. The IIN bit errors that can be OR-ed together for
selection purposes are shown below. The meanings of
the terms are also described in the Driver Specific errors
section.
BUFFER_OVFL 0x0008
EXECUTING_IIN 0x0010
CONFIG_IIN 0x0020
LOCAL_IIN 0x2000
TROUBLE_IIN 0x4000
Note that the user can define tags to determine the status
of the IIN flags returned from the device.
Note also that CDNP_WARN_IIN_ERROR is only a
warning level driver error and will not generate any
#COMs on the screen.
[DNPR] MinorIINSelectErrorFilter Refer to 0x0000 This parameter allows the user to turn on the ability of the
description driver to generate a driver error
(CDNP_ERR_IIN_ERROR) to notify the user of several
IIN (Internal indications bits) errors. These IIN errors are
normally not considered serious, and are usually only
treated as warnings, however in some circumstances, the
IIN errors may need to be treated as if the unit has failed.
Any combination of the following IIN errors can be
detected by OR-ing the selected IIN error bits together to

CitectSCADA DNPr Driver 18/08/2005 Page 49 of 85

 Citect Pty Ltd Driver User Guide

create the MinorIINSelectErrorFilter value. It should be

noted that the errors are only notified under certain
conditions. The conditions are noted in the Driver
Specific errors section. The IIN bit errors that can be OR-
ed together for selection purposes are shown below.
The meanings of the terms are also described in the
Driver Specific errors section.
BUFFER_OVFL 0x0008
EXECUTING_IIN 0x0010
CONFIG_IIN 0x0020
LOCAL_IIN 0x2000
TROUBLE_IIN 0x4000
Note that the user can define tags to determine the status
of the IIN flags returned from the device.
Note also that CDNP_ERR_IIN_ERROR is a severe level
driver error and will force the unit offline and generate
#COMs on the screen.
[DNPR] IsItemisedRequest 0 to 1 1 Requests for a basic DNP poll do not use a blocking
(grouping) algorithm as applies to most protocols. Instead
the required points are predefined in the device (as Class
0), and are requested during an integrity poll. The DNPr
driver can support requests of up to 2048 bits in one
request from Citect, but this is for contiguous data. The
data available in the driver cache will not be contiguous if
the predefined points in Class 0 are not contiguous. This
would result in that all points Citect request will be flagged
as bad quality (#COM) if any one of the points in the
requested block are not defined in Class 0. To prevent
this situation from occurring, non-digital data is not
blocked by default. All requests from Citect to the driver,
for non-digital data, are for individual points. Note that this
does not effect the data acquisition algorithm between the
driver and the device, only between Citect and the driver.
Digital types still will be optimised together. A device may
have digital types as a non-contiguous list, and may start
or end on points not on an 8 bit boundary. As Citect will
block a minimum of 8 bits for digitals, and enforce an 8 bit
boundary, the driver assumes that all bits that are not
updated by the polling sequence are irrelevant and not
configured as tags by the user. These points will always
return 0 and NO_ERROR to avoid forcing the valid points
in the same DCB into error. The flag Commissioning tests
for invalid BI points.
The default should provide the best solution for a DNP
project, however, if it is decided by a Citect representative
that blocking is required between the driver and Citect,
set IsItemisedRequest to zero. You must change
MAX_LENGTH and BIT_BLOCK fields for the DNP
protocol (in the \CITECT\BIN\PROTDIR.DBF file) to the
required blocking length in bits, and copy the PROTDIR
file to your Citect project directory. Modify the CITECT.INI
file to configure the ‘Block’ parameter to the required
value in bytes, and also the ‘MaxBits’ parameter to the
required value in bits. Disable the incremental compile
option and then RE-COMPILE your project. Note, if you
reinstall Citect, the PROTDIR.DBF file is overwritten –
you must repeat the change.
1=Individual Citect-to-Driver Non-digital requests
(RECOMMENDED)
0= Citect-to-Driver requests are blocked
(default applies to all devices)
[DNPR] MaxBits 1 to 2048 Bits 2048 Bits Max Block Size constant (only applies when
IsItemisedRequest is set to zero).
This value should be left at default unless modifying
IsItemisedRequest parameter to block read requests to a
specific value.
Refer to description of IsItemisedRequest.
Note that this field only applies to read requests, writes
will be allowed to the maximum that will result in one
Application Layer fragment, but can not be greater than
2048 bits. (Write blocking can be disabled by setting the
INI parameter [<IOServer>] ‘Blockwrites’ to 0 )
[DNPR] Commissioning 0 to 1 0 A device may have digital types as a non-contiguous list,
and may start or end on points not on an 8 bit boundary.
As Citect will block a minimum of 8 bits for digitals, and

CitectSCADA DNPr Driver 18/08/2005 Page 50 of 85

 Citect Pty Ltd Driver User Guide

enforce an 8 bit boundary, Citect requests may include

points that are not received by the device or that are
invalid for the device. For this reason, the driver assumes
that all bits that are not updated by the polling sequence
are irrelevant and not configured as tags by the user.
These points will always return 0 and NO_ERROR to
avoid forcing the valid points in the same DCB into error.
The driver waits until the first successful data acquisition
poll, before determining if a point as irrelevant. The user
MUST commission all points of the project to ensure that
every tag does in deed refer to a point that is refreshed by
the polling routine. The flag Commissioning tests for
invalid BI points, by not forcing the point to 0 and
NO_ERROR. This will then #COM all points in the DCB
containing the invalid digital point.
0= Treat non-polled points as irrelevant
1= Force non-polled points to #COM
(default applies to all devices)
Also when this INI is set, the event system will log to
"dnpr_logger.txt" the name of tags which are considered
irrelevant. e.g.
"#TRACE,Irrelevant_point,BI023,in,Unit_035"
[DNPR] StartupStaggerDelay 0 to 30000 0 Time between allowing the first unit on each port to come
online at startup. This is to avoid large amounts of startup
traffic.
[DNPR] LogCacheElement 0 to 1 0 Flag indicating if all elements in cache are to be itemised
to FAULTFND.LOG, in user project directory, at
shutdown.
This is for fault-finding purposes.
0=NO
1=YES
[DNPR] MaxMsgPerPollTime 1 to 100000 500 The maximum number of peer update messages the peer
manager is allowed to process each PollTime.
[DNPR] IPonECPModeDefault 0 to 3 2 Defines the follow-up action to be taken when a response
is received with any of the Class 1, 2, or 3 IIN bits set:
0 – For any response, immediately issue an Event Poll
1 – For any response, immediately issue an Integrity Poll
2 – For an Integrity Poll response, immediately issue
another Integrity Poll, for any other response immediately
issue an Event Poll
3 – Disables any polls being issued on IIN bits set except
the Overflow bit
4 – Disables any polls being issued on IIN bits including
the overflow bit.
[DNPR] ChannelTransmissionsPerCpuCo 0 to 20 0 Each polltime, messages are sent to each RTU if
unt messages are waiting. The default behaviour is to send
these out in the order they exist in the driver (when set to
0). However, some RTUs like the messages to go out on
one COMs channel, then the next etc. Setting this value
allows this behaviour to happen, e.g. if set to 2, and data
was waiting for Ports 0,1,2,3, then the first polltime scan
would send data out on Port 0, then Port 1, then wait until
the next polltime scan, and send data out to Port 2, then
Port 3.
[DNPR] EventQueSizeHighWatermark 0 to 50000 Defines a high watermark for the event queue. If this is
4,000,000,000 exceeded an error message will be displayed in the
kernel. A value of 0 will disable this check.
[DNPR] EventQueReadTimeout 0 to 0 Defines a timeout which displays an error message in the
4,000,000,000 kernel if the cicode event processing function is not
milliseconds extracting events within the timeout period. A value of 0
will disable this check.
[DNPR] UnitUsurpModeDefault 0, 1, 2 0 Defines the default ehaviour on usurp of a unit. The
value of 0 means that an Integrity Poll will be issued. The
value of 1 means that an RTU time read will be issued.
The value of 2 means nothing will be done.

The online status of the rtu is replicated between servers.

So regardless of what the value is set to the unit will
initially have the same status as it had on the other
server. The polling sequence is also replicated, so the
next periodic poll on the unit will occur at the same time it
would have if the usurp had not occurred (unless a value
of 0 is used, which results in the poll period being reset).
[DNPR] IntegrityPollOnUnsolicitedDefault 0 to 1 0 Defines the default behaviour of whether unsolicited data
from the device causes an integrity poll when the device

CitectSCADA DNPr Driver 18/08/2005 Page 51 of 85

 Citect Pty Ltd Driver User Guide

is offline, in order to bring the device online if possible.

[DNPR] IgnoreReadErrorsOnWrite 0 or 1 0 If set, reads of write only tags return 0000 data and no
error. This is needed when using dialup devices as Citect
reads ALL tags at connect time.
[DNPR] MaxOperateDelayDefault 1000 to 60000 5000 ms The RTU configured max. delay between a SELECT to
OPERATE command in ms. . This is used in the driver to
freeze any polling for up to this period to allow the
OPERATE command to work.
[DNPR] UseSelectClear 0 or 1 0 Default way to handle a cancel of select operation. This is
to issue an OPERATE with the CLEAR bit set. If you RTU
hardware has issues with this, then setiing this INI to 0
will issue a dummy time read instruction to cancel the
SELECT operation (that is because the OPERATE
command has to be the next sequence number and a
dummy command will force the SELECT to fail.)
[DNPR] EventPollRatioClass1Default 0 to x 1 How many event polls to issue ones for Class1. 0 will turn
Class1 polls off. (NB: The INTEGRITY poll will still ask
for class 1 static data)
[DNPR] EventPollRatioClass2Default 0 to x 1 How many event polls to issue ones for Class2. 0 will turn
Class2 polls off. (NB: The INTEGRITY poll will still ask
for class 2 static data)

[DNPR] EventPollRatioClass3Default 0 to x 1 How many event polls to issue ones for Class3. 0 will turn
Class3 polls off. (NB: The INTEGRITY poll will still ask
for class 3 static data)
[DNPR] ProcessTrendEvents 0 to x 1 Controls if you want event trends to be processed. With it
off only alarm events are processed.
[DNPR] UTCTimeSyncDefault 0 or 1 0 Sets whether UTC or local time is used for events and
TimeStamp tags. The default is local time.
[DNPR] IgnoreWarnIfOneOK 0 or 1 0 This INI when set will override warnings for missing or
stale data in a read block provided at least one item in the
block is OK. This is useful when points are not configured
in the RTU and the read block is requesting these, but
Citect does not use them. This INI applies to digital points
as well as other points.
[DNPR] CpuCheckTimeout 4000 up 20000 ms Timeout for no CPU() calls to decide that an IOServer is
locked up. The aim here is to set a time to decide that an
IOServer is stuck and cause this to USURP all units to
the peer IOServer (provided TCPIP communications still
exist).
[DNPR] EventDelayNoCheck 0 or 1 0 With EventDelayNoCheck=1 set, no alarm / trend prefix
is checked and all events are pushed up, HOWEVER any
repeated event will automatically be delayed by
alarmscantime . This mode can be used during testing
when all trends or alarms are not created to see what is
coming up (assume [dnpr]cicodetrace=1) from the dnpr
driver.
[DNPR] EventQueSizeHighPurge 0 or 1 0 When set old events will be purged above the high water
mark. If EventQueDeleteLog is set then a record of this
delete is logged.
[DNPR] EventQueSizeHighWatermark 1 up 100000 High water event queue size for warning message. This
may need the EventQueSizeHighPurge set to stop the PC
from running out of memory on trend server loss.
1
[DNPR] EventQueDeleteLog 0 or 1 0 When set purged and forced removal of events will be
logged to citect\bin\dnpr_logger.txt.
NOTE: This file is not rolled over so its size may become
very large.
[DNPR] EventProcessingEnable 0 or 1 1 Allows all event processing to be disabled when 0.
Useful during testing.
[DNPR] EventQueRequeTimeout 0 up 0 ms When asynchronous processing of events is taking place
(items removed from the event queue without being
deleted) this parameter allows a timeout before the event
is presented again as "fresh" (the assumption being the
event has not been removed). This INI is tied to the
EventQueRequeCount INI.
[DNPR] EventQueRequeCount 0 up 0 Retry count on an event before it is removed from the
event queue. If EventQueDeleteLog is set then the
removal is logged.

1
The user needs to ensure the emergency log file "dnpr_logger.txt" is managed themselves. If the file grows too
large this will adversely affect the performance of the dnpr driver.

CitectSCADA DNPr Driver 18/08/2005 Page 52 of 85

 Citect Pty Ltd Driver User Guide

[DNPR] EventEngScalingEnable 0 or 1 1 When set INT, LONG and REAL values will be scaled to
engineering units if these are set as they are pushed into
the event system.
[DNPR] EventSeqPrimary 0 or 1 1 A setting available to distinguish primary or standby
server event sequence numbers. Default 1 :
1 to 0x3fffffff event seq numbers
EventSeqPrimary=0
0x40000001 to 7fffffff event seq numbers
This may be used later in user cicode s/w for event
purging. At roll over, the same range is reused.

3.9.3.2 Parameters that are periodically read by the driver

These parameters are read every few seconds by the driver. Thus these values can be changed “on
the fly”. E.g. turn logging on or off. . NB: All these parameters require the driver debug mode to be set
to “error” or “all” for information to be placed in syslog.dat .

[DNPR] SCADADebugging 0 to 1 1 Enables detailed trace messages to view the operation of

the driver.
Temporarily disabling this flag will allow the user to
concentrate on other forms of diagnostic trace messages.
Read at driver start-up and every 2 seconds at runtime.
[DNPR] ProtocolDebugging 0 to 1 0 Enables diagnostic trace messages to view the
interaction between Citect and RTU(s) over the DNP
protocol.
The level of detail (the amount of layers of the protocol)
for the trace can be set by the DnpProtocolFilter
parameter.
Read at driver start-up and every 2 seconds at runtime.
[DNPR] UnitStateDebugging 0 to 1 0 Enables diagnostic trace messages to view unit active
state. This is part of driver redundancy.
Read at driver start-up and every 2 seconds at runtime.
[DNPR] ReplicationDebugging 0 to 1 0 Enables diagnostic trace messages to view replication of
updated cache data between peers. This is part of driver
redundancy.
Read at driver start-up and every 2 seconds at runtime.
[DNPR] DcbErrorDebugging 0 or 1 0 Enables diagnostics when a driver is reporting an error to
return the line of code reporting the error.
[DNPR] TimeNowMs 0 to infinity 0 Test mode INI that allows the time since PC startup to be
set for the driver at startup or during running. This would
be used in testing roll over of signed and unsigned
LONGs . This setting does not affect time of day data, oly
the internal count used for period work.

3.9.3.3 Parameters that apply in scope only to a specific device group

Section Function Range Default Comments

[<unit>] Timeout 1 to 32000 [DNPR] This is the same functionality as the standard parameter
mSec Timeout Timeout, but only applies to units in this device group
mSec
[<unit>] TimeoutExtension 0 to [DNPR] Extension to be added to the [<unit>] ‘Timeout’
2,000,000,000 Timeout- parameter. This extension is only required if a timeout
mSec Extension- greater than 32,000 milliseconds is needed.
Default
mSec
[<unit>] Retry 0 to 8 [DNPR] This is the same functionality as the standard parameter
Retry Retry, but only applies to units in this device group. This
is used as the number of application layer retries in the
DNP context.
[<unit>] EventPollPeriod 0 to 4,00,000 EventPoll- Period to poll device for event class data.
Sec Period- Integrity poll will poll for all classes (event and static
Default data), and occurs after every EventPollRatio event polls.
Sec
[<unit>] EventPollRatio 0 to 65,535 EventPoll- Number of event class polls for every integrity poll.
Ratio- Integrity poll will poll for all classes (event and static
Default data). Note that a value of zero implies that only integrity
polls are conducted.

CitectSCADA DNPr Driver 18/08/2005 Page 53 of 85

 Citect Pty Ltd Driver User Guide

[<unit>] PollPeriodOffset 0 to 0 The amount of time in seconds before the first periodic
2,000,000,000 poll occurs for this unit. A common start time is used for
Sec all units for this calculation. Subsequent polls occur every
EventPollPeriod after the first poll, thus the offset is
maintained between units for all subsequent polls.
[<unit>] ResponseMode 1 to 15 Response- Combination of: 1=Polled, 2=Unsolicited enabled, 4=Use
Mode- Delay Measurement,
Default 8 = perform time synch when requested.
[<unit>] DataLinkConfirm 0 to 2 DataLink- Modes allowed:
Confirm- 0 = Never, 1 = Sometimes, 2 = Always
Default (Sometimes = Multiframe only)
[<unit>] DataLinkTimeOut 1 to 65,535 DataLink- Waiting period since last frame for a data link confirm –
mSec TimeOut- only if confirm requested
Default
mSec
[<unit>] DataLinkRetrys 0 to 255 DataLink- Number of attempts to retransmit after a data link timeout
Retrys-
Default
[<unit>] DataLinkNoRetriesOnControls 0 to 1 0 If set to 1 then there are no data link layer retries when
sending control messages such as direct operate, or
select/operate. If set to 0 then normal retries apply.
Note: The data link layer will only retry if data link layer
confirmations are used, see DataLinkConfirmDefault.
[<unit>] AppLayerTimeOut 1 to [<unit>] Waiting period for application layer response.. We
2,000,000,000 Timeout + recommend that it should be set to approximately 10
mSec [<unit>] times the DataLinkTimeOut to allow for confirms and link
Timeout- layer resets that may happen as part of a successful
Extension application layer transaction. You do not have to allow for
the number of frames or fragments that are sent as part of
an integrity poll, as the timeout gets reset when each
frame of each response fragment is received. The timer
is also reset when a data link layer transaction times out.
[<unit>] OnTimeBODeviceDefault 0 to OnTimeBO Default closure time for Binary Output operations in this
2,000,000,000 DNPDefault device.
mSec mSec

[<unit>] OffTimeBODeviceDefault 0 to OffTimeBO Default opening time for Binary Output operations in this
2,000,000,000 DNPDefault device.
mSec mSec
[<unit>] QueueBODeviceDefault 0 to 1 QueueBO- Default ‘queue’ setting for Binary Output operations in this
DNPDefault device.

[<unit>] ClearBODeviceDefault 0 to 1 ClearBO- Default ‘clear’ setting for Binary Output operations in this
DNPDefault device.

[<unit>] CountBODeviceDefault 0 to 1 CountBO- Default ‘count’ setting for Binary Output operations in this
DNPDefault device.

[<unit>] DataLag 0 to DataLag- Data in cache is only considered fresh if it is no older than
2,000,000,000 Default Sec the combined periods of :
Sec - Period between Integrity Polls AND
- Period of complete timeout sequence (ie initial and
retried timeouts) AND
- DataLag period (tolerated poll delay)
The first time data is retrieved from cache for a unit and
the data is not fresh, error 0x61 is generated and a tag
read with virtual address LateRefresh will return TRUE.
This condition is reset when the late poll for the device is
eventually received.
[<unit>] DataInvalidationFactor 0 to 65535 DataInvalid- As explained in DataLagDefault, data in cache is only
ationFactor- considered to be fresh for a certain amount of time. When
Default Sec this time has been exceeded, the data is considered to be
valid, but not fresh. If the data in cache is still not
refreshed after a further ‘n’ Event periods of time (where
‘n’ = DataInvalidationFactor), then the data in cache is no
longer considered valid, and all data retrieved from cache
in this state will be marked with error 0x54
[<unit>] MaxTimeOuts 0 to 65535 MaxDNP- Number of unit timeout errors before returning a ‘unit
TimeOuts offline’ reply. Unit timeout errors can result from both
Citect requests and driver polls. (timeout error may result
from Citect request or driver poll). Refer also to parameter
[<unit>] RapidOfflineDetection
[<unit>] EnablePollPeriodWrites 0 to 1 EnablePoll Enable the adjustment of the device’s poll period via
PeriodWrite writing to a tag of address ‘PollPeriod’. This is a security
sDefault feature to ensure that an operator is not inadvertently

CitectSCADA DNPr Driver 18/08/2005 Page 54 of 85

 Citect Pty Ltd Driver User Guide

given access to adjust the poll period.

0 = FALSE
1 = TRUE
[<unit>] RapidOfflineDetection 0 to 1 Rapid- If RapidOfflineDetection is set to 0 (false), then a unit will
Offline- only be placed offline due to a comms failure detected in
Detection- regular polling requests. Failure of other Citect requests
Default (eg Tag Writes), will not be taken into account when
determining a units on-line status. This parameter allows
the driver to be configured to either provide rapid
detection of offline status, or to provide a consistent
interval of time before a unit is marked as offline.
0 = FALSE
1 = TRUE
[<unit>] AutoUnsolicitedEnable 0 to 7 [DNPR]Aut This provides the ability to explicitly specify the classes to
oUnsolicite be enabled for unsoliciteds at start-up. Currently when a
dEnableDef device is brought on-line, the driver will send a command
ault to enable unsolicited responses for all classes. An
additional INI Parameter [DNPR]
AutoUnsolicitedEnableDefault has been added to allow
the user to specify which classes are to be enabled
automatically. Acceptable values for this parameter are ‘1’
for Class1, ‘2’ for Class2, ‘4’ for Class3, or a combination
thereof. A value of zero (0)will result in NO classes being
enabled for unsoliciteds. The default value is to enable all
classes (value of ‘7’). To provide configuration down to
the device level, a corresponding INI parameter[<unit>]
AutoUnsolicitedEnable has also been implemented. The
default value for this INI parameter is the value from
[DNPR] AutoUnsolicitedEnableDefault. Note that the
driver also has a ‘virtual’ data type for enabling/disabling
unsolicited responses in a unit. The classes enabled will
be as specified by this parameter.
[<unit>] SyncReplication 0 to 1 [DNPR]Syn This provides the ability to stop all transmissions at the
cReplicatio data-link layer level to the given DNP Device while waiting
nDefault for data to be replicated to the peer. This is to ensure
that the device does not receive an acknowledgement
until the data has been safely replicated.
[<unit>] IPonECPMode 0 to 3 [DNPR]IPo Defines the follow-up action to be taken when a response
nECPMode is received with any of the Class 1, 2, or 3 IIN bits set:
Default 0 – For any response, immediately issue an Event Poll
1 – For any response, immediately issue an Integrity Poll
2 – For an Integrity Poll response, immediately issue
another Integrity Poll, for any other response immediately
issue an Event Poll
3 – Disables any polls being issued on IIN bits set
[<unit>] UnitUsurpMode 0, 1, 2 [DNPR] Defines the default bahaviour on usurp of a unit. The
UnitUsurpM value of 0 means that an Integrity Poll will be issued. The
odeDefault value of 1 means that an RTU time read will be issued.
The value of 2 means nothing will be done.

The online status of the rtu is replicated between servers.

So regardless of what the value is set to the unit will
initially have the same status as it had on the other
server. The polling sequence is also replicated, so the
next periodic poll on the unit will occur at the same time it
would have if the usurp had not occurred (unless a value
of 0 is used, which results in the poll period being reset).
[<unit>] IntegrityPollOnUnsolicited 0 to 1 [DNPR]Inte Defines the behaviour of whether unsolicited data from
grityPollOn the device causes an integrity poll when the device is
Unsolicited offline, in order to bring the device online if possible.
Default
[<unit>] MaxOperateDelay 1000 to 60000 [DNPR] The RTU configured max. delay between a SELECT to
MaxOperat OPERATE command in ms. This is used in the driver to
eDelayDefa freeze any polling for up to this period to allow the
ult OPERATE command to work.
[<unit>] EventPollRatioClass1 1 0 to x How many event polls to issue ones for Class1. 0 will turn
Class1 polls off. (NB: The INTEGRITY poll will still ask
for class 1 static data)
[<unit>] EventPollRatioClass2 1 0 to x How many event polls to issue ones for Class2. 0 will turn
Class2 polls off. (NB: The INTEGRITY poll will still ask
for class 2 static data)
[<unit>] EventPollRatioClass3 1 0 to x How many event polls to issue ones for Class3. 0 will turn
Class3 polls off. (NB: The INTEGRITY poll will still ask
for class 3 static data)

CitectSCADA DNPr Driver 18/08/2005 Page 55 of 85

 Citect Pty Ltd Driver User Guide

[<unit>] UTCTimeSync 0 or 1 0 Sets whether UTC or local time is used for events and
TimeStamp tags. The default is local time.
Where:
<unit> The INI section name that corresponds with the name for a device group
(Device_Group) defined in the ‘Address’ field of the IODevice’s form. These
parameters are used to configure behaviour that will only apply to units that
have their Device_Group name defined as the same name used as the INI
section name <unit>.
text Not currently supported (only Level 1 and Level 2 supported)

3.9.3.4 INI Parameters related to Peer Redundancy

Section Function Range Default Comments

[DNPR] EnablePeerRedundancy 0 or 1 0 1 to Enable peer driver redundancy. Only 1 peer driver is
supported.
[DNPR] PeerAddress Valid IP NONE The IP address of your peer driver
address

[DNPR] PeerPort Port 5200 Any Valid Peer Destination Port

[DNPR] LocalAddress Valid IP 127.0.0.1 The IP address of yourself for listening on
address
[DNPR] LocalPort Port 5000 Valid Port you want to listen on
[DNPR] PeerTimeout 1 to 65535 4000 Timeout time in getting a response back from your peer.
[DNPR] PeerKeepAliveTime 1 to 65535 30000 Ping time between pairs to check “they are there”
[DNPR] MaxMsgPerPollTime 1 to 500 The maximum number of peer cache updates to be
4294967295 processed per call to Cpu() which is controlled by the
“PollTime” parameter.
[DNPR] PeerCommRetryCount 0 to 10 3 Retries allowed on peer messages before the peer
comms are considered down.

3.9.3.5 INI Parameters related to Calculated Variables

Section Function Range Default Comments

[DNPR] DrvCalcsVarEnable 0 or 1 0 1 to enable the calculated variable engine.
[DNPR] DrvCalcsVarOptions * 0x00 – 0x7F 0x0 The logging options for the calculated variable engine
which go to [RUN]:DrvUtils.log. These can be a
combination of the following values.

0x7f (128) – enables all traces in the calculated variable

engine
0x08 - enables summary traces of calculations
0x04 – enables tracing of initializing and shutdown
operations for the calculated variable engine
0x02 – enables tracing of all variable changes and
calculations
0x01 – enables tracing for recursion problems
0x00 – disables all logging except for forced variable
logging

[DNPR] VarToTrace * Valid tag “” (empty Enables forced logging of changes and associated
name string) calculations for a specific variable.
[DNPR] DrvCalcsVarConfigFile Valid filepath [DATA]:Cal Specifies the path for a global CSV file containing the
to a CSV file. culatedVari configured calculations. If the supplied file name fails it
ables.csv attempts to locate the file within the Citect [DATA]
directory.
[<Unit>] DrvCalcsVarConfigFile Valid filepath [DATA]:Cal Specifies the path for a unit level CSV file containing the
to a CSV file. culatedVari configured calculations. If the supplied file name fails it
ables_<IOD attempts to locate the file within the Citect [DATA]
eviceName directory.
>.csv

* These settings are read periodically and can be changed “on the fly”.

CitectSCADA DNPr Driver 18/08/2005 Page 56 of 85

 Citect Pty Ltd Driver User Guide

3.9.3.6 PORT Bases INIs

Section Function Range Default Comments

[DNPR_<PortNa ExclusiveAccess 0 or 1 0 When set, the port and units adopt exclusive access
me>] mode. In this mode only one server is physically
connected to the port. When a unit is usurped, the other
port connects after the originating port disconnects. See
section 2.6.8 for more info.

CitectSCADA DNPr Driver 18/08/2005 Page 57 of 85

Citect Pty Ltd Driver User Guide

3.9.3.7 Cicode Functions

The following parameters relate to the cicode file dnpr.ci shipped with this driver. This file controls the
handling of timestamped events (alarms and trends) from the driver into Citect. This information
comes directly from the driver and not via the IOServer in the form of DCBs. In most circumstances
this will not need site adjustment.
System designers are urged to look through this file. It has many comments in it.

A project must have the cicode RTUEventQueProcessing() function running.

This cicode can be activated by defining a Parameters form (from the System menu) as follows:
Section Name: Code
Name: Startup
Value: Tasknew("RTUEventQueProcessing",0)

See section 3.14 for details for configuring alarm and event tags.

Section Function Range Default Comments

[DNPR] CicodeLog 0..1 0 Flag indicating if trace statements from
Cicode event handling logic should be
itemised to DNPEvent.log, in user project
directory.
The trace statements document the
initialisation of the Cicode program as well
as detailing the event data handled by the
Cicode program (that have a Trend Tag or
TimeStamped Alarm Tag defined).
These trace statements will also be sent to
the syslog if CicodeTrace is active.
Note if Cicode is unable to open the file, then
all traces will be sent to the syslog
regardless of the CicodeTrace parameter.
This parameter is useful for fault-finding
purposes.
0=NO
1=YES
[DNPR] CicodeTrace 0..1 0 Flag indicating if trace statements from
Cicode event handling logic should be
itemised to syslog.dat, in windows directory.
The trace statements document the
operation of the Cicode program, and any
errors encountered during the processing of
the event data.
In addition, any trace statements produced
by CicodeLog will be included in syslog.
Note that as these trace statements are
produced by the Cicode and not by the driver
code, they are unaffected by the kernel
DEBUG commands.
Note also that the Cicode event handling
logic will print severe warnings to the syslog
regardless of the state of this flag.
This parameter is useful for fault-finding
purposes.
0=NO
1=YES
[DNPR] DatabaseLog 0..1 0 This parameter enables a database file of all
received events (that have a Trend Tag or
TimeStamped Alarm Tag defined) to be
logged. This functionality requires the
Devices form to be completed with an entry
labelled RTULog. The Format in the form
must correspond to that used in the Cicode
program (refer to a sample project for this
format). The file will reside in the location
described by the File Name field entry in the
Devices form.
0=NO
1=YES
[DNPR] ZoomTrendInUse 0..1 0 If a zoom trend is in use anywhere in the

CitectSCADA DNPr Driver 18/08/2005 Page 58 of 85

Citect Pty Ltd Driver User Guide

project, then this flag must be set, so that the

zoom trend display will correctly serviced
with the event data.
0=NO
1=YES
[DNPR] AlarmFixString Alarm tag prefix “A_” Read by dnpr.ci cicode as well as driver
[DNPR] TrendPeriodicFixString Periodic trend tag “T_” Read by dnpr.ci cicode as well as driver
prefix
[DNPR] TrendEventFixString Event trend tag prefix “E_” Read by dnpr.ci cicode as well as driver
[DNPR] TrendPeriodicEventFixStr Periodic event trend "P_" Read by dnpr.ci cicode as well as driver
ing tag prefix

CitectSCADA DNPr Driver 18/08/2005 Page 59 of 85

Citect Pty Ltd Driver User Guide

3.10 Driver Specific Errors

Driver Error Mapped to Meaning of Error Code

Code (Hex)
0x00050 GENERIC_SOFTWARE_ERROR Software driver error, this error shouldn’t happen
0x00051 GENERIC_SOFTWARE_ERROR Memory could not be allocated for cache
0x00052 GENERIC_TOO_MANY_COMMA Could not insert request to lower API layer because of existing duplicate
NDS request
0x00053 GENERIC_ADDRESS_RANGE_E A point, used in a write request, is invalid
RROR
0x00054 GENERIC_INVALID_DATA A point or points in read request not yet valid because older than
polltime
0x00055 GENERIC_BAD_PARAMETER User has set polltime to zero
0x00056 GENERIC_INVALID_COMMAND This type is write only
0x00057 GENERIC_ADDRESS_RANGE_E More points were requested than defined by user
RROR
0x00058 GENERIC_SOFTWARE_ERROR Invalid Tag Object read sub field
0x00059 GENERIC_SOFTWARE_ERROR No matching entry inTag Object table can be found
0x0005A GENERIC_INVALID_DATA A point or points in read request not valid
0x0005B GENERIC_SOFTWARE_ERROR Cannot find a matching dcb for a write response
0X0005C GENERIC_ADDRESS_RANGE_E Data does not exist in cache
RROR
0x0005D GENERIC_GENERAL_ERROR Unable to complete write comand
0x0005E GENERIC_UNIT_WARNING IIN Error detected.
The ability of the driver to detect any individual member of this group of
alarm conditions can be turned on and off using the Citect.ini parameter
MinorIINSelectFilter. Note: the default for the driver is to turn each of
these alarms ON. This Citect error will only be returned under the
following circumstances:
1) On Citect Write requests (for Analog Outputs, CROBs, Counter
Freeze and Restart requests), and will only be returned when there
are no other errors considered more serious for that request (e.g.
Analog Output/CROB status errors described above).
2) On a front end read request (e.g. a tag is displayed) following a
back-end periodic poll periodic poll where the error was detected.
Again this error will only be returned when there are no other
errors considered more serious resulting from the back end poll
(low level API application errors have precedence).
If this error occurs, it indicates one or more of the selected minor IIN
errors have occurred under the circumstances described above. The
error code can not differentiate which of the enabled IIN flag(s) has
caused the IIN error, to accomplish this, a “Debug * ALL” command
should be issued in the kernel, and the individual IIN flags will be
reported in the syslog through the protocol diagnostic reporting.
IIN flags that can be detected are:
LOCAL_IIN – Bit 5 in byte 1 of IIN – Outstation Digital Output(s) are in
Local mode (driver can not control)
TROUBLE_IIN – Bit 6 in byte 1 of IIN – Abnormal condition flagged in
Outstation (refer to device profile).
BUFFER_OVFL - Bit 3 in byte 2 of IIN – Outstation lost data from
overflow of event buffers
EXECUTING_IIN - Bit 4 in byte 2 of IIN – Request understood but
operation already executing
CONFIG_IIN - Bit 5 in byte 2 of IIN - Current configuration in Outstation
is corrupt.
0x0005F GENERIC_GENERAL_ERROR Can't open database - Citect form may be open
0x00060 GENERIC_GENERAL_ERROR Error - Detected in queue

CitectSCADA DNPr Driver 18/08/2005 Page 60 of 85

Citect Pty Ltd Driver User Guide

0x00061 GENERIC_GENERAL_ERROR Cache refresh late due to poll delays

0x00062 GENERIC_INVALID_DATA_TYPE Requested raw type invalid for native type
0x00063 GENERIC_UNIT_WARNING An error has occurred in a device using a virtual unit tag

0x00064 GENERIC_UNIT_WARNING General NULL pointer issue, e.g. a request has occurred internally for a
device no longer installed.

0x00065 GENERIC_UNIT_OFFLINE A unit has not been configured with primary or standby and peer redun-
dancy is in operation.
0x0068 GENERIC_UNIT_OFFLINE IIN Error detected using IIN filter settings.

0x0069 GENERIC_UNIT_REMOTE A unit is not online yet but is attempting to come online.
0x006A GENERIC_UNIT_REMOTE Error - Waiting for an RTU response before coming online
0x006B GENERIC_GENERAL_ERROR Port level warning that we can't get transport
0x10002 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 2 - Function code in
response not supported

0x10003 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 3 – Response sequence
number does not match most recent request
0x10004 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 4 –Response fragment
received with no active request
0x10005 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 5 - Object/Variation not
supported
0x10006 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 6 - Object/Qualifier
combination not supported

0x10007 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 7 – Response qualifier code
not supported
0x10008 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 8 - Timeout waiting for
application layer response fragment or restart
0x10009 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 9 - Object/Variation not
supported in read response
0x1000A GENERIC_GENERAL_ERROR Low Level API Application Layer error code 10 - Object/Variation not
supported in operate response
0x1000B GENERIC_GENERAL_ERROR Low Level API Application Layer error code 11 – Error considered
serious by low level API. Internal indications bits relating to remote
device parsing of last request indicate either:
1. Device does not recognise requested objects (Bit 1 in byte 2 of IIN ).
2. Outstation rejected application request as invalid or out of range due
to formatting errors (Bit 2 in byte 2 of IIN ).
1. Function code not implemented (Bit 0 in byte 2 of IIN ).
0x1000C GENERIC_GENERAL_ERROR Low Level API Application Layer error code 12 – Response does not
match request for ‘Select before Operate’

0x1000D GENERIC_GENERAL_ERROR Low Level API Application Layer error code 13 – Response to Restart
message does not include time object
0x1000E GENERIC_GENERAL_ERROR Low Level API Application Layer error code 14 - Object/Variation not
supported in write response

0x1000F GENERIC_GENERAL_ERROR Low Level API Application Layer error code 15 – Invalid device number
(index) in application layer transmit queue

0x10010 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 16 – Response to Delay
measurement does not include time object
0x10011 GENERIC_GENERAL_ERROR Low Level API Application Layer error code 17 – Message not
processed as unsolicited responses disabled
0x20001 GENERIC_GENERAL_ERROR Analog Output/CROB Status Value 1 – Bad control request –
OPERATE received after SELECT timeout (This Citect error will only be
returned on Citect Write requests)
0x20002 GENERIC_GENERAL_ERROR Analog Output/CROB Status Value 2 – Bad control request –
OPERATE received without prior SELECT (This Citect error will only be
returned on Citect Write requests)

CitectSCADA DNPr Driver 18/08/2005 Page 61 of 85

Citect Pty Ltd Driver User Guide

0x20003 GENERIC_GENERAL_ERROR Analog Output/CROB Status Value 3 – Bad control request – formatting
errors in control request (This Citect error will only be returned on Citect
Write requests)
0x20004 GENERIC_GENERAL_ERROR Analog Output/CROB Status Value 4 – Bad control request – control
request not supported for point (This Citect error will only be returned on
Citect Write requests)

0x20005 GENERIC_GENERAL_ERROR Analog Output/CROB Status Value 5 – Bad control request – control
queue full or point already active (This Citect error will only be returned
on Citect Write requests)
0x20006 GENERIC_HARDWARE_ERROR Analog Output/CROB Status Value 6 – Bad control request – not
accepted due to hardware problems (This Citect error will only be
returned on Citect Write requests)

CitectSCADA DNPr Driver 18/08/2005 Page 62 of 85

Citect Pty Ltd Driver User Guide

3.11 Driver Error Help

The following entries should be included in the Citect PROTERR.DBF spec file.

PROTOCOL MASK ERROR MESSAGE REF. ACTION COMMENT

DNPR 0 0x00050 Software driver error, programming error Custom driver error

DNPR 0 0x00051 Memory could not be allocated for cache Custom driver error

DNPR 0 0x00052 Could not insert request as duplicate exists Custom driver error

DNPR 0 0x00053 A point, used in a write request, is invalid Custom driver error

DNPR 0 0x00054 Points in request require new poll to refresh Custom driver error

DNPR 0 0x00055 User has set polltime to zero Custom driver error

DNPR 0 0x00056 This type is write only Custom driver error

DNPR 0 0x00057 More points requested than defined by user Custom driver error

DNPR 0 0x00058 Invalid Tag Object read sub field Custom driver error

DNPR 0 0x00059 No matching entry in Tag Object table found Custom driver error

DNPR 0 0x0005A A point or points in read request not valid Custom driver error

DNPR 0 0x0005B Cannot find matching dcb for a write response Custom driver error

DNPR 0 0X0005C Data does not exist in cache Custom driver error

DNPR 0 0x0005D Unable to complete write command Custom driver error

DNPR 0 0x0005E IIN Error detected using IIN filter settings Custom driver error

DNPR 0 0x0005F Can't open database - Citect form may be open Custom driver error

DNPR 0 0x00060 Error detected in queue Custom driver error

DNPR 0 0x00061 Cache refresh late due to poll delays Custom driver error

DNPR 0 0x00062 Requested raw type invalid for native type Custom driver error

DNPR 0x00063 An error has occurred in a device using a virtual unit

0 Custom driver error
tag

DNPR 0 0x00064 General NULL pointer issue, e.g. a request has oc- Custom driver error
curred internally for a device no longer installed.

DNPR 0 0x00065 A unit has not been configured with primary or Custom driver error
standby and peer redundancy is in operation.
DNPR 0 0x0068 IIN Error detected using IIN filter settings. Custom driver error

DNPR 0 00069 Waiting for RTU response before coming online Custom driver error

DNPR 0 0006A Remote Unit not online yet, pending RTU response Custom driver error

DNPR 0 0006B Exclusive access port is offline Custom driver error

DNPR 0 0x10002 API - Function code in response not supported API error

DNPR 0 0x10003 API – Response/Request sequence No. mismatch API error

DNPR 0 0x10004 API - Response received with no active request API error

DNPR 0 0x10005 API - Object/Variation not supported API error

DNPR 0 0x10006 API - Object/Qualifier not supported API error

DNPR 0 0x10007 API - Response qualifier code not supported API error

DNPR 0 0x10008 API - Timeout waiting for application response API error

DNPR 0 0x10009 API – Unsupported Obj/Var in read response API error

DNPR 0 0x1000A API – Unsupported Obj/Var in operate response API error

DNPR 0 0x1000B API - IIN bits on RTU parsing of last request API error

DNPR 0 0x1000C API – Response mismatch, Select Before Operate API error

DNPR 0 0x1000D API – No time object in Restart response API error

DNPR 0 0x1000E API - Obj/Var not supported in write response API error

CitectSCADA DNPr Driver 18/08/2005 Page 63 of 85

Citect Pty Ltd Driver User Guide

DNPR 0 0x1000F API – Invalid device number in transmit queue API error

DNPR 0 0x10010 API – No time object in Measure-Delay response API error

DNPR 0 0x10011 API – Skip reply, Unsolicited Response disabled API error

DNPR 0 0x20001 Control - OPERATE received after SELECT timeout Ctrl Status bit error

DNPR 0 0x20002 Control – OPERATE received without prior SELECT Ctrl Status bit error

DNPR 0 0x20003 Control – formatting errors in control request Ctrl Status bit error

DNPR 0 0x20004 Control – control request unsupported for point Ctrl Status bit error

DNPR 0 0x20005 Control – queue full or point already active Ctrl Status bit error

DNPR 0 0x20006 Control - not accepted due to hardware problems Ctrl Status bit error

CitectSCADA DNPr Driver 18/08/2005 Page 64 of 85

Citect Pty Ltd Driver User Guide

3.12 Debug Messages

All driver kernel messages rely on the debug option being set. It is highly recommended this be set to
at least ERROR during commissioning. E.g. In Citect.ini, [DNPR]debugstr=* ERROR

3.12.1 SCADA Debugging

When the driver debugging utility is enabled (via a command such as ‘debug * all’), and the INI parameter SCADADebugging is
set to one, then trace statements will be produced in both the kernel window and the syslog file. The trace statements detail the
actions undertaken by the driver in order to process requests received by Citect.

The following legend describes the symbol abbreviations used in the trace statements:

Symbol Description
ad I/O point address
ut unit type
uc unit count
rt raw type
bw bit width
ch channel number
da device address
id request identification number
ec error code

The following examples have been taken from the syslog whilst the sample project was
running:
Reading Field I/O from cache (Read command is internal, it is not issued to device):
Mon Jun 07 15:15:07 1999 148:25:42.233 RD(C) BI16.VAL: Ad16 uc8 rt0 bw1 ch0 da1 id-1 ec0x0 Length 1
00 .
Mon Jun 07 15:15:22 1999 148:25:57.675 RD(C) AO2000.CTRLSTAT: Ad2000 uc1 rt8 bw8 ch0 da1 id-1 ec0x5a Length 1
00 .
Mon Jun 07 15:15:22 1999 148:25:57.675 RD(C) AO2000.VAL: Ad2000 uc1 rt4 bw32 ch0 da1 id-1 ec0x0 Length 4
00 00 00 00 ....
Mon Jun 07 15:15:22 1999 148:25:57.675 RD(C) AO2000.STAT: Ad2000 uc1 rt8 bw8 ch0 da1 id-1 ec0x0 Length 1
01 .
Mon Jun 07 15:15:26 1999 148:26:01.682 RD(C) C4000.DELTASTAT: Ad32000 uc8 rt0 bw1 ch0 da1 id-1 ec0x54 Length 1
00 .
Mon Jun 07 15:15:26 1999 148:26:01.682 RD(C) C4000.STAT: Ad32000 uc8 rt0 bw1 ch0 da1 id-1 ec0x0 Length 1
01 .
Mon Jun 07 15:15:26 1999 148:26:01.682 RD(C) C4000.DELTAVAL: Ad4000 uc1 rt4 bw32 ch0 da1 id-1 ec0x54 Length 4
01 00 00 00 ....
Mon Jun 07 15:15:26 1999 148:26:01.683 RD(C) FC4000.STAT: Ad32000 uc8 rt0 bw1 ch0 da1 id-1 ec0x5c Length 1
00 .
Mon Jun 07 15:15:26 1999 148:26:01.683 RD(C) FC4000.VAL: Ad4000 uc1 rt4 bw32 ch0 da1 id-1 ec0x5c Length 4
00 00 00 00 ....
Mon Jun 07 15:15:30 1999 148:26:05.390 RD(C) BO2004.STAT: Ad16032 uc8 rt0 bw1 ch0 da1 id-1 ec0x0 Length 1
01 .
Mon Jun 07 15:15:30 1999 148:26:05.390 RD(C) BO2004.CTRLSTAT: Ad2004 uc1 rt8 bw8 ch0 da1 id-1 ec0x5a Length 1
01 .
Mon Jun 07 15:15:30 1999 148:26:05.390 RD(C) BO2000.VAL: Ad2000 uc8 rt0 bw1 ch0 da1 id-1 ec0x0 Length 1
00 .
Mon Jun 07 15:15:30 1999 148:26:05.390 RD(C) BO2005.CONF.ONT: Ad2005 uc1 rt4 bw32 ch0 da1 id-1 ec0x0 Length 4
88 13 00 00 ....
Mon Jun 07 15:15:39 1999 148:26:14.541 RD(C) AI0.STAT: Ad0 uc8 rt0 bw1 ch0 da1 id-1 ec0x0 Length 1
01 .
Mon Jun 07 15:15:39 1999 148:26:14.541 RD(C) AI0.VAL: Ad0 uc1 rt4 bw32 ch0 da1 id-1 ec0x0 Length 4
00 00 00 00 ....

Reading RTU information from cache (Read command is internal, it is not issued to device):
Mon Jun 07 15:15:54 1999 148:26:29.309 RD(C) IIN0.IIN: Ad0 uc1 rt1 bw16 ch0 da1 id-1 ec0x0 Length 2
04 00 ..
Mon Jun 07 15:15:57 1999 148:26:32.091 RD(C) ReadTime0.ReadTime: Ad0 uc1 rt4 bw32 ch0 da1 id-1 ec0x5a Length 4
00 00 00 00 ....

Reading driver information from cache (Read command is internal, it is not issued to device):
Mon Jun 07 15:15:57 1999 148:26:32.091 RD(C) PollCount: Ad0 uc1 rt1 bw16 ch0 da1 id-1 ec0x0 Length 2
02 00 ..
Mon Jun 07 15:15:57 1999 148:26:32.091 RD(C) FailPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id-1 ec0x0 Length 2
00 00 ..
Mon Jun 07 15:15:57 1999 148:26:32.091 RD(C) IntegrityPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id-1 ec0x0 Length 2
02 00 ..
Mon Jun 07 15:15:57 1999 148:26:32.091 RD(C) FailIntPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id-1 ec0x0 Length 2
00 00 ..
Mon Jun 07 15:15:57 1999 148:26:32.091 RD(C) EventPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id-1 ec0x0 Length 2
00 00 ..
Mon Jun 07 15:15:57 1999 148:26:32.091 RD(C) FailEventPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id-1 ec0x0 Length 2
00 00 ..
Mon Jun 07 15:15:57 1999 148:26:32.091 RD(C) RTUStatus: Ad0 uc8 rt0 bw1 ch0 da1 id-1 ec0x0 Length 1
01 .
Mon Jun 07 15:15:57 1999 148:26:32.091 RD(C) LateRefresh: Ad0 uc8 rt0 bw1 ch0 da1 id-1 ec0x0 Length 1
00 .

CitectSCADA DNPr Driver 18/08/2005 Page 65 of 85

Citect Pty Ltd Driver User Guide

Direct Read from device (Non-Cache Read):

Mon Jun 07 15:15:58 1999 148:26:33.388 NCRD<ReadTime0.ReadTime: Ad0 uc1 rt4 bw32 ch0 da1 id5 ec0x0 Length 4
01 00 00 00 ....
Mon Jun 07 15:15:58 1999 148:26:33.662 NCRD>ReadTime0.ReadTime: Ad0 uc1 rt4 bw32 ch0 da1 id5 ec0x0 Length 4
01 00 00 00 ....
Time Synchronisation (Write):
Mon Aug 02 17:48:03 1999 72:54:03.156 WR<WriteTime0.WriteTime: Ad0 uc1 rt0 bw1 ch0 da1 id3 ec0x0 Length 1
01 .
Mon Aug 02 17:48:03 1999 72:54:03.641 WR>WriteTime0.WriteTime: Ad0 uc1 rt0 bw1 ch0 da1 id3 ec0x0 Length 1
01 .

Digital Control (Write):

Mon Aug 02 17:48:15 1999 72:54:15.043 WR<BO2004.DOP.LATCH: Ad2004 uc1 rt0 bw1 ch0 da1 id5 ec0x0 Length 1
01 .
Mon Aug 02 17:48:15 1999 72:54:15.571 WR>BO2004.DOP.LATCH: Ad2004 uc1 rt0 bw1 ch0 da1 id5 ec0x0 Length 1
01 .

Analog Control (Write):

Mon Aug 02 17:48:30 1999 72:54:30.146 WR<AO2000.DOP: Ad2000 uc1 rt1 bw16 ch0 da1 id7 ec0x0 Length 2
01 00 ..
Mon Aug 02 17:48:30 1999 72:54:30.550 WR>AO2000.DOP: Ad2000 uc1 rt1 bw16 ch0 da1 id7 ec0x0 Length 2
01 00 ..

Forced RTU Cold Restart (Write):

Mon Aug 02 17:48:40 1999 72:54:40.772 WR<COLDRESTART0.COLDRESTART: Ad0 uc1 rt0 bw1 ch0 da1 id8 ec0x0 Length 1
01 .
Mon Aug 02 17:48:41 1999 72:54:41.186 WR>COLDRESTART0.COLDRESTART: Ad0 uc1 rt0 bw1 ch0 da1 id8 ec0x0 Length 1
01 .

Forced Integrity Poll (Write):

Mon Aug 02 17:48:57 1999 72:54:57.392 WR<IntegrityPoll0.IntegrityPoll: Ad0 uc1 rt0 bw1 ch0 da1 id9 ec0x0 Length 1
01 .
Mon Aug 02 17:48:57 1999 72:54:57.797 WR>IntegrityPoll0.IntegrityPoll: Ad0 uc1 rt0 bw1 ch0 da1 id9 ec0x0 Length 1
01 .

Forced Event Poll (Write):

Mon Aug 02 17:49:02 1999 72:55:02.762 WR<EventPoll0.EventPoll: Ad0 uc1 rt0 bw1 ch0 da1 id10 ec0x0 Length 1
01 .
Mon Aug 02 17:49:03 1999 72:55:03.204 WR>EventPoll0.EventPoll: Ad0 uc1 rt0 bw1 ch0 da1 id10 ec0x0 Length 1
01 .

Resetting driver counters held in cache (Write command is internal, it is not issued to device):
Mon Jun 07 16:15:14 1999 149:25:49.090 WR(C) PollCount: Ad0 uc1 rt1 bw16 ch0 da1 id0 ec0x0 Length 2
01 00 ..
Mon Jun 07 16:15:14 1999 149:25:49.663 WR(C) FailPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id0 ec0x0 Length 2
01 00 ..
Mon Jun 07 16:15:12 1999 149:25:47.618 WR(C) IPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id0 ec0x0 Length 2
01 00 ..
Mon Jun 07 16:15:13 1999 149:25:48.294 WR(C) FailIPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id0 ec0x0 Length 2
01 00 ..
Mon Jun 07 16:15:15 1999 149:25:50.356 WR(C) EPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id3 ec0x0 Length 2
01 00 ..
Mon Jun 07 16:15:16 1999 149:25:51.082 WR(C) FailEPollCount: Ad0 uc1 rt1 bw16 ch0 da1 id0 ec0x0 Length 2
01 00 ..

Perioidic polling of devices (issued automatically by the driver, not a result of Citect commands):
Mon Jun 07 17:26:39 1999 150:37:14.384 Periodic Integrity Poll - Ch: 0 Unit: 1 Length 0
Mon Jun 07 17:27:09 1999 150:37:44.388 Periodic Event Class Poll - Ch: 0 Unit: 1 Length 0

3.12.2 Protocol Debugging

When the driver debugging utility is enabled (via a command such as ‘debug * all’), and the INI parameter ProtocolDebugging is
set to one, then trace statements will be produced in both the kernel window and the syslog file. The trace statements detail the
actions undertaken by the Triangle Microworks DNP Library in order to process requests received by the driver.

The following legend describes the symbols used to indicate which protocol layer the trace statements applies to:

Symbol Description
<=== Place Message in User Request
Queue
<~~~ Application Layer Transmit
<--- Transport Layer Transmit
<... Link Layer Transmit
...> Link Layer Receive
---> Transport Layer Receive
~~~> Application Layer Receive
===> Store Object Data / Callback to User Process

CitectSCADA DNPr Driver 18/08/2005 Page 66 of 85

Citect Pty Ltd Driver User Guide

The trace statements produced will be self-evident to personnel familiar with the inner
workings of the DNP protocol.

The trace statements are padded out to 110 characters per line, so that the debug 'Length 0'
will not be shown in the kernel
(but it will be included in the syslog). Lines of 110 characters will print via Notepad with a
font size of '5', and will
be equally spaced with a font type of 'terminal' .

3.12.3 Peer State Machine Debugging

From [DNPR]UnitStateDebugging=1

This information will be helpful to Citect if they need to resolve a peer redundancy issue.
It shows the state of the unit on this IOServer, and the state of its redundant unit on the other
IOServer.

e.g.

Mon Dec 09 15:23:00 2002 76:21:28.575 Unit Network ID 4 : Entered INITIALISING state. Length 0
Mon Dec 09 15:23:00 2002 76:21:28.575 Unit Network ID 4 : Entered SYNCHRONISING state. Peer state is UNKNOWN
Length 0
Mon Dec 09 15:23:00 2002 76:21:28.596 Unit Network ID 1001 : Entered INITIALISING state. Length 0
Mon Dec 09 15:23:00 2002 76:21:28.757 Unit Network ID 1 : Entered INACTIVE state. Peer state is SYNCHRONISING Length
0
Mon Dec 09 15:23:00 2002 76:21:28.757 Unit Network ID 5 : Entered INACTIVE state. Peer state is SYNCHRONISING Length
0
Mon Dec 09 15:23:00 2002 76:21:28.757 Unit Network ID 2 : Entered INACTIVE state. Peer state is SYNCHRONISING Length
0
Mon Dec 09 15:23:00 2002 76:21:28.757 Unit Network ID 6 : Entered INACTIVE state. Peer state is SYNCHRONISING Length
0
Mon Dec 09 15:23:00 2002 76:21:28.757 Unit Network ID 3 : Entered INACTIVE state. Peer state is SYNCHRONISING Length
0
Mon Dec 09 15:23:00 2002 76:21:28.757 Unit Network ID 4 : Entered INACTIVE state. Peer state is SYNCHRONISING Length
0
Mon Dec 09 15:23:38 2002 76:22:05.972 Unit Network ID 1 : Entered ACTIVATING state. Peer state is ACTIVE Length 0
Mon Dec 09 15:24:00 2002 76:22:28.342 Unit Network ID 1 : Entered ACTIVE state. Peer state is DEACTIVATING Length 0
Mon Dec 09 15:24:34 2002 76:23:02.139 Unit Network ID 3 : Entered ACTIVATING state. Peer state is ACTIVE Length 0
Mon Dec 09 15:25:00 2002 76:23:28.343 Unit Network ID 3 : Entered ACTIVE state. Peer state is DEACTIVATING Length 0

3.12.4 Useful Debugging Tips

• Too high a volume of traces can slow Citect down considerably. This is worst when the kernel
dialog is being displayed. i.e. minimising the kernel will lower the CPU content used.
• It is best to set the debug 'port' to minimise traces, e.g. "debug port010B_1 error"
It also makes the traces easier to follow if only one unit is in them
• Use the kernel "write log my message" (v5.50+) to make notes in the syslog.dat of changes
just about to happen.
• Up the default syslog.dat size, e.g. [debug]syslogsize=10000
• If a high volume of traces are being done, then set [kernel]errorbuffers=1000
• Kernel drivertraces can have PORT filtering from v5.50 on.
• Any issue to do with redundancy should have traces done on both the primary and standby
servers at the same time.
• All INI traces rely on the "debug" mode for a port being set. Without this these INIs and the
default error reports in the driver, will not work.

• Unit online/offline issues

CitectSCADA DNPr Driver 18/08/2005 Page 67 of 85

Citect Pty Ltd Driver User Guide

The best INIs for this are Protocoldebugging=1, UnitStateDebugging=1,

o
dcberrordebugging=1, and drivertraces with a mask of c0f, e.g. "drivertrace
mask=c0f"
• DATA Integrity type issues
o If a data issue is repeatable, then make the page refresh time artifically long (page
properties), say every 5s (5000) . This will minimise the trace storm if a page has
many tags and has the default 250ms scan time!
o Disable alarms and trends or background cicode, to isolate a trace to be just one
source of logic, i.e. a page refresh or alarm scan.
o A kernel "probe" window will show TAG requests to / from the client but not
necessarily to the driver. Probe results may come from the IOServer cache or an
IOServer on another PC.
o Kernel "drivertrace xxxx" WILL show requests to/from the driver on the local
IOServer. These traces will also show the returned RAW value from the driver.
Remember: The client will scale this value if engineering units are defined.
o The best INIs for data issues are Protocoldebugging=1, dcberrordebugging=1,
scadadebugging=1 or drivertrace's.
• Redundancy Issues
o The best INIs are Protocoldebugging=1, UnitStateDebugging=1,
ReplicationDebugging=1

3.13 Stats Special Counters

These are the statistics shown in the kernel window when view “driver” and then the “v” key has been
pressed.

Number Label Purpose/Meaning of this counter

0* "* Bytes Tx API - Count of bytes transmitted
1* "* Bytes Rx" API - Count of bytes received
2* "* Commands Tx" API - Count of Command requests transmitted. Includes driver write commands,
polls and responses to the RTU at the highest level, e.g. IIN responses.
3* "* Bad CRCs" API - Count of Incorrect CRCs received. This means data errors have occurred at
the lowest level where bytes are processed from the RTUs.
4* "* Buffer Overflows" API - Count of times buffer has overflowed. I.e. response fragment size exceeded
2048 bytes or 64 fragments
5* "* Bad Sequences" API - Count of times a bad sequence has occurred. Fragments received out of
sequence or first fragment not stamped as first.
6* "* LinkLayer Timeouts" API - Count of times datalink confirm has timed out. This happens when a
timeout occurs waiting on a datalink confirm of a frame sent to a remote device.
7* "* Link Layer Fails" API - Count of times datalink confirm has failed. This increments when the set
number of link layer timeouts occur and no reply.
8* "* App Layer Timeouts" API - Count of times Application Layer has timed out. This happens when a
response to a request message is not received within the application layer
timeout period configured for the device.
9* "* App Layer Fails" API - Count of times Application Layer has failed. This happens when the app
layer timeouts exceed the retry count.
10* "* Calc Var Events " Count of calculated variables changed and placed into the event system..
11* "* Unsolicited RX" Count of Unsolicted Responses received
12* "Irrelevant Events Rx" Count of received events that have been skipped as the event does not
correspond with a Trend or Alarm tag
13* "Tot Rel Events Rx" Count of all relevant events that have been processed by Cicode
ON FIRST PORT and THIRD on
14 "Event Queue Size" Count of events queued awaiting to be processed by Cicode for alarming/trending
-
15 "Delay Event Que Size" Count of events on delay queue waiting for earlier instance(s) of alarm to be
processed by Cicode before being placed on event queue
16 "Peer Messages Rx" Count of messages in on the receive peer queue. Peer redundancy needs to be
enabled.
17 "Peer Messages Tx" Count of messages sent on the send peer queue. Peer redundancy needs to be
enabled.
18 "Peer Send Queue Size " Peer send queue size. This should normally be at 0. Sustained values indicate
system overload.
19 "Peer "Connect,FAIls"" Number of successfull peer connections/failures. Peer redundancy needs to be
enabled. Format is Connects in the 1000s and fails in the 0 to 999, e.g. 1,019
means 1 connection with 19 failures.

CitectSCADA DNPr Driver 18/08/2005 Page 68 of 85

Citect Pty Ltd Driver User Guide

ON SECOND PORT ONLY

“TMW Configs" TriangleMicroWorks Configured devices buffer count. NB: Each physical port also
B14 used one of these buffers.
B15 "TMW Frames" TriangleMicroWorks communication frame buffers.
B16 "TMW LinkRecs" TriangleMicroWorks link level receive buffers.
B17 "TMW LinkTrans" TriangleMicroWorks link level transmitt buffers.
B18 "TMW ApplRecvs" TriangleMicroWorks application level receive buffers.
B19 "TMW ApplTrans" TriangleMicroWorks application level transmitt buffers.

• Items will update on a per Port basis. Non “*” items (14 on) are global to the driver and
appear in the FIRST port of the DNPr driver, then the third PORT onwards.
• Items 14 & 15 will NOT be reset when driver stats are cleared. These stats are for actual
counts which cannot be cleared.
• Items B14 to B19 are on the 2nd port and will NOT be reset when driver stats are cleared.

3.14 Processing of Timestamped Event Data

All data that is configured in a DNP RTU as event class 1,2 or 3 is considered event data. When this
data changes the RTU reports an event. Depending on the RTU’s configuration, an event is either
sent unsolicited from the RTU, or stored by the RTU and retrieved by the next poll. Event data is
always timestamped. Both analogue and digital event data are supported.

Events are also fabricated by the driver (given the current time as the timestamp) if static data is
changed without an event occurring. This should NOT occur in the regular running of the driver as
the RTU always gives you the event data before the static data. It may occur when you start up Citect
for the first time though, as the RTU may not have an event for the static data. It can also happen
after an RTU has been restarted.

For ints and reals the event system looks at the engineering units on the tag. If all units RawZero,
RawFull, EngZero, EngFull are defined then scaling will occur. If any are undefined, no scaling
occurs. An int (LONG) will automatically be converted to a REAL (RDT_REAL = 4) if the EngFull
has a decimal point, e.g.
AIx - 0, 10000, 0, 100 ! Will keep the scaled value as an LONG
AIx - 0, 10000, 0, 100.0 ! Will scale and return a REAL value
If the RawZero == EngZero AND RawFull == EngFull no scaling or data conversion will occur.
No conversion is done if a divide by zero is about to happen.
Scaling can be also explicited disabled by setting [dnpr] EventEngScalingEnable=0 .

When an event is received by the DNPR driver, it checks to see if there is a corresponding variable
tag for that address. It then checks if there is a trend tag corresponding to the variable tag found.
Periodic, Event periodic and Event Trends are all supported. You can only specify ONE trend tag per
variable tag. To find the trend tag, the DNPR driver looks for a trend tag with a special prefix added to
the name of the variable tag. The prefix is “T_” for periodic trends, “P_” for event periodic trends and
“E_” for event trends.

Events with an associated variable and trend tag are considered as relevant, and are added to the
driver’s event queue. Events without an associated variable and trend tag are considered irrelevant,
and are thrown away.

Cicode is used to process events in the driver’s event queue. This cicode can be activated by
defining a Parameters form (from the System menu) as follows:
Section Name: Code
Name: Startup
Value: Tasknew("RTUEventQueProcessing",0)

CitectSCADA DNPr Driver 18/08/2005 Page 69 of 85

Citect Pty Ltd Driver User Guide

For Periodic and Periodic Event Trends it is a good idea to configure the trend tags expression as the
variable tag that the trend corresponds to. This will make the current value of the trend always equal
to the I/O points latest value whether you have processed the event data for that latest change yet or
not. When an event occurs, it will be inserted into the trend at the time in which the event occurred,
not the time at which the event was received. The dedicated Cicode will then redraw the trend (with
the new value) from the time of the event up until the present time. Only use standard templates
when constructing trend displays to be used by Periodic or Event Periodic trends. If a “zoomtrend” is
to be used, then set the [DNPR] parameter ZoomTrendInUse=1.

We recommend that you use Event Trends though, as they are much quicker to process and they
keep the timestamp with each value change. There is no need to specify a trigger or expression for
the event trend. The sample period of the event trend should be set to roughly on average how often
you expect an event from the RTU for that I/O point plus a small tolerance. The sample period of the
Event Trend does NOT effect the timestamps of the events, it just dictates how big the history files for
the trend are.

During the processing of an event in the cicode, the alarm server is notified of the change to the
variable tag and the timestamp of the change. The alarm server will then look for any Timestamped
Digital Alarms or Timestamped Analogue Alarms that have been configured to use the variable tag of
the event. When such an alarm tag is found, the alarm will be fired if the required conditions of the
alarm have been met.

Note also that the timestamp of an alarm can be viewed in one of two forms, Date/Time or
Time/Millisecond. The form to be used is defined by the [ALARM] parameter HresType. Setting
HresType=4 defines Date/Time format, and setting HresType=7 defines Time/Millisecond format. A
format must be selected in order for device timestamped alarms to work, so an error will be generated
if it is not defined in the CITECT.INI file. The [ALARM] parameter HighResOff should be set to 1
(HighResOff=1) to force millisecond accuracy when alarms are turned off, if Time/Millisecond format
is being used. An appropriate alarm category must also be defined to correctly utilise the selected
format.

Refer to the sample project for examples of event driven Trend tags and event driven Time
Stamped Alarm tags.

v3.1.7.x on Event Enhancements

Version 3.1.7.x on of the driver introduced the concept of seperating the reading and deleting of
events from the event queue. The default behaviour is to delete an event after it has been read by the
GetRTUNextEvent() function. However it is possible to read events from the driver
(GetRTUNextEventEx(0) without deletion) and send these across to a Alarm or Trend client in an
asynchronous manner for higher perfromance. The event is known by its sequence number which will
remain unique for a very long time (1 billion events!). Then the events can be removed from the event
queue some time later. An added feature of this is the ability to have events automatically re-queued if
it takes too long for a remove event to occur. Thus the user cicode does not need to worry about
losing events. e.g.
[dnpr] EventQueRequeTimeout=30000
[dnpr] EventQueRequeCount=5
would re-send an event out 5 times, each after 30s, if the original event was NOT deleted by the user
cicode. Finally the event will be deleted automatically when all retries have been used. This only
makes sense in the context of the GetNextEventEx() function being used with the flag set not to
delete the event.

Event sequence numbers – If you need to determine which IOServer generated an event, the
sequence numbers can be assigned a range by the [dnpr]EventSeqPrimary=1 INI.

Event Queue Size – The default size is 100000 entries. By default a warning message occurs in the
syslog at this size and the queue can grow. As it grows, PC memory will be consumed. An option
exists when [dnpr]EventQueSizeHighPurge=1 to delete the OLDest events from the queue at the high
water mark. This feature allows you to protect you PC from running out of memory. Something would
have to go wrong in your system (trend or alarm server died ?) for this to happen.

CitectSCADA DNPr Driver 18/08/2005 Page 70 of 85

Citect Pty Ltd Driver User Guide

Event Delete Logging – As a backup system, the driver allows you to log deleted events at the high
watermark or when the users cicode explicitly asks for this when "RemoveEvent(nSeq, 1)" is called.
This is enabled via the [dnpr]EventQueDeleteLog=1 INI setting.

Event Data Scaling – The default setting is to scale event data based on the engineering settings for
the TAG, just how Citect clients do this. However, if you want the RAW engineering values, then this
can be guaranteed with [dnpr]EventEngScalingEnable=1.

Event Processing – It is possible to disable events from being generated by setting [dnpr]
EventProcessingEnable=0. This can be useful during testing or commisioning, or for users who don't
want to use the event system.

3.14.1 Driver Ordinals

The dnpr.dll driver has extra entry points to allow the event processing to work. The functions and
interfaces follow.

LONG ___GetRTULogStatus(void);
Returns 1 if one or move events are in the event queue. NOTE: This will return true
while events are in the queue even if they have been read but not deleted.

LONG __ _GetRTUNextEvent(void);

Returns the next event queue sequence number and automatically deletes the current
event.

LONG __ _GetRTUNextEventEx(LONG bDelete);

Returns the next event queue sequence number and only deletes the current event IF
bDelete is set to 1.

LONG __ _EmptyEventQue(void);

Empties the entire queue.

ASCIIZ _ GetRTUEventField(LONG hEventSeq, LONG fieldNumber);

Used to read data for a specific event, usually the one just retrieved by the GetRTUN-
extEvent call. fieldNumber values are :

FIELD_PENDING_ALARMS 0 // Only from 3.0.3.x, returns pending alarms

FIELD_TIMESTAMP 1
FIELD_MILLESECONDS 2
FIELD_VALUE 3
FIELD_VALUE_TYPE 4
FIELD_TAGNAME 5
FIELD_SUPPORT 6 // Only introduced from 3.0.1.x
FIELD_ISTREND 7
FIELD_NOALARMDELAY 8

FIELD_ISALARM 9 // Set to 1 IF DBF checking on, and is an alam, other-

wise always 1

CitectSCADA DNPr Driver 18/08/2005 Page 71 of 85

Citect Pty Ltd Driver User Guide

FIELD_REQUEUE_COUNT 10 // Starts from 0, needs EventQueRequeTimeout,

EventQueRequeCount INIs enabled to change
FIELD_EVENT_AS_STRING 11 // Returns one string with all event data

#4 Value Type is the standard citect RAW type values

0 DIGITAL, 1 INTEGER, 2 REAL, 4 LONG

#6 Returns an event support string from driver. Intended to allow cicode to determine if an old version
of dnpr is in use. Currently returns :
SUPPORT=NODELAY+RETRIES
NODELAY means use of the #8 read will turn off any delay in pushing up events.
RETRIES means the driver supports the re-sending of events (v3.1.7.x on)

#7 and #9 Returns 0 or 1 if checks of TAG type are enabled. By default if TAG checks are disabled,
these fields return 1. An 0 means that no Trend or Alarm entry exists for this tag.

#8 No alarm delay – This is only of use for version 6.0+ of Citect in which alarms can be "pushed" into
the alarm system . The dummy use of this field in the event startup cicode turns off event delays.

#11 format is :
IsEventTrend IsEventAlarm Tagname Citect_Value_Type Value Seconds MSSinceMidnight

hEventSeq can be any event still in the queue but is normally the last one retrieved.

GetRTUEventField() error strings :

"<Error_Init>" - Reading an GetRTUEventField() BEFORE the event system is up will return this.
"<Error>" - general error, something happened ???
"<Error_not_found>" - The event sequence number asked for does not exist
"<Error_field#>" - An invalid field number was asked for

Cicode calling this function should do a IF (LEFT(sResult, 6) = "<Error") THEN type check to vet for
errors.

LONG __ _RemoveEvent(LONG hEventSeq, LONG bLog);

Remove the event with this sequence number from the queue. If bLog is set to 1 then the
removed event is logged to dnpr_logger.txt .

3.14.2 DNPR_LOGGER.TXT Format

#Label, Tag, Citect_data_type, Value, Seconds_Since_1970, MsSinceMidNight,
TimeStamps_as_string_time

e.g.

#EVENT_DELETED,BI_1_Value,0,0,1077765609,51609203,26/02/04-14:20:09.203

Any other future entries in the logger file will have a first column identfier to allow EXCEL or ACCESS
filtering of the file.

CitectSCADA DNPr Driver 18/08/2005 Page 72 of 85

Citect Pty Ltd Driver User Guide

3.15 Hints and Tips

3.15.1 DNP Protocol

The DNP 3.0 Protocol has been designed as a generic protocol for use in the utility industries, and as
such, the protocol encompasses a broad spectrum of functionality. For most devices, it is not feasible
to implement the entire protocol, as only a subset is required.
In order to maintain compatibility between subset implementations, the DNP user group has defined
three official subsets of the DNP protocol. These are referenced as Level1, Level2 and Level3 - the
higher the number, the greater the DNP functionality that is implemented by the subset.
Most devices have a Level2 implementation as their base, with selected additional functionality from
the DNP protocol also included in the implementation. The DNP 3.0 protocol is also expanding as it
gains more usage in industry. Support of floating values is an example of this.

In an effort to help the user determine the interoperability of the components on their DNP network,
each DNP slave device and master device (eg Citect) have a document defining its implementation of
the DNP protocol. The document, known as a Device Profile Document, defines which Level is being
used for the base, the additional functionality that is supported above this level, and also any
functionality that is expected of the level but is not implemented.

A Device Profile Document will be written for Citect in the near future, and included as an Appendix.
Until then, this specification acts as a substitute in the interim.
Note that Citect is based on a Level2 implementation and will fully support all Level2 functionality.
Further functionality will also be introduced as a result of the feedback received regarding user
requirements and needs.

3.15.2 Data Acquisition within DNP

DNP offers an array of methods for data acquisition from DNP devices, but as noted, not all devices
will support all methods of data acquisition. The most basic form of data acquisition, and the one that
all DNP devices must support, is the acquisition of a group of points that have been pre-defined in the
device. This is known as a class request.
All DNP devices have four definable groups (classes) of I/O points. Class0 lists all of the I/O points
that are to have their current value sent back to Citect, when Citect issues a Class0 request. Class1
lists all of the I/O points that are to have their events (changes in value) sent back to Citect, when
Citect issues a Class1 request. Class2 and Class3 are conceptually the same as Class1, but are
separate groups to allow prioritising of event data. To summarise, Class0 requests will result in a
reply containing the current value of all of the points predefined I/O points, whereas Class1, Class2
and Class3 requests will result in a reply containing all of the buffered events that have occurred for
all of the predefined I/O points in Class1, Class2 or Class3. The DNP protocol assures that if a
request is made to a device for Class0, Class1, Class2 and Class3 data, then the device will reply
with all of the buffered events (with the most recent event received last), and then reply with the
current data. The order in which the data arrives guarantees the most recent value is held in the
driver cache, and the inclusion of Class0 static data assures that data acquisition is not overly
dependant on the report-by-exception mechanism. This form of all-classes poll is termed an Integrity
Poll.

The device may automatically send event data to Citect (this is termed an Unsolicited Response), or it
may wait until Citect requests for Class1, Class2, or Class3 data.
In either case the driver will update its cache with the value received in the event data, and also check
if the event is related to an Alarm tag or a Trend tag that needs processing.

The DNP address for Citect is defined by the [DNPR] parameter ScadaAddress. This value
must also be defined in the slave device as the master address, if it is to send unsolicited
responses to Citect.

CitectSCADA DNPr Driver 18/08/2005 Page 73 of 85

Citect Pty Ltd Driver User Guide

If the device does support unsolicited responses, then having all I/O points report through exception
(send events on change of data) will allow Citect to poll (with an Integrity Poll) the device at very low
frequencies. This data acquisition algorithm requires very low traffic throughput on the network.
If the device does not support unsolicited responses, then Citect must poll more frequently (with event
polls – Class1, Class2 and Class3) in order to keep its cache up-to-date. After every n Event Polls,
Citect is to issue an Integrity Poll to ensure the data integrity of the driver cache. The period between
polls for a device is defined by the EventPollPeriod INI parameter, and the ratio of Event Polls for
every Integrity Poll, for a device, is defined by the EventPollRatio INI parameter.

If the device does not support report-by-exception (ie, it does not buffer event data, but will only reply
with current data) then the EventPollRatio should be set to zero so that only Integrity Polls are issued,
and the EventPollPeriod should be set to a low value in order to keep the driver cache up-todate.

The DNP protocol also offers other data acquisition algorithms in which the device master (Citect) can
request points that are defined by the master, not by the slave. There are numerous methods, each
offering varying levels of control the master has in determining which points it can request. As the
level of support for these data acquisition algorithms differs from device to device, and some devices
do not support these data acquisition algorithms at all, Citect will currently only be implementing the
Class read data acquisition algorithm described above.

In summary, all of the I/O points in a device that are required by Citect should be allocated to Class0
in the device. If the device supports report-by-exception (which it should!!!), then also allocate each
point to one of the event classes.

3.15.3 Blocking Issues

Digital Reads are always blocked by Citect to a minimum of 8 bits. A DNP device can configure points
in a non continuous fashion, .e.g. Points 0 to 4, then 10 to 14 etc. Thus non-digital Citect requests are
not blocked so as to avoid the situation where a blocked request may also include a point in cache
that is not part of the pre-defined DNP3 group.

That is why the default protdir.dbf entries are 8 & 8 bits.

3.15.3.1 Compile Time

IF you know your RTU devices all have continuous point allocations, then the compile time value can
be increased. E.g. if 32 digitals are configured then the value could be set to 32 & 32 in protdir.dbf.

3.15.3.2 Runtime
Runtime blocking is controlled by the [DNPR]Block=x, the [DNPR]IsItemisedRequest=y parameter,
and the [DNPR]MaxBits=z parameters. This is when it is OK to block together several read requests
in the IOServer.

Block = MaxBits / 8, IsItemisedRequest=0

The runtime values must at least equal the compile time settings. They can however be larger than
compile time settings.

3.15.3.3 Projects using Super Genies

To utilise Super Genies with Digital Tags, you will need to modify your project settings to allow
blocking of requests up to 16 bits (default is 8 bits). To do this, you will need to make the
modifications outlined in the spec in the description of the 'IsItemisedRequest' parameter.

In particular, you will need to :

• Add the following to your INI file (in the [DNPR] section)
Block = 2
MaxBits = 16

CitectSCADA DNPr Driver 18/08/2005 Page 74 of 85

Citect Pty Ltd Driver User Guide

• IsItemisedRequest=0

CitectSCADA DNPr Driver 18/08/2005 Page 75 of 85

Citect Pty Ltd Driver User Guide

3.15.4 Citect forms and Citect tag databases

As the event processing algorithms of this driver require knowledge of the tags defined in Citect, it is
important that the Project Editor’s “Variable Tags” form, “Trend Tags” form and “Time Stamped
Alarms” form are not left open. Otherwise the driver will not be able to access the required database,
and an error code 0x5F will be produced. The “Trend Tags” database and “Time Stamped Alarms”
database are only accessed at startup, if they can not be accessed due to a form being open, a
dialogue box will instruct the user to close the forms and restart Citect. The “Variable Tags” form is
accessed at startup and when a unit is re-enabled via the cicode IODeviceControl() function. If it can
not be accessed due to the form being open, a trace statement will be sent to the syslog/kernel to
instruct the user to close the form, so that Citect can re-initialise the unit.

3.15.5 Startup considerations

In a site with many RTUs. it is useful to consider port startup staggering [dnpr] StartupStaggerDelay=
to spread the load out. Also it is a good idea to use the [<unit>] PollPeriodOffset= to stagger when
polls are issued, especially where many units are coming through one port. e.g. unit1 – 5, unit2 – 10,
unit3 – 15, would issue polls 5s after the default time for unit1, 10s after for unit2, and 15s after for
unit3.

3.15.6 Useful INI parameters for debugging

Note that the following Citect.ini parameters place an extra burden on Citect’s operation and should
only be used under debugging conditions, not under normal operation.

[DNPR]debugstr=* all Automatically enable debugging. This is needed to

OR enable driver traces to go to syslog.dat.
[DNPR]debugstr=* error
[Kernel] ErrorBuffers=200 Increases the amount of buffer space available, in order
to accommodate a high rate of debugging messages.
NB: Not needed from Citect 5.41.
[Debug] SysLogSize= 1000 Increases the syslog size, in order to accommodate a
high rate of debugging messages. Actual value depends
on disk space. NB: Not needed from Citect 5.41.
[Debug]drivertracemask=fff To view the commands and data going between the
eff IOServer and the driver
AND
[Debug]drivertrace=ver

CitectSCADA DNPr Driver 18/08/2005 Page 76 of 85

Citect Pty Ltd Driver User Guide

4. Protocol Requirements

4.1 Introduction

This section documents all the requirements of the protocol itself.

4.2 Initialising the Board

The DNPr driver relies on the relevant low level driver to handle all board initialisation.

4.3 Initialising the Port

The DNPr driver relies on the relevant low level driver to handle all port initialisation.

4.4 Initialising the IO Device

For the very first pass:

ƒ Initialise the Triangle Micro Works DNP library

For Unit Initialisation:

ƒ Determine INI parameters for this device scope
ƒ Record slave address of device
ƒ Add device for Triangle Micro Works DNP library
ƒ Create database for all tags defined for this device
ƒ Determine online status via device request

For Unit Re-Initialisation:

ƒ Reset counters and flags
ƒ Determine online status via cached status

If the peer is present and active, “InitUnit” performs synchronisation and reports off-line. It does not
talk to the device. However, if no peer exists or is inactive, then what has been described above
happens.

4.5 IO Device Online Test

The online check for unit initialisation, at start-up, is a full integrity poll. As a consequence, a
successful online check results in all of the units data being immediately ready for subsequent Citect
reads.

When a unit is offline, it is the back-ends responsibility to determine when the unit has returned by
continuing to poll the device (full integrity poll) at the same period as when it was online (but at a
lower priority). The Citect unit initialisation online test every watchtime period is serviced by the
cached unit status, not by a physical request to the device.

The online check for status unit, is a time read.

CitectSCADA DNPr Driver 18/08/2005 Page 77 of 85

Citect Pty Ltd Driver User Guide

4.6 State Flow Description

As DNP is a multi-layered protocol, transactions occur on multiple layers. The Triangle Micro Works
DNP library handles all transactions on the data link layer level autonomously. This description is only
concerned with protocol transactions handled directly by the driver.

The driver is of the frontend/backend type, hence it caches all responses of relevant data for
subsequent Citect requests. The protocol transactions on the application layer follow the simple
request/response model, with only one request outstanding per channel currently allowed.

DNP allows the master (Citect) to poll a unit for the current value of a group of pre-configured I/O
points, via a single request. This is a Class0 poll (Class 0 has all of the master’s relevant I/O points
predefined). Data reported as a current value is termed static data. DNP also allows the master to poll
a unit for value changes in a group of pre-configured I/O points, via a single request. This is a Class1,
Class2, or Class3 poll (these are all functionally equivalent, but the separate groups afford more
flexibility in configuration). Data reported as a change in value (also known as an event), is termed
dynamic data. An event may also include a timestamp field. DNP allows these different polls to be
combined into one request. A poll for Class1, Class2 and Class3 is termed an event poll, as it will
aquire all events that have been queued in the device and are awaiting transmission. A poll for
Class0, Class1, Class2 and Class3 is termed an integrity poll, as it will aquire all events that have
been queued in the device and are awaiting transmission, and then it will aquire a snapshot of all the
current values.
Refer to section 3.15.2 Data Acquisition within DNP for further details.

The driver allows each unit to have its polling period, and the ratio of integrity polls to event polls,
defined. The driver also supports additional functionality such that ‘one off’ integrity and event polls
can also be requested by the operator.

DNP allows a unit to have the master’s address be stored internally, so that the unit is capable of
transmitting unsolicited responses of event data to the master. An event may also include a
timestamp field.

The driver is capable of receiving and processing responses regardless of whether the response
contains static or dynamic data, and regardless of whether the response is initiated by a master’s
request or initiated as an unsolicited response. All responses are used to update the driver’s cache,
and relevant time-stamped events are used to update configured time-stamped alarms and trends,
via dedicated cicode.

Write requests from Citect may result in a physical write to the device, or they may only write to cache
(in the case of internal values, eg OnTime), or they may actually trigger the driver to perform a
function
(eg Reset Poll Counters). Read requests from Citect are serviced through the driver’s cache.

A point worth noting is the implementation of a device time read. A read request for a time read will
read the time from cache, this prevents the driver from continually requesting the time from a device.
A write request for a time read will write the device time to cache. A write request for a time
synchronisation will write the system time to the device.

4.7 Error Handling

The request timeout begins from when a request is transmitted by the API, not from when the request
is passed on to the API. The driver has no control over how long a request may remain pending on
the API queue.

Timeout errors detected in polling are handled identically to those detected in the processing of Citect
requests.

Timeouts are processed on three layers, with the User Layer only applying to Citect generated
requests:

CitectSCADA DNPr Driver 18/08/2005 Page 78 of 85

 Citect Pty Ltd Driver User Guide

i. Data Link Layer. If data link confirms are issued (determined by ‘DataLinkConfirm’), then a
datalink confirm must be received within ‘DataLinkTimeOut’ mSec, or a data link retry will be
issued. If ‘DataLinkRetrys’ fail consecutively, then the Application Layer timer is forced to expire.
ii. Application Layer. If the application layer does not receive a fragment within
‘AppLayerTimeOut’ mSec, then that application layer request is rejected. Note, for reasons of
efficiency, this timeout has been modified such that apon receipt of a Data Link Layer frame, the
Application Layer timeout timer is reset to AppLayerTimeOut. This prevents an Application
Layer timeout from occurring whilst frames are being received on the Data Link Layer. When a
timeout condition is reached, if the request was due to a backend poll, then an Application Layer
retry will be issued. If a response still is not received after ‘Retry’ consecutive retries, then a
DRIVER_TIMEOUT error is returned back to Citect, as an outstanding error. If this occurs
‘MaxTimeOuts’ in succession, then a DRIVER_UNIT_OFFLINE error is returned back to Citect,
as an outstanding error, and the unit is marked internally as offline. This algorithm does not
discriminate between a DRIVER_TIMEOUT detected by the Application Layer or one detected
by the User Layer. When a timeout condition is reached, if the request was due to a Citect
request, the retry sequence will be left for the User Layer (ie the driver) to process.
iii. User Layer. If the request issued was due to a Citect request, and a response is not received
within ‘Timeout’ mSec, then a User Layer retry will be issued. If a response still is not received
after ‘Retry’ consecutive retries, then a DRIVER_TIMEOUT error is returned back to Citect for
that request. If this occurs ‘MaxTimeOuts’ in succession, then a DRIVER_UNIT_OFFLINE error
is returned back to Citect, and the unit is marked internally as offline. This algorithm does not
discriminate between a DRIVER_TIMEOUT detected by the Application Layer or one detected
by the User Layer.

4.8 Special Citect.INI Values

Section Function Range Default Comments

[DNPR] TestFloodQueue 0 or 1 0 1 to cause a flood of peer cache update messages to be
sent (50,000)

CitectSCADA DNPr Driver 18/08/2005 Page 79 of 85

Citect Pty Ltd Driver User Guide

5. Design

5.1 Active Arbitration

The protocol driver implements a state engine at unit level for active arbitration. The states are
shown in Figure 1 below.

[InitUnit()]

[Has peer]
Initialising

[Is standby [Fatal error]

& Peer is active] Error
[No peer]

[No peer]
Synchronising
[InitUnit() or
UnitStatus() or
[Peer is activating]
[No peer or Channel failed or
peer inactive] No peer]
Active

Deactivating [No peer] Activating

[Peer active and

( Channel fail or
StatusUnit() or [GoActive()]
InitUnit() )]
Inactive
[( Synchronisation completed and
peer active ) or
( Is standby and peer active )]

[StopUnit()]

Stopped

[]

Figure 1 Active arbitration state diagram

CitectSCADA DNPr Driver 18/08/2005 Page 80 of 85

Citect Pty Ltd Driver User Guide

CitectSCADA DNPr Driver 18/08/2005 Page 81 of 85

Citect Pty Ltd Driver User Guide

CitectSCADA DNPr Driver 18/08/2005 Page 82 of 85

Citect Pty Ltd Driver User Guide

CitectSCADA DNPr Driver 18/08/2005 Page 83 of 85

Citect Pty Ltd Driver User Guide

6. References and Contacts

6.1 References
DNP 3.0 Basic 4 Document Set (Rev 03)
DNP V3.00 Subset Definitions (Vers 2.00)
DNP Master Software Library Triangle Micro Works Inc (Vers 1.66)

6.2 Contacts

[email protected]
Citect Pty Ltd
3 Fitzsimon Lane
Gordon, NSW 2072

DNP Organisation
http://www.dnp.org/

CitectSCADA DNPr Driver 18/08/2005 Page 84 of 85

Citect Pty Ltd Driver User Guide

CitectSCADA DNPr Driver 18/08/2005 Page 85 of 85