OSA-CBM Modular Implementation

Programmers’ Guide

The OSA-CBM Modular Implementation Framework

The OSA-CBM Modular Implementation Framework, or modular implementation, is a
framework on which programmers can build an OSA-CBM system. It implements the
OSA-CBM 3.2 standard in a way that separates data processing algorithms from transport
mechanisms. The OSA-CBM Modular Implementation Framework is open source,
protected by the MIT License, detailed in Appendix A.

Purpose of this Document

This document is meant for programmers who have downloaded the OSA-CBM modular
implementation. It assumes rudimentary understanding of the OSA-CBM standard;
guides to OSA-CBM standard (and the standard itself) are available on the MIMOSA
web site at http://www.mimosa.org.

Motivation of the Modular Implementation

OSA-CBM itself is already a highly modular architecture. It separates the functionality
of a CBM system into six layers, each with known interfaces and data types. However,
the standard only defines the message formats between layers; the internals of each layer
are considered a black box, implemented however each programmer sees fit.

An individual layer is not a simple object; it must do at least three tasks:

1. Access the data it needs to perform calculations (inputs)
2. Process the data (algorithms)
3. Present the data to customers (outputs)

Additional tasks might include archiving data in a database or adjusting processing

parameters to new conditions.

The modular implementation presented in this document and provided as open source at
http://www.sourceforge.net enables developers to treat each of these tasks independently.
As such, in the modular implementation the data processing algorithms are written
without any concern or knowledge about whether data is provided through web services,
TCP/IP sockets, or file reads. Similarly, the mechanism of input or output can be
changed without affecting or even recompiling the algorithms.

More generally, the designers of the modular implementation hope to provide developers
with a head start in creating an OSA-CBM system. The code can be used as-is, or it can
be used as guidance, or it can be improved by any vendor or coder who wishes to do so.
Elements of the Modular Implementation
The main components of the OSA-CBM Modular Implementation are shown in Figure 1
below:
Core
(.exe file) Initialization
(.xml file)

Interface Manager
(.dll file)

Interface Data Processor

Interface Data Processor
Interface Data Processor
Interface Data Processor
(.dll files) (.dll files)

Initialization Defines connections between modules

Core Loads modules and enacts configuration
Data Processor(s) Contains layer-specific processing code, including algorithms
Interface Manager Stores data produced by Data Processor(s) for use by Interface(s)
Interface(s) Handles incoming and outgoing requests
Figure 1: Modules of the Modular Implementation

Data processors contain algorithms that process data, usually acting as a layer. For
instance, a data processor implementing the HA layer would expect SD or DM input and
produce a diagnostic or health assessment. On the other side, interfaces provide the
outside world access to the data produced by the data processors. This can be done
through any mechanism available to the .NET platform, including web services, TCP/IP
sockets, flat file storage, and more. The interface manager keeps the interfaces
independent from the data processors, providing an extra layer of abstraction between the
two functions. The job of the core, by way of the initialization file, is to hook up all the
independent pieces of the implementation and keep it running. Each part of the modular
implementation will be discussed in-depth in its own section.

Contents of SourceForge repository

Figure 2: Contents of Default SourceForge download

The primary download of the “OSACBM Modular Implementation” SourceForge project,

ModularArchitecture.zip, contains the following files:

OSACBMClasses3_2.zip
This is a Visual Studio 2008 C# project that outputs a code library called
OSACBMClasses3_2.dll. This library contains C# classes automatically generated from
the standard schemas using xsd.exe, a tool that is provided as part of Visual Studio 2008.
The other part of this library is a set of interfaces written using the OSA-CBM Interface
Specification as guidance. This library is used in every project in the modular
architecture, and would be useful for any OSA-CBM .NET project.

ModuleInterfaces.zip
This is a Visual Studio 2008 C# project that outputs a code library called
ModuleInterfaces.dll. This library contains the interfaces used by modules in the
modular architecture to communicate internally. These interfaces should not be confused
with the OSA-CBM interfaces – these interfaces are used to coordinate the internal
workings of the implementation.

core.zip
This is a Visual Studio 2008 C# project that outputs an executable called core.exe. This
program acts as the coordinator of all the libraries created in the modular implementation.
The libraries are all collected in the same directory as core.exe, and an initialization file
allows the core to connect all the classes together and enable the interfaces.
InterfaceManager.zip
This is a Visual Studio 2008 C# project that outputs a code library called
InterfaceManager.dll. The interface manager is a standard part of the modular
implementation framework, connecting the data processors to the interfaces. The
interface manager uses a combination of storage and data forwarding to support all types
of interfaces.

SynchronousInterface.zip
This is a Visual Studio 2008 C# project that outputs a code library called
SynchronousInterface.dll. The synchronous interface exposes all of the data created by
data processors to the outside world via web services. Implementations not requiring this
functionality need not use this library, but may instead implement alternate interfaces.

The Core executable

The core’s job is to host and connect the libraries that contain modules. After its
initialization phase, the core does nothing except keep the active modules alive and
connected. The core allows the modules to be independent by applying dependency
injection through an initialization file called core_interface.xml. An example of this file
is listed below:

<?xml version="1.0"?>
<server xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<modules>
<module name="DALayer" file="batteryDA.dll" module="batteryDA.batteryDA" type="DataProcessor" />
<module name="DMLayer" file="batteryDM.dll" module="batteryDM.batteryDM" type="DataProcessor" />
<module name="HALayer" file="batteryHA.dll" module="batteryHA.batteryHA" type="DataProcessor" />
<module name="PALayer" file="batteryPA.dll" module="batteryPA.batteryPA" type="DataProcessor" />
<module name="AGLayer" file="batteryAG.dll" module="batteryAG.batteryAG" type="DataProcessor" />
<module name="InterfaceManager" file="InterfaceManager.dll" module="InterfaceManager.InterfaceManager"
type="InterfaceManager" />
<module name="SyncInterface" file="SynchronousInterface.dll"
module="SynchronousInterface.SynchronousInterface" type="Interface" />
</modules>
<connections>
<connection handler_module="InterfaceManager" event_module="DALayer" />
<connection handler_module="InterfaceManager" event_module="DMLayer" />
<connection handler_module="InterfaceManager" event_module="HALayer" />
<connection handler_module="InterfaceManager" event_module="PALayer" />
<connection handler_module="InterfaceManager" event_module="AGLayer" />
<connection handler_module="DMLayer" event_module="DALayer" />
<connection handler_module="HALayer" event_module="DMLayer" />
<connection handler_module="PALayer" event_module="HALayer" />
<connection handler_module="AGLayer" event_module="PALayer" />
<connection handler_module="SyncInterface" event_module="InterfaceManager" />
</connections>
</server>
Listing 1: Example core_interface.xml file
The initialization file is broken into two parts, labeled “modules” and “connections.” The
modules section gives each module a name unique to the xml document and a type that
corresponds to one of the types in ModuleInterfaces.dll. Each module also supplies the
name of the .dll that contains it as well as the fully qualified class name implementing the
class. These fields are used by the core to create and initialize instances of each module.

The connections section hooks together a “handler module” to an “event module.” As

their names suggest, a handler module subscribes to events provided by the event
module. These events are explained in the sections discussing the module types. The
names used in the connections section correspond with the unique module names in the
modules section. Typically, each of the DataProcessors will connect to the
InterfaceManager, and the InterfaceManager will connect to each of the Interfaces. In the
example above, the DataProcessors also feed data to one another up the OSA-CBM stack.

In brief, the core works by creating an instance of each of the classes described in the
modules section of the xml file. Because their interfaces are well-known (defined in
ModuleInterfaces.dll), the core can hook the functions of handler modules to the events
of event modules. Finally, a “start” method is called in each module indicating that the
modules have all been connected and processing can begin.

The IModule interface

The contents of IModule, the base interface for all modules in the modular
implementation, are shown in Listing 2:

public abstract class IModule

{
public abstract void start();
public abstract void stop();
public abstract void reset();
}
Listing 2: The IModule interface

When each object is created by the core, its constructor will be called. However, at the
time its constructor is called, the object has not been connected to any of its servers or
clients. Once the core creates and connects all of the objects to the specifications of the
initialization file, it calls the start() method on each module. The order in which modules
are started should not be assumed. So, modules should be initialized in the constructor,
but modules should begin processing in the start() method.

Similarly, modules should cease processing if the stop() method is invoked. Naturally,
start() and stop() only apply to modules that originate their own processing; modules that
simply register for and process events need not implement these methods.

The reset() method is for modules that maintain a history of data that affects current
processing activities. For example, a prognostics algorithm may trend that past thirty
health assessments to predict future state. When reset() is called, historical data should
be cleared, and algorithms should be reset to its initial state. This method may be called
whenever control parameters are changed or a module is replaced, causing new data to be
incompatible or unrelated to historical data.

The Data Processor module

The data processor interface is shown below in Listing 3:

namespace ModuleInterfaces
{
public delegate void DataEventSetHandler(DataEventSet dES);
public delegate void ErrorHandler(ErrorInfo error);
public delegate void ControlInfoHandler(ControlInfo control);

public abstract class IDataProcessor: IModule

{
public abstract event DataEventSetHandler DataReady;
public abstract event ErrorHandler ReportError;
public abstract event ControlInfoHandler ControlChanged;

public abstract void handleDataEventSet(DataEventSet dataEventSet);

public abstract void handleControlChange(ControlChange controlChange);
public abstract void handleErrorReport(ErrorInfo error);

public abstract Configuration getConfiguration();

public abstract ControlInfo getControlInfo();

public abstract void registerModule(IDataProcessor server);

}
}
Listing 3: The IDataProcessor interface from ModuleInterfaces.dll

Data processors have three sets of methods: event handling methods, data output
methods, and registration methods. The handleDataEventSet and handleControlChange
methods are for receiving data from other data processors. A data processor outputs
information through its events, and it also can respond to requests for configuration and
control parameters. Finally, the registerModule method hooks methods to a server data
processor. An example data processor registerModule method is shown in Listing 4:

public override void registerModule(IDataProcessor server)

{
server.DataReady += new DataEventSetHandler(handleDataEventSet);
server.ControlChanged += new ControlInfoHandler(handleControlChange);
server.ReportError += new ErrorHandler(handleErrorReport);
}
Listing 4: The registerModule method

The reason the server is presented to the client in this method is so the client can call
getConfiguration or getControlInfo on the server module. These methods retrieve the
server’s configuration and processing parameters respectively for the client to use as
necessary.
The Interface Manager module
An example interface manager is provided as part of the modular implementation release.
Typically, all of the data processors register their events with it, and the interfaces
maintain a reference to it. The provided interface manager stores all data events it
receives into a list, indexed by site, id, and type; thus, all data processors in a system
must maintain unique data event site/id/type indices. This is a simple proposition if the
OSA-CBM system is implemented on top of an OSA-EAI database (one of many good
reasons to use the two in concert), but otherwise must be coordinated among data
processor implementers.

The example interface manager does not forward events to interfaces, but for an
implementation of an asynchronous interface, this will become necessary. This will be
available in a future release of the modular architecture. Implementers are encouraged to
ensure and enhance the quality of the interface manager to suit their purposes.

The Interface module

A sample interface has been provided in the modular implementation release, providing a
synchronous web service interface. As can be seen with a quick glance at the code, it
simply forwards web service requests to the interface manager and returns the results.
This interface transforms the C# classes to and from xml messages compliant with the
OSA-CBM 3.2 xml schemas.

The synchronous web service interface requires a core.exe.config file to be copied into
the same directory as the core.exe created by the core project. This file configures the
WCF (Windows Communication Foundation) service exposed by the interface.
Although the functionality is provided by SynchronousInterface.dll, the configuration file
is associated with the executable, core.exe. A sample configuration file is shown in
Listing 5 below. Roughly speaking, the top half enables logging of web service requests
and the bottom half configures the web service location and functionality. Help for
coding WCF configuration files can be found in Visual Studio documentation
(http://www.msdn.com).

<?xml version="1.0" encoding="utf-8" ?>

<configuration>
<system.diagnostics>
<sources>
<source name="System.ServiceModel.MessageLogging"
switchValue="Warning, ActivityTracing">
<listeners>
<add type="System.Diagnostics.DefaultTraceListener"
name="Default">
<filter type="" />
</add>
<add name="ServiceModelMessageLoggingListener">
<filter type="" />
 </add>
</listeners>
</source>
</sources>
<sharedListeners>
<add initializeData="C:\App_messages.svclog"
type="System.Diagnostics.XmlWriterTraceListener, System,
Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
name="ServiceModelMessageLoggingListener"
traceOutputOptions="Timestamp">
<filter type="" />
</add>
</sharedListeners>
</system.diagnostics>
<system.serviceModel>
<diagnostics>
<messageLogging logEntireMessage="true"
logMessagesAtTransportLevel="true" />
</diagnostics>
<services>
<service name="SynchronousInterface.SynchronousInterface"
behaviorConfiguration="MetadataBehavior">
<endpoint address="http://localhost:8888/battery/"
contract="OSACBMClasses3_2.IOsacbmSynchronous"
binding="basicHttpBinding" />
<endpoint contract="IMetadataExchange"
binding="mexHttpBinding"
address="mex" />
</service>

</services>
<behaviors>
<serviceBehaviors>
<behavior name="MetadataBehavior" >
<serviceMetadata httpGetEnabled="true" />
</behavior>
</serviceBehaviors>
</behaviors>
</system.serviceModel>
</configuration>
Listing 5: Example WCF configuration file

Other interfaces can be created by implementing the IInterface C# interface. Alternate

interfaces can either replace or work alongside of the synchronous interface provided.
The only restrictions to the types of interfaces that can be created are limitations of
the .NET Framework and functionality of the interface manager.

Summary
The modular architecture provides a framework where the tasks of an OSA-CBM system
can be treated separately. The benefit of this framework is that common tasks can be
reused across implementations. Ideally, modules implementing standard tasks can be
added to the open source project on SourceForge. The end goal is to reduce the time,
effort, and money necessary to implement OSA-CBM compliant products.
Appendix A: The MIT License
All OSA-CBM modular implementation code provided from SourceForge
(http://www.sourceforge.net) is protected by the MIT License, an open source license.
The license is displayed on top of every code file in the project, in comments, and
appears below in Listing 6. The license also applies to “associated documentation,”
including this document. The OSA-CBM standard itself is copyrighted by the MIMOSA
standards body, with separate conditions.
Copyright (c) 2008 Penn State University / Applied Research Laboratory
(The U.S. Army Logistics Innovation Agency was the original sponsor of
this software product.)

Permission is hereby granted, free of charge, to any person obtaining a

copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Listing 6: The MIT License