Pi MSP

OSIsoft MultiSpeak Interface
Version 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, Peoples 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: 2012 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
Table of Contents
Terminology..................................................................................................................................iv Introduction...................................................................................................................................1 Meters in AF and PI.......................................................................................................................9 Preliminary Installation Steps.....................................................................................................19 Digital State Sets.........................................................................................................................29 MultiSpeak File Confirmation......................................................................................................39 Windows Service.........................................................................................................................43 Pre-Created Tags.........................................................................................................................45 Interface Checklist.......................................................................................................................48 Interface Startup..........................................................................................................................51 Validated Measurements.............................................................................................................56 MDUS Commands........................................................................................................................58 Miscellaneous Features..............................................................................................................60 Appendix A: Troubleshooting.....................................................................................................65 Appendix B: Developer Information...........................................................................................70 Appendix C: Source Registry Parameters.................................................................................77 Appendix D: Technical Support and Resources........................................................................83 Revision History..........................................................................................................................86
iii
Terminology
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.
iv
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.
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\PISCC C:\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.
vi
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.
vii
Introduction
The MultiSpeak specification from NRECA (National Rural Electric Cooperative Association) consists of standards for describing electric meters and the data that they measure. OSIsofts 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
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.
OSIsoft MultiSpeak Interface 3
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.
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. OSIsofts Prerequisites kit needs to be additionally installed by the user.
Reference Manuals
OSIsoft
PI Server manuals PI AF manuals
Supported Features
Feature Interface Part Number * Platforms APS Connector Point Builder Utility ICU Control PI Point Types Sub-second Timestamps Sub-second Scan Classes * Automatically Incorporates PI Point Attribute Changes Exception Reporting Outputs from PI Inputs to PI: Scan-based / Unsolicited / Event Tags Supports Questionable Bit Support PI-AMI-OSI-MSP-x64 64-bit Windows Server operating systems No No No Float32, Digital, String No No Not Applicable No No Unsolicited No
Feature Supports Multi-character PointSource Maximum Point Count * Uses PI SDK * Uses 64-bit PI API Automatic Point Creation Automatic Asset Creation MDUS remote commands Ping On-demand register read Remote connect Remote disconnect PINet String Support * Source of Timestamps * History Recovery * UniInt-based * Disconnected Startup Failover Vendor Software Required on PI Interface Node / PINet Node Vendor Software Required on Foreign Device Vendor Hardware Required * Additional PI Software Included with Interface Device Point Types Serial-Based Interface
Support Yes Point count of PI Server Yes No Yes Yes Yes Yes Yes Yes Yes Not applicable MultiSpeak data file Yes No No None No No No Yes Not applicable 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.
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.
Meters in AF and PI
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? a meter in a metering system and an element in AF; and meter measurements and points on the PI Server.
This section provides answers to such questions. It describes the relationship between
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>.
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>
10
</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
11
HEAD_END=MSP
and the meter asset file has meters with the following objectIDs:
734100 734101 734102 734103
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.Event MSP_734100.Log MSP_734100.State MSP_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:
12
MeasurementCategoryModifier AccumulationBehavior DirectionOfFlow MeasurementCategory TOURate Phase UOM TimeAttribute MeasurementCategoryModifier AccumulationBehavior DirectionOfFlow MeasurementCategory TOURate Phase UOM (including metric multiplier)
The second uses these:
The Interface requires the name of a meter measurement to be a concatenation of the CIM attributes. Specifically,
[MeasurementCategoryModifier]_[AccumulationBehavior]_[DirectionOf Flow]_[MeasurementCategory]_[TOURate]_[Phase]_([UOM])
or
[TimeAttribute]_[MeasurementCategoryModifier]_[AccumulationBehavi or]_[DirectionOfFlow]_[MeasurementCategory]_[TOURate]_[Phase]_([U OM])
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 MeasurementCategoryModifier AccumulationBehavior DirectionOfFlow MeasurementCategory TOURate Phase UOM Description Not applicable Summation Forward Energy TOURateA Not applicable kWh
13
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:
Attribute MeasurementCategoryModifier AccumulationBehavior DirectionOfFlow MeasurementCategory TOURate Phase UOM Description Max Indicating Forward Demand TOURateA Not applicable 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:
Attribute MeasurementCategoryModifier AccumulationBehavior DirectionOfFlow MeasurementCategory TOURate Phase UOM Description Not applicable IntervalData Forward Energy Not applicable Not applicable 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>
14
<readingType objectID="734100"> <readingTypeCode name="_Summation_Forward_Energy_TOURateA__(kWh)"> </readingTypeCode> </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) _IntervalData_Forward_Energy___(kWh)
Also, note that the value of the objectID attribute refers to the particular meter ("734100").
15
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).Value MSP_734100.Input001._Summation_Forward_Energy_TOURateA__(kWh).Value MSP_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 2010-10-19T00:00:0007:00 2010-10-19T01:00:0007:00 Value 18.883 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>
17
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).ValidatedState MSP_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.Event MSP_734100.Log MSP_734100.State MSP_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).Value MSP_734100.Input001.Max_Indicating_Forward_Demand_TOURateA__(kW).Value MSP_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
Preliminary Installation Steps

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:
19
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]
20
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=Neptune PI_COLLECTIVE_01=Jupiter
Edit the Source Registry as necessary. 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
21
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 OSIsofts 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
Edit the Source Registry as necessary. 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) (this option appears under the Advanced button) Event Queue Page Size: 64 KB 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:
22
PI Archive Subsystem PI Backup Subsystem
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 theend if "%1" == "-base" (goto theend)
The preceding changes enable the RPC PI Server to start only the necessary PI services.
23
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.exe OSIsoft.PI.Configuration.dll OSIsoft.PI.Data.dll OSIsoft.PI.Net.dll OSIsoft.PISCC.Net.dll PISCC.ini BaseMeterAssets.xml ExternalRelations.xml AMIOperationalStates.CSV AMIStatusStates.CSV AMIEventStates.CSV authTest.exe mdaPut.exe tablesClient.exe AMITagCreator.exe CacheClient.exe QueuesClient.exe TablesClient.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.State MSP_734100.Input001.Status MSP_734100.Event
[PIHOME64]\Interfaces\PISCC\MSP
PIMSPPlugIn.dll AMIRPCHandler.dll MspMeter.xml MspEventMapping.csv MspOperationalMapping.csv MspStatusesMapping.csv PI_MSP.doc
These files are the plug-in portion of the MSP Interface.
[PIHOME64]\Interfaces\PISCC\MSP\MSPTest
MspTest.exe MspTest.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
25
C:\> authTest.exe thePIServer piadmin hello ============================================================================ Authenticating to [thePIServer] via Mappings createsession() failed; error=-10407 [-10407] No Access - Secure Object ============================================================================ ============================================================================ Authenticating to [thePIServer] via Trust createsession() 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 Mapping Trust PI user logon Result Failure Failure Failure Privileges None None 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 Trust createsession() succeeded ProtocolCredentialResult: COMPANY\User1 GetProtocolDetails: 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 MDA Version is v1.0.0.0 6-February-2012 Registering RPC Tables with Session Manager. ============================================================================ Authenticating to [RUSH] via Mappings createsession() succeeded ProtocolCredentialResult: OSI\orodriguez GetProtocolDetails: 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=theAFServer AF_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:
27
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 0 1 State Unkown Disconnected
29
Value 2 3 4 5 6 7 8 9 10 11 12 13 14 79
State Connected Installed Discovered Initialized Inactive Initialization_failed Maintenance Unreachable New Retired Investigate Initializing Reserved Reserved 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,Removed 2,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
30
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 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 79 State Unkown OK PulseOverFlow TestMode MeterDiag ReverseEnergy TimeChangeCheck PowerOutage PartialData DataCollection ShortInterval LongInterval TimeCheckHE MeterId ExternalMeter MalFormedData Syntactic NoFlow NonSteadyFlow MeterInput ZeroInterval Reserved Reserved 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
OSIsoft MultiSpeak Interface 31
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_ERROR 2,Overflow 3,INTERVAL_TEST_MODE 4,INTERVAL_RAM_FAILURE,INTERVAL_ROM_FAILURE 5, 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 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 State Unknown Cartridge_Alarm_Error Cartridge_Alarm_Frozen Cartridge_Alarm_Removed Cartridge_Configuration_Change-out Cartridge_Configuration_Installed Demand_Alarm_Demand reset Demand_Alarm_Demand reset fail Demand_Alarm_High limit Demand_Alarm_Mismatch Demand_Alarm_Overload Firmware_Alarm_Command error Firmware_Alarm_Data error Firmware_Alarm_Display error Firmware_Alarm_Input error Firmware_Alarm_Invalid Firmware_Alarm_Memory error Firmware_Alarm_Message error Firmware_Alarm_Option board error Firmware_Alarm_Program error Firmware_Alarm_Register error Firmware_Alarm_Reset Firmware_Alarm_Reset error Firmware_Alarm_Self-test error Firmware_Alarm management_Acknowledged Firmware_Alarm management_Activated Firmware_Alarm management_Disabled Firmware_Alarm management_Enabled Firmware_Alarm management_Set Firmware_Configuration_Alter option Firmware_Configuration_Alternate phone Firmware_Configuration_Configuration error Firmware_Configuration_Invalid parameter Firmware_Configuration_Invalid version Firmware_Configuration_Mismatch Firmware_Configuration_Not initialized Firmware_Configuration_Reprogrammed
33
Value 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74
State Firmware_Configuration_Setup disabled Firmware_Configuration_Setup enabled Firmware_Configuration_Synch disabled Firmware_Configuration_Synch enabled Firmware_Configuration_Synched Firmware_Configuration_Upgrade pending Firmware_Configuration_Watchdog Reset Firmware_Status check_Cold start Firmware_Status check_Download status Firmware_Status check_Health OK Firmware_Status check_Procedure invoked Firmware_Status check_Test call Firmware_Status check_Warm start Load control_Alarm_Abort Load control_Status check_Changed by condition Load control_Status check_Commanded change Load control_Status check_Momentary Load control_Status check_Prepayment change Load control_Status check_Scheduled Load control_Status check_Scheduled change Load control_Status check_Started Load control_Status check_Stopped Load profile_Alarm_Almost full Load profile_Alarm_Corrupt data Load profile_Alarm_Survey failed Memory_Alarm_Allocation error Memory_Alarm_Almost full Memory_Alarm_Data error Memory_Alarm_EPROM failure Memory_Alarm_Firmware failure Memory_Alarm_Mismatch Memory_Alarm_NVRAM failure Memory_Alarm_Overflow Memory_Alarm_RAM failure Memory_Alarm_RAM full Memory_Alarm_ROM failure Memory_Alarm_Table full Memory_Status check_Parameter change
34
Value 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
State Metrology_Alarm_Alarm cleared Metrology_Alarm_Cleared Metrology_Alarm_High limit Metrology_Alarm_Input error Metrology_Alarm_Invalid Metrology_Alarm_KYZ failure Metrology_Alarm_Limit exceeded Metrology_Alarm_Low limit Metrology_Alarm_Pulse failure Metrology_Alarm_Read Missing Metrology_Alarm_Register error Metrology_Calibration_Changed Metrology_Calibration_Deviated Metrology_Calibration_Set Metrology_Quality Flag_Calculated Metrology_Quality Flag_Default Metrology_Quality Flag_Estimated Metrology_Quality Flag_Initial read Metrology_Quality Flag_Last read Metrology_Quality Flag_Measured Metrology_Quality Flag_Preset Metrology_Quality Flag_Questionable Metrology_Quality Flag_Test mode Metrology_Read Type_On-request Metrology_Read Type_Scheduled Metrology_Read Type_Self read Metrology_Status check_Last read updated Metrology_Status check_List cleared Metrology_Status check_List pointers reset Metrology_Status check_List pointers updated Metrology_Status check_Pending table activation Metrology_Status check_Pending table clear Metrology_Status check_Table written Mode_Maint mode_Started Mode_Maint mode_Stopped Mode_Metering mode_Started Mode_Metering mode_Stopped Mode_Test mode_Started
35
Value 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
State Mode_Test mode_Stopped Power_Alarm_Power out Power_End alarm_Restored Power_Outage_Minutes Power_Outage_Momentary Power_Outage_Momentary events Power_Outage_Seconds Power_Outage_Sustained Power_Outage_Sustained events Power_Outage_Total events RCD switch_Alarm_Connect failed RCD switch_Alarm_Disconnect failed RCD switch_Status check_Changed RCD switch_Status check_Connected RCD switch_Status check_Disconnected Tamper_Alarm_Cover removed Tamper_Alarm_Encoder Tamper_Alarm_Magnetic Tamper_Alarm_Physical Tamper_Alarm_Reverse rotation Tamper_Alarm_Tamper detected Tamper_Alarm_Tilt Tariff_Alarm_Demand reset Tariff_Alarm_TOU Mismatch Tariff_Credit_Adjusted Tariff_Credit_Decreased Tariff_Credit_Emergency increase Tariff_Credit_Increased Tariff_Setting_Daily rate change Tariff_Setting_Program changed Tariff_Setting_Rate change Tariff_Setting_Tier changed Tariff_Setting_Week rate change Tariff_Status check_Demand reset Tariff_Status check_RTP activated Tariff_Status check_RTP deactivated Tariff_Status check_Special schedule Reserved
36
Value 199
State Reserved 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
37
AMIEventStates.CSV AMIOperationalStates AMIStatusStates AMIEventStates
define the digital state sets
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 line 1,Disconnected,Service_Disconnect,Removed 2,Active 3,Installed 4,Discovered # This is another comment line 5,Initialized 6,Inactive 7,Init_failed 8,Maintenance 9,Unreachable 10,New 11,Retired 12,Investigate 13,Initializing
38
MultiSpeak File Confirmation

The 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.
39
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
40
i=0 i=1 i=2
cim=Max_Indicating_Forward_Demand_TOURateA__(kW) cim=_Summation_Forward_Energy_TOURateA__(kWh) 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
t=2010-10-14T13:12:24-07:00 e=Last Gasp
For example,
Meter=734100
Output to File
41
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 Service
For 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
43
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,
44
Pre-Created Tags
The 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,
45
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 PIServer PointSource MeterCount NumberOfInputs
Description The PI server where you will be creating points The point source that the interface uses The number of meters for which you want to create points The number of inputs in a meter.
46
Parameter MeasurementsPerMeter_xxxxx
Description 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 Tag names include a sequencing number, use this key to set the starting number.
TagNumberStartsFrom
47
Interface Checklist
Before 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=theInterfaceNode PI_COLLECTIVE_00=Neptune PI_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_LOADED START_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=theAFServer AF_DATABASE=MSP
Verify that you have chosen a value for the PointSource attribute of the PI points that the Interface uses:
[connector01]
48
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=MultiSpeak CONNECTOR_STATE=NOT_LOADED START_STATE=START PATH=D:\Program Files\PIPC\Interfaces\PISCC\MSP\PIMspPlugIn.dll HEAD_END=MSP AF_SERVER=theAFServer AF_DATABASE=MSP POINT_SOURCE=MSP DATA_DIRECTORY=E:\MSPData
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
49
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.
50
Interface Startup
This 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=true MAX_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.ini PISCC.exe> Loaded Module CONNECTOR01 [D:\program files\pipc\interfaces\piscc\MSP\PIMspPlugIn.dll] PISCC.exe> MspPlugIn> Using DATA_DIRECTORY=C:\MSPData
51
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.Log MSP_734100.Event MSP_734100.State MSP_734100.Input001.Status MSP_734100.Input001._IntervalData_Forward_Energy___(kWh).Value MSP_734100.Input001._Summation_Forward_Energy_TOURateA__(kWh).Value MSP_734100.Input001.Max_Indicating_Forward_Demand_TOURateA__(kW).Val ue
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
52
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.out 2010_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.State 2010-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);
53
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,
54
[PISCC] PI_COLLECTIVE_00=Neptune PI_COLLECTIVE_00=Jupiter [CONNECTOR01] Name=MultiSpeak AF_DATABASE=MSP POINT_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
55
Validated Measurements
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._IntervalData_Forward_Energy___(kWh).Value 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))
56
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)
57
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. 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:7070 MSP_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
58
Measurements Determination 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
59
Miscellaneous Features
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.
60
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:
61
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 10-Jun-2010 15:00:00 Value 234.5
and the Interface sends the following event: Timestamp: 10-Jun-2010 15:00:00
62
Value: 310.5 the PI archive for this tag will then show only a single event for 10-Jun-2010 15:00:00:
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 10-Jun-2010 15:00:00 10-Jun-2010 15:00:00 Value 234.5 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

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:
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=NOREPLACE PI_DATA_WRITE_METHOD_EVENT=APPEND
63
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.
64
Appendix A: Troubleshooting
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\ADM c:\> 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=TRUE TRACE_SINGLE_METER=734100
To facilitate troubleshooting, the Interface checks every two minutes for changes to these Source Registry parameters: TRACE_METERS TRACE_SINGLE_METER
65
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:
PISCC.exe> MspPlugIn> TRACE_METERS set to True PISCC.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? 2. Did the Interface parse this file? 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.
66
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\measurementData_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.Input001._IntervalData_Forward_Energy___(kWh).Value 2010-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? 2. Did the Interface parse this file? 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. 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\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.Event 2010-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.
67
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.
68
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>
69
Appendix B: Developer Information

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. meterAsset*.xml, measurementData*.xml, and eventData*.xml.
The Interface requires these files to be named, respectively,
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 elements ServicePointID attribute write to a PI point to represent a meters operational state (e.g., Active, Inactive, Disconnected).
70
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:

MeasurementCategoryModifier AccumulationBehavior 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]_[DirectionOf Flow]_[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 MeasurementCategoryModifier AccumulationBehavior DirectionOfFlow MeasurementCategory TOURate Phase UOM (including metric multiplier)
71
The Interface requires the name of a meter measurement to be a concatenation of the preceding CIM attributes. Specifically,
[TimeAttribute]_[MeasurementCategoryModifier]_[AccumulationBehavi or]_[DirectionOfFlow]_[MeasurementCategory]_[TOURate]_[Phase]_([U OM])
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 Interface Program options [1] Enable logging of file parsing to [c:\mspData\mspLibUse.out] [10] Check validity of CIM name ... [99] Exit this program Choose a task: 10 Enter 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 meters 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 >
72
 <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 meters 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 meters operational state. Specify the <meterStatus>, <serviceLocationID>, and <readingTypeCode> elements
73
<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.
74
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):
75
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>
76
Appendix C: Source Registry Parameters

Source Registry Example
[PISCC] PI_SERVER=theInterfaceNode PI_COLLECTIVE_00=Neptune PI_COLLECTIVE_01=Jupiter [connector01] NAME=MultiSpeak CONNECTOR_STATE=NOT_LOADED START_STATE=START PATH=D:\Program Files\PIPC\Interfaces\PISCC\MSP\PIMspPlugIn.dll HEAD_END=MSP AF_SERVER=theAFServer AF_DATABASE=MSP POINT_SOURCE=MSP DATA_DIRECTORY=E:\MSPData
PISCC Section
Parameter PI_SERVER (required) NAME (optional) DESCRIPTION (optional) PI_COLLECTIVE_XX (at least one required) Description Specify the Interface Node hostname The default value is PIsmartss. PISCC uses this parameter internally. If this parameter does not exist, the Interface creates it with the default value. 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. 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. The default value is NO. You should set this parameter to YES only if you wish to rebuild 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.
FIND_COLLECTIVE_BEFORE_CREATE (optional)
77
CONNECTOR01 Section
General
Parameter NAME (required) CONNECTOR_STATE (required) START_STATE (required) PATH (required) HEAD_END (required) Description Use a name for the Interface; for example, MultiSpeak. Use NOT_LOADED when you first start the Interface. During runtime, the Interface changes it to STARTED. Use START. Specify the fully qualified path to the PIMspPlugIn.dll file. For example, D:\Program Files\PIPC\Interfaces\PISCC\MSP\PIMspPlugIn.dll 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
Parameter AF_SERVER (required) AF_DATABASE (required) AF_ROOT_NODE (optional) Description AF Server Node hostname AF meter database name AF root node of meter elements. If this parameter does not exist, the Interface uses the root of the meter database.
PI Points
Parameter POINT_SOURCE (required) PI_DATA_WRITE_METHOD (optional) Description PointSource attribute of PI points that Interface creates; for example, MSP 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.
78
Parameter PRE_CREATED_TAGS (optional)
Description 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
Parameter DATA_DIRECTORY (required) DATA_BACKUP_DIRECTORY (optional) Description This parameter defines the directory that contains the data files which the Interface reads. 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. This parameter defines the directory that contains the data files which the MSPTest application reads. 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.
DATA_DIRECTORY_TEST (required) NUM_PARSING_THREADS (optional)
MDM Server
Parameter MSP_MDM_URL (optional) MSP_USER (optional) MSP_PASSWORD (optional) Description This parameter indicates the URL of the application that implements the MultiSpeak MDM Server. The default value is <blank>. This parameter specifies the username for the application that implements the MultiSpeak MDM Server. The default value is <blank>. This parameter specifies the password of the username for the application that implements the MultiSpeak MDM Server. The default value is <blank>. 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. The default value is <blank>.
MSP_MDM_NOTIFY_URL (optional)
79
Debugging/Testing
Parameter MAX_METERS (optional) TRACE_METERS (optional) Description The default value is 0. This parameter specifies the maximum number of meters the Interface should load. 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. 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. The default value is FALSE. A value of TRUE tells the Interface to log the results of meter asset file parsing to a file named mspLibUse.out. The default value is FALSE. A value of TRUE tells the Interface to log the results of meter measurement file parsing to a file named mspLibUse.out. The default value is FALSE. A value of TRUE tells the Interface to log the results of meter event file parsing to a file named mspLibUse.out.
TRACE_SINGLE_METER (optional)
TRACE_PARSE_ASSET_FILE (optional) TRACE_PARSE_MEAS_DATA_FILE (optional)
TRACE_PARSE_EVENT_FILE (optional)
Interface Actions
Parameter SYNC_METER_TABLE Description Acceptable values are CREATE_MISSING or 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 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
Parameter DATA_HEALTH_CHECK_PERIOD_MINUTES (optional) Description The default value is 60. 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.
80
Parameter VALIDATED_MEASUREMENTXXX (optional)
Description 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= _IntervalData_Forward_Energy___(kWh)
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
Parameter MAX_METERS (optional) TRACE_METERS (optional) Description The default value is 0. This parameter specifies the maximum number of meters the Interface should load. 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. 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. The default value is FALSE. A value of TRUE tells the Interface to log the results of meter asset file parsing to a file named mspLibUse.out. The default value is FALSE. A value of TRUE tells the Interface to log the results of meter measurement file parsing to a file named mspLibUse.out. The default value is FALSE. A value of TRUE tells the Interface to log the results of meter event file parsing to a file named mspLibUse.out.
TRACE_SINGLE_METER (optional)
TRACE_PARSE_ASSET_FILE (optional) TRACE_PARSE_MEAS_DATA_FILE (optional)
TRACE_PARSE_EVENT_FILE (optional)
81
Parameter SYNC_METER_TABLE
Description Acceptable values are CREATE_MISSING or 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 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.
82
Appendix D: Technical Support and Resources

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 San Leandro, CA, USA Philadelphia, PA, USA Johnson City, TN, USA Montreal, QC, Canada Sao Paulo, Brazil Frankfurt, Germany Manama, Bahrain Singapore Perth, WA, Australia Access Number 1 510 297 5828 1 215 606 0705 1 423 610 3800 1 514 493 0663 55 11 3053 5040 49 6047 989 333 973 1758 4429 65 6391 1811 86 021 2327 8686 61 8 9282 9220 Local Language Options English English English English, French English, Portuguese English, German English, Arabic English, Mandarin Mandarin English
83
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 sites Support Solutions, Documentation, and Support Bulletins using the advanced MS SharePoint search engine.
Email-based Technical Support

techsupport@osisoft.com 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 OSIsofts Online Technical Support, you can:

Enter a new call directly into OSIsofts 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
84
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.
85
Revision History
Date 23-Nov-2010 14-Sep-2011 Author E Tam E Tam Comments v0.0.0.2; draft for beta test v0.0.0.5; include MDM Server information v0.1.0.0; for beta installation at customer site v0.1.1.1; support CIM time attribute enumeration
4-Oct-2011 17-Oct-2011 02-Mar-2012 05-Mar-2012
E Tam E Tam T Williams MKelly
V1.0.0.x; Updated version on cover page. V1.0.0.x; Revision A, Updated formatting, fixed headers and footers, rebuilt TOC.
86

Pi MSP

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Pi MSP

Hochgeladen von

Copyright:

Verfügbare Formate

OSIsoft MultiSpeak Interface

Version 1.0.0.x Revision A

OSIsoft MultiSpeak Interface

OSIsoft MultiSpeak Interface

OSIsoft MultiSpeak Interface

OSIsoft MultiSpeak Interface

OSIsoft MultiSpeak Interface

Automated Meter Reading Solution

PI Head End Interfaces

OSIsoft MultiSpeak Interface

* See the paragraphs below for further explanation.

Automatically Incorporates PI Point Attribute Changes

OSIsoft MultiSpeak Interface

About This Manual

MultiSpeak File Format

OSIsoft MultiSpeak Interface

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

Overview of Meter Data Files

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

Meter Unique Identifier

OSIsoft MultiSpeak Interface

the Interface builds these AF meter elements:

The second uses these:

OSIsoft MultiSpeak Interface

The Interface expects the following measurement name:

The Interface expects the following measurement name:

The Interface expects the following measurement name:

Meter Asset File

OSIsoft MultiSpeak Interface

AF Elements and PI Points

The corresponding PI points that the Interface builds are named

Meter Measurement Values

while the latter has

OSIsoft MultiSpeak Interface

Archive Sizing Issues

Initial Archive File Size

Preliminary Installation Steps

The following picture shows the configuration:

OSIsoft MultiSpeak Interface

Source Registry Entries

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

Prerequisites and Supplementary Software

Edit the Source Registry as necessary.

OSIsoft MultiSpeak Interface

PI Archive Subsystem PI Backup Subsystem

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

OSIsoft MultiSpeak Interface

Interface Installation Files

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

The usage syntax for authTest is

OSIsoft MultiSpeak Interface

The preceding authentication results indicate:

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

OSIsoft MultiSpeak Interface

Exit from PI System Explorer.

Digital State Sets

OSIsoft MultiSpeak Interface

OSIsoft MultiSpeak Interface

OSIsoft MultiSpeak Interface

State Reserved Reserved

OSIsoft MultiSpeak Interface

AMIEventStates.CSV AMIOperationalStates AMIStatusStates AMIEventStates

define the digital state sets