PI_MSP

OSIsoft MultiSpeak InterfaceVersion 1.0.0.x

Revision A

OSIsoft, LLC

777 Davis St., Suite 250

San Leandro, CA 94577 USA

Tel: (01) 510-297-5800

Fax: (01) 510-357-8136

Web: http://www.osisoft.com

OSIsoft Australia • Perth, Australia

OSIsoft Europe GmbH • Frankfurt, Germany

OSIsoft Asia Pte Ltd. • Singapore

OSIsoft Canada ULC • Montreal & Calgary, Canada

OSIsoft, LLC Representative Office • Shanghai, People’s Republic of China

OSIsoft Japan KK • Tokyo, Japan

OSIsoft Mexico S. De R.L. De C.V. • Mexico City, Mexico

OSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil

OSIsoft MultiSpeak InterfaceCopyright: © 2023 OSIsoft, LLC. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework(PI-AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.

Published: 10/2012

http://www.osisoft.com/

Table of Contents

Terminology................................................................................................................................ vii

Introduction................................................................................................................................... 1

AMI................................................................................................................................... 1OSIsoft MDUS.................................................................................................................. 1PI Head End Interfaces.....................................................................................................3MultiSpeak Interface.........................................................................................................4Software Requirements....................................................................................................5Reference Manuals...........................................................................................................5Supported Features..........................................................................................................5Connection Diagram.........................................................................................................8About This Manual............................................................................................................8

Meters in AF and PI....................................................................................................................... 9

MultiSpeak File Format.....................................................................................................9Meter Unique Identifier....................................................................................................11Meter Measurements......................................................................................................13Meter Measurement Values............................................................................................16Meter Events................................................................................................................... 17VEE Points...................................................................................................................... 18Archive Sizing Issues......................................................................................................18

Preliminary Installation Steps....................................................................................................19

PI Environment...............................................................................................................19Interface Installation Files...............................................................................................24PI Environment Configuration.........................................................................................25

Digital State Sets......................................................................................................................... 29

Operational States..........................................................................................................29Status States..................................................................................................................31Events............................................................................................................................. 32User Modifications..........................................................................................................37

MultiSpeak File Confirmation.....................................................................................................39

Test Application..............................................................................................................40Meter Asset File..............................................................................................................40Meter Reading File..........................................................................................................41Meter Event File..............................................................................................................41Output to File.................................................................................................................. 41MDUS Commands..........................................................................................................42

OSIsoft MultiSpeak Interface iii

Windows Service......................................................................................................................... 43

Service Commands.........................................................................................................43Service Account..............................................................................................................44

Pre-Created Tags........................................................................................................................ 45

Source Registry Entry.....................................................................................................45User Point Creation.........................................................................................................45

Interface Checklist...................................................................................................................... 49

Source Registry Parameters...........................................................................................49Supporting Software Functionality..................................................................................50Other Prerequisites.........................................................................................................50

Interface Startup.......................................................................................................................... 53

Minimal Startup...............................................................................................................53Normal Startup................................................................................................................55

Validated Measurements............................................................................................................59

VEE Support................................................................................................................... 59Measurements Determination.........................................................................................60

MDUS Commands....................................................................................................................... 61

Source Registry Entries..................................................................................................61MDM Server Web Service Methods................................................................................61Meter Actions.................................................................................................................. 61

Miscellaneous Features..............................................................................................................63

Performance Counters....................................................................................................63Advanced AF Configuration............................................................................................65Data Write Method..........................................................................................................65

Appendix A: Troubleshooting....................................................................................................69

Message Log File............................................................................................................69Error Numbers................................................................................................................69Troubleshooting Techniques...........................................................................................69Rebuilding the Local Meter Database.............................................................................71Local Meter and Point Synchronization...........................................................................72Common Problems.........................................................................................................72Data Backfilling...............................................................................................................73Offline Tool..................................................................................................................... 73Online Tool.....................................................................................................................73

Appendix B: Developer Information..........................................................................................75

MultiSpeak File...............................................................................................................75CIM................................................................................................................................. 76Interface Tasks...............................................................................................................77MDM Server.................................................................................................................... 80Other Information............................................................................................................81

OSIsoft MultiSpeak Interface iv

Appendix C: Source Registry Parameters................................................................................83

Source Registry Example...............................................................................................83PISCC Section................................................................................................................83CONNECTOR01 Section................................................................................................84Dynamic Parameters......................................................................................................87

Appendix D: Technical Support and Resources......................................................................89

Revision History............................................................................................................................ 93

OSIsoft MultiSpeak Interface v

In

order to understand this manual, you should be familiar with the terminology that this document uses. Please be aware that the terms below are defined with respect to the operation of this Interface. That is, manuals for other OSIsoft products may indicate slightly different terminology.

AF Attribute

An AF attribute represents a characteristic of an AF element. An AF attribute can reference PI Server data, configured data, or data from other systems.

AF SDK

The AF SDK is a library of functions that allow applications to communicate and exchange data with the AF Server. PI Head End Interfaces use the AF SDK to create meter elements and attributes.

AF Server Node

An AF Server Node is a computer on which the AF Server application runs.

AF Element

An AF element is a user-centric object that contains attributes. These attributes reference PI Server data, configured data, or data from other systems. PI Head End Interfaces create AF elements that represent meters.

Buffering

In most OSIsoft products, buffering refers to the functionality of a program that:

stores temporarily the data that an interface collects in case the PI Server is offline, and

forward the data to all the PI Servers that are part of a PI Collective when they come back online.

Buffering ensures that all member of a PI Collective receive identical data from an interface. This is typically achieved using PI Buffer Subsystem (PIBufss) program.

However, the OSIsoft MultiSpeak Interface does not use PIBufss and instead uses MDA (Managed Data Access) functions for temporarily storing data and sending these data to PI Servers. The Buffers are located at /ProgramData/PISystem/Buffers/

A separate folder is created for each member of the collective:

/ProgramData/PISystem/Buffers/<collective member name>

Also separate folders are created for different data types and the data is stored in Store.dat files.

/ProgramData/PISystem/Buffers/<collective member name>/String

During normal operation no Store.dat files should be created.

OSIsoft MultiSpeak Interface vii

Terminology

CIM

CIM stands for Common Information Model. CIM describes the configuration and status of elements in an electrical network. PI Head End Interfaces use the CIM naming convention to generate the names of AF elements and PI points.

Head End System

A head end system consists of software and hardware responsible for managing a collection of smart meters. Its functionality includes data collection and remote operations.

Interface Node

An interface node is a computer running a PI Head End Interface; for example, the OSIsoft MultiSpeak Interface.

MDUS

MDUS stands for Meter Data Unification and Synchronization system. OSIsoft's MDUS connects various metering head end system to SAP for Utilities.

MDUS Command

An MDUS command is an instruction sent to a PI Head End Interface. The Interface in turn passes it to the head end system. MDUS commands include meter ping, meter on-demand read, meter remote connect, and meter remote disconnect.

PI API

The PI API is a library of functions that allow applications to communicate and exchange data with a PI Server. PI Head End Interfaces use the PI API to send data to the PI Buffer Subsystem, which in turn write data to the PI Server. The PI API exists in 32-bit and 64-bit versions.

Unlike many OSIsoft products, the OSIsoft MultiSpeak Interface does not require the PI-API.

PI Collective

A PI Collective consists of two or more replicated PI Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI client applications.

The OSIsoft MultiSpeak Interface does not yet support PI Collectives.

PIHOME

PIHOME is a Windows environment variable. It refers to the directory that is the common location for 32-bit PI client applications. A typical PIHOME is:

C:\Program Files (x86)\PIPC.

You can find the value of PIHOME by typing the following command at the Windows command prompt:

C:\> echo %pihome%

This document uses [PIHOME] as an abbreviation for the complete PIHOME directory.

OSIsoft MultiSpeak Interface viii

PIHOME64

PIHOME64 is a Windows environment variable. It refers to the directory that is the common location for 64-bit PI client applications. A typical PIHOME64 is:

C:\Program Files\PIPC.

PI Head End interfaces reside in a subdirectory of the Interfaces directory under PIHOME. For example, files for the OSIsoft MultiSpeak Interface are in

C:\Program Files\PIPC\Interfaces\PISCCC:\Program Files\PIPC\Interfaces\PISCC\MSP

You can find the value of PIHOME64 by typing the following command at the Windows command prompt:

C:\> echo %pihome64%

This document uses [PIHOME64] as an abbreviation for the complete PIHOME64 directory.

PI SDK

The PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. However, PI Head End interfaces do not invoke the standard PI SDK routines that are distributed with the PI SDK installation kit. Instead, PI Head End Interfaces make low level function calls to create and edit PI points.

PI Server Node

A PI Server Node is a computer on which PI Server programs are installed. Two or more PI Server Nodes comprise a PI Collective.

PI SMT

PI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers and PI Collectives. A single copy of PI SMT manages multiple PI Servers and PI Collectives. PI SMT runs on either a PI Server Node or an Interface Node.

Point

The PI point is the basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.

For PI Head End Interfaces, a PI point corresponds to a particular measurement on a meter. For example, for a meter named 73421 and programmed to measure interval data, the corresponding PI point would be

MSP_73421.Input001._IntervalData_Forward_Energy___(kWh).Value

Service

A Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.

Tag

The tag attribute of a PI point is the name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms tag and point interchangeably.

OSIsoft MultiSpeak Interface ix

For PI Head End Interfaces, the tagname of a PI point determines the data collection behavior. This feature is unlike that of other interfaces, which typically rely on PI point attributes such as InstrumentTag and Location codes.

VEE

VEE stands for Validation, Editing, and Estimation. When an application performs VEE, it looks at a group of data and applies a set of validation, editing, and estimation rules in order to correct anomalies.

For example, when a meter is missing a reading for a particular interval, the VEE rule can indicate that the generated value should be the reading that occurred twenty-four hours earlier.

Windows Event Log

Unlike many OSIsoft products which write informational and error messages to the pipc.log file, the OSIsoft MultiSpeak Interface logs information to the Windows Event Log (Application) instead of the pipc.log file.

x

The MultiSpeak specification from NRECA (National Rural Electric Cooperative Association) consists of standards for describing electric meters and the data that they measure. OSIsoft’s MultiSpeak Interface reads files that conform to these standards and stores the resulting meter information into PI Servers and PI AF. In addition, the Interface is capable of interacting with a MultiSpeak MDM Server.

This interface is part of OSIsoft's AMI (Advanced Metering Infrastructure) product. The next few paragraphs provide an overview of AMI, OSIsoft's AMI solution, and PI Head End Interfaces.

AMI

The newly manufactured electric meters of today are much more sophisticated than the rotary dial models from previous generations. Among their advanced features is the ability to measure energy usage for specific time intervals during a day. In addition, these commonly named smart meters support the automatic transmission of these interval data as well as remote activation and disconnection.

Smart meters form the basis for the Advanced Metering Infrastructure. AMI is the system of hardware and software components that allows electric utilites to achieve significant cost savings and improved efficiencies through policies such as

time of use billing;

elimination of manual meter readings;

quicker and more accurate response to power outages; and

demand response programs.

AMI also offers benefits for utility customers. An example is customers receiving a lower rate to turn off major appliances (such as an air conditioner) during peak usage hours.

Smart meters communicate to a collection system known as a head end system. The basic functionality of a head end is to receive meter data , make the meter data available to other systems, and send operational and configuration commands to the meters. Advanced functionality include outage detection, on demand meter reading, remote disconnection, and the processing of meter data through validation, editing, and estimation (VEE).

OSIsoft MDUS

OSIsoft supports AMI through our OSIsoft MDUS product. OSIsoft MDUS sits between various metering head end systems and SAP for Utilities. OSIsoft MDUS retrieves meter data from different head end systems, archives these data in their original fidelity, and makes the meter data readily available to SAP for Utilities.

OSIsoft MDUS also moves information in the opposite direction. For example, a customer service system schedules a meter disconnect. OSIsoft MDUS passes this request to the appropriate head end system. The head end system performs the remote disconnection.

OSIsoft MDUS consists of the following standard OSIsoft products: PI Enterprise Server, PI AF, PI Head End Interfaces, and PI Utilities Gateway. The PI Server provides aggregation

OSIsoft MultiSpeak Interface 1

Introduction

and archiving of meter data. AF supports the contexual representation of metering system assests such as meters, measurements, and points of delivery.

PI Head End Interfaces connect to different head end systems, retrieve meter usage data, and store the data into the PI Server. A PI Head End Interface also automatically retrieves meter asset information from head end systems and contextually store such information into AF. The Utilities Gateway links OSIsoft MDUS with SAP for Utilities.

PI Utilities Gateway

OSIsoft's Utilities Gateway allows SAP for Utilities easy access to PI Server data and AF data. OSIsoft bundles various Gateway Modules into Enhancement Packages that are versioned.

The Utilities Gateway supports bi-directional data transfer. It passes information from SAP for Utilities into a PI System. It also passes information from a PI System to SAP for Utilities. The information passing through Utilities Gateway to its modules can include control, configuration, and query instructions.

The Utilities Gateway has the following features:

It uses web services for integration with SAP's Service Oriented Architecture (SOA) and SAP's Enterprise Service Repository.

It provides an interface for OSIsoft products, delivering time-series data and asset information in a business context.

A rule structure in AF defines the configuration requirements for setting up data requests to and from the web services.

It keeps track of the identity of the service, the source of the service request, and time at which the service was invoked. This action facilitates an audit trail as well as recovery features.

It relies on OSIsoft's RtBaseline services to obtain data from the PI System, guaranteeing rapid response while handling secure connections to the PI System.

It uses AF to maintain PI configuration information.

It is scalable both vertically and horizontally.

The Utilities Gateway supports only SAP for Utilities. It does not support other business systems.

Automated Meter Reading Solution

PI Head End Interfaces can operate independently of the Utilities Gateway component of OSIsoft MDUS. If you want an Automated Meter Reading (AMR) solution, you do not have to implement the Utilities Gateway. Later on, you can add the Utilities Gateway as necessary.


PI Head End Interfaces

Improved Features

PI Head End Interfaces contain features that most OSIsoft interfaces do not. These features include the ability to create PI points automatically, to create AF assets automatically, and to support external commands via PI RPCs.

Most other interface programs require that you manually create PI points in order to store the data that the interface collects. In contrast, a PI Head End Interface automatically builds the points that are needed for data collection.

Other interface programs require the use of the separate APS (Automatic Point Synchronization) product in order to update PI point attributes with device point attributes. PI Head End Interfaces provide this functionality intrinsically; a separate synchronization program is unnecessary.

The vast majority of other interfaces do not utilize a foreign system's asset information. A PI Head End Interface, however, transfers relevant information from a head end asset database into PI AF for contextual storage.

Plug-in Architecture

The vast majority of OSIsoft interfaces are stand-alone executable programs; for example, PItoPI.exe. In contrast, PI Head End Interfaces are dynamic link library files that are loaded by the PI Interface Conductor Container executable (PISCC.exe). For example, the filename for the OSIsoft MultiSpeak Interface is PIMSPPlugIn.dll.

Source Registry

The vast majority of OSIsoft interfaces retrieve their startup parameters from a bat file; for example, PItoPI.exe uses PItoPI.bat. In contrast, PI Head End Interfaces obtain their parameters from a Source Registry.

Currently, the file PISCC.ini functions as the Source Registry. This file resides in the same directory as the PI Interface Conductor Container executable (PISCC.exe).

RPC PI Server

PI Head End Interfaces communicate with other PI applications by means of PI RPCs (Remote Procedure Calls). A PI Head End Interface needs to publish these RPCs to a PI Server running on the same computer as the interface itself. However, for maximum data availability, PI Head End Interfaces and the PI Server to which they send data should not run on the same computer. The solution to these two conflicting requirements is to use what is called an RPC PI Server.

An RPC PI Server consists of the PI Server programs (PI Network Manager, PI Message Subsystem, and so on) running on the same computer as a PI Head End Interface. That is, the RPC PI Server runs on an Interface Node.

However, a PI Head Interface does not send data to this RPC PI Server. In addition, the point database, snapshot, and archives for this RPC Server are empty. The main functionality of the RPC PI Server is to host the RPCs that the PI Head End Interface publishes.


Multiple PI Servers

The current version of the PI Server (v3.4.380) has an upper limit to the number of points that it can create. This limit is about 3 million. So, in order to support metering systems that require a point count that exceed this number, a single copy of a PI Head End Interface is capable of interacting with multiple, independent PI Servers.

However, High Availability and redundancy are not supported at this time.

Pre-created Tags

A feature of PI Head End Interfaces is the use of pre-created tags. When running in this configuration, the Interface itself does not create the PI points that are necessary to store the meter measurement values. Instead, the Interface renames existing PI points that the user has already created (via a point creation tool).

The use of pre-created tags allows a PI Head End Interface to minimize the time required to generate meter elements and their associated PI points.

MultiSpeak Interface

The remainder of this document describes the OSIsoft MultiSpeak Interface, or MSP Interface for brevity.

The MSP Interface performs the following functions:

it creates AF meter elements to represent electric meters that are defined in MultiSpeak files;

it creates AF measurement elements to represent meter measurements (such as interval data and register data);

it parses MultiSpeak files for meter interval usage data and stores these data into PI points;

it parses MultiSpeak files for meter register data and stores these data into PI points; and

it parses MultiSpeak files for meter events and stores these events into PI points.

After the Interface reads and processes a MultiSpeak file, it deletes the file.

Please note that the MSP Interface does not communicate with a metering head end system. Instead, the Interface merely processes data files that conform to the MultiSpeak standards.

Therefore, a separate application must interact with the metering system and generate the required data files. This application can come from a third-party systems integrator. Alternatively, you (the end user of the MSP Interface) may choose to develop such an application.

The MSP Interface can invoke MDUS commands such as meter ping, meter on-demand read, meter connect, and meter disconnect. However, a separate application that implements the MultiSpeak MDM Server specification is necessary. This application must be developed by a third-party systems integrator or the end user of the MSP Interface.

4

Software Requirements

The MSP Interface is a 64-bit application that runs on a Microsoft Windows Server operating system (e.g., Windows Server 2003) on x64. (IA64 is not supported.) The Interface reads files that conform to the MultiSpeak v4.1 standard.

The Interface sends data to the PI Server and AF Server. The versions required, are, respectively,

PI Server v3.4.380.36

AF Server 2010 (v2.2.2.3870).

The Interface Node on which the Interface runs must also have the following OSIsoft components:

PI Server v3.4.380.36 (this is the RPC PI Server);

AF Client 2010 (v2.2.2.3870).

The installation kit PIMSP_XXX.exe installs the software needed on the Interface node. OSIsoft’s Prerequisites kit needs to be additionally installed by the user.

Reference Manuals

OSIsoft

PI Server manuals

PI AF manuals

Supported Features

Feature Support

Interface Part Number PI-AMI-OSI-MSP-x64

* Platforms 64-bit Windows Server operating systems

APS Connector No

Point Builder Utility No

ICU Control No

PI Point Types Float32, Digital, String

Sub-second Timestamps No

Sub-second Scan Classes No

* Automatically Incorporates PI Point Attribute Changes

Not Applicable

Exception Reporting No

Outputs from PI No

Inputs to PI: Scan-based / Unsolicited / Event Tags

Unsolicited

Supports Questionable Bit No


Feature Support

Supports Multi-character PointSource Yes

Maximum Point Count Point count of PI Server

* Uses PI SDK Yes

* Uses 64-bit PI API No

Automatic Point Creation Yes

Automatic Asset Creation Yes

MDUS remote commands

Ping

On-demand register read

Remote connect

Remote disconnect

Yes

Yes

Yes

Yes

Yes

PINet String Support Not applicable

* Source of Timestamps MultiSpeak data file

* History Recovery Yes

* UniInt-based No

* Disconnected Startup No

Failover None

Vendor Software Required on PI Interface Node / PINet Node

No

Vendor Software Required on Foreign Device

No

Vendor Hardware Required No

* Additional PI Software Included with Interface

Yes

Device Point Types Not applicable

Serial-Based Interface No

* See the paragraphs below for further explanation.

Platforms

This Interface runs only on 64-bit Windows Server operating systems; for example, Windows 2003 Server and above.

Please contact OSIsoft Technical Support for more information.

Automatically Incorporates PI Point Attribute Changes

This Interface automatically creates all the PI points that are necessary for data collection. There is no need for the user to modify point attributes. The tagname of a PI point defines data collection attributes.

6

Uses PI SDK

The PI SDK and the 32-bit PI API are bundled together and must be installed on each PI Interface node. However, this Interface does not invoke the standard PI SDK routines that are distributed with the PI SDK installation kit. Instead, it makes low level PI Server library calls to create and edit PI points and to create and edit digital state sets.

Source of Timestamps

The MultiSpeak file specifies the timestamps for the data that the Interface writes to the PI Server.

History Recovery

The MultiSpeak data file can contain historical data for the Interface to process. In addition, if errors result in the Interface failing to send data to the PI Server, the Interface can reprocess data files for the purpose of backfilling data.


Connection Diagram

Diagram of the OSIsoft MSP Interface and its associated software components:

About This Manual

This manual is written in the format of a tutorial. The goal is to teach you, from a user perspective, how the Interface works. This document begins by explaining how a meter in a head end system is related to an AF element and to PI points. The next chapter also explains the entries in the MultiSpeak file that are necessary for the Interface to operate.

Subsequent chapters then describe prerequisite steps that you must take before you can start the Interface. These steps include setting up the PI Server environment and the AF meter database. The Interface Checklist chapter summarizes these steps.

8

As a

user of the OSIsoft MSP Interface, you may naturally ask yourself

How does a meter in a metering system appear in OSIsoft MDUS?

What measurements in a meter are supported in OSIsoft MDUS?

How does OSIsoft MDUS represent data that a meter collects?

This section provides answers to such questions. It describes the relationship between

a meter in a metering system and an element in AF; and

meter measurements and points on the PI Server.

If you are developing an application that will communicate with a metering system and will generate the MultiSpeak data files for use by the MSP Interface, this chapter answers basic questions such as

How do I describe a meter within the MultiSpeak data file?

How do I describe meter measurement capabilities (e.g, energy and demand) within the data file?

How do I describe meter measurement values (e.g., energy usage and demand usage) within the data file?

How do I represent meter events (e.g., Last Gasp) within the data file?

Appendix B contains further file format information for the application developer.

MultiSpeak File Format

Schema Files

The data files that the Interface reads are XML (eXtensible Markup Language) files that adhere to the following schemas:

mspCPSM.xsd

mspGeometry.xsd

MultiSpeak.xsd

MultispeakRealTime41.xsd

xlinks.xsd

OSIsoft makes these files available to developers who wish to generate MultiSpeak data files for use with the Interface. Please contact OSIsoft.

XML Elements

The root element in the MultiSpeak data file is <MultiSpeakMessageHeader>.

The immediate child element of <MultiSpeakMessageHeader> is <Batch>.

The immediate child element of <Batch> is <MultiSpeak>.


Meters in AF and PI

Overview of Meter Data Files

The data files which the Interface processes fall into three categories:

meter asset,

meter measurement reading, or

meter event.

Depending on the file category, the <MultiSpeak> element contains one or more of the following child elements:

<mspMeter>

<readingType>

<meterReading>

<meterEventList>

The MultiSpeak.xsd file defines these four elements as well as <MultiSpeak>. The MultiSpeakRealTime41.xsd file defines the <MultiSpeakMessageHeader> and <Batch> elements.

Meter Asset File

A meter asset file contains the <mspMeter> and <readingType> child elements of <MultiSpeak>. For example,

<MultiSpeakMessageHeader> <Batch> <MultiSpeak> <mspMeter> ... </mspMeter> <readingType> ... </readingType> </MultiSpeak> </Batch></MultiSpeakMessageHeader>

The Interface requires asset files to be named meterAsset*.xml.

Meter Reading File

A meter measurement reading file contains the <meterReading> child element of <MultiSpeak>. For example,

<MultiSpeakMessageHeader> <Batch> <MultiSpeak> <meterReading> ... </meterReading> </MultiSpeak> </Batch></MultiSpeakMessageHeader>


The Interface requires measurement reading files to be named measurementData*.xml.

Meter Event File

A meter event file contains the <meterEventList> child element of <MultiSpeak>. For example,

<MultiSpeakMessageHeader> <Batch> <MultiSpeak> <meterEventList> ... </meterEventList> </MultiSpeak> </Batch></MultiSpeakMessageHeader>

The Interface requires measurement reading files to be named eventData*.xml.

Meter Unique Identifier

Every meter in a metering system has an attribute that functions as the unique identifier. This attribute defines the name of the meter. That is, when you refer to meter "734100", you are indicating that "734100" is the value of the unique identifier.

The elements <mspMeter>, <readingType>, and <meterReading> contain the attribute objectID. The value of this attribute is the value of the unique identifier. For example, in the meter asset file,

<MultiSpeakMessageHeader> <Batch> <MultiSpeak> <mspMeter objectID="734100"> ... </mspMeter> <readingType objectID="734100"> ... </readingType> </MultiSpeak> </Batch></MultiSpeakMessageHeader>

After the Interface parses a meter asset file, it uses this unique identifier to generate

the name of elements in AF, and

the names of points on the PI Server

AF Elements

The Interface creates the name of an AF meter element by prefixing a head end name (that you define in the Source Registry) to the Meter Unique Identifier. For example, if you have in the Source Registry

HEAD_END=MSP

and the meter asset file has meters with the following objectIDs:


734100734101734102734103

the Interface builds these AF meter elements:

PI Points

For each meter element, the Interface creates PI points to store

the event information of the meter;

the transaction information of the meter;

the operational state of the meter; and

the status of meter measurements.

For example, if the meter element name is MSP_734100, the Interface builds these PI points:

MSP_734100.EventMSP_734100.LogMSP_734100.StateMSP_734100.Input001.Status

These points are of type Digital, String, Digital, and Digital respectively. A subsequent section of this manual describes the digital state sets that the Interface creates for the digital points.

Meter Measurements

CIM Naming

A meter measurement typically involves energy usage or energy demand. The CIM (Common Interface Model) IEC 61968-9 Annex C specification defines a standard for the naming of meter measurements. The MSP Interface supports two CIM naming conventions.

The first uses the following CIM attributes:

MeasurementCategoryModifier

AccumulationBehavior

DirectionOfFlow

12

MeasurementCategory

TOURate

Phase

UOM

The second uses these:

TimeAttribute



DirectionOfFlow

MeasurementCategory

TOURate

Phase

UOM (including metric multiplier)

The Interface requires the name of a meter measurement to be a concatenation of the CIM attributes. Specifically,

[MeasurementCategoryModifier]_[AccumulationBehavior]_[DirectionOfFlow]_[MeasurementCategory]_[TOURate]_[Phase]_([UOM])

or

[TimeAttribute]_[MeasurementCategoryModifier]_[AccumulationBehavior]_[DirectionOfFlow]_[MeasurementCategory]_[TOURate]_[Phase]_([UOM])

Although the following examples refer to the first naming convention, you can apply their principles to the second naming convention.

Summation Register Example

A meter has a summation register that measures delivered energy for TOU A that continues to add to previous readings. The attribute values are as follows:

Attribute Description

MeasurementCategoryModifier Not applicable

AccumulationBehavior Summation

DirectionOfFlow Forward

MeasurementCategory Energy

TOURate TOURateA

Phase Not applicable

UOM kWh

The Interface expects the following measurement name:

_Summation_Forward_Energy_TOURateA__(kWh)


Demand Register Example

The meter has a demand register that measures the peak demand for TOU A over a period. The attribute values are as follows:


MeasurementCategoryModifier Max

AccumulationBehavior Indicating


MeasurementCategory Demand

TOURate TOURateA


UOM kW


Max_Indicating_Forward_Demand_TOURateA__(kW)

Interval Data Example

The meter has a channel that measures the consumption of delivered energy. The attribute values are as follows:


MeasurementCategoryModifier Not applicable

AccumulationBehavior IntervalData


MeasurementCategory Energy

TOURate Not applicable


UOM kWh


_IntervalData_Forward_Energy___(kWh)

Meter Asset File

The <readingType> element in the MultiSpeak meter asset file contains the child element <readingTypeCode>. The latter element has a name attribute. The value of this attribute is the meter measurement CIM name. So, if a meter named 734100 supports the preceding examples (Summation Register, Demand Register, and IntervalData), the meter asset file must contain information such as:

<MultiSpeakMessageHeader> <Batch> <MultiSpeak> <readingType objectID="734100"> <readingTypeCode name="_Summation_Forward_Energy_TOURateA__(kWh)"> </readingTypeCode>

14

</readingType>

<readingType objectID="734100"> <readingTypeCode name="Max_Indicating_Forward_Demand_TOURateA__(kWh)"> </readingTypeCode> </readingType>

<readingType objectID="734100"> <readingTypeCode name="_IntervalData_Forward_Energy___(kWh)"> </readingTypeCode> </readingType> </MultiSpeak> </Batch></MultiSpeakMessageHeader>

Note that there is a separate <readingType> element for each of the three meter measurements:

_Summation_Forward_Energy_TOURateA__(kWh)

Max_Indicating_Forward_Demand_TOURateA__(kW)


Also, note that the value of the objectID attribute refers to the particular meter ("734100").


AF Elements and PI Points

For the preceding entries in the meter asset file, the Interface creates these AF elements:

The corresponding PI points that the Interface builds are named

MSP_734100.Input001._IntervalData_Forward_Energy___(kWh).ValueMSP_734100.Input001._Summation_Forward_Energy_TOURateA__(kWh).ValueMSP_734100.Input001.Max_Indicating_Forward_Demand_TOURateA__(kW).Value

The values of these PI points represent the data that the meter collects.

Meter Measurement Values

The <meterReading> element in the MultiSpeak measurement data file is the parent element for measurement values. The <readingTypeCode> child element indicates the measurement, <value> indicates the value, and <timeStamp> indicates the timestamp. For example,

<meterReading objectID="734100"> <readingValues> <readingValue> <readingTypeCode name="_IntervalData_Forward_Energy___(kWh)"> </readingTypeCode> <value>18.883</value> <timeStamp>2010-10-19T00:00:00-07:00</timeStamp> </readingValue> <readingValue> <readingTypeCode name="_IntervalData_Forward_Energy___(kWh)"> </readingTypeCode> <value>11.123</value>

<timeStamp>2010-10-19T01:00:00-07:00</timeStamp> </readingValue> </readingValues></meterReading>

16

CIM Name

Note that the same CIM measurement name occurs in the <readingTypeCode> of both <readingValue> (measurement data file) and <readingType> (meter asset file). That is, the former indicates

<readingValue> <readingTypeCode name="_IntervalData_Forward_Energy___(kWh)"> </readingTypeCode> </readingValue>

while the latter has

<readingType objectID="734100"> <readingTypeCode name="_IntervalData_Forward_Energy___(kWh)"> </readingTypeCode>

PI Point

The CIM measurement determines the PI point to which the Interface stores the value. For the preceding example, the Interface writes the data

Timestamp Value

2010-10-19T00:00:00-07:00

18.883

2010-10-19T01:00:00-07:00

11.123

to the point


Meter Events

The <meterEventList> element in the MultiSpeak meter event file is the parent element for meter events. The <meterEvent> element contains attributes (codeString and time) that indicate the actual event and its timestamp. The <meterID> element has the objectID attribute; this attribute identifies the meter.

For example,

<meterEventList> <eventInstances> <eventInstance> <meterID objectID="734100"></meterID> <meterEvent time="2010-10-14T13:12:24-07:00" codeString="Last Gasp"> </meterEvent> </eventInstance> </eventInstances></meterEventList>


The Interface stores the event value to the PI point whose name ends in "Event". For example,

MSP_734100.Event

VEE Points

The Interface has the ability to create points that external VEE (Validation, Editing, and Estimation) applications can use. Examples of the tagnames of these points are

MSP_734100.Input001._IntervalData_Forward_Energy___(kWh).ValidatedStateMSP_734100.Input001._IntervalData_Forward_Energy___(kWh).ValidatedValue

The Interface does not write to these points. Instead, an external VEE application sends data to them. The chapter Validated Measurements provides information on configuring the Interface to create these VEE points.

Archive Sizing Issues

The following discussion provides essential information for those who are responsible for installing and maintaining the Interface. It assumes some knowledge of PI System management.

Initial Archive File Size

On the PI Server, the size of an archive file determines the maximum number of points it can hold. This maximum number is one-half the archive file size. For example, if the archive is 256 MB, it can hold at most 131,072 points (256 * 1024 * 0.5).

As the previous section indicates, the Interface creates four PI points for every meter. That is,

MSP_734100.EventMSP_734100.LogMSP_734100.StateMSP_734100.Input001.Status

The Interface creates additional points to data for meter measurements such as summation, demand, and interval data. For example,

MSP_734100.Input001._Summation_Forward_Energy_TOURateA__(kWh).ValueMSP_734100.Input001.Max_Indicating_Forward_Demand_TOURateA__(kW).ValueMSP_734100.Input001._IntervalData_Forward_Energy___(kWh).Value

The Interface creates more points when VEE is involved. For example,


So, a single meter can require anywhere from 7 to 20 (or more) points. This requirement means that a PI System with archive files of size 256 MB can hold about 18,720 meters (assuming 7 points per meter) or 6,550 meters (assuming 20 points per meter).

18

The installation and configuration procedure for PI Head End Interfaces is complicated and involves many steps. Please contact OSIsoft for assistance or for a referral to qualified personnel who can perform this installation.

This chapter describes preliminary steps that you must take in order to ensure that the MSP Interface can run properly. The ultimate goals of these preliminary steps are

Confirmation that the Interface has the proper credentials to put data to the PI Server

Creation of an AF database that contains the proper meter templates

PI Environment

Before configuring the MSP Interface, you must set up and prepare the PI environment in which the Interface runs. This environment can consist of multiple, independent PI Servers.

For example, when two independent PI Servers are involved, there are four separate computers:

AF Server

PI Server1

PI Server2

Interface Node

The following picture shows the configuration:


Preliminary Installation Steps

Source Registry Entries

This portion of the manual describes the entries in the Source Registry that are relevant for Interface installation. Appendix C describes all Source Registry parameters. It also contains an example Source Registry file. You may wish to consult that example while you are reading the rest of this section.

The PISCC section begins the Source Registry. The PI_SERVER parameter within this section specifies the hostname of the Interface Node. The PI_COLLECTIVE_00 and PI_COLLECTIVE_01 parameters specify the hostnames of the PI Servers to which the Interface writes data.

For example,

[PISCC]

PI_SERVER=theInterfaceNode

PI_COLLECTIVE_00=Neptune

PI_COLLECTIVE_01=Jupiter

The CONNECTOR01 section contains parameters specific to the MSP Interface. The NAME parameter is an arbitrary identifier that you choose. However, it should reflect the Interface. For example,

[CONNECTOR01]

NAME=MultiSpeak

The CONNECTOR_STATE parameter indicates the current state of the plug-in portion of the Interface. For example,

[CONNECTOR01]

CONNECTOR_STATE=NOT_LOADED

The START_STATE indicates the action that the interface container (PISCC.exe) should take with regards to the plug-in portion of the Interface. For example,

[CONNECTOR01]

START_STATE=START

The PATH parameter specifies the location of the plug-in DLL file. For example,

PATH=D:\Program Files\PIPC\Interfaces\PISCC\MSP\PIMSPPlugIn.dll

The AF_SERVER parameter indicates the hostname of the AF Server. The AF_DATABASE parameter indicates the name of the AF database that stores meter elements. For example,

[CONNECTOR01]

AF_SERVER=theAFServer

AF_DATABASE=MSP

The POINT_SOURCE specifies the value of the PointSource attribute of the PI points that the Interface uses. For example,

[CONNECTOR01]

POINT_SOURCE=MSP

The DATA_DIRECTORY parameter indicates the directory where the Interface looks for MultiSpeak data files. For example,

[CONNECTOR01]


DATA_DIRECTORY=E:\MSPData

You should create this directory if it does not already exist.

Prerequisites and Supplementary Software

Be sure to install all necessary prerequisite kits. For example, before you can run the AF Server installation kit, you will need to install an OSIsoft PI Prerequisite kit.

In addition, the various installation kits install supplementary software. For example,

PI SDK

PI API (32-bit)

PI SMT

PI Collective Manager.

For this reason, the text below does not specifically mention the need to install these products.

AF Server Node

On the AF Server node, run the appropriate setup kits in order to install the following OSIsoft software:

AF Server

AF Client

Make sure that the hostname of the AF Server agrees with the hostname of the AF_SERVER parameter of the CONNECTOR01 section of the Source Registry. Recall that

[CONNECTOR01]

AF_SERVER=theAFServer

Edit the Source Registry as necessary.

PI Server Nodes

On each of the PI Server nodes, run the appropriate PI Server setup kit. You can optionally install the AF Client.

Make sure that the hostname of each PI Server agrees with the hostname of the PI_COLLECTIVE_XX parameter of the CONNECTOR01 section of the Source Registry. Recall that

[CONNECTOR01]PI_COLLECTIVE_00=NeptunePI_COLLECTIVE_01=Jupiter


Load Balancing on PI Servers

When the Interface is creating or renaming (in Pre-created tags mode) tags on the PI Servers, it distributes the tags evenly on the PI Servers mentioned in the piscc.ini file. For example if we have 2 PI Servers mentioned in the piscc.ini file named Neptune and Jupiter. The tags for


the first meter are created or renamed on Neptune; tags for the 2nd meter are created or renamed on Jupiter and so on. If a 3rd PI Server is added named Pluto, then new tags will be created or renamed on Pluto until its count matches that of Neptune or Jupiter.

If using Pre-created tags, the user has to create the number of tags evenly on all the PI Servers.

Interface Node

The installation kit PIMSP_1.0.0.1.exe installs software needed on the interface node. In addition, you should install OSIsoft’s Prerequisites kit.

If you are not using the interface installation kit (PIMSP_1.0.0.1.exe), you need to run the appropriate setup kits in order to install the following OSIsoft software:

PI Server

AF Client

Recall that when you install a PI Server on the interface node, this PI Server is subsequently called the RPC PI Server.

Make sure that the hostname of the Interface Node agrees with the hostname of the PI_SERVER parameter of the PISCC section of the Source Registry. Recall that

[PISCC]PI_SERVER=theInterfaceNode


RPC PI Server

License File

The RPC PI Server requires its own license file (pilicense.dat). This license file is deployed with the installation kit of the interface.

Configuration

On the Interface Node, when you run the PI Server installation kit, use the following configuration information:

Default Archive Size: 1 MB

Event Queue Size: 8 MB (this option appears under the Advanced button)

Event Queue Page Size: 64 KB (this option appears under the Advanced button)

Do not create the default points

Do not automatically start the PI services

Windows Services

After PI Server installation, go to the Windows Control panel and enable the following services to the startup type of Automatic:

PI Archive Subsystem

PI Backup Subsystem

22

PI Base Subsystem

PI License Manager

PI Message Subsystem

PI Network Manager

PI Snapshot Subsystem

PI Update Subsystem

By setting these services to Automatic, you enable the RPC PI Server to start when the computer itself starts.

Startup Command Files

In the C:\PI\ADM\pisrvstart.bat file, look for the line

@if "%1" == "-base" (goto theend)

and add

goto theend

right before it. That is, edit the file so that it reads

goto theend@if "%1" == "-base" (goto theend)

Similarly, in the C:\PI\ADM\pistart.bat file, look for the line

if "%1" == "-base" (goto theend)

and add

goto theend

right before it. That is, edit the file so that it reads

goto theendif "%1" == "-base" (goto theend)

The preceding changes enable the RPC PI Server to start only the necessary PI services.


Security

You should configure the RPC PI Server to operate with only Windows Authentication and PI Mappings.

Make sure that there is an existing PI Mapping that allows you to access the RPC PI Server via PI-SMT. Otherwise, when you follow the procedure below, you will lock yourself out of the RPC PI Server.

Run the Security plug-in to PI System Management Tools. Go to the Security Settings. Move the slide-bar such that API trusts are disabled:

This security level only affects programs (such as the Utilities Gateway) that call the Interface's RPCs. It does not affect the relationship between the Interface and the various PI Server computers.

Therefore, if you are running the Utilities Gateway, you must create an appropriate PI Mapping that allows the Utilities Gateway to access the RPC PI Server. This Mapping may map to a non-privileged PI user; for example, pidemo. The Utilities Gateway service should then run under a Windows account that is associated with this Mapping.

Interface Installation Files

On the Interface Node, the MSP Interface installation kit results in the following directories and files:

[PIHOME64]\Interfaces\PISCC

PISCC.exeOSIsoft.PI.Configuration.dllOSIsoft.PI.Data.dllOSIsoft.PI.Net.dll OSIsoft.PISCC.Net.dll PISCC.iniBaseMeterAssets.xmlExternalRelations.xmlAMIOperationalStates.CSVAMIStatusStates.CSVAMIEventStates.CSVauthTest.exemdaPut.exetablesClient.exeAMITagCreator.exeCacheClient.exeQueuesClient.exeTablesClient.exe

24

The PISCC.exe file is the executable program portion of the MSP Interface.

The PISCC.ini file is the Source Registry. The BaseMeterAssets.xml and ExternalRelations.xml files are AF meter template files.

The comma separated files (CSV) define digital state sets for use by digital points such as, respectively,

MSP_734100.StateMSP_734100.Input001.StatusMSP_734100.Event

[PIHOME64]\Interfaces\PISCC\MSP

PIMSPPlugIn.dllAMIRPCHandler.dllMspMeter.xmlMspEventMapping.csvMspOperationalMapping.csvMspStatusesMapping.csvPI_MSP.doc

These files are the plug-in portion of the MSP Interface.

[PIHOME64]\Interfaces\PISCC\MSP\MSPTest

MspTest.exeMspTest.bat

These files test whether MultiSpeak data files are suitable for use by the Interface.

PI Environment Configuration

PI Mapping and Trust Verification

On each PI Server, create a PI Mapping or PI Trust such that applications running on the Interface Node have piadmin privileges. To verify that you have correctly created the PI Trust, go to the Interface Node and run the authTest program. This program attempts authentication to a PI Server using all three of the following methods:

mappings based on Windows logon

PI Trusts

PI username and password

The usage syntax for authTest is

authTest.exe PIserver user [password]

For example, the following authenticates to the PI Server named thePIServer using

your Windows logon credentials;

a PI trust created on thePIServer for the Interface node; and

the username of piadmin and password of hello


C:\> authTest.exe thePIServer piadmin hello============================================================================Authenticating to [thePIServer] via Mappingscreatesession() failed; error=-10407[-10407] No Access - Secure Object========================================================================================================================================================Authenticating to [thePIServer] via Trustcreatesession() failed; error=-10407[-10407] No Access - Secure Object========================================================================================================================================================Authenticating to [thePIServer] via Explicit Login with User [piadmin]createsession() failed; error=-10431[-10431] Authentication method is disabled by current server policy============================================================================

The preceding authentication results indicate:

Method Result Privileges

Mapping Failure None

Trust Failure None

PI user logon Failure None

Because authentication failed, you must edit the Mapping or Trust for the Interface Node on the PI Server. Run authTest again. Repeat until the program indicates that it can authenticate to the PI Server. For example,

============================================================================Authenticating to [thePIServer] via Trustcreatesession() succeededProtocolCredentialResult: COMPANY\User1GetProtocolDetails: piadmin

The Interface connects to the PIServer using the Managed Data Access layer (MDA). To verify that you can successfully create a connection to the PI Server through MDA, go to the Interface Node and run the mdaPut.exe program.

The Usage syntax for mdaPut.exe is:

mdaPut.exe PIServer tagName dVal [ptSource]If successful, the output will be:Starting program to test ability to write to PI Server via MDAVersion is v1.0.0.0 6-February-2012Registering RPC Tables with Session Manager.============================================================================Authenticating to [RUSH] via Mappingscreatesession() succeededProtocolCredentialResult: OSI\orodriguezGetProtocolDetails: piadmin | piadmins | PIWorld========================================================================================================================================================Tag [sinusoid] not found on PI Server; program will create it========================================================================================================================================================Successfully created tag: sinusoid; ptId=172========================================================================================================================================================Waiting 3 seconds before writing to tag...========================================================================================================================================================Successfully wrote to tag [sinusoid]t=2012-02-28T15:58:21-08:00

26

v=1

If the tag is not found it will be created on the PIServer.

AF Meter Database

You must manually create the AF database that holds the meter elements. On the Interface Node, run the AF Client application PI System Explorer. Connect to the AF Server specified by AF_SERVER in the Source Registry. Create a New Database with the name indicated by the AF_DATABASE. For example,

[CONNECTOR01]AF_SERVER=theAFServerAF_DATABASE=MSP

Then, use File, Import, to load (in sequence) the meter template files provided by the Interface:

[PIHOME64]\Interfaces\PISCC\BaseMeterAssets.xml[PIHOME64]\Interfaces\PISCC\ExternalRelations.xml[PIHOME64]\Interfaces\PISCC\MSP\MspMeter.xml

Do not make changes to these meter template files.

Navigate to the Library section of PI System Explorer. Confirm that the AF database has the following Element Templates:


Exit from PI System Explorer.

28

Digital State Sets

Operational States

Metering head end systems often use enumerated values to describe the Operational State of a meter. For example,

NEW

CATALOGED

DISCOVERED

INITIALIZED

ACTIVE

INACTIVE

UNREACHABLE

REMOVED

DISCONNECTED

SERVICE_DISCONNECT

The MSP Interface expects the meter asset file to provide this information via the <meterStatus> element beneath the <mspMeter> element. For example,

<MultiSpeakMessageHeader> <Batch> <MultiSpeak> <mspMeter objectID="734100"> <meterStatusList> <meterStatus>Active</meterStatus> </meterStatusList> </MultiSpeak> </Batch></MultiSpeakMessageHeader>

The Interface stores a meter's Operational State into a State tag; for example,

MSP_734100.State

As mentioned previously, this tag is of type Digital. At first glance, it would seem logical to use the preceding enumerations as the tag's digital state set.

However, OSIsoft offers interfaces to various head end systems. These head end systems most likely will use enumerations for a meter's Operational State that differ from the preceding list. So, in order to maintain consistency for tags such as

MSP_734100.State

the Interface uses the following digital state set, which is named AMIOperationalStates.

Value State

0 Unkown

1 Disconnected


Value State

2 Connected

3 Installed

4 Discovered

5 Initialized

6 Inactive

7 Initialization_failed

8 Maintenance

9 Unreachable

10 New

11 Retired

12 Investigate

13 Initializing

14 Reserved

… Reserved

79 Reserved

The file AMIOperationalStates.CSV defines the preceding digital values. At startup, the Interface builds this state set on the PI Server, if necessary.

The file AMIOperationalStates.CSV resides in the


directory.

The comma separated file named MspOperationalMapping.CSV is responsible for mapping the value of the <meterStatus> element to the AMIOperationalStates table. This MspOperationalMapping.CSV file must reside in the same directory as the Interface plugin; that is,

[PIHOME64]\Interfaces\PISCC\MSP\MSPOperationalMapping.csv

The format of the MSPOperationalMapping.CSV file defines a many-to-one relationship between the value of the <meterStatus> element and AMIOperationalStates. That is,

[AMIOperationalStates Number],[meterStatus],[meterStatus],...

For example,

1,Disconnected,Service_Disconnect,Removed2,Active

The preceding entries indicate that when the value of the <meterStatus> element for a meter such as 734100 is either

Disconnected or

Service_Disconnect or

Removed


the Interface writes a value of 1, and thus resulting in a digital value of Disconnected for the tag MSP_734100.State.

Similarly, when the operational state is Active, the Interface writes 2, resulting in Connected for MSP_734100.State.

Status States

To maintain consistency among many head end systems, the Interface creates the digital state set named AMIStatusStates for points such as

MSP_734100.Input001.Status

These points store the status of a meter during an interval read. The digital state values for this state set are:

Value State

0 Unkown

1 OK

2 PulseOverFlow

3 TestMode

4 MeterDiag

5 ReverseEnergy

6 TimeChangeCheck

7 PowerOutage

8 PartialData

9 DataCollection

10 ShortInterval

11 LongInterval

12 TimeCheckHE

13 MeterId

14 ExternalMeter

15 MalFormedData

16 Syntactic

17 NoFlow

18 NonSteadyFlow

19 MeterInput

20 ZeroInterval

21 Reserved

… Reserved

79 Reserved

The file AMIStatusStates.CSV defines the preceding digital state values. At startup, the Interface builds this state set on the PI Server, if necessary.

The file AMIStatusStates.CSV resides in the



directory.

In the measurement data file that the Interface processes, the codeIndex attribute of the <readingStatusCode> element indicates the status of an interval reading. For example,

<meterReading objectID="734100"> <readingValues> <readingValue> <value>18.883400</value> <timeStamp>2010-10-19T00:00:00-07:00</timeStamp> <readingTypeCode name="_IntervalData_Forward_Energy___(kWh)"> </readingTypeCode> <readingStatusCode codeIndex="REVERSE_ENERGY_FLOW"> </readingStatusCode> </readingValue>

The comma separated file named MspStatusesMapping.CSV is responsible for mapping the codeIndex value to the AMIStatusStates table. This MspStatusesMapping.CSV file must reside in the same directory as the Interface plugin; for example,

[PIHOME64]\Interfaces\PISCC\MSP\MspStatusesMapping.csv

The format of the MSPStatusesMapping.CSV file defines a many-to-one relationship between an interval reading status and AMIStatusStates. That is,

[AMIStatusStates Number],[Interval Status],[Interval Status],...

For example,

1,DC_DETECT_ERROR,LOW_VOLTAGE_ERROR,RECOVERABLE_ERROR2,Overflow3,INTERVAL_TEST_MODE4,INTERVAL_RAM_FAILURE,INTERVAL_ROM_FAILURE5, REVERSE_ENERGY_FLOW

The preceding entries indicate that when the interval read status for a meter such as 734100 is

DC_DETECT_ERROR,

LOW_VOLTAGE_ERROR , or

RECOVERABLE_ERROR

the Interface writes a value of 1, resulting in a digital value of OK for the tag MSP_734100.Input001.Status.

Similarly, when the interval read status is REVERSE_ENERGY_FLOW, the Interface writes 5, resulting in ReverseEnergy for MSP_734100.Input001.Status.

Events

To maintain consistency among many head end systems, the Interface creates the digital state set named AMIEventStates for points such as

MSP_734100.Event

32

These points store the events for a meter. The digital state values for this state set are:

Value State

0 Unknown

1 Cartridge_Alarm_Error

2 Cartridge_Alarm_Frozen

3 Cartridge_Alarm_Removed

4 Cartridge_Configuration_Change-out

5 Cartridge_Configuration_Installed

6 Demand_Alarm_Demand reset

7 Demand_Alarm_Demand reset fail

8 Demand_Alarm_High limit

9 Demand_Alarm_Mismatch

10 Demand_Alarm_Overload

11 Firmware_Alarm_Command error

12 Firmware_Alarm_Data error

13 Firmware_Alarm_Display error

14 Firmware_Alarm_Input error

15 Firmware_Alarm_Invalid

16 Firmware_Alarm_Memory error

17 Firmware_Alarm_Message error

18 Firmware_Alarm_Option board error

19 Firmware_Alarm_Program error

20 Firmware_Alarm_Register error

21 Firmware_Alarm_Reset

22 Firmware_Alarm_Reset error

23 Firmware_Alarm_Self-test error

24 Firmware_Alarm management_Acknowledged

25 Firmware_Alarm management_Activated

26 Firmware_Alarm management_Disabled

27 Firmware_Alarm management_Enabled

28 Firmware_Alarm management_Set

29 Firmware_Configuration_Alter option

30 Firmware_Configuration_Alternate phone

31 Firmware_Configuration_Configuration error

32 Firmware_Configuration_Invalid parameter

33 Firmware_Configuration_Invalid version

34 Firmware_Configuration_Mismatch

35 Firmware_Configuration_Not initialized

36 Firmware_Configuration_Reprogrammed


Value State

37 Firmware_Configuration_Setup disabled

38 Firmware_Configuration_Setup enabled

39 Firmware_Configuration_Synch disabled

40 Firmware_Configuration_Synch enabled

41 Firmware_Configuration_Synched

42 Firmware_Configuration_Upgrade pending

43 Firmware_Configuration_Watchdog Reset

44 Firmware_Status check_Cold start

45 Firmware_Status check_Download status

46 Firmware_Status check_Health OK

47 Firmware_Status check_Procedure invoked

48 Firmware_Status check_Test call

49 Firmware_Status check_Warm start

50 Load control_Alarm_Abort

51 Load control_Status check_Changed by condition

52 Load control_Status check_Commanded change

53 Load control_Status check_Momentary

54 Load control_Status check_Prepayment change

55 Load control_Status check_Scheduled

56 Load control_Status check_Scheduled change

57 Load control_Status check_Started

58 Load control_Status check_Stopped

59 Load profile_Alarm_Almost full

60 Load profile_Alarm_Corrupt data

61 Load profile_Alarm_Survey failed

62 Memory_Alarm_Allocation error

63 Memory_Alarm_Almost full

64 Memory_Alarm_Data error

65 Memory_Alarm_EPROM failure

66 Memory_Alarm_Firmware failure

67 Memory_Alarm_Mismatch

68 Memory_Alarm_NVRAM failure

69 Memory_Alarm_Overflow

70 Memory_Alarm_RAM failure

71 Memory_Alarm_RAM full

72 Memory_Alarm_ROM failure

73 Memory_Alarm_Table full

74 Memory_Status check_Parameter change

34

Value State

75 Metrology_Alarm_Alarm cleared

76 Metrology_Alarm_Cleared

77 Metrology_Alarm_High limit

78 Metrology_Alarm_Input error

79 Metrology_Alarm_Invalid

80 Metrology_Alarm_KYZ failure

81 Metrology_Alarm_Limit exceeded

82 Metrology_Alarm_Low limit

83 Metrology_Alarm_Pulse failure

84 Metrology_Alarm_Read Missing

85 Metrology_Alarm_Register error

86 Metrology_Calibration_Changed

87 Metrology_Calibration_Deviated

88 Metrology_Calibration_Set

89 Metrology_Quality Flag_Calculated

90 Metrology_Quality Flag_Default

91 Metrology_Quality Flag_Estimated

92 Metrology_Quality Flag_Initial read

93 Metrology_Quality Flag_Last read

94 Metrology_Quality Flag_Measured

95 Metrology_Quality Flag_Preset

96 Metrology_Quality Flag_Questionable

97 Metrology_Quality Flag_Test mode

98 Metrology_Read Type_On-request

99 Metrology_Read Type_Scheduled

100 Metrology_Read Type_Self read

101 Metrology_Status check_Last read updated

102 Metrology_Status check_List cleared

103 Metrology_Status check_List pointers reset

104 Metrology_Status check_List pointers updated

105 Metrology_Status check_Pending table activation

106 Metrology_Status check_Pending table clear

107 Metrology_Status check_Table written

108 Mode_Maint mode_Started

109 Mode_Maint mode_Stopped

110 Mode_Metering mode_Started

111 Mode_Metering mode_Stopped

112 Mode_Test mode_Started


Value State

113 Mode_Test mode_Stopped

114 Power_Alarm_Power out

115 Power_End alarm_Restored

116 Power_Outage_Minutes

117 Power_Outage_Momentary

118 Power_Outage_Momentary events

119 Power_Outage_Seconds

120 Power_Outage_Sustained

121 Power_Outage_Sustained events

122 Power_Outage_Total events

123 RCD switch_Alarm_Connect failed

124 RCD switch_Alarm_Disconnect failed

125 RCD switch_Status check_Changed

126 RCD switch_Status check_Connected

127 RCD switch_Status check_Disconnected

128 Tamper_Alarm_Cover removed

129 Tamper_Alarm_Encoder

130 Tamper_Alarm_Magnetic

131 Tamper_Alarm_Physical

132 Tamper_Alarm_Reverse rotation

133 Tamper_Alarm_Tamper detected

134 Tamper_Alarm_Tilt

135 Tariff_Alarm_Demand reset

136 Tariff_Alarm_TOU Mismatch

137 Tariff_Credit_Adjusted

138 Tariff_Credit_Decreased

139 Tariff_Credit_Emergency increase

140 Tariff_Credit_Increased

141 Tariff_Setting_Daily rate change

142 Tariff_Setting_Program changed

143 Tariff_Setting_Rate change

144 Tariff_Setting_Tier changed

145 Tariff_Setting_Week rate change

146 Tariff_Status check_Demand reset

147 Tariff_Status check_RTP activated

148 Tariff_Status check_RTP deactivated

149 Tariff_Status check_Special schedule

150 Reserved

36

Value State

… Reserved

199 Reserved

The file AMIEventStates.CSV defines the preceding digital state values. At startup, the Interface builds this state set on the PI Server, if necessary.

The file AMIEventStates.CSV resides in the


directory.

In the meter event file that the Interface processes, the codeString and time attributes of the <meterEvent> element indicate the meter event. For example,

<meterEventList> <eventInstances> <eventInstance> <meterID objectID="734100"></meterID> <meterEvent time="2010-10-14T13:12:24-07:00" codeString="Last Gasp"> </meterEvent> </eventInstance> </eventInstances></meterEventList>

The comma separated file named MspEventMapping.CSV is responsible for mapping the meter events to the AMIEventStates table. This MspEventMapping.CSV file must reside in the same directory as the Interface plugin; for example,

[PIHOME64]\Interfaces\PISCC\Msp\MspEventMapping.csv

The format of the MspEventMapping.CSV file defines a many-to-one relationship between meter events and AMIEventStates. That is,

[AMIEventStates Number],[event string],[event string]...

For example,

114,Last Gasp,Last-Gasp

The preceding entries indicate that when the <meterEvent> element has a codeString attribute of

Last Gasp or

Last-Gasp

for a meter such as NP_ab00dd100000, the Interface writes a value of 114, resulting in the digital value of Power_Alarm_Power out for the tag MSP_734100.Event.

User Modifications

As the preceding paragraphs indicate, the comma separated files

AMIOperationalStates.CSV

AMIStatusStates.CSV


AMIEventStates.CSV

define the digital state sets

AMIOperationalStates

AMIStatusStates

AMIEventStates

in the PI Server that the Interface uses for its Digital points.

If these digital state sets do not contain all the digital state values that you need, you may add your own digital state values by editing these CSV files. However, do not edit the entries that are marked Reserved.

Be sure also to add the corresponding mapping within the MSP Interface specific files. These files are named

MspOperationalMapping.CSV

MspStatusesMapping.CSV, and

MspEventMapping.CSV

You will need to consult the documentation of the application that generates the MultiSpeak data files. Such documentation should indicate the expected values for <meterStatus>, <codeIndex>, and <codeString>. By knowing these expected values, you will be able to edit the MspOperationalMapping.CSV, MspStatusesMapping.CSV, and MspEventMapping.CSV files.

Within the CSV files, lines that begin with '#' or '; ' are comments. For example,

# This is a comment line1,Disconnected,Service_Disconnect,Removed2,Active3,Installed4,Discovered# This is another comment line5,Initialized6,Inactive7,Init_failed8,Maintenance9,Unreachable10,New11,Retired12,Investigate13,Initializing

38

MultiSpeak File ConfirmationThe MSP Interface does not communicate with a metering head end system. Instead, the Interface relies on another application

to interact with the head end system,

to generate data files in the MultiSpeak format, and

to put these files where the Interface can read them.

So, in order for the Interface to work properly, the data files must be in a format that the Interface understands.


Test Application

Included in the Interface distribution kit is an application called MSPTest. MSPTest uses the same internal parsing library as the Interface. It parses data files and shows you their contents; for example,

meter name

service delivery point for the meter

measurement values

meter events

In this manner, MSPTest informs you whether a data file is compatible with the Interface.

MSPTest is located in

[PIHOME64]\Interfaces\PISCC\MSP\MSPTest\MSPTest.exe

MSPTest requires two command line parameters. These parameters specify

the location of the source registry; and

the MSP Interface connector section in the source registry

For example,

C:\> MSPTest.exe -sr=..\..\piscc.ini -he=connector01

The contents of the source registry must contain an entry for DATA_DIRECTORY_TEST. For example,

[connector01]DATA_DIRECTORY_TEST=C:\mspData\test

This DATA_DIRECTORY_TEST entry refers to the directory that contains data files whose format and contents you wish to confirm.

Meter Asset File

To validate a meter asset file, select Option 100 and provide the name of the meter asset file. If the file is valid, MSPTest displays information such as

meter name,

meter operational state,

service delivery point

meter measurements

For example,

Number of meters is 2-----------------------nMeter=1 Meter=734100 state=Connected sdpId=sdpId_0 i=0 cim=Max_Indicating_Forward_Demand_TOURateA__(kW) i=1 cim=_Summation_Forward_Energy_TOURateA__(kWh) i=2 cim=_IntervalData_Forward_Energy___(kWh)-----------------------nMeter=2 Meter=734101 state=Connected sdpId=sdpId_1 i=0 cim=Max_Indicating_Forward_Demand_TOURateA__(kW)


i=1 cim=_Summation_Forward_Energy_TOURateA__(kWh) i=2 cim=_IntervalData_Forward_Energy___(kWh)

Meter Reading File

To validate a meter reading file, select Option 101 and provide the name of the meter reading file. If the file is valid, MSPTest displays information such as

meter name,

timestamp of the measurement reading

measurement name (in CIM)

measurement value

measurement status (if available)

For example,

Meter=734100 t=2010-10-19T00:00:00-07:00 m=_IntervalData_Forward_Energy___(kWh) v=18.8834 status=Reverse_Energy_Flow t=2010-10-19T01:00:00-07:00 m=_IntervalData_Forward_Energy___(kWh) v=9.8834 t=2010-10-19T02:00:00-07:00 m=_IntervalData_Forward_Energy___(kWh) v=10.8834 t=2010-10-19T03:00:00-07:00 m=_IntervalData_Forward_Energy___(kWh) v=11.8834

Meter Event File

To validate a meter reading file, select Option 102 and provide the name of the meter event file. If the file is valid, MSPTest displays information such as

meter name

timestamp of the meter event

meter event

For example,

Meter=734100 t=2010-10-14T13:12:24-07:00 e=Last Gasp

Output to File

A data file can contain so much information that it is impractical to view its contents in the Windows command prompt. For example, there are 100 meters in a single meter asset file. In this situation, you should select Option 1 so that MSPTest logs file parsing results to a file named mspLibUse.out.


MDUS Commands

The MSP Interface can invoke MDUS commands such as meter ping, meter on-demand read, meter connect, and meter disconnect. However, a separate application that implements the MultiSpeak MDM Server specification is necessary.

Options 300 through 308 of MSPTest allow you to test the application that implements the MultiSpeak MDM Server specification.

42

Windows ServiceFor normal operations, you should run the Interface as a Windows service. A service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.

Service Commands

Creating the Interface Service

During an install, the install kit creates the service to PISCC.exe.

Removing the Interface Service

During an uninstall, the install kid removes the service to PISCC.exe

Starting the Interface Service

To start the service for the Interface, open a Windows command prompt and change to the directory where the piscc.exe and piscc.ini files are. Type the following command

C:\> piscc.exe -start

If you are not in the directory where the piscc.exe and piscc.ini files are, use the following:

C:\> net start piscc

You can also use the Windows Services control panel to start the Interface service.

Stopping the Interface Service

To stop the service for the Interface, open a Windows command prompt and change to the directory where the piscc.exe and piscc.ini files are. Type the following command

C:\> piscc.exe -stop

If you are not in the directory where the piscc.exe and piscc.ini files are, use the following:

C:\> net stop piscc

You can also use the Windows Services control panel to stop the Interface service.

Querying the Interface Service

To determine whether the service for the Interface is currently running, open a Windows command prompt and change to the directory where the piscc.exe and piscc.ini files are. Type the following command:

C:\> piscc.exe -query


Service Account

When the install kit creates the service, the service runs under the Local System account. However, this account does not have the requisite privileges to create AF meter elements.

Accordingly, you must use the Windows Services control panel and change the properties of this Interface service. Specify a logon account (typically, a domain account) that has the proper privileges. For example,


Pre-Created TagsThe MultiSpeak Interface supports the use of pre-created tags. When running in this configuration, the Interface does not perform any point creation. Instead, the Interface renames existing PI points that you have already created via the AMITagCreator.exe that is located in the %PIHOME64%bin directory.

The remainder of this section discusses the steps you need to take if you wish to run the Interface using pre-created tags.

Source Registry Entry

To enable the use of pre-created tags, specify a value of YES for the PRE_CREATED_TAGS parameter in the Source Registry. For example,

[connector01]PRE_CREATED_TAGS=YES

User Point Creation

Rules

The points that you create for use by the Interface must follow two rules

The tagname begins with _res

The tag's Point Source attribute has the value specified in the POINT_SOURCE parameter of the Source Registry.

These points must be created using the AMITagCreator.exe.

Tags per Point Type per Meter

Before starting the Interface, you should create a sufficient number of tags of the various point types (Float32, Int32, String, and Digital). In this manner, the Interface can rename these PI points while it is processing the meter asset files.

The representation of a meter in the PI Server requires at least five tags. The first four are associated with the meter itself. For example,

MSP_734100.Event (Digital, state set AMIEventStates)MSP_734100.Log (String)MSP_734100.State (Digital, state set AMIOperationalStates)MSP_734100.Input001.Status (Digital, state set AMIStatusStates)

In addition, a meter must contain at least one measurement. For example,

MSP_734100.Input001._Summation_Forward_Energy_TOURateA__(kWh).Value (Float32)

When you configure the Interface for Validated Measurements, the Interface needs two more pre-created tags to rename. For example,



The former is of type Int32 and the latter Float32.

So, the number of tags per point type for a single meter is

Digital – 3

String – 1

Float32 – number of meter measurements; add 1 if VEE is involved

Int32 – 1 if VEE is involved

Digital States

Recall that before you can create a digital point, the point's digital state set must already exist. So, prior to creating the pre-created tags for the Interface, you must first create the following digital state sets. (You can use PI-SMT for this creation.)

AMIEventStates

AMIOperationalStates

AMIStatusStates

You need not fill these state sets with all the required states. At startup, the Interface will fill in the required states.

AMITagCreator

Use the AMITagCreator.exe to add the pre-created tags to be used by the interface. To configure the tool, edit the file app.config to reflect your system.

The tool will create tags with the format: _res_[PointType]_nnnnnnnn. For example _res_PI_float32_00000001

<?xml version="1.0" encoding="utf-8" ?><configuration> <appSettings> <add key="PIServer" value="MyPIServer" /> <add key="PointSource" value="MyPointSource" /> <add key="MeterCount" value="1" /> <add key="NumberOfInputs" value="1" />

 <add key="MeasurementsPerMeter_float32" value="3" />

<add key="TagNumberStartsFrom" value="0" /> </appSettings></configuration>

Parameter Description

PIServer The PI server where you will be creating points

PointSource The point source that the interface uses

MeterCount The number of meters for which you want to create points

NumberOfInputs The number of inputs in a meter.



MeasurementsPerMeter_xxxxx The number of measurements per meter. Use this parameter to create other needed value tags, for instance an additional tag to be used for VEE.

Enter a different key depending on the point type. For example:

MeasurementsPerMeter_float32

MeasurementsPerMeter_int32

MeasurementsPerMeter_float64

TagNumberStartsFrom Tag names include a sequencing number, use this key to set the starting number.


Interface ChecklistBefore you start the Interface, make sure that you fully understand the information presented in the previous chapters. Confirm that the Source Registry parameters have the proper values. Confirm the functionality of supporting software. Confirm other prerequisites (as described below).

Source Registry Parameters

PISCC Section

Verify that the PI_SERVER parameter in the PISCC section of the Source Registry indicates the hostname of the PI Interface Node. Verify that the PI_COLLECTIVE_XX parameters contain the hostnames of the PI Servers that the Interface writes data to.

For example,

[PISCC]PI_SERVER=theInterfaceNodePI_COLLECTIVE_00=NeptunePI_COLLECTIVE_01=Jupiter

CONNECTOR01 Section

Verify that you have specified a NAME for the interface plug-in module. This value is an arbitrary identifier that you choose. However, it should refer the Interface (e.g., MultiSpeak).

[connector01]NAME=MultiSpeak

Verify the CONNECTOR_STATE and START_STATE parameters.

[CONNECTOR01]CONNECTOR_STATE=NOT_LOADEDSTART_STATE=START

Verify that PATH contains the location of the interface plug-in module:

[connector01]PATH=D:\Program Files\PIPC\Interfaces\PISCC\MSP\PIMspPlugIn.dll

Verify that you have specified a head end identifier. The Interface uses this identifier in its naming convention for AF meter elements and PI points.

[connector01]HEAD_END=MSP

Verify AF parameters:

[connector01]AF_SERVER=theAFServerAF_DATABASE=MSP

Verify that you have chosen a value for the PointSource attribute of the PI points that the Interface uses:

[connector01]


POINT_SOURCE=MSP

Verify the name of the directory where the Interface looks for MultiSpeak data files:

[connector01]DATA_DIRECTORY=E:\MSPData

The preceding text places a CONNECTOR01 section before for each group of parameters. This placement emphasize that these parameters are part of CONNECTOR01. In reality, the Source Registry must have only a single CONNECTOR01 section. For example,

[connector01]NAME=MultiSpeakCONNECTOR_STATE=NOT_LOADEDSTART_STATE=STARTPATH=D:\Program Files\PIPC\Interfaces\PISCC\MSP\PIMspPlugIn.dllHEAD_END=MSP

AF_SERVER=theAFServerAF_DATABASE=MSP

POINT_SOURCE=MSP


Supporting Software Functionality

AF Server

Confirm that the AF Server contains a database for storing meter elements. This database must contain the proper element templates (i.e., templates defined by BaseMeterAssets.xml and SilverSpringMeter.xml). Recall that you can use the PI System Explorer for this confirmation.

Data File Compatibility

Confirm that the MultiSpeak data files are compatible with the Interface. Recall that you can use the MSPTest application. (Obviously you cannot test the compatibility of each and every data file. However, you should test a least one meter asset file, one meter reading file, and one meter event file.)

Other Prerequisites

PI Digital State Sets

The Interface reads CSV files to create digital state sets. These files are named

AMIOperationalStates.CSV

AMIStatusStates.CSV

AMIEventStates.CSV


Use a simple text editor to verify that they contain suitable digital state values. In addition, verify that the files

MspOperationalMapping.CSV

MspStatusesMapping.CSV

MspEventMapping.CSV

indicate the correct mappings.

You will need to consult the documentation of the application that generates the MultiSpeak data files. Such documentation should indicate the expected values for <meterStatus>, codeIndex, and codeString. By knowing these expected values, you will be able to edit the MspOperationalMapping.CSV, MspStatusesMapping.CSV, and MspEventMapping.CSV files.

Windows Service

Verify that you have configured the Interface to run as a Windows service. Confirm that this service has the proper logon credentials so that it can create AF meter elements.

Pre-Created Tags

If you are running the Interface using pre-created tags, confirm that the Source Registry contains

[connector01]PRE_CREATED_TAGS=YES

Also, determine the number of meters and their associated measurements. Based on this number, calculate the total number of Float32, Int32, String, and Digital tags required. Add a safety factor. Create these tags. These tags must follow these rules:

The tagname begins with _res

The tag's Point Source attribute has the value specified in the POINT_SOURCE parameter of the Source Registry.

If you are using multiple PI Servers, distribute the point creation among the various PI Servers specified in PI_COLLECTIVE_XX.


Interface StartupThis chapter presents the conclusion of all the work that you have undertaken. It walks you through the steps of an interface startup.

Minimal Startup

Before embarking on a full-scale interface startup using real data files, OSIsoft recommends that you first perform a minimal startup. This startup type allows you to understand and to verify the functionality of the different Interface components.

You should already have a meter asset file that references actual meters. Alternatively, the Interface distribution kit includes an example meter asset file called meterAsset_Sample.xml. It resides in

[PIHOME64]\Interfaces\PISCC\MSP\meterAsset_Sample.xml

This file contains meter definitions for two meters. You can use this asset file as the input for a minimal startup if you do not have an actual meter asset file.

Source Registry Parameters

To configure the Interface for a minimal startup, enter the following parameters and values to the Source Registry:

[CONNECTOR01]TRACE_METERS=trueMAX_METERS=5

The TRACE_METERS setting tells the Interface to log messages at various stages of its meter creation and PI point update process.

The MAX_METERS setting limits the meter database to 5 meters.

Startup Confirmation

Before starting the Interface, delete all the files in the DATA_DIRECTORY. Start the Interface by typing the following command at the Windows command prompt or by using the Windows services control panel:

C:\> net start piscc

Check that the Interface started correctly by looking at the Windows Event Log. It should contain messages such as

PISCC.exe> Opened Source Registry: D:\program files\pipc\interfaces\piscc\piscc.iniPISCC.exe> Loaded Module CONNECTOR01 [D:\program files\pipc\interfaces\piscc\MSP\PIMspPlugIn.dll]PISCC.exe> MspPlugIn> Using DATA_DIRECTORY=C:\MSPData


Meter Asset File Parsing

With the Interface running, copy the meter asset file to the DATA_DIRECTORY directory. This meter asset file is either

a file that references actual meters, or

meterAsset_Sample.xml

The following events occur:

1. The Interface parses the meter asset file and creates the appropriate meter and measurement elements in AF.

2. The Interface creates the corresponding PI points for the meter and its measurements.

3. The PI Server receives the value of the meter's operational state.

To confirm that Step 1 occurred, run the PI System Explorer and load the AF meter database. You should see meter and measurement elements. For example,

If you wish, you can confirm that the AF meter element attribute named ServicePointID contains the appropriate value.

To confirm that Step 2 occurred, run PI System Management Tools and the Point Builder plug-in. Search for points related to the meter. For example,

MSP_734100.LogMSP_734100.EventMSP_734100.StateMSP_734100.Input001.StatusMSP_734100.Input001._IntervalData_Forward_Energy___(kWh).ValueMSP_734100.Input001._Summation_Forward_Energy_TOURateA__(kWh).ValueMSP_734100.Input001.Max_Indicating_Forward_Demand_TOURateA__(kW).Value

To confirm that Step 3 occurred, use the Archive Editor plug-in. Look at the value of the meter's operational state tag; e.g.,

MSP_734100.State

Confirm that this value agrees with the value of the <meterStatus> element in the data file.

After you have familiarized yourself with the Interface's operation, you can stop it via

C:\> net stop piscc


or by using the Windows service control panel.

Debug Files

A value of True for the TRACE_METERS parameter tells the Interface to log messages at various stages of its meter creation and point update process. Examples of filenames that contain these messages are:

Asset_2010_5_14_13.out2010_5_14_13.out

The former contains information on data sent to AF. For example,

MSP_734100 [New]; has 3 measurements i=0 Meas=Max_Indicating_Forward_Demand_TOURateA__(kW) i=1 Meas=_Summation_Forward_Energy_TOURateA__(kWh) i=2 Meas=_IntervalData_Forward_Energy___(kWh) ServicePointID=[sdpId_0]

The latter contains information on data sent to the PI Server. For example,

MSP_7341000.State2010-05-14T13:52:47-07:00 PI_Type_digital istat=2

Normal Startup

Sample Startup Removal

For normal startup, either remove or comment out the parameter TRACE_METERS and MAX_METERS.

[CONNECTOR01];TRACE_METERS=true;MAX_METERS=5

Startup Sequence

Start the Interface. Then, start the application which

generates MultiSpeak data files, and

copies these files to the DATA_DIRECTORY.

The application should first copy meter asset files before copying the other file types. This sequence allows the Interface to create the necessary PI points to hold the meter measurement data.

Data Collection Loop

During steady-state operation, the Interface continuously performs the following actions:

look for and parse meter asset files (meterAsset*.xml);

update AF elements and the attributes of PI points as appropriate;

update the value of the operational state PI points with a meter's <meterStatus>;

look for and parse meter reading files (measurementData*.xml);


update the value of meter measurement PI points with meter usage data;

look for and parse event files (eventData*.xml);

update the value of the meter event PI points with meter event data.

File Parsing Errors

If the Interface encounters errors during the parsing of a meter file, it renames it. The name of the renamed file is the name of the original file plus ".renamed". For example,

meterAsset_1.xml

becomes

meterAsset_1.xml.renamed

Interface Data Files

When the Interface runs, it creates data files in two directories:

[PIHOME64]\Interfaces\PISCC[PIHOME64]\Interfaces\PISCC\MSP

Various threads of the Interface write to and read from these files in order to create AF meter elements and PI points.

PISCC

The filename in the PISCC directory is:

AMIRecNoList.tbl

MSP

The filenames in the MSP directory are:

<Name>_<AF_DATABASE>_meters.tbl

<Name>_<AF_DATABASE>_meters_queue.dat

<Name>_<AF_DATABASE>_meters_sync_queue.dat

<Name>_<PI_COLLECTIVE_XX>_<POINT_SOURCE>_Cache.dat

<Name>_<PI_COLLECTIVE_XX>_<POINT_SOURCE>_PreCache.dat

<Name>__missingtag_queue.dat

<PI_COLLECTIVE_XX>createtag_queue.dat

<PI_COLLECTIVE_XX>deploytag_queue.dat

<PI_COLLECTIVE_XX>edittag_queue.dat

<PI_COLLECTIVE_XX>statetable_queue.dat

<PI_COLLECTIVE_XX>tagrequest_queue.dat

where <PI_COLLECTIVE_XX>, <Name>, <AF_DATADATABASE>, and <POINT_SOURCE> refer to parameter values within the Source Registry. For example,

[PISCC]PI_COLLECTIVE_00=NeptunePI_COLLECTIVE_00=Jupiter

56

[CONNECTOR01]Name=MultiSpeakAF_DATABASE=MSPPOINT_SOURCE=mspsrc

result in files with names such as

MultiSpeak_MSP_meters.tbl

MultiSpeak_MSP_meters_queue.dat

MultiSpeak_MSP_meters_sync_queue.dat

MultiSpeak_Neptune_mspsrc_Cache.dat

MultiSpeak_Neptune_mspsrc_PreCache.dat

MultiSpeak_Jupiter_mspsrc_Cache.dat

MultiSpeak_Jupiter_mspsrc_PreCache.dat

MultiSpeak__missingtag_queue.dat

Neptunecreatetag_queue.dat

Neptunedeploytag_queue.dat

Neptuneedittag_queue.dat

Neptunestatetable_queue.dat

Neptunetagrequest_queue.dat

Jupitercreatetag_queue.dat

Jupiterdeploytag_queue.dat

Jupiteredittag_queue.dat

Jupiterstatetable_queue.dat

Jupitertagrequest_queue.dat


VEE Support

In order to support VEE (Validation, Editing, and Estimation) applications, the Interface has the ability to create PI points that hold a validated value and a validated state.

Recall that for each meter measurement, the Interface creates a PI point to hold its measurement value. For example, for these three measurements

the Interface creates the following three PI points:


MSP_734100.Input001._Summation_Forward_Energy_TOURateA__(kWh).Value

MSP_734100.Input001.Max_Indicating_Forward_Demand_TOURateA__(kW).Value

To tell the Interface to create PI points that hold a validated value and a validated state, use the VALIDATED_MEASUREMENT001 parameter and specify an appropriate measurement. For example, Source Registry contents of

[connector01]

VALIDATED_MEASUREMENT001=_IntervalData_Forward_Energy___(kWh)

result in the Interface creating the following PI points:

MSP_734100.Input001._IntervalData_Forward_Energy___(kWh).ValidatedValue

MSP_734100.Input001._IntervalData_Forward_Energy___(kWh).ValidatedState

The .ValidatedValue point is of type Float32. The .ValidatedState point is of type Int32. The Interface does not write to these points. Instead, an external VEE application sends data to them.

To specify multiple validated measurements, increase the trailing digits of the parameter VALIDATED_MEASUREMENT. For example,

[connector01]VALIDATED_MEASUREMENT001=_IntervalData_Forward_Energy___(kWh)VALIDATED_MEASUREMENT002=_IntervalData_Forward_Energy___(kVARh)VALIDATED_MEASUREMENT003=_IntervalData_Forward_Energy___(Vavg(A-N))


Validated Measurements

Measurements Determination

To determine the values for use with the parameter VALIDATED_MEASUREMENT, look in the meter asset file for the name attribute of the <readingType> element. For example,

<readingType objectID="734100"> <readingTypeCode name="_IntervalData_Forward_Energy___(kWh)"> </readingTypeCode></readingType>

tells you to use

VALIDATED_MEASUREMENT001=_IntervalData_Forward_Energy___(kWh)


The MSP Interface can invoke MDUS commands such as meter ping, meter on-demand read, meter connect, and meter disconnect. However, a separate application that implements the MultiSpeak MDM Server specification is necessary. This application must be developed by a third-party systems integrator or the end user of the MSP Interface.

Source Registry Entries

To indicate that the Interface will interact with a MultiSpeak MDM Server, specify

the URL of the MDM Server, and

a URL indicating the port number on which the Interface will receive data from this MDM Server.

For example,

[CONNECTOR01]MSP_MDM_URL=http://192.168.100.134:7070MSP_MDM_NOTIFY_URL=http://192.168.4.14:7400

The first entry tells the Interface the location of the MDM Server (i.e., port 7070 on the computer whose IP address is 192.168.100.134).

The second entry indicates that the Interface (which resides on a computer whose IP is 192.168.4.14) will listen on port 7400 for messages from the MDM Server.

MDM Server Web Service Methods

Per the MultiSpeak specification, an MDM Server must implement the following two web service methods:

GetMethods()

PingURL()

When the Interface starts up and determines that the MSP_MDM_URL is valid, it connects to the MDM Server and invokes GetMethods(). The MDM Server then returns a list of operations that it supports. Based on this list, the Interface can perform a meter ping, meter on-demand read, meter connect, and meter disconnect. Specifically,

InitiateOutageDetectionEventRequest() – ping

InitiateMeterReadingByMeterID() – on-demand read

InitiateConnectDisconnect() – remote connect and disconnect

Meter Actions

The Interface supports MDUS commands sent from external applications. The RPC PI Server, which runs on the same computer as the Interface,

receives RPCs from programs such as the Utilities Gateway, and


MDUS Commands

dispatches them to the Interface

Based on what the RPC contains, the Interface connects to the MDM Server to perform one of the following actions:

ping a meter

read a meter's registers

connect a meter

disconnect a meter


This chapter describes additional features of the Interface.

Performance Counters

The Interface creates Windows Performance Counters. This feature allows external applications the ability to monitor the performance and health of the Interface. You can use any application that is capable of reading Windows Performance Counters. Examples include the Windows Perfmon Utility (perfmon.exe) and OSIsoft's PI Performance Monitor Interface.

PISCC Object

There are three counters associated with the PISCC (PI Interface Conductor Container) object. Here's a screenshot from PI System Management Tools:

Connector Count

The value of this counter indicates the number of running connectors; that is, the number of plug-in DLL modules that PISCC has loaded and are running.

Connector Health Status

This counter has a value of 1 when any of the plug-in modules indicates an error condition. It has a value of 0 when all plug-in modules are without a fault.

The MSP Interface performs a single check to determine whether to raise an error condition. The Interface checks whether it has processed a MultiSpeak data file during the past 60 minutes. If not, the Interface indicates a fault.


Miscellaneous Features

You can change the frequency via the Source Registry parameter DATA_HEALTH_CHECK_PERIOD_MINUTES. The default is 60 minutes:

[CONNECTOR01]DATA_HEALTH_CHECK_PERIOD_MINUTES=60

Connector Heartbeat Status

This counter has a value of 1 when any of the plug-in modules has stopped updating its health status counter. It has a value of 0 when all plug-in modules are updating their health status counter.

MSP Interface Object

The name of the UIQ Interface object comes from the NAME parameter in the Source Registry. For example,

NAME=Msp64

results in a performance counter object name of PISCC_Msp64:

Advanced AF Configuration

Root Node

By default, the Interface creates meter elements at the root of the AF database:


You can tell the Interface to put the meter elements under another AF Element via the AF_ROOT_NODE parameter. For example,

[CONNECTOR01]AF_ROOT_NODE=HE

results in

Data Write Method

The PI_DATA_WRITE parameter in the Source Registry determines how mode with which the Interface writes to a PI Server. These modes are:

REPLACE

APPEND

NOREPLACE (default)

REPLACE

The Interface can write a value to the PI Server such that if a data value already exists at a given timestamp, it replaces the value. For this configuration, set the PI_DATA_WRITE parameter in the Source Registry to REPLACE. Specifically,

[CONNECTOR01]PI_DATA_WRITE_METHOD=REPLACE

For example, if the tag


already has in the PI archive the event

Timestamp Value

10-Jun-2010 15:00:00 234.5

and the Interface sends the following event:

Timestamp: 10-Jun-2010 15:00:00


Value: 310.5

the PI archive for this tag will then show only a single event for 10-Jun-2010 15:00:00:

Timestamp Value

10-Jun-2010 15:00:00 310.5

APPEND

If you want multiple events for the same timestamp, set the PI_DATA_WRITE parameter in the Source Registry to APPEND. Specifically,

[CONNECTOR01]PI_DATA_WRITE_METHOD=APPEND

For this situation, the PI archive will contain

Timestamp Value

10-Jun-2010 15:00:00 234.5

10-Jun-2010 15:00:00 310.5

NOREPLACE

You can also configure the Interface such that it does not replace an existing archive event. Use the value of NOREPLACE:

[CONNECTOR01]PI_DATA_WRITE_METHOD=NOREPLACE

For this situation, if the PI archive already contains the event

Timestamp Value

10-Jun-2010 15:00:00 234.5

and the Interface sends the following event:

Timestamp: 10-Jun-2010 15:00:00

Value: 310.5

the PI archive for this tag will then show only a single event for 10-Jun-2010 15:00:00:

Timestamp Value

10-Jun-2010 15:00:00 234.5

Meter Events

The PI_DATA_WRITE_METHOD_EVENT parameter allows the Interface to write meter events into the PI Server using a mode that is different from the mode with which it writes measurement values. For example,

[CONNECTOR01]PI_DATA_WRITE_METHOD=NOREPLACEPI_DATA_WRITE_METHOD_EVENT=APPEND

66

tells the Interface not to replace an existing archive when it processes measurement values, but to append archive events when it processes meter events. In this configuration, it is possible for the PI Server to contain multiple meter events for a single timestamp.


Message Log File

The Interface writes informational and error messages to Windows Event Log (Application). The Source of the messages is PISCC. The Event ID of the messages is 31415.

Error Numbers

Positive error numbers indicate operating system errors. Negative numbers refer to PI System errors. Use the pidiag utility translates an error number into text. This utility is located in the ADM subdirectory of the PI Server installation directory. For example,

c:\> cd D:\PI\ADMc:\> pidiag –e –10401 [-10401] No Write Access - Secure Object

Troubleshooting Techniques

The best way to start troubleshooting the Interface is to understand how the Interface works. During steady-state operation, the Interface continuously performs the following actions:

look for and parse meter asset files (meterAsset*.xml);

update AF elements and the attributes of PI points as appropriate;

update the value of the operational state PI points with a meter's <meterStatus>;

look for and parse meter reading files (measurementData*.xml);

update the value of meter measurement PI points with meter usage data;

look for and parse event files (eventData*.xml);

update the value of the meter event PI points with meter event data.

So, when the Interface is not behaving as expected, you need to investigate which of the above actions caused the anomaly.

Meter Tracing

You can enable meter tracing via Source Registry parameters. For example, if you are interested in the meter 734100:

TRACE_METERS=TRUETRACE_SINGLE_METER=734100

To facilitate troubleshooting, the Interface checks every two minutes for changes to these Source Registry parameters:

TRACE_METERS

TRACE_SINGLE_METER

So, you need not stop and re-start the Interface for these parameters to take effect. However, you should check that the Windows Event Log indicates:


Appendix A: Troubleshooting

PISCC.exe> MspPlugIn> TRACE_METERS set to TruePISCC.exe> MspPlugIn> TRACE_SINGLE_METER=734100

Meter Element

The steps for the creation of a meter element in AF are:

parse a file named meterAsset*.xml, and

update AF elements

So, if a meter appears in the measurement asset file but does not appear in AF, questions relating to troubleshooting are:

1. Is the meterAsset*.xml file compatible with the Interface?

2. Did the Interface parse this file?

3. Did the Interface try to update AF?

For Step #1, run the MSPTest application to verify that the Interface will be able to parse the meter asset file.

For Step #2, check the Windows Event Log for a message indicating that the Interface parsed the file. For example,

PISCC.exe> MspPlugIn> Finished parsing: C:\MSPData\meterAsset_Sample.xml

For Step #3, because of the meter tracing parameters in the Source Registry, the Interface writes informational messages to a file with a name such as Asset_2010_5_14_13.out:

MSP_734100 [New]; has 3 measurements i=0 Meas=Max_Indicating_Forward_Demand_TOURateA__(kW) i=1 Meas=_Summation_Forward_Energy_TOURateA__(kWh) i=2 Meas=_IntervalData_Forward_Energy___(kWh) ServicePointID=[sdpId_0]

Meter Usage Data

The steps for the Interface to update meter usage data are:

parse a file named measurementData*.xml, and

update the value of meter measurement PI points with meter usage data.

So, if meter usage data appear in the measurement data file but does not appear in the PI archive, questions relating to troubleshooting are:

1. Is the measurementData*.xml file compatible with the Interface?


3. Did the Interface try to send meter usage data to the PI Server?

For Step #1, run the MSPTest application to verify that the Interface will be able to parse the meter usage file.


PISCC.exe> MspPlugIn>Finished parsing: C:\MSPData\measurementData_Sample.xml

70

For Step #3, the meter tracing parameters tell the Interface to log information on sending data to PI points. The filename is, for example, 2010_5_14_13.out. It contains text such as

MSP_734100.Input001._IntervalData_Forward_Energy___(kWh).Value2010-05-14T13:15:00-07:00 PI_Type_float32 drval=98.76 ival=0

Meter Event Data

The steps for the Interface to update meter event data are:

parse a file named eventData*.xml, and

update the value of meter measurement PI points with meter event data.

So, if a meter event appears in the event data file but does not appear in the PI archive, questions related to troubleshooting are:

1. Is the eventData*.xml file compatible with the Interface?


3. Did the Interface try to send event data to the PI Server?

For Step #1, run the MSPTest application to verify that the Interface will be able to parse the meter asset file. Also, confirm that the codeString value appears in the MspEventMapping.CSV file.


PISCC.exe> MspPlugIn> Finished parsing: C:\MSPData\eventData_Sample.xml

For Step #3, the meter tracing parameters tell the Interface to log information on sending data to PI points. The filename is, for example, 2010_5_14_13.out. It contains text such as

MSP_734100.Event2010-10-14T13:12:24-07:00 PI_Type_digital istat=19

Rebuilding the Local Meter Database

The local file to which the Interface writes meter information has the name

<Name>_<AF_DATABASE>_meters.tbl

where <Name> and <AF_DATADATABASE> refer to parameter values within the Source Registry. An example of a local meter database file is

MultiSpeak_MSP_meters.tbl

Should this file become corrupted and unusable by the Interface, you can rebuild it. Follow these steps:

1. Stop the Interface.

2. Rename the local meter database file.

3. If the Interface writes data to more than one PI Server (i.e., there are multiple PI_COLLECTIVE_XX entries), you must set the value of the parameter FIND_COLLECTIVE_BEFORE_CREATE to be YES.

4. Start the Interface.


5. Put meter asset files into the directory where the Interface expects them. That is, in the directory specified by DATA_DIRECTORY.

Note that the FIND_COLLECTIVE_BEFORE_CREATE parameter resides in the PISCC section of the Source Registry. That is,

[PISCC]FIND_COLLECTIVE_BEFORE_CREATE=YES

Local Meter and Point Synchronization

When the Interface starts up, it reads its local meter and point databases and synchronizes each meter with its corresponding PI points. There may be occasions when the Interface fails to properly perform this association. When this situation happens, you can tell the Interface to re-run the synchronization via the parameter SYNC_METER_TABLE in the CONNECTOR01 section of the Source Registry.

The value that you enter for SYNC_METER_TABLE must be either CREATE_MISSING or YES. That is,

[CONNECTOR01]SYNC_METER_TABLE=CREATE_MISSING

or

[CONNECTOR01]SYNC_METER_TABLE=YES

A value of CREATE_MISSING tells the Interface to synchronize meters with their PI points and to create any PI points that may be missing.

A value of YES tells the Interface to synchronize meter with their PI points, but not to create any PI points that may be missing.

When the Interface finishes the synchronization, it writes the value of PROCESSED to the parameter.

The Interface checks for changes in the Source Registry every two minutes. So, up to two minutes can elapse before the Interface performs the action that you have specified.

Common Problems

PI Points not Receiving Values

When the Interface connects to a PI Server, it authenticates to it via either a PI Mapping or a PI Trust. If the authentication results in a PI user or PI identity with limited privileges (e.g., pidemo), then the Interface will not be able to write data to PI points. So, you must modify the PI Mapping or PI Trust so that authentication results in a user with sufficient privileges to write data to PI points.

72

Data Backfilling

To backfill meter data, manually copy MultiSpeak data files to the DATA_DIRECTORY. You should first copy meter asset files before copying the other file types. This sequence allows the Interface to create the necessary PI points to hold the meter measurement data.

Offline Tool

QueuesClient.exe can be used to output the contents of *queue.dat files created by the PISCC framework. Usage:

To get the entire file contents:

QueuesClient.exe <Enter path to cache file>

To get only the header information of the file:

QueuesClient.exe <Enter path to cache file> -header

CacheClient.exe can be used to output the contents of the *Cache.dat and *PreCache.dat files. Usage:

CacheClient.exe <Enter path to cache file>

Online Tool

TablesClient.exe can be used to view the contents of the *.tbl file. This is an interactive tool that can be used only when PISCC is running.

CacheClient.exe can be used to output the contents of the *Cache.dat and *PreCache.dat files. Usage:

CacheClient.exe <Enter path to cache file>


This chapter provides information for the developer of the application that generates the MultiSpeak files that the Interface processes.

MultiSpeak File

XML Schema

The data files that the MSP Interface processes are XML files that adhere to the following schemas:

mspCPSM.xsd

mspGeometry.xsd

MultiSpeak.xsd

MultispeakRealTime41.xsd

xlinks.xsd

Please contact OSIsoft to obtain these files.

File Types

With respect to the Interface, the data files fall into three categories:

meter asset,

meter measurement reading, and

meter event.

The Interface requires these files to be named, respectively,

meterAsset*.xml,

measurementData*.xml, and

eventData*.xml.

Interface Functionality

The Interface parses data files in order to provide the following functionality

create a meter element in AF

create measurement elements in AF to represent meter measurement capabilities (e.g., energy, demand, and profile)

update a meter element’s ServicePointID attribute

write to a PI point to represent a meter’s operational state (e.g., Active, Inactive, Disconnected).


Appendix B: Developer Information

write to a PI point to represent a meter measurement (e.g., energy usage, demand usage, and interval data)

write to a PI point to represent a meter event (e.g., Last Gasp)

CIM

The Interface uses the CIM (Common Interface Model) IEC 61968-9 Annex C specification for the naming of meter measurements. It supports two CIM naming conventions.

Naming Convention #1

The first uses these attributes:



DirectionOfFlow

MeasurementCategory

TOURate

Phase

UOM

The Interface requires the name of a meter measurement to be a concatenation of the preceding CIM attributes. Specifically,

[MeasurementCategoryModifier]_[AccumulationBehavior]_[DirectionOfFlow]_[MeasurementCategory]_[TOURate]_[Phase]_([UOM])

Examples of measurements that follow this convention are:

Max_Indicating_Forward_Demand_TOURateA__(kW)_Summation_Forward_Energy_TOURateA__(kWh)_IntervalData_Forward_Energy___(kWh)

Naming Convention #2

The second naming convention uses these attributes:

TimeAttribute



DirectionOfFlow

MeasurementCategory

TOURate

Phase

UOM (including metric multiplier)


The Interface requires the name of a meter measurement to be a concatenation of the preceding CIM attributes. Specifically,

[TimeAttribute]_[MeasurementCategoryModifier]_[AccumulationBehavior]_[DirectionOfFlow]_[MeasurementCategory]_[TOURate]_[Phase]_([UOM])

Examples of measurements that follow this convention are:

Daily-Shifted_Max_Indicating_Forward_Demand_TOURateA__(kW)Daily-Shifted_Summation_Forward_Energy_TOURateA__(kWh)RESERVED_IntervalData_Forward_Energy___(kWh)

Naming Convention Verification

You can check the validity of a CIM measurement via Option 10 of the MSPTest program:

========================================================================Program to test compatibility of files for MSP InterfaceProgram options[1] Enable logging of file parsing to [c:\mspData\mspLibUse.out][10] Check validity of CIM name...[99] Exit this programChoose a task: 10Enter the CIM name to validate: Max_Indicating_Forward_Demand_TOURateA__(kW)Modifier = [Max]Accumulation Behavior = [Indicating]Direction = [Forward]Category = [Demand]TOU = [TOURateA]Phase = []UOM = [kW]

[Max_Indicating_Forward_Demand_TOURateA__(kW)] is a CIM name acceptable to the Interface

Interface Tasks

This section provides information on how you can cause the Interface to perform various tasks by providing it with various MultiSpeak files.

The plugin directory contains the example files that are mentioned subsequently. For example,

D:\Program Files\PIPC\Interfaces\PISCC\MSP

AF Meter Creation

To create a meter in AF, provide the Interface with a meter asset file (meterAsset*.xml). The file must contain the meter’s service delivery point (<serviceLocationID>) and at least one meter measurement (<readingTypeCode>). For example,

<MultiSpeakMessageHeader Version="4.1 osisoft=1.0"><Batch><MultiSpeak> <mspMeter objectID="734100"> <utilityInfo >


 <serviceLocationID>sdpId_0</serviceLocationID> </utilityInfo> </mspMeter> <readingType objectID="734100"> <readingTypeCode name="Max_Indicating_Forward_Demand_TOURateA__(kW)"> </readingTypeCode> </readingType></MultiSpeak></Batch></MultiSpeakMessageHeader>

You can quickly create many meter elements in AF by specifying multiple meters within a single meter asset file. The file meterAsset_dev_meterCreate.xml provides an example.

If you do not have a service delivery point for a meter, simply specify a placeholder for the <serviceLocationID> element. For example, the following indicates toBeDetermined as the service delivery point:

<mspMeter objectID="734100"> <utilityInfo >  <serviceLocationID>toBeDetermined</serviceLocationID> </utilityInfo> </mspMeter>

Meter Operational State

To update the PI point that represents a meter’s operational state, provide the Interface with a meter asset file (meterAsset*.xml). The <meterStatus> element indicates the operational state. For example,

<MultiSpeakMessageHeader Version="4.1 osisoft=1.0"><Batch><MultiSpeak> <mspMeter objectID="734100"> <meterStatusList> <meterStatus>Active</meterStatus> </meterStatusList> </mspMeter></MultiSpeak></Batch></MultiSpeakMessageHeader>

You will need to provide documentation to the end user that indicates the expected values for <meterStatus>. The end user will then be able to edit the MspOperationalMapping.CSV file.

You can quickly update many operational state values by specifying multiple meters within a single meter asset file. The file meterAsset_dev_OperState.xml provides an example.

Meter Creation with Operational State

You can combine meter creation with the updating of a meter’s operational state. Specify the <meterStatus>, <serviceLocationID>, and <readingTypeCode> elements

78

<MultiSpeakMessageHeader Version="4.1 osisoft=1.0"><Batch><MultiSpeak> <mspMeter objectID="734100"> <meterStatusList> <meterStatus>Active</meterStatus> </meterStatusList> <utilityInfo >  <serviceLocationID>sdpId_0</serviceLocationID> </utilityInfo> </mspMeter> <readingType objectID="734100"> <readingTypeCode name="Max_Indicating_Forward_Demand_TOURateA__(kW)"> </readingTypeCode> </readingType></MultiSpeak></Batch></MultiSpeakMessageHeader>

The file meterAsset_Sample.xml provides an example for multiple meter creation along with the updating of the meters’ operational state.

Measurement Value Storage into PI

To store a measurement value into PI, provide the Interface with a measurement reading file (measurementData*.xml). You indicate the measurement value via the <value>, <timeStamp>, and <readingType> elements. The <readingStatusCode>, which represents the status of an interval reading, is optional. The <timeStamp> must be in ISO 8601 format.

<MultiSpeakMessageHeader Version="4.1 osisoft=1.0"><Batch><MultiSpeak> <meterReading objectID="734100"> <readingValues> <readingValue> <value>18.883400</value> <timeStamp>2010-10-19T00:00:00-07:00</timeStamp> <readingTypeCode name="_IntervalData_Forward_Energy___(kWh)"> </readingTypeCode>

<readingStatusCode codeIndex="Reverse_Energy_Flow"> </readingStatusCode> </readingValue> </readingValues></MultiSpeak></Batch></MultiSpeakMessageHeader>

You will need to provide documentation to the end user that indicates the expected values for the codeIndex attribute of <readingStatusCode>. The end user will then be able to edit the MspStatusesMapping.CSV file.

The file measurementData_dev.xml provides an example for storing meter measurement values into PI.


Meter Event Storage into PI

To store a measurement event into PI, provide the Interface with an event file (eventData*.xml). You indicate the event via the time and codeString attributes of the <meterEvent> element. The time attribute must be in ISO 8601 format. For example,

<MultiSpeakMessageHeader Version="4.1 osisoft=1.0"><Batch><MultiSpeak> <meterEventList> <eventInstances> <eventInstance> <meterID objectID="734100"></meterID> <meterEvent time="2010-10-14T13:12:24-07:00" codeString="Last Gasp"> </meterEvent> </eventInstance> </eventInstances> </meterEventList></MultiSpeak></Batch></MultiSpeakMessageHeader>

You will need to provide documentation to the end user that indicates the expected values for the codeString attribute of <meterEvent>. The end user will then be able to edit the MspEventMapping.CSV file.

The file eventData_dev.xml provides an example for storing meter events into PI.

Tasks Sequence

Before it can store a meter measurement value into PI, the Interface must already have information about the meter and it measurement capabilities. Similarly, the Interface cannot store a meter event to a meter that it does not know about. So, before providing a measurement data file or an event file to the Interface, you must provide a meter asset file.

MDM Server

If you want the Interface to be able to invoke MDUS commands (ping, on-demand read, and remote connect/disconnect) you need to implement a MultiSpeak MDM Server. This web server must support the following:

GetMethods()

PingURL()

InitiateOutageDetectionEventRequest() – ping request

InitiateMeterReadingByMeterID() – on-demand read request

InitiateConnectDisconnect() – remote connect and disconnect request

The preceding methods are commands that the Interface sends to the MDM Server.

To return a result to the Interface, the MDM Server must invoke the following web services (which the Interface implements):

80

ODEventNotification() – ping result

ReadingChangedNotification() – on-demand read

CDStateChangedNotification() – remote connect and disconnect

Other Information

Version Compatibility

In the MultiSpeak data files, the Version attribute of the <MultiSpeakMessageHeader> element must indicate “4.1 osisoft=1.0”. That is,

<MultiSpeakMessageHeader Version="4.1 osisoft=1.0">… </MultiSpeakMessageHeader>

The 4.1 represents the version of the MultiSpeak schema files. The 1.0 is used internally by the Interface.

Application Information

You can indicate the version of your application via the <VendorApp> element. For example,

<MultiSpeakMessageHeader Version="4.1 osisoft=1.0"><VendorApp > <AppName>PI MDUS</AppName> <AppVersion>0.0.1.4</AppVersion> <Company>OSIsoft, LLC</Company> <Function>Test of Generic file-based MDUS</Function></VendorApp>… </MultiSpeakMessageHeader>


Source Registry Example

[PISCC]PI_SERVER=theInterfaceNode

PI_COLLECTIVE_00=NeptunePI_COLLECTIVE_01=Jupiter

[connector01]NAME=MultiSpeakCONNECTOR_STATE=NOT_LOADEDSTART_STATE=STARTPATH=D:\Program Files\PIPC\Interfaces\PISCC\MSP\PIMspPlugIn.dllHEAD_END=MSP

AF_SERVER=theAFServerAF_DATABASE=MSP

POINT_SOURCE=MSP


PISCC Section


PI_SERVER

(required)

Specify the Interface Node hostname

NAME

(optional)

The default value is PIsmartss.

PISCC uses this parameter internally. If this parameter does not exist, the Interface creates it with the default value.

DESCRIPTION

(optional)

The default value is Smart Connector Conductor.

PISCC uses this parameter internally. If this parameter does not exist, the Interface creates it with the default value.

PI_COLLECTIVE_XX

(at least one required)

The PI_COLLECTIVE_XX parameter, where XX indicates two digits ranging from 00 to 99, specifies the PI Server(s) to which the Interface writes data. For example,

PI_COLLECT_00=Neptune

PI_COLLECT_01=Jupiter

tells the Interface to write data to the PI Servers whose hostnames are Neptune and Jupiter.

FIND_COLLECTIVE_BEFORE_CREATE

(optional)

The default value is NO.

You should set this parameter to YES only if you wish to re-build the local meter database. A YES value tells the Interface to locate the correct PI_COLLECTIVE_XX before creating the PI points for a meter.


Appendix C: Source Registry Parameters

CONNECTOR01 Section

General


NAME

(required)

Use a name for the Interface; for example, MultiSpeak.

CONNECTOR_STATE

(required)

Use NOT_LOADED when you first start the Interface. During runtime, the Interface changes it to STARTED.

START_STATE

(required)

Use START.

PATH

(required)

Specify the fully qualified path to the PIMspPlugIn.dll file. For example,

D:\Program Files\PIPC\Interfaces\PISCC\MSP\PIMspPlugIn.dll

HEAD_END

(required)

Use a name for the head end; for example, MSP. The Interface uses this value when it generates names for AF elements and PI points.

AF


AF_SERVER

(required)

AF Server Node hostname

AF_DATABASE

(required)

AF meter database name

AF_ROOT_NODE

(optional)

AF root node of meter elements. If this parameter does not exist, the Interface uses the root of the meter database.

PI Points


POINT_SOURCE

(required)

PointSource attribute of PI points that Interface creates; for example, MSP

PI_DATA_WRITE_METHOD

(optional)

The default value is NOREPLACE.

A value of APPEND tells the Interface to write data to the PI Server such that there can be multiple events for a single timestamp.

A value of NOREPLACE tells the Interface not to write data to the PI Server if the particular timestamp already has an event.

A value of REPLACE results in the Interface replacing an existing event.

84


PRE_CREATED_TAGS

(optional)

The default value is NO.

If this parameter exists, the Interface does not create PI points on the PI Servers indicated in the PI_COLLECTIVE_XX parameters. Instead, the Interface uses existing points

that have the point source indicated by the POINT_SOURCE parameter, and

whose tagname begins with _res

Data Files


DATA_DIRECTORY

(required)

This parameter defines the directory that contains the data files which the Interface reads.

DATA_BACKUP_DIRECTORY

(optional)

This parameter defines the directory to which the Interface, after processing a meter file, writes a backup copy of the file.

The name of the backup file is the name of the original file plus ".backup". For example, "meterAsset_1.xml" becomes "meterAsset_1.xml.backup".

If this parameter does not exist, the Interface does not create backup files.

DATA_DIRECTORY_TEST

(required)

This parameter defines the directory that contains the data files which the MSPTest application reads.

NUM_PARSING_THREADS

(optional)

The default value is 3. The minimum is 1; the maximum is 10.

This parameter specifies the number of threads that the Interface allocates to parse meter files.

MDM Server


MSP_MDM_URL

(optional)

This parameter indicates the URL of the application that implements the MultiSpeak MDM Server.

The default value is <blank>.

MSP_USER

(optional)

This parameter specifies the username for the application that implements the MultiSpeak MDM Server.


MSP_PASSWORD

(optional)

This parameter specifies the password of the username for the application that implements the MultiSpeak MDM Server.


MSP_MDM_NOTIFY_URL

(optional)

This parameter specifies the URL of the application that receives responses from the MultiSpeak MDM Server. Its IP address must refer to the computer on which the Interface runs.



Debugging/Testing


MAX_METERS

(optional)

The default value is 0.

This parameter specifies the maximum number of meters the Interface should load.

TRACE_METERS

(optional)

The default value is FALSE.

A value of TRUE tells the Interface to log messages at various stages of its meter creation and PI point update process.

TRACE_SINGLE_METER

(optional)

The value of this parameter is a meter name. If present, the Interface logs messages only for the specified meter.

The parameter is in effect only if TRACE_METERS is TRUE.

TRACE_PARSE_ASSET_FILE

(optional)


A value of TRUE tells the Interface to log the results of meter asset file parsing to a file named mspLibUse.out.

TRACE_PARSE_MEAS_DATA_FILE

(optional)


A value of TRUE tells the Interface to log the results of meter measurement file parsing to a file named mspLibUse.out.

TRACE_PARSE_EVENT_FILE

(optional)


A value of TRUE tells the Interface to log the results of meter event file parsing to a file named mspLibUse.out.

Interface Actions


SYNC_METER_TABLE Acceptable values are CREATE_MISSING or YES.


A value of YES tells the Interface to synchronize meters with their PI points, but not to create any PI points that may be missing.

When the Interface finishes the synchronization, it writes the value of PROCESSED to this parameter.

Miscellaneous


DATA_HEALTH_CHECK_PERIOD_MINUTES

(optional)


This parameter tells the Interface how often to check whether it has processed a real-time meter event or a meter data file. It affects the Connector Health Status performance counter.

86


VALIDATED_MEASUREMENTXXX

(optional)

This parameter tells the Interface to create points for validated measurements. You need to change the XXX in the parameter name to a three digit numeral. For example,VALIDATED_MEASUREMENT001=


Dynamic Parameters

Most of the preceding parameter values are set at the time of interface startup. That is, if you want to change their values, you must stop and re-start the Interface.

However, the following parameters are dynamic. While the Interface is running, you can edit their values in the Source Registry. Within two minutes, the Interface re-reads the Source Registry and uses the new parameter values.

CONNECTOR01 Section


MAX_METERS

(optional)


This parameter specifies the maximum number of meters the Interface should load.

TRACE_METERS

(optional)


A value of TRUE tells the Interface to log messages at various stages of its meter creation and PI point update process.

TRACE_SINGLE_METER

(optional)

The value of this parameter is a meter name. If present, the Interface logs messages only for the specified meter.

The parameter is in effect only if TRACE_METERS is TRUE.

TRACE_PARSE_ASSET_FILE

(optional)


A value of TRUE tells the Interface to log the results of meter asset file parsing to a file named mspLibUse.out.

TRACE_PARSE_MEAS_DATA_FILE

(optional)


A value of TRUE tells the Interface to log the results of meter measurement file parsing to a file named mspLibUse.out.

TRACE_PARSE_EVENT_FILE

(optional)


A value of TRUE tells the Interface to log the results of meter event file parsing to a file named mspLibUse.out.



SYNC_METER_TABLE Acceptable values are CREATE_MISSING or YES.


A value of YES tells the Interface to synchronize meters with their PI points, but not to create any PI points that may be missing.

When the Interface finishes the synchronization, it writes the value of PROCESSED to this parameter.

88

You can read complete information about technical support options, and access all of the following resources at the OSIsoft Technical Support Web site:

http://techsupport.osisoft.com (http://techsupport.osisoft.com)

Before You Call or Write for Help

When you contact OSIsoft Technical Support, please provide:

Product name, version, and/or build numbers

Computer platform (CPU type, operating system, and version number)

The time that the difficulty started

The log file(s) at that time

Help Desk and Telephone Support

You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table below to find the most appropriate number for your area. Dialing any of these numbers will route your call into our global support queue to be answered by engineers stationed around the world.

Office Location Access Number Local Language Options

San Leandro, CA, USA 1 510 297 5828 English

Philadelphia, PA, USA 1 215 606 0705 English

Johnson City, TN, USA 1 423 610 3800 English

Montreal, QC, Canada 1 514 493 0663 English, French

Sao Paulo, Brazil 55 11 3053 5040 English, Portuguese

Frankfurt, Germany 49 6047 989 333 English, German

Manama, Bahrain 973 1758 4429 English, Arabic

Singapore 65 6391 1811

86 021 2327 8686

English, Mandarin

Mandarin

Perth, WA, Australia 61 8 9282 9220 English


Appendix D: Technical Support and Resources

http://techsupport.osisoft.com/

Support may be provided in languages other than English in certain centers (listed above) based on availability of attendants. If you select a local language option, we will make best efforts to connect you with an available Technical Support Engineer (TSE) with that language skill. If no local language TSE is available to assist you, you will be routed to the first available attendant.

If all available TSEs are busy assisting other customers when you call, you will be prompted to remain on the line to wait for the next available TSE or else leave a voicemail message. If you choose to leave a message, you will not lose your place in the queue. Your voicemail will be treated as a regular phone call and will be directed to the first TSE who becomes available.

If you are calling about an ongoing case, be sure to reference your case number when you call so we can connect you to the engineer currently assigned to your case. If that engineer is not available, another engineer will attempt to assist you.

Search Support

From the OSIsoft Technical Support Web site, click Search Support.

Quickly and easily search the OSIsoft Technical Support Web site’s Support Solutions, Documentation, and Support Bulletins using the advanced MS SharePoint search engine.

Email-based Technical Support

[email protected]

When contacting OSIsoft Technical Support by email, it is helpful to send the following information:

Description of issue: Short description of issue, symptoms, informational or error messages, history of issue

Log files: See the product documentation for information on obtaining logs pertinent to the situation.

Online Technical Support

From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.

Using OSIsoft’s Online Technical Support, you can:

Enter a new call directly into OSIsoft’s database (monitored 24 hours a day)

View or edit existing OSIsoft calls that you entered

View any of the calls entered by your organization or site, if enabled

See your licensed software and dates of your Service Reliance Program agreements


mailto:[email protected]

Remote Access

From the OSIsoft Technical Support Web site, click Contact Us > Remote Support Options.

OSIsoft Support Engineers may remotely access your server in order to provide hands-on troubleshooting and assistance. See the Remote Access page for details on the various methods you can use.

On-site Service

From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service Visit.

OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more information.

Knowledge Center

From the OSIsoft Technical Support Web site, click Knowledge Center.

The Knowledge Center provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. For these options, click Knowledge Center on the Technical Support Web site.

The Search feature allows you to search Support Solutions, Bulletins, Support Pages, Known Issues, Enhancements, and Documentation (including user manuals, release notes, and white papers).

System Manager Resources include tools and instructions that help you manage: Archive sizing, backup scripts, daily health checks, daylight saving time configuration, PI Server security, PI System sizing and configuration, PI trusts for Interface Nodes, and more.

Upgrades

From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.

You are eligible to download or order any available version of a product for which you have an active Service Reliance Program (SRP), formerly known as Tech Support Agreement (TSA). To verify or change your SRP status, contact your Sales Representative or Technical Support (http://techsupport.osisoft.com / ) for assistance.


http://techsupport.osisoft.com/

Date Author Comments

23-Nov-2010 E Tam v0.0.0.2; draft for beta test

14-Sep-2011 E Tam v0.0.0.5; include MDM Server information

4-Oct-2011 E Tam v0.1.0.0; for beta installation at customer site

17-Oct-2011 E Tam v0.1.1.1; support CIM time attribute enumeration

02-Mar-2012 T Williams V1.0.0.x; Updated version on cover page.

05-Mar-2012 MKelly V1.0.0.x; Revision A, Updated formatting, fixed headers and footers, rebuilt TOC.


Revision History

PI_MSP

Documents

program filespipcinterfacespisccmsppimspplugin

piservertheinterfacenode

program filespipcinterfacespisccmsp

afservertheafserver

including

party systems

pi buffer

parses multispeak