DNPR Users Guide
DNPR Users Guide
DNPr Driver
User Information and Design
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 :
Contents
1. INTRODUCTION 6
1.1 Scope. 6
1.2 Outline. 6
1.3 Terms 7
3. USER INTERFACE 15
3.1 Introduction 15
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
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
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
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.
Section 1 – Introduction.
This section defines the scope of a board driver specification and outlines the items
addressed by the specification.
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
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.
serial or IP
Citect
Ethernet
Event data corresponding to the above mentioned static data should be assigned to Classes 1,2 or 3.
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).
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.
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.
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.
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.” .
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
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
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.
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.
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.
!
! Sample Configuration File
!
! Example of using a constant string, Note spaces and commas allowed within quotes
<none>, @Logcurrentvalues, Power_Total, “Current value of Power_total, in MegaWatts”
Note: The integrity poll always asks for the static data for all event classes.
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.
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.
Where:
• “aaa.bbb.ccc.ddd” is the RTU’s IP address.
“e” is the port number of the RTU.
-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.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.
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
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.
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
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
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.
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
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
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.
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)
Quality
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)
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.
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
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
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
but requested
operation already
executing.
No Object
Bit 5 of Byte 2 of the IIN.ConfigIIN DIGITAL R/O
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
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)
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.
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.
1,2,3
Binary Output Control Bon.Doperate.TC DIGITAL W/O. Selects and activates point operation
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
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.
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
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
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.
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.
Where:
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).
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.
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
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.
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
Virtual Tag Time Virtualn.Val.TS LONG UTC time associated with value
Stamp (milliseconds
since midnight)
Virtual Tag Quality Virtualn.Val.QUAL LONG OPC quality associated with value.
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:
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.
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.
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
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.
[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] 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
[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.
[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
[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.
[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.
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 .
[<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
[<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)
[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”.
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.
See section 3.14 for details for configuring alarm and event tags.
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)
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)
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 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 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 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 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 0x10002 API - Function code in response not supported API error
DNPR 0 0x10004 API - Response received with no active request 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 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 0x1000E API - Obj/Var not supported in write response API error
DNPR 0 0x1000F API – Invalid device number in transmit queue 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
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 .
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
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
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' .
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
These are the statistics shown in the kernel window when view “driver” and then the “v” key has been
pressed.
• 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.
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)
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.
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.
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.
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.
Returns the next event queue sequence number and only deletes the current event IF
bDelete is set to 1.
LONG __ _EmptyEventQue(void);
Used to read data for a specific event, usually the one just retrieved by the GetRTUN-
extEvent call. fieldNumber values are :
#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.
"<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.
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 .
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.
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.
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.
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.
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.
The runtime values must at least equal the compile time settings. They can however be larger than
compile time settings.
• IsItemisedRequest=0
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.
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.
4. Protocol Requirements
4.1 Introduction
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.
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 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.
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:
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.
5. Design
[InitUnit()]
[Has peer]
Initialising
[No peer]
Synchronising
[InitUnit() or
UnitStatus() or
[Peer is activating]
[No peer or Channel failed or
peer inactive] No peer]
Active
[StopUnit()]
Stopped
[]
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/