Version 1.2.1Version 1.2.1

User ManualUser Manual

Plantstreamer® 1.2.1 User Manual

1st of February 2010

Copyright © 2010 by Ciengis, Sistemas de Controlo Avançado, SA.

Ciengis

IPN, Rua Pedro Nunes

3030-199 Coimbra

PORTUGAL

Table of Contents

1 About Plantstreamer....................................................................................................1

2 System Requirements..................................................................................................3

3 How to install...............................................................................................................4

3.1 Microsoft Windows................................................................................................4

3.2 Linux (Ubuntu)......................................................................................................4

3.2.1 Option I – Add the Plantstreamer repository to the sources list.....................4

3.2.2 Option II - Download and install the .deb file manually.................................4

3.3 Alternative installation..........................................................................................5

4 How to compile............................................................................................................6

5 How to use...................................................................................................................7

5.1 OPC server connection.........................................................................................7

5.2 Adding additional connections..............................................................................8

5.3 Selecting OPC items.............................................................................................9

5.4 Manually adding OPC items................................................................................10

5.4.1 Adding OPC items........................................................................................11

5.4.2 Finding OPC items.......................................................................................11

5.5 Composite tags...................................................................................................12

5.6 Saving/loading configurations............................................................................13

5.7 Logging data.......................................................................................................13

5.8 Exporting the OPC item list.................................................................................14

6 Output back-ends......................................................................................................15

6.1 PostgreSQL database..........................................................................................15

6.1.1 Connection to the PostgreSQL server..........................................................15

6.1.2 Export into CSV files....................................................................................16

6.1.3 Import tag selection....................................................................................17

6.2 Text files.............................................................................................................17

6.2.1 Advanced options............................................................................................18

Plantstreamer®

1 About Plantstreamer

Plantstreamer is a multi-platform software designed to log data from a plant control

system using OPC-DA v2.0 and store it into a persistent back-end.

Currently there are two different back-end choices:

PostgreSQL database;

Text file (e.g. Comma-Separated Values).

The main features of Plantstreamer 1.2.1 are:

Free and open source software;

Multi-platform user interface;

Connection to the OPC server using the OPC-DA standard protocol v2.0;

Synchronous and asynchronous data retrieval from the OPC Server;

Connection to redundant OPC servers upon failure of the main server;

User generated composite tags;

Easy selection of tags:

from the OPC server list;

manual input;

Loading/saving from/to an XML file.

The data is stored periodically in the back-end with a user defined time period.

The database back-end requires a connection to a PostgreSQL database, a

powerful and open source SQL database system. It is an ideal solution for large

amounts of data where the stored data may be accessed using any of the PostgreSQL

supported protocols, such as ODBC and JDBC. Additionally, it is possible to export the

data from the database into a CSV file using Plantstreamer itself.

Plantstreamer® 1.2.1 User Manual 1

Plantstreamer®

Alternatively, the text back-end may be chosen and Plantstreamer will write

directly to a text file. This may be useful for small amounts of data, since it usually

produces large files when compared to the spaced taken by the database. The text file

back-end can create Comma-Separated Values (CSV) files, a common file format that

may be opened on almost any spreadsheet software.

Plantstreamer® 1.2.1 User Manual 2

Plantstreamer®

2 System Requirements

The following requirements are needed to run Plantstreamer:

Java JRE from Sun Microsystems version 1.6 or higher;

Hardware requirements are the same as those required to run Java VM;

An OPC compliant server with the OPC-DA 2.0 support;

PostgreSQL version 8.1 or higher.

Plantstreamer® 1.2.1 User Manual 3

Plantstreamer®

3 How to install

Please choose the installation process for your operating system in the following

sections.

3.1 Microsoft Windows

Download the newest windows executable from the Plantstreamer web page:

http://www.plantstreamer.com/

Click the executable and follow the installation steps.

3.2 Linux (Ubuntu)

Plantstreamer was tested with Ubuntu 9.4 (Jaunty Jackalope), nevertheless it should

also work with any Debian derivative Linux distribution. If you have a different

distribution please follow the instructions in the Alternative installation.

There are two ways of installing Plantstreamer:

3.2.1 Option I – Add the Plantstreamer repository to the sources list

1. Add the following line to the “/etc/apt/sources.list" file:

deb http://ciengis.com/plantstreamer/files/software/bin/Debian/ ./

2. Install Plantstreamer, as root:

apt-get update;

apt-get install plantstreamer

3.2.2 Option II - Download and install the .deb file manually

1. Download the newest .deb file from the Plantstreamer web page:

http://www.plantstreamer.com/

2. Install the .deb as root:

dpkg -i plantstreamer_1.2.1-1.deb;

apt-get -f install

To start Plantstreamer just execute the following command:

Plantstreamer® 1.2.1 User Manual 4

Plantstreamer®

plantstreamer

3.3 Alternative installation

Download the Plantstreamer jar bundle from the download section of the Ciengis®

web page and unzip the content into a local directory. Plantstreamer may be started

either by clicking the file Plantstreamer.jar (Windows) or by running the file with the

following command in the same folder:

java -jar Plantstreamer.jar

This installation method will not install any Plantstreamer files in your system,

therefore if you wish to remove it you can just delete the Plantstreamer directory.

Plantstreamer® 1.2.1 User Manual 5

Plantstreamer®

4 How to compile

This section is aimed at developers who want to build Plantstreamer from its

sources, regular users should skip this section.

In order to compile Plantstreamer it is required the Java Development Kit (JDK) from

Sun Microsystems version 1.6 or higher and Apache Ant version 1.7. It is

recommended the usage of the NetBeans IDE in order to define the libraries and their

paths.

Plantstreamer uses he following libraries and their dependencies:

Library Description

SwingX 1.0 Extensions to the Swing GUI toolkit

Substance 5.3 Configurable and customizable production-quality Java look and feel library for Swing applications

Utgard Independent OPC-DA libraries for Java

Jasypt 1.5 Java encryption library

Communications Abstract connection handling library

DBCom PostgreSQL connection handling library

OPCCom OPC connection handling library

CommonSwingExtras Collection of useful classes for Swing graphical user interfaces

OPC2Out Library for reading data from an OPC server and storing it in a backend

Additionally, there is a patch that must be applied to the Utgard library (openscada-

lib). It is available at the Plantstreamer web site.

Once the patch is applied and the libraries defined go to the Plantstreamer project

folder and compile it by issuing the following command:

ant build.xml

Plantstreamer® 1.2.1 User Manual 6

Plantstreamer®

5 How to use

Plantstreamer has an extremely easy mode of operation allowing the user to have it

up and running with a few simple steps:

1 When Plantstreamer is launched the OPC connection (Picture 1) dialog is

displayed. Define the connection properties and establish a connection to the

OPC server.

2 If there are redundant servers available, add then using the Connection Manager

dialog (Picture 2).

3 Select the relevant tags that need to be logged from the tree-table item list

(Picture 3).

4 Select the desired output back-end and edit its configuration options.

5 Define the sampling rate (Picture 9) and then just press the “Start Logging”

button.

Please read the following sections to gain a deeper insight about the Plantstreamer

user interface.

5.1 OPC server connection

In order to connect to the OPC server, if not already open, the OPC connection

dialog can be opened by going to:

Actions -> Connect to OPC.

Plantstreamer® 1.2.1 User Manual 7

Picture 1: OPC connection dialog.

Plantstreamer®

To establish a connection make sure the OPC Server is reachable through your

network and follow the steps:

1 Insert the OPC server credentials in the dialog;

2 Press the refresh button next to the server list to retrieve the available OPC

servers;

3 Select the desired server

4 Press Connect.

5.2 Adding additional connections

In order to increase the reliability of the logging process, additional OPC servers and

PostgreSQL databases can be added to the list of connections. These redundant

servers will allow Plantstreamer to reestablish connections to new servers when the

communication with current server fails.

To add more servers servers go to the connection manager:

Window -> Connection Manager.

Use the add button to insert new connections in the connection list. The Up and

Down buttons allows to define the order in which the connections are used by

Plantstreamer.

Plantstreamer® 1.2.1 User Manual 8

Picture 2: Connection manager dialog.

Plantstreamer®

Note: The connection manager allows to define these additional connections, but it

does not check if these servers are truly redundant. Please make sure that the connection

information actually points to redundant servers.

5.3 Selecting OPC items

Once the connection to the OPC server is established, the list of OPC items is

retrieved from the server.

Note: if the OPC server does not support browsing it may not be possible to fetch

the list of tags. In such case, please refer to the “Manually adding OPC items” section.

Note: Item properties are not automatically retrieved from the OPC server. Select

any tag and the available properties will be fetched from the OPC server.

The are several icons in the tree-table:

Icon Meaning

Root folder containing the OPC items received from the server

OPC item branch with may contain OPC items or other branches

OPC item

OPC item with properties

OPC item property

OPC item property containing other properties

Plantstreamer® 1.2.1 User Manual 9

Picture 3: Available tags tree-table (upper) and select tags table (lower).

Plantstreamer®

Root folder containing all composite tags

User created composite tag

To select the desired tags press the check box in the save column and the selected

OPC items will be validated by the OPC server and, if valid, added to the list of

selected tags. Alternatively, instead of clicking the check box, it is possible to drag the

OPC items to the selection table.

Selecting a branch will cascade the selection to all the OPC items and branches in

this branch. However, selecting an OPC item or property will not cascade the selection

to the their child properties.

The user may also select individual elements of arrays.

The array element selection may be performed simply by clicking the element in the

table or by adding the element indexes to the element list.

To insert new elements into element list using the text field, type the indexes

numbers separated by any non-numeric characters.

5.4 Manually adding OPC items

By default Plantstreamer will attempt to retrieve the list of available OPC items from

the server. However there are some situations when this action is not desired or even

possible:

the OPC server contains too many OPC items;

the connection to the OPC server is slow;

Plantstreamer® 1.2.1 User Manual 10

Picture 4: OPC property panel for arrays items.

Plantstreamer®

the OPC server does not support browsing.

In such cases, it is best to manually add the OPC items either by typing the full OPC

item ID or by using the find dialog.

To manually add OPC items, disconnect Plantstreamer from any OPC server and

disable the “Auto Fetch Tags” in:

Options -> Auto Fetch Tags.

5.4.1 Adding OPC items

To add a single OPC item go to:

Actions -> Add Item.

Insert the exact OPC item ID in the dialog box and press OK. Plantstreamer will

attempt to validate the id in the OPC server and, if successful, adds it to the tag list.

5.4.2 Finding OPC items

When the exact OPC item id is not known or when the ids follow a pattern it may be

useful to use the Find Items dialog. Go to:

Actions -> Find Items.

Plantstreamer® 1.2.1 User Manual 11

Picture 5: Add OPC item dialog.

Plantstreamer®

Insert the search pattern and hit OK. All OPC items that match the criteria will be

added to the tag list.

Note: The filter criteria syntax is OPC server dependent.

5.5 Composite tags

Plantstreamer allows the user to define more complex tags using a scripting

language. These tags are called composite and may be created in the actions menu:

Actions -> Create Composite Tag.

Once created, it will be available in the composite tag root folder. The user can

define the name, scripting language, result data type, and script for the composite tag

in the Item Properties panel (Picture 7).

In order to reference OPC items in the script, they have to be added to the list of

OPC items in the table seen in Picture 7. To add new items just click the “Add...” button

and then select the desired tags. It is also possible to use the mouse to drag OPC

items into the table. The item reference's in the script can be altered by editing

column “Variable Name”. Please make sure that all the variables in the script

reference an existing OPC item variable name or another variable declared in the

Plantstreamer® 1.2.1 User Manual 12

Picture 6: Find OPC items dialog.

Picture 7: Composite tag properties panel.

Plantstreamer®

script.

When the script is compilable and has a valid syntax the text area background will

turn into a light green.

5.6 Saving/loading configurations

The configuration options, such as the list of connections and the selected tags, can

be saved into an XML file:

File -> Save As...

Later, these options can be loaded:

File -> Open...

If there is more than one password protected connection, the user can define a

master password to save the connection passwords in a secure way. The usage of the

master password is optional.

5.7 Logging data

By default Plantstreamer saves the data synchronously, however, it is also possible

to log asynchronously by selecting the check box in:

Options -> Asynchronous

When using the asynchronously data access please make sure the OPC server

Plantstreamer® 1.2.1 User Manual 13

Picture 8: Master password creation dialog.

Plantstreamer®

supports this feature.

If you would like to save the items' units and descriptions, select the check box in:

Options -> Save Descriptions and Units

If these properties are available, Plantstreamer will store them into the output back-

end.

Before starting the logging process, define your desired sampling interval.

Finally, just press the “Start Logging” button to begin saving data (Picture 9).

5.8 Exporting the OPC item list

Plantstreamer allows to export the OPC list displayed in the tree-table into a

Comma-Separated Values (CSV) file.

Establish a connection to the OPC server and open the Export OPC Item List dialog:

File -> Export -> OPC Item List...

It is also possible to export all the OPC item's properties, which requires additional

time to fetch the information from the OPC server.

Plantstreamer® 1.2.1 User Manual 14

Picture 10: OPC item list export dialog.

Picture 9: Log panel.

Plantstreamer®

6 Output back-ends

6.1 PostgreSQL database

PostgreSQL is a powerful, free, open source object-relational database system which

runs on all major operating systems, such as Linux, UNIX and Windows. The data

stored in the PostgreSQL database may be accessed using any of the PostgreSQL

native programming interfaces for C/C++, Java, .Net, Perl, Python, Ruby, Tcl, and

ODBC. Additionally, Plantstreamer allows to export the data stored in the database

into a CSV file.

To use this back-end follow the steps:

1 Select “Database” from the list of available Output types (Picture 11);

2 Establish a connection to the database (Connection to the PostgreSQL server);

3 Define the database table name to use.

6.1.1 Connection to the PostgreSQL server

Open the database connection dialog (Picture 12) either by pressing the Connect

button in the Database panel (Picture 11), or by going to:

Actions -> Database -> Connect...

Plantstreamer® 1.2.1 User Manual 15

Picture 12: PostgreSQL database connection dialog.

Picture 11: Database back-end selection.

Plantstreamer®

Type in the database name, user name, password, and host. The database port is

set to the PostgreSQL default and therefore most users will not require to change it.

The database schema and table space are optional. Finally, just press the Connect

button.

6.1.2 Export into CSV files

To export the data logged by Plantstreamer in the database, connect the database

and then open the database export dialog (Picture 13):

Actions -> Database -> Export Data Saved in the Database...

Then select the database table and the CSV file name. To export the data within a

time interval, select the check box “Filter by write time” and define the initial and final

time. Please notice that the write time may not match the OPC time for each item.

Plantstreamer® 1.2.1 User Manual 16

Picture 13: Database data export dialog.

Plantstreamer®

Additionally, the user may export only a subset of the variables saved in the

database by editing the selection in the “Variables” tab.

6.1.3 Import tag selection

Any previously saved selection in the database can be imported by selecting an

existing table name in the “Table Name” drop-down menu and then by going to:

Actions-> Database -> Import Selection

If there is no selection in the database for the current OPC server name, then the

selection will be empty.

6.2 Text files

One of the most portable formats used to store tabular data are simple text files

where each data element is delimited from the next by specific character. The most

common text file format uses a comma as a delimiter and is designated as Comma-

Separated Values (CSV). A CSV file may be opened on almost any spreadsheet

software. Text files are extremely useful for small amounts of data, however are not as

efficient as a database and will consume considerably more space.

To use this back-end follow the steps:

1 Select “Text file” from the list of available Output types (Picture 15);

2 Define the text file name either by pressing the “Select File...” button or by

editing the file directly in the input field.

Plantstreamer® 1.2.1 User Manual 17

Picture 14: Tag selection in the database data export dialog.

Plantstreamer®

6.2.1 Advanced options

The text file output back-end allows the customization of some of its options. They

are accessible by going to:

Actions-> Text File -> Advanced...

Plantstreamer's default delimiter character is a comma (used to create CSV files),

however it is also possible to define a custom character. The delimiter can be virtually

any character as long as it is not one of the following:

• any number (0-9),

• dot (.),

• plus (+),

• minus (-),

• letter e or E,

• and double quotes (“).

The user may also wish to split the file into several according to a maximum

number of rows each file may hold. Plantstreamer will create new files by appending to

base file name either the file's creation number or creation date.

Plantstreamer® 1.2.1 User Manual 18

Picture 15: Text file back-end selection.

Picture 16: Advanced options for text files.