Technical Bulletin Issue Date October 3, 2003 Using M-Collector Using M-Collector...2 Introduction... 2 Key Concepts... 3 M-Collector... 3 Configuration... 3 Runtime Display...4 Maximum Capacity... 6 Collection Types...6 Historian Database... 6 Activity and Error Log Files... 7 Failure and Rescheduling... 8 Remote Connections... 8 Detailed Procedures... 9 Configuring Data Sources... 9 Configuring Data Storages... 10 Configuring Groups... 11 Starting or Stopping All Trend Collection... 16 Starting or Stopping Group Trend Collection... 16 Auto Starting Trend Collection... 16 Reference Tables... 17 Configuration Parameters... 17 2003 Johnson Controls, Inc. www.johnsoncontrols.com Code No. LIT-1153700 Software Release 5.3
2 Using M-Collector Technical Bulletin Using M-Collector Introduction The M-Collector collects time series data (trend data) into a common historian database from a set of OLE for Process Control (OPC) Data Access (DA) servers that connect to devices such as N30 Supervisory Controllers and Companion/Facilitator panels (panel units). M-Trend and other Open Database Connectivity (ODBC) compliant energy analysis applications, such as Visual Basic applications or spreadsheet applications, use the common historian database for analysis or further processing. This chapter describes how to: configure data sources configure data storages configure groups start or stop all trend collection start or stop group trend collection auto start trend collection
Using M-Collector Technical Bulletin 3 Key Concepts M-Collector The M-Collector collects trend data into a database from a set of OPC DA servers that connect to supervisory controllers. M-Collector uses a scheduled pull mechanism of trend data from supervisory controllers archiving the data samples into historian databases. In other words, at a specified time, the M-Collector application retrieves trend data as opposed to the devices sending trend data to M-Collector. Figure 1 is an overview of the M-Collector. Supervisory Controller Historian Database Query ODBC Client Applications Read Read M-Collector Write Write Supervisory Controller Historian Database Query ODBC Client Applications (M-Trend) Configuration Database Field Devices (N30s, for example) M-Collector Collecting the Data Storing the Data in M-Historian Files Viewing the Data (M-Trend, for example) M-collector Figure 1: M-Collector Overview Configuration To use M-Collector, users must configure: data sources - list of online OPC DA servers data storages - list of available historian databases that can record samples groups - associations between points for which trend data is collected and historian databases and the scheduled times and days for trend data collection The collection information is stored in the configuration database, M-Collector.config.mdb.
4 Using M-Collector Technical Bulletin Runtime Display When M-Collector is running, the main window shows all current collections in progress (Figure 2). Each line represents a collection group scheduled for the current day. If a group collection is in progress and it is periodic, the next scheduled collector event for that group appears in the list. Table 1 lists possible group statuses. Figure 2: M-Collector Listing Collection Activities for the Current Day Table 1: Group Status Status Ready Initializing Connecting Disconnecting Receiving Saving Terminating Description Ready to execute at the scheduled time Initializing its internal state and acquiring resources needed for collecting data Connecting to an offline device; it could be dialing a remote site Disconnecting from a device Receiving data from data source servers Saving data into a historian database Terminating and releasing resources
Using M-Collector Technical Bulletin 5 Data Source Note: A data source name is a program ID of an OPC DA server available in the system in which the M-Collector is running. Example program IDs of OPC DA servers are: JC.BNOPC: for the BACnet compliant JCI BN OPC DA server for communicating with N30 Supervisory Controllers and third-party BACnet devices JC.LNOPC: for the LONWORKS compliant JCI LN OPC DA server for communicating with LONMARK compliant devices JC.CFOPC: Companion/Facilitator OPC DA server for communicating with Companion controllers JC.NCTrend is included with Facility Explorer for Total Energy Management Data Storages Data storages are ODBC Data Source Names (DSNs) available in the system in which M-Collector is running. Examples are SQL Historian and Microsoft Access Historian. Note: The Microsoft Access Historian database limit is.99 GB. Tag A tag is a string of characters that identifies a data point. This string follows the OPC DA convention for tag names. For the N30 Supervisory Controllers (JC.BNOPC DA server), the information included in the string is site name, point name, and point attribute. For example: @507Michigan:N30A:OutdoorTemperature.Present Value The tag above identifies an object controlled by the N30A device that stores the value of the outdoor temperature at the 507 Michigan site. M-Collector configuration window has a browser to allow navigation and selection of tag names. Note: Data coming in from M-Collector and CF Connect, if both are writing to the same historian database, may show up as different tag names, although it is the same tag. By default, M-Collector puts @Sitename: in front of the tag name and CF Connect does not. This problem is prevented by using the single trend collection database option in CF Connect where the @Sitename: prefix is used. Group A group is a set of tags with the same parameters such as collection time, period rate, time stamp options. Each group must have a unique
6 Using M-Collector Technical Bulletin name. Tags can belong to one or more groups. A group should collect only from tags within a single site. Configuration Database A configuration database is a set of logical tables containing M-Collector configuration settings. The configuration database is used to set the behavior and the activity of the M-Collector. Maximum Capacity M-Collector s capacity limit depends on the computer s processor, memory, and the frequency of trend data collection. If users try to add groups or tags and the system runs out of memory, M-Collector reports an error in the error log file. The tested limit is 20 groups and 100 tags per group for a total of 2,000 tags with a 60-second period. Collection Types Different data sources support different trend data collection types. There are two major types of collections: buffered collection - reading data from the buffer of a device (local sampling by the supervisory controller) snapshot collection - reading the current value of data points at a particular time (M-Collector reads the current value via OPC DA Server.) The BN OPC DA server supports both snapshot and buffered collections (tag values stored in a trend log buffer associated with data points). The Companion/Facilitator OPC server supports only snapshot collection. The CF Connect application can be used to read the buffers from the Companion/Facilitator panels. Use the N1 Trend Collector application to read the buffers from the Network Control Modules. Historian Database Trend data collected from multiple sources is stored in either one database or multiple databases. When the historian database has no space available, the M-Collector displays an error message and the collection stops. For M3 Workstation and M5 Workstation, the Microsoft Access database is installed with M-Collector, but the configuration database is designed to support other database systems. The SQL Historian installation CD installs M-Collector on the same computer as the SQL Historian.
Using M-Collector Technical Bulletin 7 Activity and Error Log Files Collection activities record into a log file called M-Collector.Log.yymm.txt, where yy is the last two digits of the year and mm is the month of the activities. All error messages are stored in M-Collector.Error.yymm.txt. By default, only the error log is turned on, and the activity log is turned off. In most cases, the user needs to inspect only the error file to determine whether the M-Collector is working properly. If needed, use the registry editor to turn on and off the log files. Failures are noted by a counter in the runtime display. The log file is a text file with the following format: <date> <time> <flag> <description> <zero or more lines of additional description> Where <flag> can be Success:, Failure:, or Cancelled:, and <description> contains information about tags, groups, site name, and other related information. For example: 12/01/99 13:40:58 Failure: BN Snap1 at 12/01/99 13:40:58; It was still receiving. 12/01/99 13:41:00 Success: BN Snap1 at 12/01/99 13:40:53; 12/01/99 13:41:03 Failure: BN Snap1 at 12/01/99 13:41:08; It was still initializing. 12/01/99 13:41:03 Success: BN Snap1 at 12/01/99 13:41:03; 12/01/99 13:42:50 Success: BN Buffered Collection at 12/01/99 13:42:50; 12/01/99 13:42:53 Success: BN Snap1 at 12/01/99 13:42:53; 12/01/99 13:42:55 Success: BN Buffered Collection at 12/01/99 13:42:55; 12/01/99 13:42:58 Success: BN Snap1 at 12/01/99 13:42:58; These failures would indicate the period specified for collection is too fast for the OPC DA servers and/or the historian database to keep up. OPC DA servers may have limitations that could prevent the successful trend data collection given the desired schedule. The Companion/Facilitator OPC DA server is limited to one connection at a time, and modem connection must be accounted for. The BN OPC DA server also has limits, including one connection for each service port or modem and a maximum of two simultaneous connections over Ethernet.
8 Using M-Collector Technical Bulletin Failure and Rescheduling If M-Collector fails to collect data, the collection is retried. In the Groups dialog box, users determine the number of times to reschedule and minutes between retries (Figure 6). The default is rescheduled five minutes later with a maximum of three retries before stopping and reporting an error to the activity log. A collection stops if any of the following happens: Collection has been tried t times (as defined in the Groups dialog box [see Figure 6]). Time of the retry is equal to or larger than the time of the next scheduled collection. Reset time is reached. User terminates the collection. User exits the system. Remote Connections M-Collector supports connecting to remote sites for the BN and Companion/Facilitator OPC DA servers. If the desired site connection is not established at the time of collection, M-Collector first connects to the site, collects the defined samples, and then disconnects. M-Collector can remotely connect up to two sites at the same time through the BN OPC DA server and one site through the Companion/Facilitator OPC DA server. Do not mix tags from different remote sites together in the same group. The first tag in the list indicates which remote site is connected, and any subsequent tags from a different remote site will not have data collected.
Using M-Collector Technical Bulletin 9 Detailed Procedures Configuring Data Sources To configure data sources: 1. Select Start > Programs > Johnson Controls > M-Collector. The M-Collector application dialog box appears (Figure 3). Figure 3: M-Collector Application Dialog Box 2. Select Configure > Data Sources. The Data Sources dialog box appears (Figure 4).
10 Using M-Collector Technical Bulletin Figure 4: Data Sources Dialog Box 3. Select the data source you want M-Collector to use. 4. Click < to move the selected data sources. Click << to move all the data sources. 5. Click > to remove a single data source. Click >> to remove all the data sources. 6. Click Save. Configuring Data Storages To configure data storages: 1. Select Start > Programs > Johnson Controls > M-Collector. The M-Collector application appears (Figure 3). 2. Select Configure > Data Storages. The Data Storages dialog box appears (Figure 5).
Using M-Collector Technical Bulletin 11 Figure 5: Data Storages Dialog Box 3. Select the data storages you want M-Collector to use. 4. Click < to move the selected data storage. Click << to move all the data storages. 5. Click > to remove a single data storage. Click >> to remove all the data storages. 6. Click Save. Note: Use only qualified historian databases. The Access Historian database is installed with M-Collector. To use multiple Access Historian databases, copy the trend.mdb file from the Access Historian installation directory, add an ODBC data source name to the new file. Configure data storages in M-Collector. Refer to M-Trend User s Manual to connect M-Trend to the databases. Configuring Groups To configure groups: 1. Select Start > Programs > Johnson Controls > M-Collector. The M-Collector application dialog box appears (Figure 3). 2. Select Configure > Groups. The Groups dialog box appears (Figure 6).
12 Using M-Collector Technical Bulletin Figure 6: Groups Dialog Box 3. Click Add. 4. Enter a Group name to uniquely identify each group. Click OK. 5. Use Table 2 to fill in the fields.
Using M-Collector Technical Bulletin 13 Table 2: Groups Dialog Box Fields Field Data Source Type Name Tags Data Storages Name Collection Time Start Period Rate Days Time Stamp Device Time Zone Max Retries Retry Delay Description Lists available data source types based on the OPC server. Options include Snapshot and Trend Log for JC.BNOPC. Lists OPC DA server used for trend collection. Lists OPC attributes from which to collect trend data. Refer to Deleting a Tag Associated with a Group, Adding a Tag to a Group, and Changing Tag Properties for details. Lists ODBC data source name defined in Configuring Data Storages. Lists time to start collection. Lists frequency of trend collection. Lists days to collect trend data. Note: When setting collection time, note that up to two sites can be connected at the same time through BN OPC DA server and one site through Companion/Facilitator OPC server. Determines in which time stamp format the data is stored: Universal Time Coordinated (UTC) or local time. Use UTC if the data is being collected from sites in different time zones. Lists available time zones. Select the right time zone for the device from which data is being collected. Lists number of attempts to retrieve the trend data. After the maximum retries listed here, an error message is sent to the error and activity log file. Lists number of minutes between retries. Range is 0-1440. Default is 5 minutes. 6. Click Close.
14 Using M-Collector Technical Bulletin Adding a Tag to a Group To add a tag to a Group: 1. Select Start > Programs > Johnson Controls > M-Collector. The M-Collector application dialog box appears (Figure 3). 2. Select Configure > Groups. The Groups dialog box appears (Figure 6). 3. Select the group. 4. Click the Add Tag button. The Add Tag dialog box appears (Figure 7). Figure 7: Add Tag Dialog Box 5. Browse through the hierarchy and select a tag. 6. Click OK. Deleting a Tag Associated with a Group To delete a tag associated with a group: 1. Select Start > Programs > Johnson Controls > M-Collector. The M-Collector application dialog box appears (Figure 3). 2. Select Configure > Groups. The Groups dialog box appears 3. Select the group.
Using M-Collector Technical Bulletin 15 4. Select the tag. 5. Click the Delete Tag button. Changing Tag Properties To change tag properties: 1. Select Start > Programs > Johnson Controls > M-Collector. The M-Collector application dialog box appears (Figure 3). 2. Select Configure > Groups. The Groups dialog box appears (Figure 6). 3. Select the tag. 4. Click the Properties button. The Tag Properties dialog box appears (Figure 8). Figure 8: Tag Properties Dialog Box 5. Edit the fields described in Table 3. Table 3: Tag Properties Field Field Tag Name Tag Alias Dead Band Value Description Lists the selected tag. This field is not editable. Allows users to save a tag with a different name. Determines whether another value is collected based on how close that value is to the current sample. For example, if saving energy consumption only differs by more than 5 from the previous value, set the deadband value to 5. 6. Click OK. Note: Shorten long Tag Names using Tag Alias, thereby making it easier to use the tag in M-Trend.
16 Using M-Collector Technical Bulletin Starting or Stopping All Trend Collection To start or stop all trend collection: 1. Select Start > Programs > Johnson Controls > M-Collector. The M-Collector application appears (Figure 3). 2. Select Collection > Start or Collection > Stop. Starting or Stopping Group Trend Collection To start or stop one or more groups from trend collection: 1. Select Start > Programs > Johnson Controls > M-Collector. The M-Collector application appears (Figure 3). 2. Select Configure > Groups. The Groups dialog box appears (Figure 6). 3. Select the Group s name and select or clear days. Auto Starting Trend Collection To auto start trend collection: 1. Make a shortcut to the M-Collector program in the Windows Startup folder. 2. Right click on the shortcut and select properties. 3. Add the /c command line parameter to the end of the M-Collector Target line. Example: C:\Program Files\Johnson Controls\M-Collector\mcollector.exe /c Note: Be sure to enter a space before /c. Include quotation marks in the Target line. 4. Select minimized in the Run pull-down window. 5. When the computer reboots, M-Collector automatically starts up in minimized mode. Notes: If the time/date on the workstation Personal Computer (PC) is modified backwards, M-Collector stops saving samples retrieved from trend collection to the database. Shut down and restart M- Collector to begin sampling again. If the time/date on the workstation PC must be changed backwards, shut down M-Collector before changing the time/date. Then restart M- Collector.
Using M-Collector Technical Bulletin 17 Reference Tables Configuration Parameters The following parameters are for global use and are not specific for a tag or a group. We recommend using the default values. The values may be adjusted to match the performance of the PC hardware and software. The parameter values are stored in the system registry under key: Table 4: Parameter Table HKEY_LOCAL_MACHINE\SOFTWARE\Johnson Controls\ M-Collector\Settings Field Name Type Size Default Description Reset Time Date/Time 4 00:10:00 The time M-Collector clears up unsuccessful collections and restarts fresh collections each day (HH:mm:ss). Read Timeout Integer 4 240,000 Delay to wait for reading values from an OPC server (milliseconds). Dial Timeout Integer 4 300,000 Delay to wait for a dialing process (milliseconds). Companion/Facilitator panels need more than three minutes to upload its compan.db. Log Activities Integer 4 0 Log activities into file M-Collector.Log.yymm.txt. (1 = yes, 0 = no) Log Errors Integer 4 1 Log error messages into file M-Collector.Error.yymm.txt. (1 = yes, 0 = no) Maximum Number of Rows for Status Table Thread Max Number Thread Waiting Time Thread Waiting Time Total OPC Group Life Time Integer 4 25 Maximum number of rows for status table. Integer 4 23 Maximum number of collections/thread running at the same time. Integer 4 10,000 Delay to request for another thread after maximum number of thread was reached. (milliseconds) Integer 4 14,400,000 Total delay to request for another thread after maximum number of thread was reached. (milliseconds) Integer 4 2 00:00:01 Lifetime of OPC groups. OPC groups are removed if this value is less than the collection group period rate. (days hh:mm:ss) Controls Group 507 E. Michigan Street P.O. Box 423 Milwaukee, WI 53201 www.johnsoncontrols.com Printed in U.S.A.