Copyright ? 2011 Green Energy Corp. All Rights Reserved.
?
Document Control #: 02.004.000.000.000
Release Date: 20111220
This documentation is based on the Reef documentation but is enhanced with additional information.
Once the operational data is being collected from the field using Reef, applications can be created to analyze or affect the system in new and novel ways. Some common application patterns are detailed in this section, though most non-trivial applications will have aspects of more than one pattern.
To get Measurements into and out of Reef from Communication Endpoints it is usually necessary to communicate with the device using a specific, single-purpose protocol. Protocol Adapters need to be written for each field protocol; they will convert the protocol-specific details into the protocol neutral Reef form. Protocol Adapters are responsible for two main data flows: acquiring Measurements from the field and issuing CommandRequests. Additionally, most Protocol Adapters have the responsibility of informing Reef when communications links are unavailable or unreliable.
Examples of Protocol Adapters
Legacy Protocols: DNP3, Modbus and similar protocols are used in the field to communicate with low-level embedded hardware and PLC devices.
Interoperation Protocols: There are a number of emerging standards for interoperation between applications and business groups. Examples include MultiSpeak, CIM etc.
Services Used
MeasurementService publishes batches of Measurements.
CommandService provides a means to issue commands to remote device.
EndpointService informs Reef when a communication link goes online of offline.
Simulators are a specialized type of Protocol Adapter which simulate field telemetry in order to drive development and testing. Simulators may vary wildly in complexity and features, but most usually include one or more "backdoors" so a trainer or developer can affect the state of the system in a predictable way.
System analyzers are applications that observe the state of the system, perform processing and produce a result. These results may themselves be published to the system as Measurements or Events, or sent to an external process.
Examples of system analyzers
Renewables Performance: If Reef is used to monitor a renewable power plant, an analyzer may calculate the efficiency of the system as a whole every few seconds. If those efficiency numbers were then republished as Measurements, the built-in trending and historical functionality of Reef could be used to monitor production efficiency over time.
Power Flow Analysis: An electrical utility distribution system may analyze Measurement data to determine where real and reactive power is flowing in order to drive future deployments. Analysis of this type may be very time-consuming and thus be run every few hours with specialized software.
Services Used
MeasurementService
EventService
System automation is usually the next step after system analysis. Once a system is well understood there is often a way to automate and manage the system to achieve new and interesting goals. Automation systems will issue controls and setpoints to field devices to achieve a desired goal. Automation is usually driven by a combination of operator input and field data.
Examples of System Automation
Automated Demand Response (ADR): If an electrical utility's customers are taxing its resources on a hot summer afternoon, an ADR application can be started by an operator. The ADR application will start issuing "reduce usage" commands to customers until the load on the system drops below the nominal operating values.
Circuit Switching: Switching which circuit is serving a particular feeder can require the operation of a large number of circuit breakers in a highly prescribed order. Such modifications can be performed by a human operator but the operation will take longer and be more prone to errors. An automated switching application can take the high level operator goal and translate it to the commands necessary to get the circuits switched safely and quickly.
Services Used
Same services as System Analyzers
CommandService to issue commands and manage the system
When a system is deployed there is usually a need for visualizing and interacting with that system. Reef offers a powerful thin-client application that provides a multi-user HMI but it may not be appropriate for all systems. HMIs are simply applications like any other Reef application, and they do not have any special access to data not exposed through the APIs. Custom HMIs or visualizations can be added to any outside system that can use the APIs. In some cases adding a simple visualization of Reef data to an existing system is more effective than replacing a complex system just to display that data.
Services Used
EntityService to get "shape" of system and interconnections between resources
CommandService to issue commands and manage the system
MeasurementService to monitor system state
Configuring Reef to communicate with a large existing deployment can be an expensive undertaking. In small scale or new deployments, encoding the system in the XML file format is usually going to be the most effective way to setup a deployment. But with a large or irregular system, writing a custom configuration importer may be more cost-effective and reliable. Importers will generally be translating from an exported file format from another system and will usually need to be custom written for each exported file format. Another way to load a complex configuration is to translate the configuration into the XML loader format.
Conversely there may be times when we need to seed other systems with data that is stored in Reef. Bulk export of the configuration in Reef can be done using the standard XML file format but in many cases an application wants a particular subset of configuration. For example an application may want to be given the list of all pieces of equipment with a certain attribute and their related devices. This could be mined from the XML file format or extracted from Reef directly using the APIs.
An important part of developing an application for Reef is determining how it will run and where it will be deployed. Some applications are "single shot" affairs: they start, run through a procedure and then complete. Configuration importers/exporters are common "single shot" applications. Other, "persistent", applications are designed to run constantly, continuously performing some operation or waiting for operator input.
Applications that are only designed to run through a procedure once and then complete are the simplest to develop and maintain. In most cases other Reef users will not need to be aware that applications of this type are running. These sorts of applications have much lower requirements for error handling and reconnecting. They are usually triggered by an operator or management process and errors/issues will be noticed immediately.
A large class of applications are designed to be run indefinitely. This includes HMIs, Protocol Adapters, Simulators, System Automation and Analysis tools. Applications of this sort are incredibly important for the correct functioning of the system and must be monitored to ensure that they are available. This requirement means that persistent applications must be much more error tolerant and also report status to Reef so we can inform users when an application is no longer behaving. If a customer already has process monitoring tools in place for other applications then a persistent application can be written without any of the Reef specific application tools.
Procedure?2.1.?Persistent Application Lifecycle
Connect to Reef message broker.
Acquire AuthToken using an appropriate user and password. In the case of a program, like an HMI, that acts only as a proxy for other users, the application should use a separate user for registering/heartbeating the application.
Register application with Reef. This includes sending the application's "capabilities", the name of this application instance, and also the location data about where the application is being run from. Application "capabilities" include high level functions such as "ProtocolAdapter" or "MeasurementProcessor" and lower level functionality like "Heartbeats". Each capability indicates some behaviors the application can be relied upon to perform.
Optionally start heartbeating behavior (if capable). Heartbeating at the application level allows both the application and Reef to keep track of whether the other is still functioning.
Optionally post required capability-specific information. Some capabilities require applications to include additional information before they can be used effectively. "ProtocolAdapter", for example, needs to tell Reef the names of the protocols it can adapt so the stream coordinating process can assign CommunicationEndpoints correctly.
Do the "work" of the application. This may be performing a Reef-directed task like MeasurementProcessing or ProtocolAdapting, or may be entirely custom. Applications will run until either they have completed their work or been signaled to shutdown.
When an application is shutdown it should remove inform Reef by unregistering itself. If the application is using heartbeats it will automatically unregister itself when the heartbeat process is stopped.
The "Heartbeat" capability is implemented by applications so Reef can detect if the application goes offline unexpectedly. If an application reports the "Heartbeat" capability it is expected to post a "keep alive" message to the StatusSnapshot service on a regular period. The period length is usually configured by Reef but can be overridden by individual applications. An application may send heartbeats more often than requested if convenient.
If too long a period elapses between "keep alives", Reef will assume the application is no longer running and mark the application offline. If an application that was marked offline comes back to life and resumes sending heartbeats we will mark the application back online. If the heartbeat service marks an application offline or online it is handled the same as if the application itself had sent regular messages.
Heartbeating has the added benefit that the application can verify that the services are still available and reachable. This provides a method for an event-driven application to get some notification that they should not expect to receive any events from Reef.
The heartbeat system is very important to reliability and error tolerance of the system as a whole. Other systems rely on the heartbeat system to inform them when an application goes offline. Without heartbeat-like behavior it is impossible to determine when and if an event-driven or "quiet" application has stopped functioning.
Some of the services in Reef that implement key "capabilities" have been written so that it is possible to add new functionality without recreating container or application code. Many of these extension points rely on the OSGi framework to dynamically handle the discovery of these additional implementations.
Reef provides an interface that defines how simple telemetry protocols hook into the system. Such protocols perform the following functions:
Update measurement values
Update communication channel health (i.e. TCP connect/disconnect)
Update protocol communication health (i.e. good bad/comms)
Receive control requests and update the result
In the Reef system, the process of configuring and assigning communication paths is centrally managed by the measurement stream coordination subsystem, while providing implementations of actual protocols is left to plugin-style protocol adapters. The coordinators communicate with protocol implementations through the Endpoint and EndpointConnection service objects, which represent static configuration and a "live" instance of a communication assignment, respectively.
Another approach is to say that in Reef, a protocol is a specific type of client application that listens for endpoint configuration pertaining to itself, then receives commands from and publishes measurements to the endpoint's "stream". The tasks of receiving endpoint configuration and managing the measurement stream are in turn handled by FEP (front-end processor) objects, which leaves protocol adapters with responsibility for establishing communications and translating between Reef and protocol-specific data models.
Protocol adapters implement two methods: one notifies the adapter when an EndpointConnection is added, the other when one is removed. Between these two events, it is responsible for publishing measurements as necessary and handling any command requests. The Reef examples have a demonstration of how a protocol adapter can be implemented.
Finally, adapters need to provide themselves to the Reef system as plugins. They do so by being deployed into the Reef runtime as OSGi bundles which publish themselves as services.
Reef runs inside an Open Service Gateway Initiative (OSGi) container. OSGi is a component architecture for Java that allows modules, called "bundles", to be deployed at runtime. A bundle is just a standard Java jar file with additional metadata that describes dependencies and the classes that the bundle exports. Numerous examples of creating bundles with Maven can be found within the Reef codebase.
Maven includes a plugin for creating bundles from Jar files. Refer to the documentation online for the Maven bundle plugin for specifics. The plugin section for the DNP3 protocol is provided below as an example:
org.apache.felix maven-bundle-plugin ${maven-bundle.version} true Reef DNP3 Protocol org.totalgrid.reef.protocol.dnp3.common.Activator org.totalgrid.reef.protocol.dnp3.* org.slf4j;version="[1.5,2.0)",* <_nouses>true
Bundle-Name is the name that will displayed within the Karaf shell when the bundle is loaded
Bundle-Activator is the fully qualified name of the Activator for the bundle (Activators described in following section)
Bundle-Name is the name that will displayed within the Karaf shell when the bundle is loaded
Private-Package matches the classes that the bundle will not make publicly available
Import-Package matches the namespaces that the bundle will need to import to function
| Caution | |
|---|---|
You must change the packaging type of the artifact from "jar" to "bundle".
|
An Activator implements the org.osgi.framework.BundleActivator interface. It defines two methods, start and stop, that control the lifecycle of the bundle component. Reef protocol Activators must publish the ProtocolAdapter interface to the OSGi service registry so that the system will load them. When the adapter deactivates a service removed event is fired throughout the system the adapter will automatically unload.
Most protocols will require some form of configuration beyond that provided by the Reef. This might include connection settings for the communications layer or mappings between the protocol's data model and Reef's measurements and commands.
Reef models can reference external configuration files during protocol configuration. These configuration files can be of any arbitrary format. Refer to the Reef modeling guide for more detailed information. Any file that you name in the excerpt below will automatically be provided to the protocol as part of the EndpointConnection service object.
name="SomeDevice">
name="modbus">
fileName="comms/SomeDeviceConfiguration.xml" xmlns:common="common.loader.reef.totalgrid.org" />
......
It is the responsibility of the ProtocolAdapter to deserialize the raw configuration data and throw a ReefServiceException if anything goes wrong during the process.