XML nodes, elements, and attributes

Save PDF

Last UpdatedNov 18, 2022
7 minute read

There are three major nodes that must be included in the PI DNP3 XML configuration file. The nodes are the Root, IOGroup, and RTU nodes.

Root Node

The root node must be named PIDNP.Session.

Root Node Attribute	Description
Address Required	This specifies the PI DNP3 interface 16-bit DNP3 master address. This will be the Master Address on the network. The user must choose an address that is unique on the DNP network. Some RTUs will need to be configured to specifically respond to this address.
DLRetries Optional	This is the number of times to retry when waiting on an ACK to a Data-Link message request. If connecting to multiple RTUs, set this value to zero to improve interface performance. Valid range {0 - 15} Default: 3
ALRetries Optional Example: <PIDNP.Session Address="1" DLRetries="3" ALRetries="3"	This is the number of times to retry when waiting on an ACK to an Application layer message request. If connecting to multiple RTUs, set this value to zero or one to improve interface performance. Valid range {0 - 15} Default: 3

Root Node Attribute

Description

Address

Required

This specifies the PI DNP3 interface 16-bit DNP3 master address. This will be the Master Address on the network. The user must choose an address that is unique on the DNP network.

Some RTUs will need to be configured to specifically respond to this address.

DLRetries

Optional

This is the number of times to retry when waiting on an ACK to a Data-Link message request.

If connecting to multiple RTUs, set this value to zero to improve interface performance.

Valid range {0 - 15}

Default: 3

ALRetries

Optional

Example: <PIDNP.Session Address="1" DLRetries="3" ALRetries="3"

This is the number of times to retry when waiting on an ACK to an Application layer message request.

If connecting to multiple RTUs, set this value to zero or one to improve interface performance.

Valid range {0 - 15}

Default: 3

Note: To improve interface performance, it is recommended to set the XML file DLRetries and ALRetries equal to zero when connecting to multiple RTUs.

IOGroup Nodes

Child nodes of the root node are IOGroup nodes. The IOGroup nodes are used to specify the properties of a physical device such as a communication port, or TCP port. The IOGroup node has one attribute - Type. The type must be either Serial or TCP. The child nodes will depend on the type. A serial communications port will have different child nodes from a TCP port. The IOGroup is also used to group RTUs together that communicate through the same serial port. Each Serial IOGroup node will have one or more RTUInfo child nodes. Each of the RTUInfo nodes will represent an RTU that the PI DNP3 interface will communicate with through the physical port described by the IOGroup child nodes.

For TCP Input/Output, there must only be one RTUInfo child node per IOGroup. There are at least 64,000 TCP ports available on a machine that supports TCP/IP. It takes overhead both on the server side and on the client side to release and reacquire a TCP socket. For this reason, RTUs should not share the connection, and each RTU that communicates via TCP should be assigned to its own IOGroup thereby acquiring its own port on the interface machine. However, different TCP/IP IOGroup Nodes can have the same IP Address as long as they have different assigned Port numbers.

IOGroup Child Nodes for Type="Serial"	Description
Example: <IOGroup Type="Serial">
Port Required	The numeric value of the serial COM port to use. For example: if using COM1 set this value to 1. Valid range: {1 - Max Port} Example: <Port>1</Port>
Baud Optional	The speed at which to communicate. The default value is 9600. Valid range: {See serial specification} Default: <Baud>9600</Baud>
Parity Optional	The error checking parity to use. This can be 2 for even, 1 for odd, and 0 for none. Valid range: {0,1,2} Default: <Baud>0</Baud>
DataBits Optional	The number of data bits. The default value is 8. Valid range: {See serial specification} Default: <DataBits>8</DataBits>
StopBits Optional	The number of stop bits following a message. This can be 1 for one, 2 for two, or 3 for one and a half stop bits. Valid range: {1,2,3} Default: <StopBits>1</StopBits>
IOGroup Child Nodes for Type="TCP"	Description
Example: <IOGroup Type="TCP">
IP Required if TCP	The Host name or IP address of the RTU. Valid range: {Any valid address or name} Example: <IP>192.164.55.128</IP>
Port Optional	The TCP/IP port to use for communication. Valid range: {0 - Max Port Number} Default: <Port>20000</Port>

IOGroup Child Nodes for Type="Serial"

Description

Example: <IOGroup Type="Serial">

Port

Required

The numeric value of the serial COM port to use. For example: if using COM1 set this value to 1.

Valid range: {1 - Max Port}

Example: <Port>1</Port>

Baud

Optional

The speed at which to communicate.

The default value is 9600.

Valid range: {See serial specification}

Default: <Baud>9600</Baud>

Parity

Optional

The error checking parity to use. This can be 2 for even, 1 for odd, and 0 for none.

Valid range: {0,1,2}

Default: <Baud>0</Baud>

DataBits

Optional

The number of data bits.

The default value is 8.

Valid range: {See serial specification}

Default: <DataBits>8</DataBits>

StopBits

Optional

The number of stop bits following a message. This can be 1 for one, 2 for two, or 3 for one and a half stop bits.

Valid range: {1,2,3}

Default: <StopBits>1</StopBits>

IOGroup Child Nodes for Type="TCP"

Description

Example: <IOGroup Type="TCP">

Required if TCP

The Host name or IP address of the RTU.

Valid range: {Any valid address or name}

Example: <IP>192.164.55.128</IP>

Port

Optional

The TCP/IP port to use for communication.

Valid range: {0 - Max Port Number}

Default: <Port>20000</Port>

RTUInfo Nodes

The RTUInfo node is a child of the IOGroup node. This node describes the information specific for a single RTU. The IOGroup node can have one or more RTUInfo nodes.

RTUInfo Child Nodes	Description
Address Required	The DNP address of the device. Valid range: {0 - Max Integer} Example: <Address>100</Address>
ClearRestart Optional	If set to a value of 1, the interface will attempt to clear the RTU Restart Internal Indication (IIN) bit if it is set. Valid range: {0,1} 0 means do not clear restart IIN bit 1 means clear restart IIN bit Default: <ClearRestart>0</ClearRestart> Example: <ClearRestart>1</ClearRestart>
CloseOnDataError Optional	TCP connection only. If set to a value of 1, the interface will close and reestablish a new TCP connection to the RTU when the maximum retyr attempts for data failed to retrieve data from the RTU. Valid range: {0,1} 0 means do not close TCP connection on error 1 means close TCP connection on error. Default: <CloseOnDataError>0</CloseOnDataError> Example: <CloseOnDataError>1</CloseOnDataError>
IntegrityReconnect Optional	Specifies if the interface must perform an integrity scan on the RTU on reconnection with the RTU after a communications failure. For this attribute to be effective, the "IntegrityScan" attribute must be set to a value greater than zero. Meanings: 0 - No integrity scan on reconnect 1 - Perform an integrity scan on reconnect Valid range: {0,1} Default: <IntegrityReconnect>0</IntegrityReconnect> Example: <IntegrityReconnect>1</IntegrityReconnect>
IntegrityScan Optional	Specifies in minutes how often an integrity scan is performed. An integrity scan will only be performed if this attribute is set to something other than zero. If the value is greater than zero, then an integrity scan will be performed at start-up and then at the frequency configured with this attribute. Valid range: {0 - Max Integer} Default: <IntegrityScan>10</ IntegrityScan> Example: <IntegrityScan>0</ IntegrityScan>
NoResetLinkReply Optional	If set to a value of 1, the interface will not wait for the RTU to reply to a Reset Link request sent by the interface. NOTE: This attribute should only be used for RTUs that may not be DNP3 compliant. Typically, an RTU must reply to a received Reset Link request. See Appendix D for additional details on using this attribute. Valid range: {0,1} 0 means wait for a reply 1 means do not wait for a reply Default: <NoResetLinkReply>0</NoResetLinkReply> Example: <NoResetLinkReply>1</NoResetLinkReply>
NoResetLinkOnCrcError Optional	If set to a value of 0, the interface will not attempt to call Reset Link on an RTU with a CRC error in the RTU response. Valid range: {0,1} 0 means call Reset Link 1 means do not call Reset Link Default: < NoResetLinkOnCrcError>1</ NoResetLinkOnCrcError> Example: < NoResetLinkOnCrcError>0</ NoResetLinkOnCrcError>
ReadTimeout Optional	In milliseconds, the amount of time to wait for an entire message to be sent across the network. Depending on the type of network, this value may need to be increased to avoid a timeout. Valid range: {250 - 60000} Default: <ReadTimeout>2000</ReadTimeout> Example: <ReadTimeout>5000</ReadTimeout>
RequestQualifier Optional	Specifies the DNP3 qualifier that the interface will use when sending requests for static data. The default value is "1". There are some field RTUs that only support the "No Range Field" qualifier. In this case, the RTU must use a request qualifier "6" value. If the request qualifier is set to a value of 0, 1, or 2, the interface will use the smallest possible qualifier code as based on the largest index number of the requested object. If the request qualifier is set to "6", the interface will always use this qualifier value for RTU requests. Meanings: 0 - One Octet Start and Stop Indices 1 - Two Octet Start and Stop Indices 2 - Four Octet Start and Stop Indices 6 - No Range Field (all of a given type) The default value is 1, two octet start and stop indices. Valid range: {0,1,2,6} Default: <RequestQualifier>1</RequestQualifier> Example: <RequestQualifier>6</RequestQualifier>
RtuName Optional	The name assigned to this RTU. This attribute is only used for message logging. If the attribute is not defined, the default name of "DNP3_Device" will be used. It is not necessary to enclose the name in quotes Default: <RtuName>DNP3_Device</RtuName> Example: <RtuName>ION8400_Stubby</RtuName>
TimeSource Optional	The TimeSource node is used to identify the source of the timestamp for event data. There are three valid values that can be used in the type parameter of this node; RTU, Adjusted, and PI. Valid range: {RTU, Adjusted, PI} Default: <TimeSource>RTU</TimeSource> Example: <TimeSource>PI</TimeSource>
TimeSync Optional Format: freq:type:autotime	The TimeSync node determines if the RTU time is synchronized with the PI Server time, whether the RTU time is configured as local or UTC1, and if the interface should automatically synchronize the RTU if the "NEED TIME" bit is set in the Internal Indications (IIN) of the RTU. All values sent to the PI server will be time-stamped with a UTC time. The freq parameter of this node specifies how often the time on the RTU will be synchronized with the time from the PI Server. If freq is defined to be zero, then the time on the RTU will never be synchronized. If freq is greater than zero, then the RTU time will be synchronized when the interface starts and every freq hours thereafter. The type parameter of the TimeSync node informs the interface of whether the RTU is configured in local or in UTC time. The two valid values for the type parameter are UTC and Local. Knowing if the RTU is configured for UTC or Local serves two purposes. First, configuration informs the interface about what time format must be sent to the RTU during time synchronizations. Secondly, it allows the interface to correctly adjust the timestamp of event data received from the RTU. If the autotime parameter is set to '1', then the interface will attempt to time synchronize the RTU if the "NEED TIME" bit is set in the Internal Indications (IIN) of the RTU regardless of when the last synchronization occurred. Freq valid range: {0-65535} Type valid range: {UTC, LOCAL} Autotime valid range: {0,1} Default: <TimeSync>0:UTC:0</TimeSync> Means: no timesynching, rtu is UTC, autotime disabled Example: <TimeSync>0:Local:1</TimeSync> Means: no timesynching, rtu is Local, autotime enabled Example: <TimeSync>1:Local:1</TimeSync> Means: timesynching, rtu is Local, autotime enabled Backward Compatibility. The DNP3 interface version 1.4.x TimeSync supports the previous version's way of only entering a number for the hours. If the parameter appears in the XML file as <TimeSync>12</TimeSync>, then the time synchronize frequency is every 12 hours and the RTU time is assumed to be UTC.
Unsolicited Optional 1 Coordinated Universal Time - (UTC, World Time) The standard time common to every place in the world. UTC is derived from International Atomic Time (TAI) by the addition of a whole number of "leap seconds."	The Unsolicited node sets the interface configuration for unsolicited messages from the RTU. Meanings: 0 - Do not enable unsolicited messages from RTU 1 - Enable unsolicited messages from RTU Valid range {0,1} Default: < Unsolicited>0</Unsolicited> Example: < Unsolicited>0</Unsolicited> Example: < Unsolicited>1</Unsolicited>

RTUInfo Child Nodes

Description

Address

Required

The DNP address of the device.

Valid range: {0 - Max Integer}

Example: <Address>100</Address>

ClearRestart

Optional

If set to a value of 1, the interface will attempt to clear the RTU Restart Internal Indication (IIN) bit if it is set.

Valid range: {0,1} 0 means do not clear restart IIN bit

1 means clear restart IIN bit

Default: <ClearRestart>0</ClearRestart>

Example: <ClearRestart>1</ClearRestart>

CloseOnDataError

Optional

TCP connection only. If set to a value of 1, the interface will close and reestablish a new TCP connection to the RTU when the maximum retyr attempts for data failed to retrieve data from the RTU.

Valid range: {0,1} 0 means do not close TCP connection on error

1 means close TCP connection on error.

Default: <CloseOnDataError>0</CloseOnDataError>

Example: <CloseOnDataError>1</CloseOnDataError>

IntegrityReconnect

Optional

Specifies if the interface must perform an integrity scan on the RTU on reconnection with the RTU after a communications failure. For this attribute to be effective, the "IntegrityScan" attribute must be set to a value greater than zero.

Meanings:

0 - No integrity scan on reconnect

1 - Perform an integrity scan on reconnect

Valid range: {0,1}

Default: <IntegrityReconnect>0</IntegrityReconnect>

Example: <IntegrityReconnect>1</IntegrityReconnect>

IntegrityScan

Optional

Specifies in minutes how often an integrity scan is performed. An integrity scan will only be performed if this attribute is set to something other than zero. If the value is greater than zero, then an integrity scan will be performed at start-up and then at the frequency configured with this attribute.

Valid range: {0 - Max Integer}

Default: <IntegrityScan>10</ IntegrityScan>

Example: <IntegrityScan>0</ IntegrityScan>

NoResetLinkReply

Optional

If set to a value of 1, the interface will not wait for the RTU to reply to a Reset Link request sent by the interface.

NOTE: This attribute should only be used for RTUs that may not be DNP3 compliant. Typically, an RTU must reply to a received Reset Link request. See Appendix D for additional details on using this attribute.

Valid range: {0,1} 0 means wait for a reply

1 means do not wait for a reply

Default: <NoResetLinkReply>0</NoResetLinkReply>

Example: <NoResetLinkReply>1</NoResetLinkReply>

NoResetLinkOnCrcError

Optional

If set to a value of 0, the interface will not attempt to call Reset Link on an RTU with a CRC error in the RTU response.

Valid range: {0,1} 0 means call Reset Link

1 means do not call Reset Link

Default: < NoResetLinkOnCrcError>1</ NoResetLinkOnCrcError>

Example: < NoResetLinkOnCrcError>0</ NoResetLinkOnCrcError>

ReadTimeout

Optional

In milliseconds, the amount of time to wait for an entire message to be sent across the network. Depending on the type of network, this value may need to be increased to avoid a timeout.

Valid range: {250 - 60000}

Default: <ReadTimeout>2000</ReadTimeout>

Example: <ReadTimeout>5000</ReadTimeout>

RequestQualifier

Optional

Specifies the DNP3 qualifier that the interface will use when sending requests for static data. The default value is "1". There are some field RTUs that only support the "No Range Field" qualifier. In this case, the RTU must use a request qualifier "6" value.

If the request qualifier is set to a value of 0, 1, or 2, the interface will use the smallest possible qualifier code as based on the largest index number of the requested object. If the request qualifier is set to "6", the interface will always use this qualifier value for RTU requests.

Meanings:

0 - One Octet Start and Stop Indices

1 - Two Octet Start and Stop Indices

2 - Four Octet Start and Stop Indices

6 - No Range Field (all of a given type)

The default value is 1, two octet start and stop indices.

Valid range: {0,1,2,6}

Default: <RequestQualifier>1</RequestQualifier>

Example: <RequestQualifier>6</RequestQualifier>

RtuName

Optional

The name assigned to this RTU. This attribute is only used for message logging. If the attribute is not defined, the default name of "DNP3_Device" will be used. It is not necessary to enclose the name in quotes

Default: <RtuName>DNP3_Device</RtuName>

Example: <RtuName>ION8400_Stubby</RtuName>

TimeSource

Optional

The TimeSource node is used to identify the source of the timestamp for event data. There are three valid values that can be used in the type parameter of this node; RTU, Adjusted, and PI.

Valid range: {RTU, Adjusted, PI}

Default: <TimeSource>RTU</TimeSource>

Example: <TimeSource>PI</TimeSource>

TimeSync

Optional

Format: freq:type:autotime

The TimeSync node determines if the RTU time is synchronized with the PI Server time, whether the RTU time is configured as local or UTC1, and if the interface should automatically synchronize the RTU if the "NEED TIME" bit is set in the Internal Indications (IIN) of the RTU.

All values sent to the PI server will be time-stamped with a UTC time. The freq parameter of this node specifies how often the time on the RTU will be synchronized with the time from the PI Server. If freq is defined to be zero, then the time on the RTU will never be synchronized. If freq is greater than zero, then the RTU time will be synchronized when the interface starts and every freq hours thereafter. The type parameter of the TimeSync node informs the interface of whether the RTU is configured in local or in UTC time. The two valid values for the type parameter are UTC and Local. Knowing if the RTU is configured for UTC or Local serves two purposes. First, configuration informs the interface about what time format must be sent to the RTU during time synchronizations. Secondly, it allows the interface to correctly adjust the timestamp of event data received from the RTU.

If the autotime parameter is set to '1', then the interface will attempt to time synchronize the RTU if the "NEED TIME" bit is set in the Internal Indications (IIN) of the RTU regardless of when the last synchronization occurred.

Freq valid range: {0-65535}

Type valid range: {UTC, LOCAL}

Autotime valid range: {0,1}

Default: <TimeSync>0:UTC:0</TimeSync>

Means: no timesynching, rtu is UTC, autotime disabled

Example: <TimeSync>0:Local:1</TimeSync>

Means: no timesynching, rtu is Local, autotime enabled

Example: <TimeSync>1:Local:1</TimeSync>

Means: timesynching, rtu is Local, autotime enabled

Backward Compatibility. The DNP3 interface version 1.4.x TimeSync supports the previous version's way of only entering a number for the hours. If the parameter appears in the XML file as <TimeSync>12</TimeSync>, then the time synchronize frequency is every 12 hours and the RTU time is assumed to be UTC.

Unsolicited

Optional

1 Coordinated Universal Time - (UTC, World Time) The standard time common to every place in the world. UTC is derived from International Atomic Time (TAI) by the addition of a whole number of "leap seconds."

The Unsolicited node sets the interface configuration for unsolicited messages from the RTU.

Meanings:

0 - Do not enable unsolicited messages from RTU

1 - Enable unsolicited messages from RTU

Valid range {0,1}

Default: < Unsolicited>0</Unsolicited> Example: < Unsolicited>0</Unsolicited> Example: < Unsolicited>1</Unsolicited>

PI Interface for DNP3