Copyright ? 2011 Green Energy Corp. All Rights Reserved.
?
Document Control #: 02.004.000.000.000
Release Date: 20111220
The goal of this document is for communication engineers and integrators to understand how to build an XML file that accurately models their system. The readers of this document should have read the "Overview" document first, this document uses terminology from that overview pervasively. Specific sections to focus on are "System Concepts - Model", "Subsystems - Modeling in Reef" and "Subsystems - Measurement Subsystem".
Reef utilizes xml configuration files to load in the model for a real world system.
A single xml configuration file contains all of the equipment, measurement, and control definitions, the messaging parameters, and the endpoint definitions. Each communication link requires an additional xml configuration file for communication parameters.
Multiple configuration files can be used for different sections of the system. Some users may find having one file for each logical unit of equipment to be helpful. In the power utility industry a single substation is often configured and managed as a unit. In other cases the equipment model is managed by a domain expert and the communication model is created and manged by a commuincations or SCADA engineer; in those cases it is helpful to split the communication and equipment models into two files.
| Caution | |
|---|---|
|
The XML loader performs a number of checks on the "validity" of the model when loading a file. If the configuration of a single piece of equipment or endpoint is split over multiple files the verification step may produce warnings, those validity checks can be disabled in that case. |
The messageModel section of the Reef configuration xml is the location were logging, alarming, and event reporting are all configured. Messages are categorized using the parent messageSet element. Message sets are assigned a name, severity, type, and state.
The actionModel section of the Reef configuration xml is where actionSets are defined. An actionSet is used to designate what state of a measurement will trigger a message. An actionSet is attached to a measurement in the equipmentModel section of the xml. An actionSet is assigned by name to a measurement by using the name of the actionSet.
The equipmentModel section of the Reef configuration xml defines all of the logical devices in the system. Profiles can be created in equipmentModel for measurements and equipment to allow for ease of configuration. SCADA Measurements are defined and associated with stations and/or field equipment in equipmentModel.
The communicationModel section of the Reef configuration xml is the location where all of the communication and endpoint measurement index mapping parameters are configured. The Reef system is configured with all of the necessary parameters required to communicate with all of the end devices. SCADA measurements defined in the equipmentModel section are linked to actual measurements in endpoint devices. All required scaling is also done in the communicationModel section.
It is important to use the correct "xml namespace" in the each section. There are two representations of many of the elements that share the same name and are differentiated by what namespace they belong to. For example the communicationModel and equipmentModel both have elements named "equipment" and "control" but they are always referred to as "eq:equipment" or "cm:equipment" to make it clear which type we are using. The elements in the equipmentModel section are all prefaced with "eq:". In the communicationModel section elements are prefaced with "cm:". In the messageModel and actionModel sections there is no namespace. Care must therefore be taken to make sure the correct namespace is used in each section, especially if copy-pasting similar sections between the two.
| Caution | |
|---|---|
|
If the wrong namespace is used there will be no warning or errors, it will just be as if that section was not in the document. |
Each configuration file needs to "import" the xml namespaces before use. An example of the minimal configuration file follows although it is recommended that users start with one of the included samples. https://github.com/gec/reef/tree/master/assembly/src/main/filtered-resources/samples
version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
targetNamespace="configuration.loader.reef"
xmlns="configuration.loader.reef.totalgrid.org"
xmlns:eq="equipment.loader.reef.totalgrid.org"
xmlns:cm="communications.loader.reef.totalgrid.org"
xsi:noNamespaceSchemaLocation="configuration.xsd">
The messageModel section of the Reef configuration xml is where "system messages" are configured. All "system messages" are sent to the EventService where the messaging configuration is applied to route the message to correct locations. "System messages" can be configured to be handled as a log, event or alarm.
Every Event generated in the system has a "name" used in other parts of the system. When an Event is produced we lookup the configuration for the alarm in the Messages service to determine how it should be handled. Each Event type can be configured with different behaviors and textual messages on a per installation basis. The XML Element that allows us to specify those settings is
name="OutOfReasonable" severity="3" type="ALARM" state="UNACK_AUDIBLE">
Measurement not reasonable: {value}{unit} validity {validity}
name Name for the message.
severity Value from 1 to 8 used to prioritize events. 1 is the highest priority message.
type Must be either ALARM, EVENT, or LOG. Types are hierarchical. Alarm types will also produce event and log messages. Event types will also produce log messages. If type is ALARM the state setting must also be set.
state Defines the starting alarm state. This allows the integrator to configure an alarm to be "UNACK_AUDIBLE" or "UNACK_SILENT" when it comes into existence.
message The message string is configurable allowing for site or locale specific messages. Many system events have named "attributes" that include extra information about a specific occurrence. Attributes may be things like the value of a measurement that is above a predetermined limit or the name of the agent who has just logged in. Each named attribute (surrounded by curly braces) will be inserted into the message description when it is processed by the EventService.
System messages can be configured in groups called messageSets. Message sets have a severity, type, and state. If the optional attributes are not assigned for a message, the attributes of the parent messageSet are assigned to the message by default. The name of the parent messageSet is concatenated with a period to the message name. The following is an example of the modeling of a messageSet:
name="System" severity="8" type="EVENT">
name="UserLogin" severity="4">User login {status} {reason}
name="UserLogout">User logged out
This would produce two messages with names "System.UserLogin" and "System.UserLogout". Events with type "System.UserLogin" would have severity 4 because we overrode the default severity of 8.
The equipment model section defines the system in the way an engineer would expect to see it embedded
The most important element in the equipmentModel section is the
name="CB11001">
name="CircuitBreaker" />
name="Bkr" unit="breakerStatus">
name="Close" />
name="Trip" />
name="Mw" unit="Mw">
actionSet="RLC" low="10" high=?30?/>
name="Close" />
name="Trip" />
name="TargetVoltage" />
In this example the following objects were created:
CB11001 (Equipment, CircuitBreaker)
CB11001.Bkr (Point, Status)
CB11001.Mw (Point, Analog)
CB11001.Trip (Command, Control)
CB11001.Close (Command, Control)
CB11001.TargetVoltage (Command, Setpoint)
In most systems there will be many pieces of equipment that are logically modeled the same way. In many cases the hardware in the field will vary depending on location and when it was installed but to applications and operators we want to model them as the same sort of equipment. Replicating the same configuration for every device is error prone and hard to manage so we have introduced "profiles" that can be reused by multiple equipment. The "profiles" concept is used through the modeling: points, commands, equipment definitions all have support for profiles to minimize duplication. Generally a profile for an element has the same fields as the element itself so a "regular" definition can easily be made a profile.
We can define an
name="CircuitBreakerProfile"> name="CircuitBreaker" /> name="Bkr" unit="breakerStatus"> name="Close" /> name="Trip" /> name="Mw" unit="Mw"> actionSet="RLC" low="10" high="30"/> name="Close" /> name="Trip" /> name="TargetVoltage" /> name="CB11001"> name="CircuitBreakerProfile" /> name="CB11002"> name="CircuitBreakerProfile" /> name="CB11003"> name="CircuitBreakerProfile" /> name="Temperature" unit="F">
Points are owned by Equipment and have at least a name and a unit. There are three sub-types of points who differ in what type of data they will have.
Status - These are boolean values, representing either true or false. In many cases a value of true or false is too vague to be useful so the string will be transformed into an enumeration giving a context specific name for the value.
Analog - These are floating point values. These often represent measured real-world values like voltages and temperatures.
Counter - These are integer point values. These more commonly are internal status values like reboot count or status enumerations.
When points are defined we also define a number of properties about each Point, including display names, linked commands, units and alarming settings.
Sample status point configuration. It shows that it is linked via feedback to the "Close" and "Trip" controls. Shows how to translate a raw boolean value into a string enumeration that cannot be misinterpreted. Lastly it is configured to perform the "OutOfNominal" actionSet if the value is "Open".
name="Bkr_A" unit="breakerStatus">
name="Close" />
name="Trip" />
fromUnit="raw" toUnit="breakerStatus" transformationType="status">
fromValue="true" toValue="Open" />
fromValue="false" toValue="Closed" />
stringValue="Open" actionSet="OutOfNominal"/>
Sample analog point configuration. It shows that it is linked via feedback to the "TargetVoltage" setpoint. It also shows an example of nested limits. We activate the OutOfNominal actionSet if the value strays outside of the 10-30 Mw range and the more severe OutOfSafe actionSet when the value gets further away from the nominal values.
name="Mw" unit="Mw">
name="TargetVoltage" />
actionSet="OutOfNominal" low="10" high="30"/>
actionSet="OutOfSafe" low="5" high="35"/>
Like equipment, point definitions can be templated using pointProfiles. The status example could be rewritten as follows which makes defining three similar breakers easy:
name="BreakerStatusProfile" unit="breakerStatus"> name="Close" /> name="Trip" /> fromUnit="raw" toUnit="breakerStatus" transformationType="status"> fromValue="true" toValue="Open" /> fromValue="false" toValue="Closed" /> name="Bkr_A" pointProfile="BreakerStatusProfile"/> name="Bkr_B" pointProfile="BreakerStatusProfile"/> name="Bkr_C" pointProfile="BreakerStatusProfile"/>
ActionSets define a group of actions we will perform if a measurement meets some criteria. The criteria for when an actionSet should be activated is described in the Point Definition section.
Example of an actionSet to trigger when a value leaves its nominal range. When the measurement first leaves the nominal range an Event is generated with the error code "Scada.OutOfNominal". This actionSet will also update the quality of every measurement that isn't in the nominal range to indicate it is abnormal.
name="OutOfNominal">
name="Scada.OutOfNominal"/>
Example of an actionSet that just marks a point as abnormal. An actionSet does not need to include all of the options.
name="MarkAbnormal">
The communicationModel section of the Reef configuration xml is the location where all of the communication and endpoint measurement index mapping parameters are configured. The Reef system is configured with all of the necessary parameters required to communicate with all of the Endpoints. Points defined in the equipment section are linked to actual measurements in endpoint devices. All required scaling is also done in the communications modeling sections.
An Endpoint is an intelligent electronic device (IED) that Reef will communicate with to monitor telemetered data.
Protocol Reef communicates to each Endpoint using a field device communication protocol. Each protocol may have extra capabilities but at a minimum Reef expects each protocol to produce Measurements and handle CommandRequests. Example of Reef supported protocols are "dnp3" (Distributed Network Protocol) and "benchmark" (simple randomized simulations). Many protocols require more configuration information or specific input files than just the list of Points and Commands they are responsible for. In these situations extra, opaque, configuration files can be included with the protocol definition.
Interface Many communication protocols, including nearly all field device protocols, communicate to the Endpoint at a predetermined serial or TCP/IP location. Interfaces encompass both of those sorts of "port" definitions but may be extended to support other addresses in the future. Interface elements can be defined inside an endpoint element or defined in the communicationsModel and referenced by name.
Points and Commands Endpoints are related to Points and Commands defined in the equipmentModel. An Endpoint is the "source" of Measurements for Points and the "sink" where CommandRequests are sent to the field device. Each Point and Command is linked by including the same nested equipment structure used to declare the Entity in the equipmentModel. If per Point/Command protocol specific information is needed it is included with each Point/Command.
Each Point should also include the "unit" of the data reported by the communication protocol. Sometimes a field device is reading a "real world" value directly and the correct unit can simply be attached but in many cases the value reported by the Endpoint needs furthur processing before it has a real meaning. A common example of this is using a generic Analog-to-Digital converter attached to a transducer to current on a wire. The A2D converter reports the voltage output of the transducer (usually in the milli-volt range) which must be translated to current by some scaling factor specific to the transducer being used. In this case it is helpful for the communication engineer to attach a unit like "rawTransducerOutput-mV" so in processing steps it will be clear why the value needs to be translated. This allows us to validate the measurement processing pipeline steps to verify that each measurement produced by the Endpoint will end up translated to have the correct final unit. If the unit is unspecified the default unit of "raw".
Points and Commands options can use profiles so that the same configuration can be applied to multiple entries.
The following is a minimal endpoint configuration:
name="Sel351Endpoint1">
name="benchmark"/>
name="ChapelHill">
name="CB11001">
name="Trip"/>
name="Close"/>
name="TargetVoltage"/>
name="Bkr"/>
name="Mw" unit="Mw"/>
This defines an Endpoint that is responsible for two Points and three Commands. This example is using the "benchmark" protocol which requires no per Point/Command information so it is very simple. It is often worthwhile for a communication engineer to start by defining all of the endpoints using "benchmark" and checking that all of the points are correctly linked and have the correct processing steps.
Serial Port Interface definitions include an extra piece of information beyond the standard serial configuration properties called "location." This is the name of computer that the serial port is physically located on. When Reef tries to assign ProtocolAdapaters to each Endpoint it needs to make sure that it only assigns a ProtocolAdapter that has direct access to the serial port in the interface using the "location". Each ProtocolAdapter reports its "location" when it registers itself with Reef, usually using the hostname of the server.
TCP/IP Ports have a very similar need though they are much more flexible than serial ports. Clearly we can connect to a TCP/IP port on another machine in general but determining if a given ProtocolAdapter can reach a particular address is not a simple task. To handle this issue we use the attribute "network" which is the name of a set of addresses that are all reachable from each other. In the situation where there is no network partitions then you can use the default of "network="any"". Each ProtocolAdapter reports which "networks" it has access to along with its "location" when registering.
The following example demonstrates a real world network topology and how ProcotolAdapters would be assigned:
name="E1" ip="192.168.0.60" network="sub1"/> name="E2" device="/dev/tty01" baud="9600" location="sub1-server"/> name="E3" ip="192.168.50.82" network="sub2"/> name="E4" ip="10.0.0.50" network="corp"/> name="E5" ip="2.3.4.5" network="inet"/>
The DNP3 Protocol is a very common communication protocol among utilities in North America. The Reef implementation of DNP3 requires that the user specify a few additional parameters for each Point and Command.
DNP3 is an "indexed" protocol so each Point and Command is identified only by its placement in the list of matching data points. Each Point and Command needs to include a value for the "index" attribute, the loader will verify that all elements include an index and that no index is duplicated to multiple Points. So for example a status point representing a fire alarm may have the index "0" and the status point indicating a door ajar sensor may have the index "1". Since there is no other context information it is vitally important that the index be correct for every point, if the two indexes in the previous example were reversed then we would think a fire occurred every time the door was opened. Since so many of the field protocols are "indexed" the index attribute is included directly on all of the Point and Command elements, non-indexed protocols will ignore those attributes.
We must also declare the DNP3 command code we are using for controls. In Reef we represent each "action" as a single Control, but in older field devices it is common to have a single Control perform multiple actions depending on the "Control Code" sent. The DNP3 "Control Codes" (attribute name "type") are PULSE, LATCH_ON, LATCH_OFF, PULSE_CLOSE, PULSE_TRIP.
The following is a simple DNP3 Endpoint configuration:
name="Sel351Endpoint1">
name="dnp3">
name="comms/sel_351_endpoint1.xml">
name="i1" ip="192.168.100.30" netmask="255.255.255.0"
port="8003" network="any"/>
name="ChapelHill">
name="CB11001">
name="Trip" index="16">
type="PULSE_TRIP" onTime="1000"
offTime="1000" count="1"/>
name="Close" index="16">
type="PULSE_CLOSE" onTime="1000"
offTime="1000" count="1"/>
name="TargetVoltage" index="1" />
name="Bkr" index="4"/>
name="Mw" index="14">
rawLow="0" rawHigh="50" engLow="100.0"
engHigh="200.0" EngUnit="Mw"/>
This defines a DNP3 Endpoint that is responsible for two Points and three Commands and includes the additional information necessary for each element. Notice that the "Trip" and "Close" Controls have the same index but different control codes. Notice also that the "Mw" Point is scaled from the "raw" range of 0,+50 to 100.0,200.0 before having the unit "Mw" attached.
We also include a link to a configuration file the DNP3 protocol uses to configure the communications. It contains details like the polling parameters, slave DNP3 address, timeouts etc. An example of a configuration file is available with the samples.
| Caution | |
|---|---|
|
The DNP3 implementation does not use DNS to lookup ip addresses so only explicit IP addresses may be used in the interface definitions. |
This section assumes that the user has access to a running Reef system and the correct permissions to run the loader.
For this section we are using we have an XML Model file we need to load it into Reef. The model can be loaded by any user with "Create" privileges on all of the necessary resources, generally a user with "admin" role is necessary.
To upload the model use the command "load".
karaf@root> load samples/integration/config.xml
Loading Equipment: Found PointProfiles: BreakerStatus, TrippedStatus
Loading Equipment: Found EquipmentProfiles: MockBreaker, MockLine, Substation
Loading Equipment: processing equipment 'SimulatedSubstation'
Loading Equipment: processing equipment 'StaticSubstation'
Loading Communications: processing endpoint 'SimulatedEndpoint'
Loading Communications: processing endpoint 'StaticEndpoint'
POINTS SUMMARY:
Points found in equipmentModel and communicationsModel: 6
Points found in equipmentModel only: 0
Points found in communicationsModel only: 0
CONTROLS SUMMARY:
Controls found in equipmentModel and communicationsModel: 6
Controls found in equipmentModel only: 0
Controls found in communicationsModel only: 0
Processing 72 objects
0 of 72 |+++++++++++++++++++++++++++++++++*++++++++++++++++
50 of 72 ++++++++++++++++++++++|
Statistics. Finished in: 1092 milliseconds
CREATED(+) : 71
UPDATED(*) : 1
Types:
TriggerSet : 6
Command : 6
Entity : 18
ConfigFile : 6
EntityAttributes : 6
EntityEdge : 22
Endpoint : 2
Point : 6
Configuration loaded.
karaf@root>
There are two main classes of error that will be encountered while trying to load a model, "Critical Errors" and "Validation Errors".
"Critical Errors" are caused as the XML file is being initially parsed. These sorts of errors are usually caused by trying to reference configuration files or profiles that do not exist. Critical errors can cascade, an early error may cause a number of later errors that will be cleared up if the initial error is fixed. We attempt to keep handing the file and return all errors at once so the user can fix as many errors as possible on each attempt. If there are a large amount of errors, the best course of action is fix errors in the order they appear in the message. A file with "critical errors" cannot be loaded into Reef.
The second class of errors is "Validation Errors". These errors are generated after the entire file has been loaded without "critical errors" and attempts to validate that the file describes a valid system. These checks assume that each file is a self-contained unit that fully describes the system. If multiple files are used in a model some verification checks will fail, the loader can be configured to upload the model even if it has verification errors.
Validation Checks
Each Point and Command is only owned by one piece of Equipment ("owns" relationship).
Each Point and Command is only attached to one Endpoint ("source" relationship).
Point, Command, Endpoint names are all unique.
Endpoints are checked for unique indexes per Point and Command for "Indexed" protocols like dnp3.
See the "XML Modeling" document for specific troubleshooting information.
The following are two examples of the error messages if we try to "load" a file that doesn't exist. The error message prints out the full path of the file we tried to load so we can verify that it is trying to load the file from the correct place.
karaf@root> load missingconfig.xml
Error loading configuration file 'missingconfig.xml' null
Error running command: javax.xml.bind.UnmarshalException
- with linked exception:
[java.io.FileNotFoundException:
C:\code\scada\reef\totalgrid-reef-0.3.1-SNAPSHOT\missingconfig.xml
(The system cannot find the file specified)]
karaf@root> load samples\integration\config.xml
Error loading configuration file 'samplesintegrationconfig.xml' null
Error running command: javax.xml.bind.UnmarshalException
- with linked exception:
[java.io.FileNotFoundException:
C:\code\scada\reef\totalgrid-reef-0.3.1-SNAPSHOT\samplesintegrationconfig.xml
(The system can not find the file specified)]
| Caution | |
|---|---|
|
Note that you should always use forward-slashes in the path, even on windows. The second example shows what occurs if you use back-slashes, it will just merge the sections into one file. |
When trying to load configuration files we attempt to locate the config files using a relative path from the main xml file. If those configuration files are missing we consider that a critical error, we will attempt to continue loading the file but not all other errors will be caught.
Assuming the model we are loading has the following XML snippet, we need to make sure that the file "device_dnp3.xml" is in a directory "comms" below "config.xml".
name="FieldDevice">
name="dnp3">
name="comms\device_dnp3.xml" />
..... >
karaf@root> load samples/integration/config.xml
Loading Equipment: Found PointProfiles: BreakerStatus, TrippedStatus
Loading Equipment: Found EquipmentProfiles: MockBreaker, MockLine, Substation
Loading Equipment: processing equipment 'SimulatedSubstation'
Loading Equipment: processing equipment 'StaticSubstation'
Loading Communications: processing endpoint 'SimulatedEndpoint'
Errors detected, attempting to continue loading,
not all errors may be detected until these errors are fixed.
Loading Communications: processing endpoint 'StaticEndpoint'
Critical Errors found:
Config Files: - Error loading config file: samples\integration\comms\device_dnp3.xml
Message: samples\integration\comms\device_dnp3.xml
(The system cannot find the file specified)
Fix Critical Errors and try again.
Configuration invalid, fix errors or add ignoreWarnings argument
The "unload" command removes all configuration objects from the system, allowing a new configuration to be loaded from scratch.
karaf@root> unload
Finding items to delete starting at nodes:
Disabling endpoints: StaticEndpoint, SimulatedEndpoint
Waiting for StaticEndpoint, SimulatedEndpoint to stop...
Waiting for SimulatedEndpoint to stop...
Endpoints stopped.
Processing 25 objects
0 of 25 |-------------------------|
Statistics. Finished in: 735 milliseconds
DELETED(-) : 25
Types:
Command : 6
Entity : 6
ConfigFile : 5
Endpoint : 2
Point : 6
Deleted 25 objects successfully.
karaf@root>