PI AMI Interface for Itron OpenWay Collection Engine Version 1.6.9.x
OSIsoft, LLC 777 Davis St., Suite 250 San Leandro, CA 94577 USA Tel: (01) 510-297-5800 Fax: (01) 510-357-8136 Web: http://www.osisoft.com OSIsoft Australia Perth, Australia OSIsoft Europe GmbH Frankfurt, Germany OSIsoft Asia Pte Ltd. Singapore OSIsoft Canada ULC Montreal & Calgary, Canada OSIsoft, LLC Representative Office Shanghai, People s Republic of China OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil OSIsoft France EURL Paris, France PI AMI Interface for Itron OpenWay Collection Engine Copyright: 2015 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 Coresight, PI Data Services, PI Event Frames, 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: 04/2015
Table of Contents Terminology... v Introduction... 1 AMI... 1 PI AMI Interfaces... 1 OpenWay Interface... 2 PIItronOWListener... 3 Software Requirements... 3 Reference Manuals... 3 Supported Operating Systems... 3 Supported Features... 4 Connection Diagram... 6 About This Manual... 6 Meters in AF and PI... 9 AF Elements... 9 AF Element Template... 12 Meter Measurements and Attributes... 15 Summary... 26 Installation Steps... 29 OpenWay Web Service Endpoints... 29 Meter Attributes and Measurements... 30 PI Environment... 40 Interface Installation Files... 42 PI Environment Configuration... 43 Files Editing... 46 Digital State Sets... 55 Profile Status Tags... 55 Meter Event Tag... 56 Meter Exception Tag... 58 Windows Service... 59 Service Commands... 59 Service Account... 60 PIItronOWListener... 61 Startup Command File... 61 Basic Source Registry Parameters... 61 Advanced Source Registry Parameters... 62 PI AMI Interface for Itron OpenWay Collection Engine iii
Table of Contents Windows Service Commands... 62 Interface Checklist... 65 Meter Attributes... 65 Interface Configuration Files... 66 Source Registry... 67 PI Archive Size... 69 Pre-Created Tags... 71 Interface Startup... 73 Minimal Startup... 73 Normal Startup... 74 Miscellaneous Features... 77 Unknown Meter Files... 77 Performance Counters... 78 Data Write Method... 79 Add or Remove Meter Measurements and Attributes... 81 Rename Existing Meter Measurements and Attributes... 92 Unknown Meter Files... 98 Appendix A: Troubleshooting... 99 Message Log File... 99 Error Numbers... 99 Utilities... 99 Appendix B: Source Registry Parameters... 103 Source Registry Example... 103 PISCC Section... 103 CONNECTOR00 Section... 104 Appendix C: Technical Support and Resources... 111 Revision History... 115 iv
Terminology PI Server naming conventions OSIsoft is revising terminology to reflect the growth of PI Server from its original singleserver architecture. The term PI Data Archive means the component that stores time-series data (formerly called PI Server). The term PI Server means the entire suite of PI System server products, and includes both PI Data Archive and PI Asset Framework. This document uses the revised 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 Data Archive 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 AMI 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 Data Archive data, configured data, or data from other systems. PI AMI 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 Data Archive is offline, and forward the data to all the PI Data Archives 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 mechanism is typically achieved using PI Buffer Subsystem (PIBufss) program. However, the PI AMI Interface for Itron OpenWay Collection Engine does not use PIBufss. Instead, it uses components of AFSDK for temporarily storing data and sending these data to PI Data Archives. The buffers are located at \ProgramData\OSIsoft\MDA\Buffer\ A separate folder is created for each member of the collective: \ProgramData\OSIsoft\Buffer\<collective member name> PI AMI Interface for Itron OpenWay Collection Engine v
Terminology Also, separate folders are created for different data types. The data are stored in Store_xx.dat files. For example, \ProgramData\OSIsoft\Buffer\<collective member name>\string\store_0.dat 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 AMI Interface; for example, the PI AMI Interface for Itron OpenWay Collection Engine. MDUS MDUS stands for Meter Data Unification and Synchronization system. OSIsoft PI System and partner products connect various metering head end system to business systems such as SAP Industry Solution for Utilities. MDUS Command An MDUS command is an instruction sent to a PI AMI 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 Data Archive. PI Interfaces use the PI API to send data to the PI Buffer Subsystem, which in turn writes data to the PI Data Archive. The PI API exists in 32-bit and 64-bit versions. Unlike many OSIsoft products, the PI AMI Interface for Itron OpenWay Collection Engine does not require the PI-API. PI Collective A PI Collective consists of two or more replicated PI Data Archives that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Data Archive in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI client applications. 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. vi
AMI 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 AMI interfaces reside in a subdirectory of the Interfaces directory under PIHOME64. For example, files for the PI AMI Interface for Itron OpenWay Collection Engine are in C:\Program Files\PIPC\Interfaces\PISCC C:\Program Files\PIPC\Interfaces\PISCC\ItronOW 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 AMI Interfaces do not invoke the standard PI SDK routines that are distributed with the PI SDK installation kit. Instead, PI AMI Interfaces make low level function calls to create and edit PI points. PI Data Archive Node A PI Data Archive Node is a computer on which PI Data Archive programs are installed. Two or more PI Data Archive 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 Data Archives and PI Collectives. A single copy of PI SMT manages multiple PI Data Archives and PI Collectives. PI SMT runs on either a PI Data Archive Node or an Interface Node. Point The PI point is the basic building block for controlling data flow to and from the PI Data Archive. For a given timestamp, a PI point holds a single value. For PI AMI Interfaces, a PI point corresponds to a particular measurement on a meter. For example, for a meter identified as 73421 and programmed to measure interval data, the corresponding PI point could be HE_73421.60min_delivered_kWh 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. PI AMI Interface for Itron OpenWay Collection Engine vii
Terminology For PI AMI Interfaces, you configure the tagname of a PI point via a measurements configuration mapping file. Windows Event Log The PI AMI Interface for Itron OpenWay Collection Engine logs information to the Windows Event Log (Application). viii
Introduction OSIsoft's PI AMI Interface for Itron OpenWay Collection Engine receives meter data from Itron's OpenWay Collection Engine head end system and stores the information into PI Data Archives and PI AF. This interface is part of OSIsoft's AMI (Advanced Metering Infrastructure) product suite. The next few paragraphs provide an overview of AMI, OSIsoft's AMI solution, and PI AMI 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). PI AMI Interfaces Improved Features PI AMI Interfaces contain features that most OSIsoft interfaces do not. These features include the ability to create PI points automatically and to create AF assets automatically. 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 AMI 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 PI AMI Interface for Itron OpenWay Collection Engine 1
Introduction AMI Interfaces provide this functionality intrinsically; a separate synchronization program is unnecessary. The majority of other interfaces do not utilize a foreign system's asset information. A PI AMI 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 AMI Interfaces are dynamic link library files that are loaded by the PI Interface Smart Conductor Container executable (PISCC.exe). For example, the filename for the PI AMI Interface for Itron OpenWay Collection Engine is PIItronOWPlugIn.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 AMI 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 Smart Conductor Container executable (PISCC.exe). Pre-created Tags A feature of PI AMI Interfaces is the use of pre-created tags. This feature means that the Interface creates ahead of time the PI points that represent meter measurements. When the Interface receives meter configuration information, it will simply rename these existing PI points. The use of pre-created tags allows a PI AMI Interface to minimize the time required to generate meter elements and their associated PI points. OpenWay Interface The remainder of this document describes the PI AMI Interface for Itron OpenWay Collection Engine, or OpenWay Interface for brevity. The Itron OpenWay Interface performs the following functions: it creates AF meter elements to represent meters that are in the OpenWay Head End; within these meter elements, it creates AF attributes to represent meter measurements (such as interval data and register data); it parses a MultiSpeak compliant file to fill in the attributes of these meter elements; it receives meter interval usage data and stores these data into PI points; and it receives meter register data and stores these data into PI points. 2
PIItronOWListener PIItronOWListener The OpenWay Collection engine sends meter data and meter events via the DataArrived web service message. It sends meter exceptions via the ExceptionsArrived web service message. OSIsoft's PIItronOWListener application receives these messages and creates XML data files. The OpenWay Interface then parses these files and updates the PI Data Archive. Like the OpenWay Interface, the PIItronOWListener program runs as a Windows service. A later section of this manual details the parameters for installing, starting, and stopping PIItronOWListener as a Windows service. Software Requirements The Itron OpenWay Interface is a 64-bit application that runs on a Microsoft Windows Server operating system (e.g., Windows Server 2012) on x64. (IA64 is not supported.) The Interface sends data to the PI Data Archive and AF Server. The versions required, are, respectively, PI Data Archive 2012 (v3.4.390.16) AF Server 2014 (v2.6.0). The Interface Node on which the Interface runs must also have the following OSIsoft components: AF Client 2014 (v2.6.0). The installation kit ItronOW_XXX.exe installs the software needed on the Interface node. Prior to running the ItronOW_XXX.exe installation kit, the Windows.NET Framework 3.5 and / or.net Framework 4.5 features need to be enabled. Reference Manuals OSIsoft PI Data Archive manuals PI AF manuals Itron OpenWay Collection Engine Web Services Reference Guide Supported Operating Systems 64 bit versions of: Windows Server 2008 R2 SP1 and above, Windows Server 2012, Windows Server 2012 R2, Windows 7 SP1 and above, Windows 8 and 8.1. The interface is designed to run on the above mentioned Microsoft Windows operating systems and their associated service packs. Please contact OSIsoft Technical Support for more information. PI AMI Interface for Itron OpenWay Collection Engine 3
Introduction Supported Features Feature Interface Part Number 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 Supports Multi-character PointSource Maximum Point Count Support PI-AMI-IT-OW-X64 No No No Float32, Digital, String No No Not Applicable No No Unsolicited No Yes Point count of PI Data Archive * Uses PI SDK Yes * Uses 64-bit PI API No Automatic Point Creation Automatic Asset Creation MDUS remote commands Ping On-demand register read Remote connect Remote disconnect PINet String Support Yes Yes No No No No No Not applicable * Source of Timestamps OpenWay * History Recovery Yes * UniInt-based No * Disconnected Startup Yes 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 None No No No Yes 4
Supported Features Feature Device Point Types Serial-Based Interface Support Not applicable No * See the paragraphs below for further explanation. 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. 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 Data Archive library calls to create and edit PI points and to create and edit digital state sets. Uses 64-bit PI API The Interface does not use the PI-API. Source of Timestamps OpenWay provides the source of timestamps for the data that the Interface writes to the PI Data Archive. History Recovery OpenWay sends historical data to the PIItronOWListener program. This program in turn generates data files for the Interface for processing. If errors result in the Interface failing to send data to the PI Data Archive, you can ask OpenWay to re-export the data to PIItronOWListener (and hence the Interface) for backfilling. UniInt-based UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoftdeveloped template used by developers, and is integrated into many interfaces. This Interface does not use UniInt. Disconnected Start-Up The Itron OpenWay Interface supports disconnected start-up. Disconnected start-up is the ability of an interface to start up and collect data without a connection to the PI Data Archive. PI AMI Interface for Itron OpenWay Collection Engine 5
Introduction Connection Diagram Diagram of the Itron OpenWay Interface and its associated software components: PI Data Archive PI AF Server Low-level PI Server calls AF SDK PIItronOWListener OpenWay Interface using components of AFSDK functions Interface Node Itron OpenWay Collection Engine 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. So, instead of initially delving into the Interface's technical details and operational principles, this document first explains how a meter in OpenWay is related to an AF element and to PI points. 6
About This Manual Subsequent chapters then describe prerequisite steps that you must take before you can start the Interface. These steps include setting up the PI Data Archive environment and the AF meter database. The Interface Checklist chapter summarizes these steps. PI AMI Interface for Itron OpenWay Collection Engine 7
Meters in AF and PI As a user of the Itron OpenWay Interface, you may naturally ask yourself How does a meter in OpenWay appear in PI AF and the PI Data Archive? What measurements in a meter are supported in PI AF and the PI Data Archive? How do PI AF and the PI Data Archive represent data that a meter collects? This section provides answers to such questions. It describes the relationship between a meter in OpenWay and an element in AF; and meter measurements and points on the PI Data Archive. AF Elements Meter Identifier Each meter in the OpenWay Collection Engine is represented by an ESN (Electronic Serial Number). For example, 2.16.840.1.114416.0.48073113 The portion of this ESN after the rightmost dot is the meter identifier. For the preceding example, the meter identifier is 48073113 This meter identifier is also known as the short serial number. The Interface uses this attribute to generate the name of elements in AF, and the names of points on the PI Data Archive 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 identifier. For example, if you have in the Source Registry HEAD_END=OW and there are meters in OpenWay with the following ESNs: 2.16.840.1.114416.0.4001827 2.16.840.1.114416.0.4001828 the Interface builds these AF meter elements: PI AMI Interface for Itron OpenWay Collection Engine 9
Meters in AF and PI (The Interface stores configuration information in the ExternalRelationsConfigRec element.) The Interface also stores into AF information about a meter's application group and configuration group. For example, the following screenshot shows PI System Explorer displaying the value of these attributes for the meter whose meter id is 4001827: Meter Attributes via MultiSpeak File The OpenWay Collection Engine does not contain information about meter attributes such as transformer, substation, and feeder. However, the Interface is capable of storing these attributes into AF. To do so, it parses a MultiSpeak compliant meter asset file. A later chapter in this manual describes this process. If you choose utilize this feature, PI System Explorer should display the values for these attributes as shown. For example, 10
AF Elements Head End ID Omission If you do not want meter element names to contain a head end identifier, set the Source Registry parameter OMIT_HEAD_END_IN_NAME to Yes. That is, OMIT_HEAD_END_IN_NAME=Yes Consequently, the meter elements in AF will be named 4001827 4001828 instead of OW_4001827 OW_4001828 Meter Retrieval from OpenWay How does the Interface know for which meters to create AF elements? The answer is that it asks for meters from OpenWay based on Application Group or Configuration Group specifications that you provide via the USE_APPLICATION_GROUP_QUERY_METERS parameter in the piscc.ini file. Application Group can be set in the piscc.ini file. Configuration Group is set in the MeasurementMappings.xml file. For example, if you have in the Source Registry APPLICATION_GROUPS_00=All_Meters_3.9 APPLICATION_GROUPS_01=VoltageMonitoring the Interface retrieves all the meters in OpenWay that belong to these two Application Groups. PI AMI Interface for Itron OpenWay Collection Engine 11
Meters in AF and PI AF Element Template When the Interface creates an AF meter element, it makes use of an element template. For example, the following screenshot shows that the preceding OW_4001827 element uses a template named CommercialMeters: Attributes An element template stores definitions for meter configuration attributes such as transformer and substation. An element template also stores measurement attributes such as average voltage and energy. (Please note that a meter measurement attribute is a PI point reference.) The following screenshot indicates five measurement attributes seven configuration attributes for the element template named CommercialMeters. 12
AF Element Template User Definitions You can add, remove, or rename the configuration attributes (e.g., Latitude and Longitude) of this element template. You can add or remove measurement attributes to reflect the capabilities of the meters represented by this template. For example, you may wish to add a measurement that indicates the commercial meters' maximum total demand. Your CommercialMeters template will then look like: PI AMI Interface for Itron OpenWay Collection Engine 13
Meters in AF and PI After you run the Interface, you should not change the name of a measurement attribute. The reason is that these attributes are PI point references. If you must change the name of a measurement attribute, the Interface supports this feature. PI Points For each attribute that is a measurement attribute/pi point reference, the Interface creates a corresponding PI point. The name of this PI point comes from the name of the AF meter element along with the name of the attribute. For the preceding examples, the Interface creates PI points named: OW_4001827.RegisterVoltagePhaseA OW_4001827.StatusForVh(a) OW_4001827.VoltagePhaseA OW_4001827.VoltagePhaseB OW_4001827.VoltagePhaseC OW_4001827.Max_Total_Demand 14
Meter Measurements and Attributes Meter Measurements and Attributes Meter Data Files You may wonder where the Interface obtains the values for meter measurements such as OW_4001827.RegisterVoltagePhaseA OW_4001827.StatusForVh(a) OW_4001827.VoltagePhaseA OW_4001827.VoltagePhaseB OW_4001827.VoltagePhaseC OW_4001827.Max_Total_Demand The answer is that the Interface parses meter data files. These files, named XXX.xml, are created by the PIItronOWListener component of the Interface. When the PIItronOWListener application receives DataArrived web service messages from the OpenWay Collection Engine, it creates XXX.xml data files. The Interface parses these files to write data to PI points. Subscribing for Meter Data How does OpenWay know to send DataArrived messages to PIItronOWListener? The answer is that OpenWay must be configured so that PIItronOWListener is a data subscriber. You can manually perform this configuration yourself. Or, you can set up the Interface so that it subscribes PIItronOWListener at startup. A subsequent chapter of this manual describes this procedure. Interrogating for Meter Data The frequency at which OpenWay sends DataArrived messages is controlled by a polling mechanism, or in OpenWay terminology, an interrogation. You have the option of either performing the interrogation yourself, or configuring the Interface to interrogate OpenWay periodically. A subsequent chapter of this manual describes these procedures. Load Profile Values and Register Values A DataArrived message from OpenWay can contain both load profile data and register data. For example, PI AMI Interface for Itron OpenWay Collection Engine 15
Meters in AF and PI Here is an example of the XML representation: <DataArrived> <input> <ReadDataCollection> <ReadData> <LoadProfileChannels>... </LoadProfileChannels> <RegisterValues>... <RegisterValue> <Quantity>ins V(a)</Quantity> <Value>258.9</Value> <Timestamp>2013-08-014T22:08:08Z</Timestamp> </RegisterValue> </RegisterValues> </ReadData> </ReadDataCollection> </input> </DataArrived> 16
Meter Measurements and Attributes How does the Interface match the values in a DataArrived message with a particular PI point? For example, for the preceding file excerpt, how does the Interface know that OW_4001827.RegisterVoltagePhaseA should receive the value 258.9? The answer is that you must supply the Interface with such knowledge. You do so by editing the Interface's measurements configuration file. Measurements Configuration File At startup, the Interface reads the file named MeasurementMappings.XML. This measurements configuration file provides necessary information about the relationship between the Interface's internal parameters and parameters that you define. This file is located in the same directory as PISCC.exe. You are responsible for editing this MeasurementMappings.XML file. Here is an excerpt of an example file: <Mappings> <OSIsoft:MeterTemplate> <OSIsoft:MappedAFTemplate>CommercialMeters</OSIsoft:MappedAFTemplate > <OSIsoft:MeterType>OWMeterA</OSIsoft:MeterType > <OSIsoft:TemplateIdentifier>PG 101</OSIsoft:TemplateIdentifier> <OSIsoft:TemplateIdentifier>PG 102</OSIsoft:TemplateIdentifier> <OSIsoft:Measurement> <OSIsoft:AFValue>RegisterVoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT00</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:RegisterValue>ins V(a)</OSIsoft:RegisterValue> </OSIsoft:OW> </OSIsoft:Measurement> <OSIsoft:Measurement> <OSIsoft:AFValue>VoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT01</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfileChannel> <OSIsoft:ApplyPulseMultiplier>Yes</OSIsoft:ApplyPulseMultiplier> </OSIsoft:OW> </OSIsoft:Measurement> </OSIsoft:MeterTemplate> </Mappings> PI AMI Interface for Itron OpenWay Collection Engine 17
Meters in AF and PI AF Element Template Before the Interface creates a meter in AF, it first creates a meter record in its external relations table (also known as the local meter database). The Interface creates this meter record based on one of the following internal record types: OWMeterA OWMeterB OWMeterC OWMeterD OWMeterE OWMeterF OWMeterG OWMeterH OWMeterI OWMeterJ OWMeterK OWMeterL Recall that when the Interface creates an AF meter element, it makes use of an element template such as CommercialMeter. Accordingly, the lines <Mappings> <OSIsoft:MeterTemplate> <OSIsoft:MappedAFTemplate>CommercialMeters</OSIsoft:MappedAFTemplate > <OSIsoft:MeterType>OWMeterA</OSIsoft:MeterType> tell the Interface to use internal record type OWMeterA when creating meters that use the template CommercialMeter. Template Identifier Configuration Group How does the Interface know to apply the CommercialMeters template for a particular meter? The answer is that each meter in OpenWay is a member of a configuration group. The measurements configuration file specifies the relationship between configuration groups and an AF template. For example, <OSIsoft:MappedAFTemplate>CommercialMeters</OSIsoft:MappedAFTemplate > <OSIsoft:MeterType>OWMeterA</OSIsoft:MeterType> <OSIsoft:TemplateIdentifier>PG 101<OSIsoft:TemplateIdentifier> 18
Meter Measurements and Attributes <OSIsoft:TemplateIdentifier>PG 102<OSIsoft:TemplateIdentifier> The preceding text indicates that for meters whose configuration group is PG 101 or PG 102, the Interface will use internal record type OWMeterA and the CommercialMeters template. Single Meter Template If you want all your meters to use a common AF template, you must specify all your configuration group values in the measurements configuration file. For example, <OSIsoft:MappedAFTemplate>CommercialMeters</OSIsoft:MappedAFTemplate > <OSIsoft:MeterType>OWMeterA</OSIsoft:MeterType> <OSIsoft:TemplateIdentifier>PG 101<OSIsoft:TemplateIdentifier> <OSIsoft:TemplateIdentifier>PG 102<OSIsoft:TemplateIdentifier>... <OSIsoft:TemplateIdentifier>PG 199<OSIsoft:TemplateIdentifier> Measurement Data For a single meter, the Interface supports reading up to 20 float measurements and 10 integer measurements. The former are known internally as MEASFLT00 MEASFLT01 MEASFLT19 The latter are known internally as MEASINT00 MEASINT01 MEASINT09 Lines in MeasurementMappings.XML such as <OSIsoft:Measurement> <OSIsoft:AFValue>RegisterVoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT00</OSIsoft:PlugIn> </OSIsoft:Measurement> <OSIsoft:Measurement> <OSIsoft:AFValue>VoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT01</OSIsoft:PlugIn> </OSIsoft:Measurement> PI AMI Interface for Itron OpenWay Collection Engine 19
Meters in AF and PI tell the Interface the relationship between an AF measurement attribute (e.g., VoltagePhaseA) and one of its internal measurements (e.g., MEASFLT01). Register Values Within a DataArrived message, register values appear in <RegisterValues>. For example, <DataArrived> <input> <ReadDataCollection> <ReadData> <RegisterValues> <RegisterValue> <Quantity>ins V(a)</Quantity> <Value>258.9</Value> <Timestamp>2013-08-014T22:08:08Z</Timestamp> </RegisterValue> </RegisterValues> </ReadData> 20
Meter Measurements and Attributes </ReadDataCollection> </input> </DataArrived> In the measurements configuration file, you need to put information within <OSIsoft:RegisterValue> to tell the Interface how to obtain the register value data within OpenWay's DataArrived message. For example, <OSIsoft:Measurement> <OSIsoft:AFValue>RegisterVoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT00</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:RegisterValue>ins V(a)</OSIsoft:RegisterValue> </OSIsoft:OW> </OSIsoft:Measurement> The preceding example indicates that the measurement RegisterVoltagePhaseA should receive the value within <RegisterValue> whose <Quantity> matches "ins V(a)". That is, Load Profile Channels and Interval Values Within a DataArrived message, interval values appear in <IntervalValues>. For example, PI AMI Interface for Itron OpenWay Collection Engine 21
Meters in AF and PI The actual interval values are in the <ChannelValue> of each <IntervalValue> within the <IntervalValues>. For example, <DataArrived> <input> <ReadDataCollection> <ReadData> <LoadProfileChannels> <LoadProfileChannel> <IntervalLength>15</IntervalLength> <PulseMultiplier>0.025</PulseMultiplier> <Quantity>Vh(a)</Quantity> <IntervalValues> <IntervalValue> <ChannelValue>21.625</ChannelValue> </IntervalValue> <IntervalValue> <ChannelValue>24.625</ChannelValue> </IntervalValue>... </IntervalValues> </LoadProfileChannel> </LoadProfileChannels> </ReadData> </ReadDataCollection> </input> 22
Meter Measurements and Attributes </DataArrived> In the measurements configuration file, you need to put information within <OSIsoft:LoadProfileChannel> to tell the Interface how to obtain load profile data within OpenWay's DataArrived message. For example, <OSIsoft:Measurement> <OSIsoft:AFValue>VoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT01</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfileChannel> <OSIsoft:ApplyPulseMultiplier>Yes</OSIsoft:ApplyPulseMultiplier> </OSIsoft:OW> </OSIsoft:Measurement> The preceding example indicates that the measurement VoltagePhaseA should receive the values within <LoadProfileChannel> whose <Quantity> matches "Vh(a)". That is, Meter Interval Length The preceding screenshots for <DataArrived> show that a meter's interval length is indicated within the <IntervalLength> element of <LoadProfileChannel>. If you want the Interface to store this interval length value into a PI point, you must put the appropriate entries into the measurements configuration file. That is, <OSIsoft:Measurement> <OSIsoft:AFValue>IntervalLength</OSIsoft:AFValue> <OSIsoft:PlugIn>INTERVALLENGTHTAG</OSIsoft:PlugIn> </OSIsoft:Measurement> PI AMI Interface for Itron OpenWay Collection Engine 23
Meters in AF and PI Meter Pulse Multiplier The preceding screenshots for <DataArrived> show that a meter's pulse multiplier is indicated with the <PulseMultiplier> element of <LoadProfileChannel>. If you want the Interface to store this pulse multiplier value into a PI point, you must put the appropriate entries into the measurements configuration file. That is, <OSIsoft:Measurement> <OSIsoft:AFValue>PulseMultiplier</OSIsoft:AFValue> <OSIsoft:PlugIn>PULSEMULTIPLIERTAG</OSIsoft:PlugIn> </OSIsoft:Measurement> If you want the interface to send the scaled LoadProfileChannel value to PI, then the following element should be specified in the Measurement Mapping file below the LoadProfileChannel element. Please note that the order of the elements must be maintained. That is the element <OSIsoft:LoadProfileChannel> should be the first element under <OSIsoft:OW> and <OSIsoft:ApplyPulseMultiplier> should be the next element. <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfileChannel> <OSIsoft:ApplyPulseMultiplier>Yes</OSIsoft:ApplyPulseMultiplier> </OSIsoft:OW> A value of Yes indicates that the interval values will be multiplied by the Pulse Multiplier before being sent to PI. Interval Value and Profile Status An <IntervalValue> element can contain <ProfileStatus> elements. For example, For a single meter, the Interface supports reading up to 10 profile statuses. These statuses are known internally as STATUS00 STATUS01 STATUS09 24
Meter Measurements and Attributes If you want the Interface to store the profile status for an <IntervalValue>, you must put the appropriate entries into the measurements configuration file. For example, <OSIsoft:Measurement> <OSIsoft:AFValue>VoltagePhaseA_Status</OSIsoft:AFValue> <OSIsoft:PlugIn>STATUS00</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:StatusValue>Vh(a)</OSIsoft:StatusValue> </OSIsoft:OW> </OSIsoft:Measurement> The preceding example indicates that the VoltagePhaseA_Status should receive the values within the <ProfileStatus> elements for the <LoadProfileChannel> whose <Quantity> matches "Vh(a)". Configuration Attributes The measurements configuration file also contains entries that describe the relationship between an AF element template attributes and attributes such as: For example, <Mappings> electronic serial number (ESN) configuration group application group template name pulse multiplier interval length owmeter time <OSIsoft:MeterTemplate> <OSIsoft:MappedAFTemplate>CommercialMeters</OSIsoft:MappedAFTemplate > <OSIsoft:MeterType>OWMeterA</OSIsoft:MeterType> <OSIsoft:Attribute> <OSIsoft:AFValue>SerialNumber</OSIsoft:AFValue> <OSIsoft:PlugIn>ESN</OSIsoft:PlugIn> </OSIsoft:Attribute> <OSIsoft:Attribute> <OSIsoft:AFValue>ConfigurationGroup</OSIsoft:AFValue> <OSIsoft:PlugIn>CONFIG_GROUP</OSIsoft:PlugIn> </OSIsoft:Attribute> PI AMI Interface for Itron OpenWay Collection Engine 25
Meters in AF and PI <OSIsoft:Attribute> <OSIsoft:AFValue>ApplicationGroup</OSIsoft:AFValue> <OSIsoft:PlugIn>APP_GROUP</OSIsoft:PlugIn> </OSIsoft:Attribute> </OSIsoft:MeterTemplate> </Mappings> In the preceding text, the <OSIsoft:AFValue> value is the name of the AF element template attribute. You are free to choose a name to your liking. The <OSIsoft:PlugIn> value is known internally to the Interface. You must use one of these values ESN CONFIG_GROUP APP_GROUP TEMPLATE_NAME INTERVALLENGTH PULSEMULTIPLIER OWMETER_TIME Summary The beginning of this chapter posed these questions: How does a meter in OpenWay appear in PI AF and the PI Data Archive? What measurements in a meter are supported in PI AF and the PI Data Archive? How do PI AF and the PI Data Archive represent data that a meter collects? The preceding has shown you that a meter in OpenWay appears as a meter element in AF. This meter element is associated with an AF template, a template that contains both configuration attributes and measurement attributes. Configuration attributes are electronic serial number, configuration group, and application group. The OpenWay Collection Engine does not contain attributes such as transformer, substation, and feeder. However, the Interface is capable of storing these attributes into AF. To do so, it parses a MultiSpeak compliant meter asset file. A later chapter in this manual describes this process. Measurement attributes represent the quantities that the meter measures (e.g., kwh and kvar). In AF, measurement attributes are always PI point references. Accordingly, the PI Data Archive contains PI tags whose value represents quantities such as kwh and kvar. The Interface supports register and load profile channel measurements that appear in a DataArrived web service message that OpenWay sends to the PIItronOWListener program. The PIItronOWListener program receives these DataArrived messages and creates XML data files. 26
Summary For the values in these XML data files, the Interface uses its measurements configuration file (i.e., MeasurementMappings.XML) to determine into which PI points it writes data. So, the files that you must edit for proper interface operation are AF meter template files (you can edit these via PI System Explorer) MeasurementMappings.XML (you edit this via a standard text editor) The next section describes steps for installing and configuring the Interface. PI AMI Interface for Itron OpenWay Collection Engine 27
Installation Steps The installation and configuration procedure for PI AMI 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 steps that you must take to ensure that the OpenWay Interface runs properly. The goals of these steps are to Determine the meter configuration attributes that should appear in AF Determine the meter measurements whose values will be stored in PI points Confirm that the Interface has the proper credentials to write data to the PI Data Archive Create an AF database that contains the proper meter templates Edit configuration files OpenWay Web Service Endpoints The Interface invokes web service calls on the OpenWay Collection Engine. It makes use of the following services: DataService EndpointMembershipService ReportService SubscriptionService You must specify in the Source Registry file the endpoint for these web services. For example, [CONNECTOR01] OW_URL_DATA=http://192.168.14.173:8103/ami/2008/10/data OW_URL_ENDPOINTMEMBERSHIP=http://192.168.14.173:8103/ami/2008/10/membership OW_URL_REPORT=http://192.168.14.173:8103/ami/2009/08/reporting OW_URL_SUBSCRIPTION=http://192.168.14.173:8103/ami/2009/08/subscriptions The preceding entries indicate that OpenWay is running on a computer whose IP address is 192.168.14.173. If the OpenWay web service requires a username and password, you must also put these into the Source Registry: [CONNECTOR01] OW_USER=theUser OW_PASSWORD=thePassword PI AMI Interface for Itron OpenWay Collection Engine 29
Installation Steps Meter Attributes and Measurements An essential step to installing and configuration the Interface is to decide which specific meter attributes (i.e., meter configuration) and measurements (i.e., meter data) you want the Interface to capture. Configuration Attributes from OpenWay A meter in OpenWay has these configuration attributes: electronic serial number: This is provided by the collection engine when we query for meters configuration group: This is provided in the MeasurementMappings.xml file application group: this is provided in the piscc.ini file interval length: This is obtained from the DataArrived message of the data files pulse multiplier: This is obtained from the DataArrived message of the data files template name: This is configured in the MeasurementMapping.xml file owmeter time: This is updated internally by the interface to re-sync individual meters So, you must decide which of these attributes you want to have appear in AF and the name under which they should appear in AF. For example, you might choose the following Interface's internal attribute name ESN CONFIG_GROUP APP_GROUP INTERVALLENGTH PULSEMULTIPLIER TEMPLATE_NAME OWMETER_TIME Name in AF SerialNumber ConfigurationGroup ApplicationGroup IntervalLength PulseMultiplier TemplateName OWmeterTime If you do, the measurements configuration file (MeasurementsMappings.XML) must have these entries. Examples of a few of the above attribute mappings are shown below: <Mappings> <OSIsoft:MeterTemplate>... <OSIsoft:Attribute> 30
Meter Attributes and Measurements <OSIsoft:AFValue>SerialNumber</OSIsoft:AFValue> <OSIsoft:PlugIn>ESN</OSIsoft:PlugIn> </OSIsoft:Attribute> <OSIsoft:Attribute> <OSIsoft:AFValue>ConfigurationGroup</OSIsoft:AFValue> <OSIsoft:PlugIn>CONFIG_GROUP</OSIsoft:PlugIn> </OSIsoft:Attribute> <OSIsoft:Attribute> <OSIsoft:AFValue>ApplicationGroup</OSIsoft:AFValue> <OSIsoft:PlugIn>APP_GROUP</OSIsoft:PlugIn> </OSIsoft:Attribute> </OSIsoft:MeterTemplate>... </Mappings> Configuration Attributes from an External System The Interface supports meter configuration attributes (such as transformer, substation, and feeder) that are stored in an external system. This support requires you to create a meter asset file that complies with the MultiSpeak v4.1 standard. This file is an XML file. The name of this file must begin with "meterasset". That is, its filename must be meterasset*.xml. Its contents must conform to these MultiSpeak schemas: mspcpsm.xsd mspgeometry.xsd MultiSpeak.xsd MultispeakRealTime41.xsd xlinks.xsd MultiSpeak Asset File The root element in the MultiSpeak meter asset file is <MultiSpeakMessageHeader>. The immediate child element of <MultiSpeakMessageHeader> is <Batch>. The immediate child element of <Batch> is <MultiSpeak>. A child element of <MultiSpeak> is <mspmeter>. Instances of this element contain a meter's configuration attributes and their values. The "objectid" attribute of the <mspmeter>element is the meter's electronic serial number. The <extname> element contains the configuration attribute while the <extvalue> contains its value. An example of the contents of a MultiSpeak asset file is: PI AMI Interface for Itron OpenWay Collection Engine 31
Installation Steps <MultiSpeakMessageHeader Version="4.1 osisoft=1.0"> <Batch> <MultiSpeak> <mspmeter objectid="2.16.840.1.114416.0.4001827"> <extensionslist> <extensionsitem> <extname>afvalue:transformer</extname> <extvalue>7565070913</extvalue> </extensionsitem> <extensionsitem> <extname>afvalue:feeder</extname> <extvalue>2363</extvalue> </extensionsitem> <extensionsitem> <extname>afvalue:substation</extname> <extvalue>2044</extvalue> </extensionsitem> </extensionslist> </mspmeter> </MultiSpeak> </Batch> </MultiSpeakMessageHeader> The Interface looks for meter asset files in the directory specified as DATA_DIRECTORY in the Source Registry. For example, [CONNECTOR01] DATA_DIRECTORY=C:\OWData When the Interface finds a meterasset*.xml file in the data directory, it parses the file and updates meter attribute values. Accordingly, the preceding example allows the Interface to produce the following: 32
Meter Attributes and Measurements MultiSpeak Attributes For each meter, the Interface is capable of storing 40 MultiSpeak attributes that are of type String. These attributes are known internally as ATTSTR00 ATTSTR01 ATTSTR39 The Interface is capable of storing 25 attributes of type Float. These attributes are known internally as ATTFLT00 ATTFLT01 ATTFLT24 The Interface is capable of storing 20 attributes of type Integer. These attributes are known internally as ATTINT00 ATTINT01 ATTINT19 The measurements configuration file describes the relationship between these internal attributes and the attributes defined in the MultiSpeak asset file. For the preceding example of transformer, substation, and feeder, this MeasurementMappings.XML file should have these entries: <Mappings> <OSIsoft:MeterTemplate>... <OSIsoft:Attribute> <OSIsoft:AFValue>Transformer</OSIsoft:AFValue> <OSIsoft:PlugIn>ATTINT00</OSIsoft:PlugIn> </OSIsoft:Attribute> <OSIsoft:Attribute> <OSIsoft:AFValue>Feeder</OSIsoft:AFValue> <OSIsoft:PlugIn>ATTINT01</OSIsoft:PlugIn> </OSIsoft:Attribute> <OSIsoft:Attribute> <OSIsoft:AFValue>Substation</OSIsoft:AFValue> <OSIsoft:PlugIn>ATTINT02</OSIsoft:PlugIn> </OSIsoft:Attribute> PI AMI Interface for Itron OpenWay Collection Engine 33
Installation Steps </OSIsoft:MeterTemplate> </Mappings> Meter Data Files As the previous chapter indicates, the Interface writes data to PI points by parsing meter data files named XXX.xml. The PIItronOWListener program creates these files when it receives DataArrived and ExceptionsArrived messages from OpenWay. Subscription to OpenWay Before the PIItronOWListener program can receive messages from OpenWay, it must first be a subscriber. If you want the Interface to perform the subscription, put entries into the Source Registry. Specifically, [CONNECTOR01] OW_SUBSCRIBE=TRUE OW_DATA_SUBSCRIBER=http://intfNode:7102 OW_DATA_SUBSCRIBER_NAME=piOwInterfaceData OW_EXCEPTION_SUBSCRIBER=http://intfNode:7103 OW_EXCEPTION_SUBSCRIBER_NAME=piOwInterfaceExcept The preceding entries indicate that PIItronOWListener is running on a computer whose name is "intfnode". In addition, PIItronOWListener is expecting DataArrived messages on port 7102 and ExceptionsArrived messages on port 7103. PIItronOWListener Receiving Messages Even if you do not want the Interface to perform the subscription, you must configure PIItronOWListener to receive DataArrived and ExceptionsArrived messages. This configuration involves these two preceding Source Registry entries: [CONNECTOR01] OW_DATA_SUBSCRIBER=http://intfNode:7102 OW_EXCEPTION_SUBSCRIBER=http://intfNode:7103 OpenWay Interrogation The PIItronOWListener program receives OpenWay DataArrived messages when OpenWay is polled, or interrogated. If you want the Interface to perform this interrogation, put entries into the Source Registry. Specifically, [CONNECTOR01] OW_INTERROGATE=TRUE One interrogation request is issued for Profile, Register and Event Reads. By default, the Interface interrogates for values every 8 hours starting at midnight. You can change these frequencies by setting a pattern via these Source Registry parameters: [CONNECTOR01] INTERROGATE_READ_START_TIME_HR_MIN=00:00 INTERROGATE_READ_END_TIME_HR_MIN=12:00 34
Meter Attributes and Measurements INTERROGATE_WINDOW_START_TIME_HR_MIN=12:00 INTERROGATE_WINDOW_END_TIME_HR_MIN=02:00 INTERROGATE_SEND_REQUEST_TIME_HR_MIN=12:00 The preceding entries indicate that the Interface will interrogate every 12 hours for register, event and interval values starting at midnight. The interval window will be 2 hours and the first request will be made at 12 noon. The offsets are calculated from midnight and not when the interface is started. Another parameter that the interface writes to in the piscc.ini file is: INTERROGATE_LAST_READ_END_TIME=0 If starting the interface for the first time this value should be set to 0. This indicates that the interface has never interrogated the head end for values and will interrogate for the first time with INTERROGATE_READ_START_TIME_HR_MIN as midnight. When the interface is shut down, INTERROGATE_LAST_READ_END_TIME will be populated with the end time of the last interrogation. This way when the interface is started up again, it can start interrogation where it last left off. As per Itron s recommendation, the interface will start the interrogation only from 00:00 of that day. For example if the timestamp of the time the interface started was: 2014-03-05T08:15:30-08:00 And the: INTERROGATE_LAST_READ_END_TIME=2014-03-02T08:00:00-08:00 The next interrogation read start time will be 2014-03-05T00:00:00-08:00. To get values in the gap between 2014-03-05T08:15:30-08:00 and 2014-03-05T00:00:00-08:00, a manual interrogation should be triggered by the Itron Collection Engine. Meter Measurements and AF Values A DataArrived message from OpenWay contains meter measurements. These measurements are register values, interval values, and profile status values. Register Values The Interface collects register values based on the <Quantity> element of the <RegisterValue> element of the DataArrived message. The following screenshot indicates a <Quantity> of "ins V(a)": PI AMI Interface for Itron OpenWay Collection Engine 35
Installation Steps In order for the Interface to collect data for this measurement, you have to come up with a name for this measurement (e.g., RegisterVoltagePhaseA), and use one of the Interface's internal measurements (e.g., MEASFLT00) You then edit the measurements configuration file so that it has this mapping information. That is, <OSIsoft:Measurement> <OSIsoft:AFValue>RegisterVoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT00</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:RegisterValue>ins V(a)</OSIsoft:RegisterValue> </OSIsoft:OW> </OSIsoft:Measurement> Load Profile Channels and Interval Values The Interface collects interval values based on the <Quantity> element of the <LoadProfileChannel> element of the DataArrived message. The following screenshot indicates a <Quantity> of "Vh(a)": 36
Meter Attributes and Measurements In order for the Interface to collect data for this measurement, you have to come up with a name for this measurement (e.g., VoltagePhaseA), and use one of the Interface's internal measurements (e.g., MEASFLT01) You then edit the measurements configuration file so that it has this mapping information. That is, <OSIsoft:Measurement> <OSIsoft:AFValue>VoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT01</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfileChannel> </OSIsoft:OW> </OSIsoft:Measurement> Load Profile Channels and Profile Status The Interface can record values for the profile status of a <LoadProfileChannel> element of the DataArrived message. Again, the <Quantity> element is the key. Here's an example of the measurements configuration file: <OSIsoft:Measurement> <OSIsoft:AFValue>VoltagePhaseA_Status</OSIsoft:AFValue> <OSIsoft:PlugIn>STATUS00</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:StatusValue>Vh(a)</OSIsoft:StatusValue> </OSIsoft:OW> </OSIsoft:Measurement> PI AMI Interface for Itron OpenWay Collection Engine 37
Installation Steps Meter Events The DataArrived message from OpenWay includes meter event information. For example, The Interface can store the value of the <Name> element into a PI point that you define. If you want the Interface to do so, you must edit the measurements configuration file so that the Interface's internal EventTag maps to your PI point. For example, <OSIsoft:Measurement> <OSIsoft:AFValue>MeterEvent</OSIsoft:AFValue> <OSIsoft:PlugIn>EventTag</OSIsoft:PlugIn> </OSIsoft:Measurement> If the meter's identifier is 4001827, the preceding example indicates that the Interface will write "Meter Configuration Changed By Unexpected Source" to the PI point OW_4001827.MeterEvent. Please be aware that the OW_4001827.MeterEvent point is of type Digital. Its digital state set is AMIEventStates. You must ensure that this state set has all the possible values for the <Name> element. 38
Meter Attributes and Measurements Meter Exceptions The ExceptionsArrived message from OpenWay contains meter exceptions information. For example, The Interface can store the value of the <Name> element into a PI point that you define. If you want the Interface to do so, you must edit the measurements configuration file so that the Interface's internal ExceptionTag maps to your PI point. For example, <OSIsoft:Measurement> <OSIsoft:AFValue>MeterException</OSIsoft:AFValue> <OSIsoft:PlugIn>ExceptionTag</OSIsoft:PlugIn> </OSIsoft:Measurement> If the meter's identifier is 4001827, the preceding example indicates that the Interface will write "Meter Configuration Changed by Unexpected Source" to the PI point OW_4001827.MeterException. Please be aware that the OW_4001827.MeterException point is of type Digital. Its digital state set is AMIEventStates. You must ensure that this state set has all the possible values for the <Name> element. PI AMI Interface for Itron OpenWay Collection Engine 39
Installation Steps PI Environment Configuration of the OpenWay Interface involves setting up and preparing the PI environment in which the Interface runs. This environment consists of PI Data Archives in a High Availability configuration. As such there are four separate computers: AF Server HA Primary PI Data Archive HA Secondary PI Data Archive Interface Node The following picture shows the configuration: HA Primary PI Data Archive HA Secondary PI Data Archive Low-level PI Data Archive calls OpenWay Interface using components of AF SDK Interface Node AF SDK PI AF Server 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 40
PI Environment 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. For example, [PISCC] PI_SERVER=theInterfaceNode The CONNECTOR01 section contains parameters specific to the OpenWay Interface. The NAME parameter is an arbitrary identifier that you choose. However, it should reflect the Interface. For example, [CONNECTOR01] NAME=OpenWay The PI_COLLECTIVE_00 parameter specifies the name of the PI Collective to which the Interface writes data. PI_COLLECTIVE_00=Neptune 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\ItronOW\PIItronOWPlugIn.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=Meters The POINT_SOURCE specifies the value of the PointSource attribute of the PI points that the Interface uses. For example, [CONNECTOR01] POINT_SOURCE=OpenWay 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, both 32-bit and 64-bit PI AMI Interface for Itron OpenWay Collection Engine 41
Installation Steps 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 Data Archive Nodes On the Primary and Secondary PI Data Archive Nodes, run the appropriate PI Data Archive setup kit. You can optionally install the AF Client. Interface Node The installation kit installs software needed on the interface node. In addition, you may need to install OSIsoft s Prerequisites kit. Interface Installation Files On the Interface Node, the Interface installation kit results in the following directories and files: [PIHOME64]\Interfaces\PISCC PISCC.exe PISCC_sample.ini OSIsoft.PI.Configuration.dll OSIsoft.PI.Data.dll OSIsoft.PI.Net.dll OSIsoft.PISCC.Net.dll AMIMeter.xml AMIEventStates.CSV AMIOperationalStates.CSV AMIStatusStates.CSV amiput.exe authtest.exe CacheClient.exe 42
PI Environment Configuration QueuesClient.exe TablesClient.exe The PISCC.exe file is the executable program portion of the OpenWay Interface. The PISCC.ini file is the Source Registry. An example Source Registry file named PISCC_sample.ini is included from which a PISCC.ini file can be created. The AMIMeter.xml file is an AF meter template file. The comma separated files (CSV) define digital state sets for use by digital points created by the Interface. [PIHOME64]\Interfaces\PISCC\ItronOW PIItronOWPlugIn.dll OW_Sample_Template.xml PIItronOWListener.exe PIItronOWListener.bat PI_ItronOW.docx PI_ItronOW_ReleaseNotes.txt MeasurementMappings_OW.xml The first six files are the plug-in portion of the OpenWay Interface. The last file is an example of the measurements configuration file. [PIHOME64]\Interfaces\PISCC\ItronOW\Test PIItronOWTest.exe PIItronOWTest.bat These files test the web services between the Interface and OpenWay. PI Environment Configuration PI Collective and Mapping and Trust Verification Make sure that the collective name agrees with the PI_COLLECTIVE_00 entry of the PISCC section of the Source Registry. For example, recall that [PISCC] PI_COLLECTIVE_00=Neptune Edit the Source Registry as necessary. For this PI Collective, 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 Mapping or Trust, go to the Interface Node and run the authtest program. This program attempts authentication to a PI Data Archive using all three of the following methods: mappings based on Windows logon PI Trusts PI username and password The usage syntax for authtest is PI AMI Interface for Itron OpenWay Collection Engine 43
Installation Steps authtest.exe PIserver user [password] For example, the following authenticates to the PI Data Archive named thepiserver using your Windows logon credentials; a PI trust created on thepiserver for the Interface node; and the username of piadmin and password of hello C:> authtest.exe thepiserver piadmin hello ============================================================================ Authenticating to [thepiserver] via 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 Result Privileges Mapping Failure None Trust Failure None PI user logon Failure None Because authentication failed, you must edit the Mapping or Trust for the Interface Node on the PI Collective. Run authtest again. Repeat until the program indicates that it can authenticate to the PI Data Archive. For example, ============================================================================ Authenticating to [thepiserver] via Trust createsession() succeeded ProtocolCredentialResult: COMPANY\User1 GetProtocolDetails: piadmin The Interface connects to the PI Data Archive using components of the AF SDK. To verify that you can successfully create a connection to the PI Data Archive through components of the AF SDK and write data to the PI Data Archive, go to the Interface Node and run the amiput.exe program. The Usage syntax for amiput.exe is: amiput.exe PIServer tagname dval [ptsource] If the program is successful, the output will be similar to: Starting program to test ability to write to PI Server Version is v1.0.0.0 6-February-2012 Registering RPC Tables with Session Manager. ============================================================================ Authenticating to [RUSH] via Mappings createsession() succeeded 44
PI Environment Configuration 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 v=1 ============================================================================ If the program does not find the PI point, it will create the point in the PI Data Archive. 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=Meters Then, use File, Import, to load (in sequence) the meter template file that the Interface provides: [PIHOME64]\Interfaces\PISCC\AMIMeter.xml Navigate to the Library section of PI System Explorer. Confirm that the AF database has the following Element Templates: PI AMI Interface for Itron OpenWay Collection Engine 45
Installation Steps Files Editing The files that you must edit for proper interface operation are AF meter template files (you can edit these via PI System Explorer) MeasurementMappings.XML (you edit this via a standard text editor) AF Meter Template Files The Interface installation kit provides a sample meter template file named OW_Sample_Template.xml. This file defines a meter template named CommercialMeters. After you have used PI System Explorer to import the AMIMeter.XML file, you should import OW_Sample_Template.xml. You will then see the CommercialMeters template: 46
Files Editing If you do not like the name of the template (CommercialMeters), you can change it. Configuration Attributes You should confirm that the AF template contains the configuration attributes that you want the Interface to fill in. For example, if you are interested in these attributes, Interface's internal attribute name or MultiSpeak attribute CONFIG_GROUP APP_GROUP ATTINT00 ATTINT01 Name in AF ConfigurationGroup ApplicationGroup Substation Transformer the AF template should contain these entries: Measurement Attributes You should confirm that the AF template contains the measurements that you want the Interface to collect. For example, if you are interested in these measurements, <Quantity> specification in DataArrived message Register Value, ins V(a) Name in AF RegisterVoltagePhaseA PI AMI Interface for Itron OpenWay Collection Engine 47
Installation Steps Load Profile Channel, Vh(a) Load Profile Channel, Vh(b) Load Profile Channel, Vh(c) ProfileStatus for Load Profile Channel, Vh(a) VoltagePhaseA VoltagePhaseB VoltagePhaseC StatusForVh(a) the AF template should contain these entries: Adding and Editing Attributes You will most likely need to edit the supplied OW_Sample_Template.xml meter template file so that it contains the attributes that are relevant to your situation. You can perform this edit within PI System Explorer. Configuration Attributes When you add or edit configuration attributes, be sure to use the correct AF value type. Specifically, Interface's internal attribute name or MultiSpeak attribute ESN CONFIG_GROUP AF value type String String 48
Files Editing APP_GROUP INTERVALLENGTH PULSEMULTIPLIER ATTSTRXX ATTFLTXX ATTINTXX String Int32 Single String Single Int32 Measurement Attributes When you add or edit measurement attributes, be sure to use the correct AF value type. Specifically, Interface's internal measurement name MEASFLTXX MEASINTXX STATUSXX EventTag ExceptionTag AF value type Single Int32 String String String Measurements Configuration File The setup kit installs a file named MeasurementMappings_OW.XML. You must copy this file to the directory where PISCC.EXE is located. Then, rename this file to be MeasurementMappings.XML. You edit the resulting MeasurementMappings.XML measurements configuration file via a standard text editor. This file associates an AF meter template name with a record type (OWMeterA, OWMeterB, OWMeterC, OWMeterD, OWMeterE, OWMeterF, OWMeterG, OWMeterH, OWMeterI, OWMeterJ, OWMeterK, or OWMeterL) internal to the Interface, associates a configuration group with a record type, associates a measurement attribute in AF with an Interface's internal measurement (MeasFlt00, MeasFlt01, etc.), tells the Interface how to collect data for meter measurements, associates a meter configuration attribute in AF with an attribute known to the Interface (ESN, CONFIG_GROUP, etc.), PI AMI Interface for Itron OpenWay Collection Engine 49
Installation Steps associates a meter configuration attribute in AF with a generic MultiSpeak attribute known to the Interface (AttStr00, AttFlt00, AttInt00, etc.). The root element in this file is <Mappings>; it contains one or more <OSIsoft:MeterTemplate> elements. That is, <Mappings> <OSIsoft:MeterTemplate> </OSIsoft:MeterTemplate> </Mappings> Meter Template and Configuration Group Association The <OSIsoft:MeterTemplate> element contains elements that associate an AF meter template name with a record type internal to the Interface. It also relates OpenWay configuration groups with a meter template. For example, <OSIsoft:MeterTemplate> <OSIsoft:MeterType>OWMeterA</OSIsoft:MeterType> <OSIsoft:MappedAFTemplate>CommercialMeters</OSIsoft:MappedAFTe mplate> <OSIsoft:TemplateIdentifier>PG 100</OSIsoft:TemplateIdentifier> <OSIsoft:TemplateIdentifier>PG 101</OSIsoft:TemplateIdentifier> </OSIsoft:MeterTemplate> The preceding tells the Interface that meters whose configuration group is PG 100 or PG 101 should use the AF template named CommercialMeters. Measurement Association A <OSIsoft:MeterTemplate> element also contains one or more <OSIsoft:Measurement> elements. That is, <OSIsoft:MeterTemplate> <OSIsoft:Measurement> </OSIsoft:Measurement> <OSIsoft:Measurement> </OSIsoft:Measurement> </OSIsoft:MeterTemplate> Contents of a <OSIsoft:Measurement> element associate a measurement attribute in AF with an Interface's internal measurement (MeasFlt00, MeasFlt01, etc.). They also tell the Interface how to collect data. For example, for <Quantity> specification in Name in AF 50
Files Editing DataArrived message Register Value, ins V(a) Load Profile Channel, Vh(a) Load Profile Channel, Vh(b) Load Profile Channel, Vh(c) RegisterVoltagePhaseA VoltagePhaseA VoltagePhaseB VoltagePhaseC there will be 4 <OSIsoft:Measurement> elements: <OSIsoft:MeterTemplate> <OSIsoft:Measurement> <OSIsoft:PlugIn>MeasFlt00</OSIsoft:PlugIn> <OSIsoft:AFValue>RegisterVoltagePhaseA</OSIsoft:AFValue> <OSIsoft:OW> <OSIsoft:RegisterValue>ins V(a)</OSIsoft:RegisterValue> </OSIsoft:OW> </OSIsoft:Measurement> <OSIsoft:Measurement> <OSIsoft:PlugIn>MeasFlt01</OSIsoft:PlugIn> <OSIsoft:AFValue>VoltagePhaseA</OSIsoft:AFValue> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfileChannel> </OSIsoft:OW> </OSIsoft:Measurement> <OSIsoft:Measurement> <OSIsoft:PlugIn>MeasFlt02</OSIsoft:PlugIn> <OSIsoft:AFValue>VoltagePhaseB</OSIsoft:AFValue> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(b)</OSIsoft:LoadProfileChannel> </OSIsoft:OW> </OSIsoft:Measurement> <OSIsoft:Measurement> <OSIsoft:PlugIn>MeasFlt03</OSIsoft:PlugIn> <OSIsoft:AFValue>VoltagePhaseC</OSIsoft:AFValue> <OSIsoft:OW> PI AMI Interface for Itron OpenWay Collection Engine 51
Installation Steps <OSIsoft:LoadProfileChannel>Vh(c)</OSIsoft:LoadProfileChannel> </OSIsoft:OW> </OSIsoft:Measurement> </OSIsoft:MeterTemplate> Attribute Association Finally, a <OSIsoft:MeterTemplate> element contains one or more <OSIsoft:Attribute> elements. That is, <OSIsoft:MeterTemplate> <OSIsoft:Attribute> </OSIsoft:Attribute> <OSIsoft:Attribute> </OSIsoft:Attribute> </OSIsoft:MeterTemplate> Each <OSIsoft:Attribute> element associates a meter configuration attribute in AF with an attribute known internally to the Interface. Attributes known internally to the Interface include the MultiSpeak attributes (ATTSTR00, ATTFLT00, ATTINT00, etc.). For example, for Attribute known to Interface ESN CONFIG_GROUP ATTINT00 ATTINT01 ATTINT02 Name in AF SerialNumber ConfigurationGroup Transformer Substation FeederCode there will be 5 <OSIsoft:Attribute> elements: <OSIsoft:MeterTemplate> <OSIsoft:Attribute> <OSIsoft:PlugIn>ESN</OSIsoft:PlugIn> <OSIsoft:AFValue>SerialNumber</OSIsoft:AFValue> <\OSIsoft:Attribute> <OSIsoft:Attribute> <OSIsoft:PlugIn>CONFIG_GROUP</OSIsoft:PlugIn> <OSIsoft:AFValue>ConfigurationGroup</OSIsoft:AFValue> 52
Files Editing <\OSIsoft:Attribute> <OSIsoft:Attribute> <OSIsoft:PlugIn>ATTINT00</OSIsoft:PlugIn> <OSIsoft:AFValue>Transformer</OSIsoft:AFValue> <\OSIsoft:Attribute> <OSIsoft:Attribute> <OSIsoft:PlugIn>ATTINT01</OSIsoft:PlugIn> <OSIsoft:AFValue>Substation</OSIsoft:AFValue> <\OSIsoft:Attribute> <OSIsoft:Attribute> <OSIsoft:PlugIn>ATTINT02</OSIsoft:PlugIn> <OSIsoft:AFValue>FeederCode</OSIsoft:AFValue> </OSIsoft:Attribute> </OSIsoft:MeterTemplate> PI AMI Interface for Itron OpenWay Collection Engine 53
Digital State Sets The Interface writes data to digital PI points. Accordingly, the Interface requires that the PI Data Archive contain these digital state sets: AMIEventStates AMIOperationalStates AMIStatusStates The Interface can automatically create these state sets at startup. The procedure is that it checks the Interface directory (such as C:\Program Files\PIPC\Interfaces\PISCC) for the existence of digital state files. If the Interface finds the file AMIEventStates.CSV, it creates the AMIEventStates digital state set. If the Interface finds the file AMIOperationalStates.CSV, it creates the AMIOperationalStates digital state set. If the Interface finds the file AMIStatusStates.CSV, it creates the AMIStatusStates digital state set. Profile Status Tags The Interface can record values for the profile status of the <IntervalValue> element of the <LoadProfileChannel> element of the DataArrived message. The Interface supports reading up to 10 profile statuses. These statuses are known internally as STATUS00 STATUS01 STATUS09 Here's a screenshot of a DataArrived message that contains a profile status: PI AMI Interface for Itron OpenWay Collection Engine 55
Digital State Sets The value of the <Quantity> element tells the Interface how to collect this profile status. Here's an example of the measurements configuration file: <OSIsoft:Measurement> <OSIsoft:AFValue>VoltagePhaseA_Status</OSIsoft:AFValue> <OSIsoft:PlugIn>STATUS00</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:StatusValue>Vh(a)</OSIsoft:StatusValue> </OSIsoft:OW> </OSIsoft:Measurement> The profile status tags are digital tags whose digital state set is AMIStatusStates. The Interface creates this state set based on the contents of the AMIStatusStates.CSV file. Therefore, you must ensure that this file contains all the enumerated values for the <ProfileStatus> element of the DataArrived message. Meter Event Tag The DataArrived message from OpenWay includes meter event information. The Interface can write to a PI tag the value of the <Name> element of the <MeterEvent> element. For example, 56
Meter Event Tag The Interface stores meter events to a measurement known internally as EventTag. You must edit the measurements configuration file so that EventTag maps to your PI point. For example, <OSIsoft:Measurement> <OSIsoft:AFValue>MeterEvent</OSIsoft:AFValue> <OSIsoft:PlugIn>EventTag</OSIsoft:PlugIn> </OSIsoft:Measurement> The event tag is a digital tag whose digital stat set is AMIEventStates. The Interface creates this state set based on the contents of the AMIEventStates.CSV file. Therefore, you must ensure that this file contains all the enumerated values for the <Name> element of the DataArrived message. PI AMI Interface for Itron OpenWay Collection Engine 57
Digital State Sets Meter Exception Tag The ExceptionsArrived message from OpenWay includes meter exception information. The Interface can write to a PI tag the value of the <Name> element of the <MeterException> element. For example, The Interface stores meter exceptions to a measurement known internally as ExceptionTag. You must edit the measurements configuration file so that ExceptionTag maps to your PI point. For example, <OSIsoft:Measurement> <OSIsoft:AFValue>MeterException</OSIsoft:AFValue> <OSIsoft:PlugIn>ExceptionTag</OSIsoft:PlugIn> </OSIsoft:Measurement> The exception tag is a digital tag whose digital stat set is AMIEventStates. The Interface creates this state set based on the contents of the AMIEventStates.CSV file. Therefore, you must ensure that this file contains all the enumerated values for the <Name> element of the <MeterException> element of the ExceptionsArrived message. 58
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 PI AMI Interface for Itron OpenWay Collection Engine 59
Windows Service 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 local administrator privileges. For example, 60
PIItronOWListener The OpenWay Collection Engine sends DataArrived and ExceptionsArrived messages to the PIItronOWListener program. When this program receives DataArrived messages, it creates files named XXX_Data.XML. When it receives ExceptionsArrived messages, it creates files named XXX_Exception.XML. The Interface parses these files and updates the PI Data Archive. Startup Command File The PIItronOWListener.exe executable file requires two command line parameters: sr, explicit path to the Source Registry OW, reference to the OpenWay Interface section within the Source Registry Make sure that the associated startup command file (PIItronOWListener.bat) has the correct values for these parameters. For example,.\piitronowlistener.exe sr="d:\program files\pipc\interfaces\piscc\piscc.ini" OW=connector01 Basic Source Registry Parameters You will most likely need to modify following Source Registry parameters: Parameter DATA_DIRECTORY OW_DATA_SUBSCRIBER OW_EXCEPTION_SUBSCRIBER Description DATA_DIRECTORY defines the directory that contains the files that PIItronOWListener creates. It also indicates where the Interface reads data files. This parameter contains a URL that specifies the name of the computer on which PIItronOWListener runs. The URL also specifies the port on which PIItronOWListener receives DataArrived messages from OpenWay. This parameter contains a URL that specifies the name of the computer on which PIItronOWListener runs. The URL also specifies the port on which PIItronOWListener receives ExceptionsArrived messages from OpenWay. An example value for this parameters is: [CONNECTOR01] DATA_DIRECTORY=E:\OWData OW_DATA_SUBSCRIBER=http://intfNode:7102 OW_EXCEPTION_SUBSCRIBER=http://intfNode:7103 PI AMI Interface for Itron OpenWay Collection Engine 61
PIItronOWListener Advanced Source Registry Parameters Parameter DATA_BACKUP_DIRECTORY OW_SSL_SERVER_MODE OW_SSL_SERVER_FILE OW_SSL_SERVER_PASSWORD OW_SSL_SERVER_CA_FILE OW_SSL_SERVER_CA_PATH OW_SSL_SERVER_DH_FILE Description This parameter specifies the directory to which PIItronOWListener creates backup of the files that are based DataArrived and ExceptionsArrived messages. This parameter is a number that represents the SSL server mode of PIItronOWListener. This parameter refers to PIItronOWListener's private key file. This parameter is the password to read the private key file. This parameter refers to the file that is used to authenticate clients. It also contains the client certificates. This parameter refers to a directory name that contains client certificates. This parameter specifies a DH file. Windows Service Commands The install kit creates the services when it installs the software on the interface node. Use the following steps to install the services if you are not using the install kit. Creating the PIItronOWListener Service To create the Windows service for PIItronOWListener, open a Windows command prompt and change to the directory where the PIItronOWListener.exe and PIItronOWListener.bat files are. For example, go to C:\Program Files\PIPC\Interfaces\PISCC\ItronOW Type the following command C:> PIItronOWListener.exe -install -display "PIItronOWListener" auto -depend PINetMgr The preceding command creates a service named PIItronOWListener. This PIItronOWListener service starts when the operating system itself starts. It is dependent on the PINetMgr service. Removing the PIItronOWListener Service To remove the service for PIItronOWListener, open a Windows command prompt and change to the directory where the PIItronOWListener.exe and PIItronOWListener.bat files are. Type the following command C:> PIItronOWListener.exe -remove 62
Windows Service Commands Starting the PIItronOWListener Service To start the service for PIItronOWListener open a Windows command prompt and change to the directory where the PIItronOWListener.exe and PIItronOWListener.bat files are. Type the following command C:> PIItronOWListener.exe -start If you are not in the directory where the piscc.exe and piscc.bat files are, use the following: C:> net start PIItronOWListener You can also use the Windows Services control panel to start the PIItronOWListener service. Stopping the PIItronOWListener Service To stop the service for PIItronOWListener, open a Windows command prompt and change to the directory where the PIItronOWListener.exe and PIItronOWListener.bat files are. Type the following command C:> PIItronOWListener.exe -stop If you are not in the directory where the piscc.exe and piscc.bat files are, use the following: C:> net stop PIItronOWListener You can also use the Windows Services control panel to stop the PIItronOWListener service. Querying the PIItronOWListener Service To determine whether the service for PIItronOWListener is currently running, open a Windows command prompt and change to the directory where the PIItronOWListener.exe and PIItronOWListener.bat files are. Type the following command: Message file C:> PIItronOWListener.exe -query The PIItronOWListener application logs messages to PIItronOWListener.log. This file is located in the Interface directory of the application itself. For example, C:\Program Files\PIPC\Interfaces\PISCC\ItronOW PI AMI Interface for Itron OpenWay Collection Engine 63
Interface Checklist Before you start the Interface, make sure that you fully understand the information presented in the previous chapters. You should follow these steps: Determine the meter attributes that you want to appear in AF. Create a meter database in AF. Confirm that AF contains the correct meter templates. Confirm entries in the Interface's measurements configuration file. Confirm the entries in the Interface's Source Registry file. Confirm that the size of the PI archive files is correct. Meter Attributes Before starting the Interface, determine which meter configuration attributes you want to appear in AF. These attributes include OpenWay attributes and attributes from MultiSpeak files. OpenWay Attributes The Interface's internal names for its OpenWay attributes, along with their data type, are: ESN (String) CONFIG_GROUP (String) APP_GROUP (String) INTERVALLENGTH (Integer) PULSEMULTIPLIER (Float) Later on, you will need to edit the measurements configuration file in order to map these internal names to a name that appears in AF. MultiSpeak Attributes The Interface's internal names for its MultiSpeak attributes that are of type String are: ATTSTR00 ATTSTR01... ATTSTR39 The Interface's internal names for its MultiSpeak attributes that are of type Float are: ATTFLT00 ATTFLT01... ATTFLT24 The Interface's internal names for its MultiSpeak attributes that are of type Integer are: PI AMI Interface for Itron OpenWay Collection Engine 65
Interface Checklist ATTINT00 ATTINT01... ATTINT19 Later on, you will need to edit the measurements configuration file in order to map these internal names to a name that appears in AF. This same AF name also appears in the MultiSpeak asset file. Measurement Attributes For each meter measurement for which you want the Interface to collect data, you must come up with a meaningful name. For example, RegisterVoltagePhaseA VoltagePhaseA VoltagePhaseB VoltagePhaseC You will need to use these names in the next step, which is to create an AF database, load a meter template, and edit the template attributes. AF Database and Template 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=Meters Then, use File, Import, to load (in sequence) the meter template files provided by the Interface: [PIHOME64]\Interfaces\PISCC\AMIMeter.xml [PIHOME64]\Interfaces\PISCC\ItronOW\OW_Sample_Template.xml Edit the OW sample AF meter template and its attributes so that their names are meaningful to you. Interface Configuration Files Measurements Configuration File The setup kit installs a file named MeasurementMappings_OW.XML. You must copy this file to the directory where PISCC.EXE is located. Then, rename this file to be MeasurementMappings.XML. Ensure that this measurements configuration file (MeasurementMappings.XML) has the information necessary for the Interface to collect data for meter measurements. For example, <OSIsoft:Measurement> 66
Source Registry <OSIsoft:AFValue>RegisterVoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT00</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:RegisterValue>ins V(a)</OSIsoft:RegisterValue> </OSIsoft:OW> </OSIsoft:Measurement> <OSIsoft:Measurement> <OSIsoft:AFValue>VoltagePhaseA</OSIsoft:AFValue> <OSIsoft:PlugIn>MEASFLT01</OSIsoft:PlugIn> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfileChannel> </OSIsoft:OW> </OSIsoft:Measurement> This file also contains information about configuration attributes. For example, <OSIsoft:Attribute> <OSIsoft:AFValue>SerialNumber</OSIsoft:AFValue> <OSIsoft:PlugIn>ESN</OSIsoft:PlugIn> </OSIsoft:Attribute> A previous section of this manual provides the details of the format of the contents of this file. Source Registry Verify that the Source Registry has the appropriate 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. For example, [PISCC] PI_SERVER=theInterfaceNode CONNECTORXX 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 to the Interface. [CONNECTOR00] NAME=OWPlugIn Verify the CONNECTOR_STATE and START_STATE parameters. PI AMI Interface for Itron OpenWay Collection Engine 67
Interface Checklist [CONNECTOR00] CONNECTOR_STATE=NOT_LOADED START_STATE=START Verify that PATH contains the location of the interface plug-in module: [CONNECTOR00] PATH=C:\Program Files\PIPC\Interfaces\PISCC\ItronOW\PIItronOWPlugIn.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. [CONNECTOR00] HEAD_END=OW Verify the hostname of the PI Collective. Verify that you have chosen a value for the PointSource attribute of the PI points that the Interface creates: [CONNECTOR00] PI_COLLECTIVE_00=Neptune POINT_SOURCE=OW Verify AF parameters: [CONNECTOR00] AF_SERVER=theAFServer AF_DATABASE=Meters Verify parameters for connecting to OpenWay via web services: [CONNECTOR00] OW_URL_DATA=http://owce:8103/ami/2008/10/data OW_URL_ENDPOINTMEMBERSHIP=http://owce:8103/ami/2008/10/membership OW_URL_REPORT=http://owce:8103/ami/2009/08/reporting OW_URL_SUBSCRIPTION=http://owce:8103/ami/2009/08/subscriptions OW_USER=theUser OW_PASSWORD=thePassword Verify parameters that specify the application groups of meters: [CONNECTOR00] APPLICATION_GROUPS_00=applGroupFirst APPLICATION_GROUPS_01=applGroupSecond Verify the directory in which the Interface looks for files that PIItronOWListener creates based on DataArrived and ExceptionsArrived messages received from OpenWay. [CONNECTOR00] DATA_DIRECTORY=C:\OWData If you want the Interface to interrogate OpenWay, verify interrogation parameters: 68
PI Archive Size [CONNECTOR00] OW_INTERROGATE=TRUE INTERROGATE_READ_START_TIME_HR_MIN=00:00 INTERROGATE_READ_END_TIME_HR_MIN=08:00 INTERROGATE_WINDOW_START_TIME_HR_MIN=08:00 INTERROGATE_WINDOW_END_TIME_HR_MIN=15:00 INTERROGATE_SEND_REQUEST_TIME_HR_MIN=07:30 ;NOTE: The below parameter is populated by the interface and not the user INTERROGATE_LAST_READ_END_TIME=0 If you want the Interface to subscribe to OpenWay, verify subscription parameters: [CONNECTOR00] OW_SUBSCRIBE=TRUE OW_DATA_SUBSCRIBER_NAME=piOwInterfaceData OW_EXCEPTION_SUBSCRIBER_NAME=piOwInterfaceExcept Verify parameters for the PIItronOWListener program: [CONNECTOR00] OW_DATA_SUBSCRIBER=http://theIntferfaceNode:7102 OW_EXCEPTION_SUBSCRIBER=http://theInterfaceNode:7103 PI Archive Size The size of an archive file determines the maximum number of points that it can hold. This maximum number is one-half the archive file size. For example, if the archive is 512 MB, it can hold at most 262,144 points (512 * 1024 * 0.5). So, before you start the Interface you must calculate the total number of necessary points given the ultimate number of meters the number of PI points per meter a safety factor for non-interface points Based on this number, you can then create archive files that are the correct size. PI AMI Interface for Itron OpenWay Collection Engine 69
Pre-Created Tags When the Interface first starts up, it creates a sample meter using internal record type OWMeterA. This sample meter has a meter id named "SampleMeter". During the process of creating the sample meter, the Interface pre-creates about 94,000 PI tags. The attributes of these tags are: the tagname begins with _res the point source correspond to the value of the POINT_SOURCE parameter in the Source Registry This point creation process can take a long time. You can monitor the progress by logging on the PI Data Archive Node, opening a command prompt, running piartool, and looking at the point count. For example, Later on, when the Interface builds meters, the Interface will rename these existing pre-created PI tags. Because renaming a tag is much faster than creating a new tag, the Interface can quickly build meters. When the Interface sees that the number of pre-created tags has fallen below a certain threshold, it will create another group of 94,000. Again, this point creation process can take a long time. If you do not want the Interface to create the sample meter at startup, set in the Source Registry OMIT_SAMPLE_METER=YES When the Interface runs under this configuration, it pre-creates PI tags when it creates the first meter. As mentioned previously, this point creation process can take a long time. PI AMI Interface for Itron OpenWay Collection Engine 71
Interface Startup This chapter walks you through the steps of an interface startup. Minimal Startup Before you embark on a full-scale interface startup, OSIsoft recommends that you first perform a minimal startup. This startup type allows you to understand and verify the basic functionality of the Interface. Interactive Startup PISCC Open a Windows command prompt with Administrator privileges. Go to the directory where PISCC.exe is located; for example, C:\Program Files\PIPC\Interfaces\PISCC Start the Interface interactively: C:> piscc.exe You should see messages such as: PISCC Information: 0 : Starting interactively PISCC (PI Smart Connector Container) v1.2.2.0 21-Mar-2013 PISCC Information: 0 : Loaded Module CONNECTOR00 [C:\Program Files\PIPC\Interfaces\PISCC\ItronOW\PIItronOWPlugIn.dll] Unless you had OMIT_SAMPLE_METER=YES in the Source Registry, the Interface will create the sample meter in AF. To confirm, run PI System Explorer and verify that the Interface created the sample meter and its PI points. The screenshot below shows an example: PI AMI Interface for Itron OpenWay Collection Engine 73
Interface Startup PIItronOWListener Open a Windows command prompt. Go to the directory where PIItronOWListener.exe is located; for example, C:\Program Files\PIPC\Interfaces\PISCC\ItronOW Start PIItronOWListener interactively: C:> PIItronOWListener.bat You should see messages such as Starting interactively PIItronOWListener program v1.0.0.0 16-Sep-2013 In Source Registry, using OpenWay=connector00 Starting DataSubscriber Server on port 7102 over HTTP Starting ExceptionSubscriber Server on port 7103 over HTTP OpenWay Interrogation Perform an interrogation of OpenWay such that it sends a DataArrived message to PIItronOWListener. PIItronOWListener should then indicate a message such as Wrote file : C:\OWData\2013_09_16_11_22_32_016_INTFNODE_Data.xml PISCC should then parse this file and write data to the PI Data Archive. Normal Startup During normal startup, both the Interface executable (PISCC.exe) and the PIItronOWListener application (PIItronOWListener.exe) run as Windows Services. Service Startup To stop the Interface running interactively, use Control-C in the command window where PISCC.exe is running. You should see messages such as PISCC Information: 0 : OWPlugIn> Stopping connector: OWPLUGIN PISCC Information: 0 : AFReSyncThread Signaled to start. PISCC Information: 0 : AFReSyncThread Finished queuing. PISCC Warning: 0 : Connector with NAME=OWPLUGIN stopped PISCC Information: 0 : Unloading Connector: OWPLUGIN PISCC Warning: 0 : Exiting Connector: OWPLUGIN PISCC Information: 0 : Connector with NAME=OWPLUGIN exited Then, start the Interface as a Windows Service. You can do so by using the Windows services control panel. To stop PIItronOWListener running interactively, use Control-C in the command window where PIItronOWListener.exe is running. Then, start PIItronOWListener as a Windows Service. 74
Normal Startup Data Collection Loop During steady-state operation, the PIItronOWListener creates XML files from the DataArrived and ExceptionsArrived messages that it receives from OpenWay. In addition, the Interface continuously performs the following actions: parse these XXX_Data.XML and XXX_Exception.XML files; update the value of meter measurement PI points with meter usage data; parse MultiSpeak compliant meterassetxxx.xml files; update AF elements and the attributes of PI points as appropriate; periodically interrogate OpenWay so that it sends DataArrived messages to PIItronOWListener; periodically query OpenWay for meters. Interface Data Files During runtime, the Interface creates the following files: <PI_COLLECTIVE_XX>createtag_queue.0000.dat <PI_COLLECTIVE_XX>createtag_queue_stats.dat <PI_COLLECTIVE_XX>deploytag_queue.0000.dat <PI_COLLECTIVE_XX>deploytag_queue_stats.dat <PI_COLLECTIVE_XX>edittag_queue.0000.dat <PI_COLLECTIVE_XX>edittag_queue_stats.dat <PI_COLLECTIVE_XX>statetable_queue.0000.dat <PI_COLLECTIVE_XX>statetable_queue_stats.dat <PI_COLLECTIVE_XX>tagrequest_queue.0000.dat <PI_COLLECTIVE_XX>tagrequest_queue_stats.dat Meters_<PI_COLLECTIVE_XX>_<Point_Source>_Cache.dat Meters_<PI_COLLECTIVE_XX>_<Point_Source>_PreCache.dat <Name>_<PI_COLLECTIVE_XX>_meters_queue.0000.dat <Name>_<PI_COLLECTIVE_XX>_meters_queue.stats.dat <Name>_<PI_COLLECTIVE_XX>_meters.tbl where <PI_COLLECTIVE_XX>, <AF_Server>, <Point_Source>, and <Name> refer to parameter values within the Source Registry. For example, [CONNECTOR00] NAME=OWPlugIn PI_COLLECTIVE_00=Zeus AF_Server=theAFServer Point_Source=OW result in PI AMI Interface for Itron OpenWay Collection Engine 75
Interface Startup Zeuscreatetag_queue.0000.dat Zeuscreatetag_queue_stats.dat Zeusdeploytag_queue.0000.dat Zeusdeploytag_queue_stats.dat Zeusedittag_queue.0000.dat Zeusedittag_queue_stats.dat Zeusstatetable_queue.0000.dat Zeusstatetable_queue_stats.dat Zeustagrequest_queue.0000.dat Zeustagrequest_queue_stats.dat Meters_Zeus_OW_Cache.dat Meters_Zeus_OW_PreCache.dat OWPlugIn_theAFServer_meters_queue.0000.dat OWPlugIn_theAFServer_meters_queue.stats.dat OWPlugIn_theAFServer_meters.tbl 76
Miscellaneous Features Unknown Meter Files A DataArrived message from OpenWay data file typically contains readings for many meters. For example, The preceding screenshot indicates readings for meters 4003381, 4003382, 4003383, and 4003384. When the Interface parses the corresponding file, it checks whether each meter is present in its local meter table. If so, the Interface stores the meter readings into the appropriate PI tags. However, if the Interface does not find a particular meter in its local meter table, it creates an unknown meter file. This file contains the readings just for this unknown meter. The name of this file indicates the meter id of the meter. For example, 2013_4_2_17_7_9_159_UNK_4003384.xml Later on, the Interface periodically queries OpenWay for meters. When OpenWay returns meter 4003384, the Interface will put this meter into its local meter table. The Interface will then parse this unknown meter file and store the meter readings into PI tags. The purpose for the creation of these unknown meter files is to prevent data loss. If you want to disable this feature of unknown meter file creation, set PI AMI Interface for Itron OpenWay Collection Engine 77
Miscellaneous Features SERIALIZE_UNKNOWN_METERS=NO in the Source Registry. 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 OpenWay Interface checks whether it has parsed a DataArrived or ExceptionsArrived file during the past 60 minutes. If it has not, it raises a fault. You can change this frequency via the Source Registry parameter DATA_HEALTH_CHECK_PERIOD_MINUTES. The default is 60 minutes: [CONNECTOR01] 78
Data Write Method 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. OpenWay Interface Object The name of the OpenWay Interface object comes from the NAME parameter in the Source Registry. For example, NAME=OWPlugin results in a performance counter object name of PISCC_OWPlugIn: Data Write Method The PI_DATA_WRITE parameter in the Source Registry determines the mode with which the Interface writes to a PI Data Archive. These modes are: REPLACE REPLACE APPEND NOREPLACE (default) The Interface can write a value to the PI Data Archive 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, [CONNECTOR00] PI_DATA_WRITE_METHOD=REPLACE PI AMI Interface for Itron OpenWay Collection Engine 79
Miscellaneous Features For example, if the tag OW_734100.Average_voltage already has in the PI archive the event Timestamp Value 10-Jun-2010 15:00:00 234.5 and the Interface sends the following event: Timestamp: 10-Jun-2010 15:00:00 Value: 310.5 the PI archive for this tag will then show only a single event for 10-Jun-2010 15:00:00: Timestamp Value 10-Jun-2010 15:00:00 310.5 APPEND If you want multiple events for the same timestamp, set the PI_DATA_WRITE parameter in the Source Registry to APPEND. Specifically, [CONNECTOR01] PI_DATA_WRITE_METHOD=APPEND For this situation, the PI archive will contain Timestamp Value 10-Jun-2010 15:00:00 234.5 10-Jun-2010 15:00:00 310.5 NOREPLACE You can also configure the Interface such that it does not replace an existing archive event. Use the value of NOREPLACE: [CONNECTOR01] PI_DATA_WRITE_METHOD=NOREPLACE For this situation, if the PI archive already contains the event Timestamp Value 10-Jun-2010 15:00:00 234.5 and the Interface sends the following event: Timestamp: 10-Jun-2010 15:00:00 Value: 310.5 the PI archive for this tag will then show only a single event for 10-Jun-2010 15:00:00: Timestamp Value 10-Jun-2010 15:00:00 234.5 80
Add or Remove Meter Measurements and Attributes Add or Remove Meter Measurements and Attributes You may wish to update the Interface to collect more or less meter data. There are two types of data collection updates you can make: Add a meter measurement or attribute. Remove an existing meter measurement or attribute. Recall that you must define an AF element template for each unique meter type. The AF templates then determine what data are available in the PI system for each instance of a meter. Therefore, the AF element template is one place where you must look to update what meter measurements and attributes are available. How does a particular meter type become associated with an AF element template? You establish this association in the Measurement Mapping configuration file, MeasurementMappings.XML. This configuration file is located in the PISCC directory. The Interface reads it at startup. In this file, you create a direct mapping between the data available for a meter and which subset of these data the Interface stores into PI. This configuration file also includes a mapping between the different meter types and their AF element templates. So, the Measurement Mapping file is another place you must update when you want to add or remove meter measurements or attributes. For example, an AF element template for a particular meter type contains a number of meter measurements. In AF, a meter measurement is represented by a PI point data reference attribute. When you create a PI point data reference attribute, it receives a PI tag assignment. So, when the Interface updates the PI tag for a meter measurement with values from the OW system, you can see these values within AF. AF element attributes also represent meter configuration information. However, unlike meter measurements, meter configuration attributes are represented by static attribute values that most closely represent their native data type. These attribute values live only in the AF technical database. Note: Please refer to the previous section Meters in AF and PI for a complete discussion on data flow between Itron OpenWay and the PI system. Why would you add or remove a meter measurement? You should remove a meter measurement or attribute only if you no longer require a piece of data to be actively updated by the Interface. Conversely, if you want the Interface to collect data for a measurement or attribute that is not currently available in the PI system, you will want to add it to the Interface configuration. How to Add a New Meter Measurement or Attribute Let s start with a simple example. You have configured the Interface to collect data for a single meter measurement. For instance, here is the PI data point for a meter with identifier 1000081: Itron_1000081.Vh(a) PI AMI Interface for Itron OpenWay Collection Engine 81
Miscellaneous Features Now, suppose you wish to add an additional meter measurement: Itron_1000081.Max Vh(a) How would you accomplish this task? Adding a new meter measurement requires four steps: Update the meter s AF element template to include the new measurement or attribute. Update the MeasurementMappings.XML file to include a new mapping between the measurement or attribute and its associated AF attribute template. Update the Source Registry configuration file to enable Measurement Mapping changes. Restart the Interface. Note that in this example we describe adding a new meter measurement. However, the same procedure applies to adding a new meter configuration attribute. Update the Meter s AF Element Template The AF element template associated with a particular meter type defines what data are available for each instance of that meter type. Therefore, the first place you should look to add a new measurement or attribute is the AF element template definition. For the purposes of this example, let s assume we have one meter type with the AF element template OW_Test. Below is a screenshot from PI System Explorer that displays an instance of this meter type in the AF technical database: 82
Add or Remove Meter Measurements and Attributes The first step to adding a meter measurement or attribute is to update its AF element template. You can use PI System Explorer to edit existing AF element templates. The screenshots below show an example of how to update the existing AF element template OW_test to include a new measurement attribute, Max Vh(a).This new measurement attribute template is a PI point data reference. This means that it references a PI tag. PI AMI Interface for Itron OpenWay Collection Engine 83
Miscellaneous Features In this example, we have shown how to add a new meter measurement, which is always represented as a PI point reference attributes. You would follow the same procedure to add a new meter configuration attribute. The difference is that you would choose an AF attribute type that best matches its native data type in the OW system. After editing the AF meter template, you must check-in your changes in order for the new measurements to take effect. You can then proceed to the next task updating the Measurement Mapping configuration file. 84
Add or Remove Meter Measurements and Attributes Update the Measurement Mapping Configuration File You must add an entry to the MeasurementMappings.XML configuration file so that the Interface can map data received from OW to the new meter measurements or configuration attributes that you have added to the AF element template. Below is a sample configuration file. It has a single meter measurement entry. This entry defines the Vh(a) measurement. <Mappings> <OSIsoft:MeterTemplate> <OSIsoft:MappedAFTemplate>OW_TEST</OSIsoft:MappedAFTemplate> <OSIsoft:MeterType>OWMeterB</MeterType > <OSIsoft:TemplateIdentifier>100<OSIsoft:TemplateIdentifier> <OSIsoft:TemplateIdentifier>110<OSIsoft:TemplateIdentifier> <OSIsoft:Measurement> <OSIsoft:PlugIn>MEASFLT00</OSIsoft:PlugIn> <OSIsoft:AFValue>Vh(a)</OSIsoft:AFValue> <OSIsoft:OW><OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfil echannel> </OSIsoft:OW> </OSIsoft:Measurement> </OSIsoft:MeterTemplate> </Mappings> Below is an example of the updated MeasurementMappings.XML file. It includes the new mapping entry for the additional meter measurement Max Vh(a), which you added to the AF Template in the previous step. <Mappings> <OSIsoft:MeterTemplate> <OSIsoft:MappedAFTemplate>OW_TEST</OSIsoft:MappedAFTemplate> <OSIsoft:MeterType>OWMeterB</MeterType > <OSIsoft:TemplateIdentifier>100<OSIsoft:TemplateIdentifier> <OSIsoft:TemplateIdentifier>110<OSIsoft:TemplateIdentifier> <OSIsoft:Measurement> <OSIsoft:PlugIn>MEASFLT00</OSIsoft:PlugIn> <OSIsoft:AFValue>Vh(a)</OSIsoft:AFValue> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfileChann el> PI AMI Interface for Itron OpenWay Collection Engine 85
Miscellaneous Features </OSIsoft:OW> </OSIsoft:Measurement> <OSIsoft:Measurement> <OSIsoft:PlugIn>MEASFLT01</OSIsoft:PlugIn> <OSIsoft:AFValue>Max Vh(a)</OSIsoft:AFValue> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Max Vh(a)</OSIsoft:LoadProfileChannel> </OSIsoft:OW> </OSIsoft:Measurement> </OSIsoft:MeterTemplate> </Mappings> In this example, we have described how to add an entry for a new meter measurement. Note that the procedure to add a new meter configuration attribute would be very similar to the preceding. The only difference is that you would update the configuration file with a new <OSIsoft:Attribute> entry instead of a <OSIsoft:Measurement> entry. Now that you have updated the Measurement Mapping file, you can move to the third step updating the Source Registry configuration file to enable mapping changes. Edit the Source Registry Configuration File At startup the Interface reads the Source Registry configuration file, PISCC.ini, which is located in the PISCC directory. This file contains user specific input parameters such as PI Data Archive names, AF server name, Point Source, and many others. The parameter in the Source Registry that you must set when adding a meter measurement or attribute is ENABLE_MAPPING_CHANGE. That is, [CONNECTOR00] ENABLE_MAPPING_CHANGE=YES The value of YES for this parameter tells the Interface that a measurement or attribute has been added or removed. As a result, the Interface will walk its local meter table and update each meter with the new configuration. The Interface does this on startup before it begins processing new data updates. The Interface will also update each meter record in AF to reflect the new configuration. If you update the AF template and the Measurement Mapping file, but do not enable this parameter on startup, then the Interface applies the new attributes and measurements to new meters only. That is, the Interface will not add the new attributes or measurements to existing meters. After updating the Source Registry to enable mapping change, you are ready to execute the final step restart the Interface. 86
Add or Remove Meter Measurements and Attributes Restart the Interface At startup, when the Interface sees the value of YES for the ENABLE_MAPPING_CHANGE parameter, it will update the Source Registry to indicate that it is processing the mapping change. [CONNECTOR00] ENABLE_MAPPING_CHANGE=PROCESSING After the Interface has successfully updated all existing meters with the new mapping, it writes to the Source Registry with the following status: [CONNECTOR00] ENABLE_MAPPING_CHANGE=COMPLETED If the Interface fails to process the mapping change, it writes to the Source Registry with this status: [CONNECTOR00] ENABLE_MAPPING_CHANGE=FAILED The Interface attempts to apply mapping changes to individual meters before it begins processing new data updates. The time required to process new meter attributes or measurements depends on factors such as Total meter count. In general, the larger the meter count the more time required to process the mapping change. Number of attributes or measurements added. The Interface must apply these changes to each individual meter. In general, adding measurements will take longer to process than removing existing ones. If adding meter measurements the Interface will likely need to create additional PI points. Creating PI points requires being connected to the PI Data Archive. PI Data Archive response times for point creation will also impact the time required to process mapping changes. Note that if the Interface fails to process the mapping change fails for any reason, it will shut down. You must investigate and resolve issues before the Interface can successfully start up and begin data collection. How to Remove an Existing Meter Measurement or Attribute You may decide that you no longer require a meter measurement or attribute to be updated. This section describes how to configure the Interface so that it no longer collects data for a particular meter measurement or meter attribute. The previous section, How to Add a New Meter Measurement, described a meter with two measurements: Itron_1000081.Vh(a) Itron_1000081.Max Vh(a) Now, suppose you wish to configure the Interface such that it does not update one of these two meter measurements. How would you accomplish this task? PI AMI Interface for Itron OpenWay Collection Engine 87
Miscellaneous Features Removing an existing meter measurement or configuration attribute from the Interface update list requires four steps: Update the meter s AF element template, removing the undesired measurement or attribute. Update the MeasurementMappings.XML file such that the undesired measurement or attribute mapping is removed. Update the Source Registry configuration file to enable Measurement Mapping changes. Restart the Interface. Note that in this example we describe removing an existing meter measurement. However, the same basic procedure applies to removing an existing meter configuration attribute. Update the Meter s AF Element Template The AF element template associated with a particular meter type defines what data are available for each instance of that meter. Therefore, the first place you should look to remove an existing measurement or attribute is the AF element template definition. For the purposes of this example let s assume we have one meter type with the AF element template OW_test. Below is a screenshot from PI System Explorer that displays an instance of this meter type in the AF technical database: The first step to removing an existing meter measurement or attribute is to update its AF element template. You can use PI System Explorer to edit existing AF element templates. 88
Add or Remove Meter Measurements and Attributes The screenshots below show an example of how to update the existing AF element template OW_Test to exclude the existing attribute template, Max Vh(a). Note that deleting the PI point data reference from the AF element template does not delete the PI tag itself. The PI tag and historical meter data associated with that meter measurement are preserved within the PI system. In this example, we have shown how to remove an existing meter measurement. You would follow the same procedure to remove an existing meter configuration attribute. That is, use PI System Explorer to delete the attribute. After editing the AF meter template, you must check-in your changes. You can then proceed to the next task updating the Measurement Mapping configuration file. Update the Measurement Mapping Configuration File In the MeasurementMappings.XML file, you must remove the matching mapping entry for the meter measurement that you have deleted from the AF element template. Below is a sample configuration file. The initial Measurement Mapping configuration has entries for two meter measurements: Vh(a) and Max Vh(a) <Mappings> <OSIsoft:MeterTemplate> <OSIsoft:MappedAFTemplate>OW_TEST</OSIsoft:MappedAFTemplate> <OSIsoft:MeterType>OWMeterB</MeterType > <OSIsoft:TemplateIdentifier>100<OSIsoft:TemplateIdentifier> PI AMI Interface for Itron OpenWay Collection Engine 89
Miscellaneous Features <OSIsoft:TemplateIdentifier>110<OSIsoft:TemplateIdentifier> <OSIsoft:Measurement> <OSIsoft:PlugIn>MEASFLT00</OSIsoft:PlugIn> <OSIsoft:AFValue>Vh(a)</OSIsoft:AFValue> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfileChannel> </OSIsoft:OW> </OSIsoft:Measurement> <OSIsoft:Measurement> <OSIsoft:PlugIn>MEASFLT01</OSIsoft:PlugIn> <OSIsoft:AFValue>Max Vh(a)</OSIsoft:AFValue> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Max Vh(a)</OSIsoft:LoadProfileChannel> </OSIsoft:OW> </OSIsoft:Measurement> </OSIsoft:MeterTemplate> </Mappings> The above mapping configuration shows that meter types with a matching template identifier will be created in the PI system using the AF element template OW_test. This AF element template defines two meter measurements - Vh(a) and Max Vh(a). Please see the previous section Measurements Configuration File for a detailed description of how to configure MeasurementMappings.XML. Below is an example of an updated MeasurementMappings.XML file with the mapping for meter measurement Max Vh(a) removed. The configuration file now contains only a single mapping entry; it is for the measurement Vh(a). <Mappings> <OSIsoft:MeterTemplate> <OSIsoft:MappedAFTemplate>OW_Test</OSIsoft:MappedAFTemplate> <OSIsoft:MeterType>OWMeterB</MeterType > <OSIsoft:TemplateIdentifier>100<OSIsoft:TemplateIdentifier> <OSIsoft:TemplateIdentifier>110<OSIsoft:TemplateIdentifier> <OSIsoft:Measurement> <OSIsoft:PlugIn>MEASFLT00</OSIsoft:PlugIn> <OSIsoft:AFValue>Vh(a)</OSIsoft:AFValue> <OSIsoft:OW> <OSIsoft:LoadProfileChannel>Vh(a)</OSIsoft:LoadProfileChannel> </OSIsoft:OW> </OSIsoft:Measurement> </OSIsoft:MeterTemplate> 90
Add or Remove Meter Measurements and Attributes </Mappings> In this example, we have described how to remove an entry for an existing meter measurement. Note that the procedure to remove an existing meter attribute is very similar to the preceding. The only difference is that you would update the configuration file to remove an <OSIsoft:Attribute> entry instead of a <OSIsoft:Measurement> entry. Now that you have updated the Measurement Mapping file, you can move to the third step updating the Source Registry configuration file to enable mapping changes. Edit the Source Registry Configuration File At startup the Interface reads the Source Registry configuration file, PISCC.ini, which is located in the PISCC directory. This file contains user specific input parameters such as PI Data Archive names, AF server name, Point Source, and many others. The parameter in the Source Registry that you must set when adding a meter measurement or attribute is ENABLE_MAPPING_CHANGE. That is, [CONNECTOR00] ENABLE_MAPPING_CHANGE=YES If you update the AF template and the Measurement Mapping file, but do not enable this parameter on startup, then the Interface applies the updated attributes and measurements to new meters only. That is, the Interface will not add the updated attributes or measurements to existing meters. After updating the Source Registry to enable mapping change, you are ready to execute the final step restart the Interface. Restart the Interface At startup, when the Interface sees the value of YES for the ENABLE_MAPPING_CHANGE parameter, it will update the Source Registry to indicate that it is processing the mapping change. [CONNECTOR00] ENABLE_MAPPING_CHANGE=PROCESSING After the Interface has successfully updated all existing meters with the new mapping, it writes to the Source Registry with the following status: [CONNECTOR00] ENABLE_MAPPING_CHANGE=COMPLETED If the Interface fails to process the mapping change, it writes to the Source Registry with this status: [CONNECTOR00] ENABLE_MAPPING_CHANGE=FAILED The Interface attempts to apply mapping changes to individual meters before it begins processing new data updates. The time required to process new meter attributes or measurements depends on factors such as Total meter count. In general, the larger the meter count the more time required to process the mapping changes. PI AMI Interface for Itron OpenWay Collection Engine 91
Miscellaneous Features Number of attributes or measurements removed. The Interface must apply these changes to each individual meter. Note that if the Interface fails to process the mapping change for any reason, it will shut down. You must investigate and resolve issues before the Interface can successfully start up and begin data collection. Rename Existing Meter Measurements and Attributes You may decide that you want to change the name of an existing meter measurement or attribute. Recall that you define an AF element template for each unique meter type. In AF, a meter measurement is represented by a PI point data reference attribute. When you create a PI point data reference attribute, it receives a PI tag assignment. Therefore, the AF element template is one place where you must look to update the naming of meter measurements and attributes. How does a particular meter type become associated with an AF element template? You establish this association in the Measurement Mapping user configuration file, MeasurementMappings.XML. This configuration file is located in the PISCC directory. The Interface reads it at startup. In this file, you create a direct mapping between the data available for a meter and which subset of these data the Interface stores into PI. This configuration file also includes a mapping between the different meter types and their AF element templates. So, the Measurement Mapping configuration file is a file you must update to change the name of a meter measurement or attribute. Why would you rename a meter measurement or attribute? If you rename a meter measurement or a configuration attribute, the data associated with the measurement or attribute will not change. However, you may decide that a new name is more suitable. For example, the new name might make meter data easier for you to locate in searches, or help you better interpret the data by providing more context. How to Rename Meter Measurements in PI or AF Let s start with a simple example. You have configured the Interface to collect data for a single meter measurement. For instance, here is the PI data point for the measurement of a meter with ID 1000081: Itron_1000081.ins V(a) Now, suppose you wish to rename this meter measurement to be: Itron_1000081.Vh(d) How would you accomplish this task? Renaming an existing meter measurement or attribute requires four steps: Update the meter s AF element template, editing the existing measurement or attribute from the old name to the new one. Update the MeasurementMappings.XML file to include the new name for the measurement or attribute that you have edited in the AF element template. 92
Rename Existing Meter Measurements and Attributes Update the Source Registry configuration file to enable Tag Rename changes. Restart the Interface. Note that in this example we describe how to rename an existing meter measurement. However, the same basic procedure applies to the renaming of a meter attribute. Update the Meter s AF Element Template The AF element template associated with a particular meter type defines what data are available for each instance of that meter type. Therefore, the first place you should look to rename a new measurement or attribute is the AF element template definition. For the purposes of this example let s assume we have one meter type with the AF element template OW_Test. Below is a screenshot from PI System Explorer that displays an instance of this meter type in the AF technical database: The first step to rename a meter measurement or attribute is to update the AF element template. You can use PI System Explorer to edit existing AF element templates. The screenshots below show an example of how to rename an existing attribute in the AF element template OW_Test. Note that the example shows a meter measurement attribute, which is a PI point data reference. This means that the AF attribute references a PI tag. However, the process of updating the AF element template does not rename the PI tag itself. PI AMI Interface for Itron OpenWay Collection Engine 93
Miscellaneous Features 94
Rename Existing Meter Measurements and Attributes In this example, we have shown how to rename an existing meter measurement in AF. You would follow the same procedure to rename an existing meter attribute. That is, edit the AF element template, editing the attribute of interest with the new name. After editing the AF meter template, you must check-in your changes in order for the new attribute name to take effect. You can then proceed to the next task updating the Measurement Mapping configuration file. Update the Measurement Mapping Configuration File You must update the matching mapping entry for the meter measurement that you renamed in the AF element template. The following Measurement Mapping configuration has a single entry for the meter measurement ins V(a). It has not yet been updated for the new meter measurement name. <Mappings> <OSIsoft:MeterTemplate> <OSIsoft:MappedAFTemplate>OW_TEST</OSIsoft:MappedAFTemplate> <OSIsoft:MeterType>OWMeterB</MeterType > <OSIsoft:TemplateIdentifier>100<OSIsoft:TemplateIdentifier> <OSIsoft:TemplateIdentifier>110<OSIsoft:TemplateIdentifier> PI AMI Interface for Itron OpenWay Collection Engine 95