Visualising a Fluid Level Control Loop:Eclipse SCADA and 4DIAC

Ben SchneiderGeorg Neugschwandtner

fortiss GmbH, Munich

20th April, 2015

ContentsIntroduction 2

Get to know Eclipse SCADA and set up the development environment 2Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Setting up the development environment . . . . . . . . . . . . . . . . . . . . . . . . 3Test the development setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Collection of tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Small Footprint Protocol with FORTE and Eclipse SCADA 5Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Build SFP for FORTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Compile a version of FORTE older than 1.7.0 . . . . . . . . . . . . . . . . . . . . . . 6Set up a small example SFP-Server on FORTE . . . . . . . . . . . . . . . . . . . . . 7Connect to FORTE with ESAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Visualisation of the fluid level control demo 9Structure of the overall system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9IEC 61499 application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Setup the Eclipse SCADA master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Eclipse SCADA Infrastructure Model (ESIM) . . . . . . . . . . . . . . . . . . . . 10Eclipse SCADA Component Model (ESCM) . . . . . . . . . . . . . . . . . . . . . 12

Eclipse SCADA VI client development . . . . . . . . . . . . . . . . . . . . . . . . . . 14Drawing visualisation elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Add properties to symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Dynamic content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Start your visualisation application with Eclipse . . . . . . . . . . . . . . . . . 20Build a standalone visualisation client application . . . . . . . . . . . . . . . . 20

Tips for developing your own VI client . . . . . . . . . . . . . . . . . . . . . . . . . . 20

General Eclipse SCADA troubleshooting tips 22

1

Introduction

This document describes the implementation and visualisation of a fluid level control loopin a simulated tank system. The control loop is implemented in IEC 61499 using the 4DIACIDE, with the controller running on FORTE (4DIAC runtime) and the process simulationrunning on FBRT (FBDK runtime). The control system is visualised with Eclipse SCADA.

This demo was developed in 2014/15 at fortiss in Munich by Ben Schneider, GeorgNeugschwandtner and Alois Zoitl. We would like to thank Jens Reimann and Jürgen Roseof IBH Systems and James H. Christensen of Holobloc Inc. for their work that this projectbuilds upon and their support.

The first section of this document gives an overview of Eclipse SCADA for all those who havenot already worked with it and summarises references for information and tutorials. Thesecond section gives detailed instructions on how to build FORTE with support for EclipseSCADA’s SFP (Small Footprint Protocol) to enable communication between controller andvisualisation. The third section describes how to develop a Visual Interface client withEclipse SCADA.

After reading this document, you will be able to run the fluid level control demo on yourPC. You will also know the basics to start creating your own control system with controllerand operator screen using 4DIAC and Eclipse SCADA.

Note: This document contains hyperlinks. Click on page numbers and figure numbers to be taken to the

appropriate page. Click on blue text to open the website referenced in the text.

Get to know Eclipse SCADA and set up the developmentenvironment

If you don’t know yet what Eclipse SCADA is and what it is capable of, take a closer lookat the Overview subsection in this section. When starting to develop an Eclipse SCADAapplication, you will find that there is currently no single, comprehensive source of infor-mation for such an undertaking. This section fills the gap and collects the references toinformation sources that are currently spread over the web.

Note: Eclipse SCADA started as openSCADA. In June 2013, openSCADA became an Eclipse project, now called

Eclipse SCADA. Since June 2013, the development focuses on Eclipse SCADA. However, there are features of

openSCADA which Eclipse SCADA does not provide. For further information visit the openSCADA website. The

available documentation sometimes applies to both and sometimes only to a specific version of openSCADA or

Eclipse SCADA.

Overview

To get a rough overview of Eclipse SCADA and its basic concepts, I recommend checkingout the following sources (in the given order):

• Slides for the presentation of Eclipse SCADA at EclipseCon 2013

• Website of Eclipse SCADA (and openSCADA)

• Wikipedia article on Eclipse SCADA (take a look at the references!)

2

• Youtube Screencast by Jürgen Rose: Building an example application from scratch

• Book Eclipse SCADA - The definite guide by Jens Reimann and Jürgen Rose: Imple-mentation details and tutorials

• Eclipse SCADA git repositories: Implementation details and samples

• Google Group for openSCADA: News, troubleshooting and technical discussion

In general, an Eclipse SCADA system consists of 3 main components: the drivers (dataaccess), a master server (data storage and management) and clients (operator screens).Drivers can be, for example, Modbus, Simatic S7 PLC, JDBC or SNMP. An Eclipse SCADAmaster server collects the data and provides functionalities like historical data (HD) andalarms and events (AE) to the SCADA application if desired. The clients access valuesstored on the master and display them to the user. In this document, we will see two kindsof Eclipse SCADA clients: ESAC (Eclipse SCADA Admin Client) and the VI (Visual Interface)client.

The next steps, after getting an overview of the capabilities of Eclipse SCADA, are to setup the development environment and start playing around with Eclipse SCADA followingsome tutorials. These steps are described in the next two subsections.

Setting up the development environment

Before you can actually start implementing a SCADA system with Eclipse SCADA, you haveto set up the development environment. For this, you have to complete the following steps:

• Install Java: see Eclipse SCADA - The definite guide or view the Screencast on Youtube

• Install Eclipse and the Eclipse SCADA plugins: see Setting up a SCADA project andThe definite guide section 3.1.1.2 or view the Screencast on Youtube

– In addition to the installed release version of Eclipse SCADA (i.e. the EclipseSCADA plugins, as described above) you have to install the development versionin order to build and run the fluid level control demo described in this document.The demo was tested with Eclipse SCADA release 1.3 and the following milestone:

http://download.eclipse.org/eclipsescada/downloads/org.eclipse.scada/drops/0.2.0/S201410310907/p2/

Install this in the same way as the release version (via Help → Install New Soft-ware). The last version of Eclipse SCADA can be found on the Eclipse SCADAhomepage.

Note: After the fluid level control demo was finished, release 0.2 of the Eclipse SCADA tools became

available. The demo was not tested with the 0.2 release. It may be easier to install the 0.2 release

instead of an earlier release and the additional nightlies as described above.

– Note: You can also clone and import the Eclipse SCADA packages manually (see How to clone git

repositories with EGit). After cloning, you have to import the cloned projects into your workspace (in

Git View: right click the repository you want to import and click import projects). After importing

the projects, clean (Project → Clean. . . ) and rebuild (Projects → Build All) your workspace (see

section Troubleshooting on page 22).

• Set up a target platform definition (view the screencast on Youtube from minute 1:28).More information on target definitions in Eclipse can be found online on the Eclipsewebsite.

3

Test the development setup

• Configure a master server.

The configuration of an Eclipse SCADA master server is defined by the World Model,which consists of 2 models: the Eclipse SCADA Component Model (ESCM) and theEclipse SCADA Infrastructure Model (ESIM). In the ESIM you can, for example, spec-ify protocol drivers that the master server will use to pull in tag values from the un-derlying systems. The ESCM defines, among other things, where tag values are heldand how they are stored. You can see an example configuration of a master server inthe screencast (minute 8).

• Try an example client.

For an example visualisation implementation, which gives you an overview of thestructure of an Eclipse SCADA visualisation and a starting point for your own devel-opment, clone and import the following Git repository:

http://git.eclipse.org/c/eclipsescada/org.eclipse.scada.samples.git/

Collection of tutorials

Now that you have successfully set up the development environment, you can start playingaround with Eclipse SCADA. You could have a look at the following things:

• Eclipse SCADA Tutorial (in German) which contains the Eclipse Magazin Tutorial, theModbus tutorial and a short introduction on developing Eclipse SCADA VI clients

• Download and execute the DemoClient to get an impression of a visualisation withEclipse SCADA

• Eclipse SCADA Admin Client (ESAC): ESAC can connect to a running master serverand browse for variables/items or deploy configurations to a running Equinox basedSCADA application

• Eclipse Magazin article: OpenSCADA Test Client (OSTC), example implementation ofa Client, external driver and master server

An external driver will be necessary (in a slightly different form) to connect FORTEand Eclipse SCADA using SFP (as described in section 3).

Note: With a recent Eclipse SCADA version things will look a little different from this article, e.g. the

OSTC is replaced with ESAC.

• Creating a standalone visualisation application setup shows, how you can create aproject for an Eclipse SCADA VI client

• Modbus TCP device connection and export shows how to manually export a hive in-stance and integrate an external data source into the server

If you have come this far, you know the basic concepts of Eclipse SCADA, have a prepareddevelopment environment and already done some tutorials on Eclipse SCADA, so you cannow start developing your own application. The next section describes how to include theSmall Footprint Protocol (SFP) to FORTE in order to communicate with the Eclipse SCADAmaster server. Visual Interface (VI) Client development is described in more detail later onin this document (page 9).

4

Small Footprint Protocol with FORTE and Eclipse SCADA

This section describes how to set up communication with the SFP between FORTE andEclipse SCADA. SFP is used to access the data of small embedded devices with the leastpossible impact on the device’s performance. Clients can ask the server which tags itprovides and then access the values of the tags by cyclic polling.

I used Eclipse on Windows (Cygwin toolchain) for the procedures described in the nextsections.

Prerequisites

Install Java and Eclipse (as described in the section “Setting up the development environ-ment” on page 3).

Install Cygwin with at least the following tools:

• GIT(git: Distributed version control system)

• autoconf stable version and autoconf extensible package(automatic configure script builder)

• automake(Tool for generating GNU-compliant Makefiles)

• libtool(Devel/libtool: Generic library support script)

• libevent-devel and libevent(Event notification library)

• make(the GNU version of the ‘make’ utility)

• gcc-core and gcc-g++(GNU compiler collection)

Install the Eclipse SCADA Admin Client (at least version 0.2.0 M8 or higher; see section“Collection of tutorials” on page 4).

Build SFP for FORTE

FORTE (version 1.7.0 or higher) supports SFP by default1. How to build FORTE with theopenSCADA_SFP libs using Cygwin is described next.

Prerequisites:

SFP libraries (based on libevent) have to be installed first.

• Repository: git://git.openscada.org/org.openscada.asgard.git – /libeclipsescada-sfp-server – Branch 1.2 or 1.3

• GitWeb link to source code

Checkout from git:

5

$ mkdir sfp$ cd sfp$ git clone -b 1.3 git://git.openscada.org/org.openscada.asgard.git$ cd org.openscada.asgard/libeclipsescada-sfp-server

Initialize autoconf:

$ autoreconf --install

Configure & make:

$ ./configure$ make$ make install

Download the latest release (you need at least version 1.7.0) of the FORTE source codefrom the 4DIAC webpage and build FORTE with CMake and Eclipse (Cygwin-toolchain).You can find detailed instructions on how to do this in the 4DIAC-Help under Installa-tion/FORTE/. . . .

In addition to the configuration described there, you have to check theFORTE_COM_EclipseSCADA_SFP checkbox and provide yourFORTE_ECLIPSE_SCADA_SFP_SERVER_LIB_DIR, of the SFP libs you compiled before.

Note: If an error occurs after successfully compiling sfp/libs (saying: sfp/libs not found), copy the folder

libeclipsescada-sfp-server-version and the appropriate .a and .la files from <path/to/cygwin>/usr/local/libto <path/to/cygwin>/lib. You can also avoid this Cygwin issue by specifying prefix options, when invoking

configure (console prompt: ./configure –prefix=/usr), even as this is considered bad practice on Unix systems.

Compile a version of FORTE older than 1.7.0

In this section2 I describe, how I built FORTE for SFP, because at that time you had tocheckout FORTE from the Mercurial repository and change the branch by to the open-SCADA_SFP branch. Use your favorite Mercurial tool (I used TortoiseHg) to check outFORTE from Sourceforge into your Eclipse workspace. Afterwards you have to change thebranch to openSCADA_SFP, as follows:

Checkout FORTE & change the branch (TortoiseHG):

$ hg clone http://hg.code.sf.net/p/fordiac/forte$ cd forte$ hg update -r openSCADA_SFP

The last revision of the openSCADA_SFP branch is 1429 (f024a04270f0). At this revisionthe branch was closed and merged into the master branch of FORTE.

Note: I used FORTE 1.6.1 (openSCADA_SFP branch) and libevent 2.0.21 for the demo.

Note: At the moment the 4DIAC code migrates to Eclipse, therefore I am not sure how long the link to clone

the repository (http://hg.code.sf.net/p/fordiac/forte) will be available.

6

Set up a small example SFP-Server on FORTE

After setting up FORTE with SFP, you can test it by starting an SFP-Server in FORTE andmonitoring the value/s it serves with the Eclipse SCADA Admin Client (ESAC). FORTEcontains its local hive of variables stored in the SFP server. ESAC provides an SFP clientwhich is able to poll the variables from the server (getting started with ESAC).

To configure the server within FORTE, place publish/subscribe Service InterfaceFunction Blocks (SIFB) in your IEC 61499 application. A screenshot of a minimalSFP-server is shown in figure 1 (4DIAC 1.7.0 was used for the implementation ofthe test application). The ID parameter of the example publisher has the structure<protocol_name>[<itemname>] (in this example, sfp[feed_valve_control.mode]).The Qualifier Input (QI) must be set to TRUE, otherwise the execution of the block will beterminated/inhibited. FORTE needs strong typing. Therefore you have to make sure (e.g.with converter function blocks) that the data input SD (Publisher) or the data output RD(Subscriber) have appropriate types. Don’t forget to initialize the publisher correctly fromthe resource. How this is done is shown online in the 4DIAC Help under Tutorials/4DIACFramework/X+3 Tutorial/System Management/Resources.

Figure 1: Test application for communication between FORTE and ESAC

Download the application to your FORTE. You can monitor the state using the 4DIAC De-bug perspective (detailed information about debugging in 4DIAC can be found in the 4DIACHelp in section Deployment of IEC 61499 Applications and Monitoring and Debugging Func-

7

tionalities). As a running FORTE is a requirement for downloading your test applicationyou have to start it either by executing the forte.exe manually or by adjusting the 4DIACpreferences with the path to your forte executable.

Connect to FORTE with ESAC

After setting up an example publisher you can send values by forcing the IN data input ofthe BOOL2BOOL function block to TRUE or FALSE and triggering a Request (REQ) input eventat the BOOL2BOOL in the debugging perspective of 4DIAC. The value is now sent to the SFPclient. For now, we use ESAC as the SFP client.

To access the values with ESAC you need to configure the connection to FORTE via SFP.The connection URI should look as follows: da:sfp://localhost:9999, where da standsfor data acquisition (the protocol variant), sfp (Small Footprint Protocol) is the used proto-col and 9999 is the standard port for SFP. If you open a new connection (by double clickingon the connection) and a new “realtime list” in ESAC, you can drag and drop the valuesinto the “realtime list” and monitor their current state. The result could look similar tofigure 2. The messages FORTE shows (console output) are not relevant in this example.

Figure 2: FORTE and ESAC connected via SFP

Since in this example the value is published by FORTE, ESAC is not able to change thevalue (e.g. with a write operation). If you want to send values from the ESAC to FORTE, youcan configure a subscriber quite similar to the publisher shown before and change valuesby right click → Write Operation (on the value you want to change) in ESAC. Make surethat you do not change the type of the variables!

Note:

• You can publish multiple values (PUBLISH_0. . . X) with a single publisher SIFB, but only 0 or 1 datainputs are possible (SUBSCRIBE_0. . . 1) for one subscriber.

8

• At the moment, it’s not possible to have tags with read and write access at the same time, since youcan’t have a Publish and Subscribe SIFB for the same tag.

Visualisation of the fluid level control demo

This section describes the development of the Eclipse SCADA application for the fluid levelcontrol demo. Before you proceed, make sure that you are familiar with all the stepsdescribed in the previous sections. Also, make sure that FORTE with SFP and the EclipseSCADA development environment are correctly running and configured on your system.If this is the case, you should be able to run the complete demo, which will be describedin detail in the following. Furthermore, you should be able to start developing your ownEclipse SCADA VI client application after completing this section.

Structure of the overall system

The structure of the overall system is shown in figure 3. A small screencast, which givesan overall impression of the tank demo can be seen on Youtube.

Figure 3: Structure of the overall system

The simulation of the tank system is realised with the Function Block Development Kit(FBDK). FBDK provides function blocks which are – in this case – used for modeling and

9

visualising a pump, a tank, a valve and pipes. FORTE and the Function Block RuntimeEnvironment (FBRT) communicate via publisher/subscriber messaging according to theIEC 61499 Compliance Profile for Feasibility Demonstrations. More information on FBDKcan be found online at www.holobloc.com.

FORTE executes the function block application for controlling the fluid level in the tankand provides the Eclipse SCADA Master Server with data from the devices (in this casesimulated devices). The tank application running on FORTE consists of a PID controllerand the subscribers and publishers for communication via SFP.

The Eclipse SCADA Master Server stores and manages the collected data from FORTE.The VI client connects to the master server via NGP (next generation protocol – an EclipseSCADA internal protocol) and visualises the process. You can set up your desired operatorscreen (“view” in Eclipse SCADA terms) with the VI client. ESAC is an alternative to accessthe data managed by the master server. You can monitor the state of the observed variablesin the realtime list of ESAC, as described in the section above.

Note: You need at least version 0.2.0 M8 of Eclipse SCADA for SFP support.

IEC 61499 application

You should be able to find the IEC 61499 FBN for the fluid level control demo where youfound this document. Unzip it and import it into your 4DIAC-IDE via File → Import →Existing projects (select “copy into workspace”). Figure 4 shows the application as it isdisplayed in 4DIAC. The SFP publisher/subscriber SIFBs are encapsulated in the OPER-ATOR_SCREEN subapplication. The cyan coloured blocks and the PUMP_VIEW subappli-cation are mapped to the FBRT resource; the remainder of the blocks is mapped to theFORTE resource.

The Eclipse SCADA application is described in the next section.

Setup the Eclipse SCADA master

In order to access the values on the SFP server within FORTE with an Eclipse SCADA VIclient, it is necessary to set up an Eclipse SCADA master server. The following sectionshows everything that is necessary for this, but you can also find the configuration fileswhere you found the IEC 61499 application and VI client source code.

To configure the master server, you need to set up its Eclipse SCADA Infrastructure Model(ESIM) and Component Model (ESCM). A general example can be seen in the screencast byJürgen Rose (minute 8) and in the Eclipse Magazin article, where a master for a Modbussystem is set up. For the fluid level control demo, start a new Eclipse SCADA Configurationproject and configure the master for SFP as described in the next two subsections.

Eclipse SCADA Infrastructure Model (ESIM)

The ESIM defines the infrastructure of your system, such as drivers, protocols, whichservers to start and the hardware where these servers should run on. In our case we needto configure the master server to access an external driver (running on FORTE) via SFP.The properties of the external driver are shown in figure 5.

10

Figure 4: IEC 61499 application of the fluid level control demo

11

Figure 5: Eclipse SCADA Infrastructure Model of the master server

The properties for the master server itself are:

• Driver: External Driver tankControl @localhost

• Instance Number: 1

• Name: SFP\Master on localhost

Eclipse SCADA Component Model (ESCM)

To configure the values accessed and stored by the master server we have to change theproperties of the ESCM file. Here, you configure the values and their location on the masterserver. An example configuration for the manual override mode of the tank system is shownin figure 6.

Note that the Source Name in figure 6 is set to feed_valve_control.mode, which corre-sponds to the SFP server tag name in figure 1: It is possible to perform a name translation,when desired, from the name the driver uses (Source Name), to the name the VI client uses(Name). Master On defines on which master server the value is managed and Connectionis the driver from/to which the value is received/sent. The ESCM is organised in levels togroup the values on your master server together and define a storage hierarchy.

12

Figure 6: Eclipse SCADA Component Model of the master server

Name translation in the fluid level control demo (ESCM file):Source Name Namelevel.measured level.actualLevellevel.set_point level.setLevelfeed_valve_control.mode feed_valve_control.modefeed_valve_control.set_position feed_valve_control.actualValvePositionfeed_valve_control.manual_set_position feed_valve_control.setValvePosition(not used yet) pump.actualPumpRevolutionpump.set_speed pump.setPumpRevolution

How the VI client connects to the server is described in subsection Add Properties to Sym-bols (page 15).

The next step after configuring the master is developing the VI client, which will be de-scribed in the next section.

13

Eclipse SCADA VI client development

The following describes in detail how to develop an Eclipse SCADA VI client. It requires abasic understanding of Eclipse SCADA (see the first part of this document).

You should be able to find the VI client source code for the fluid level control demo whereyou found this document. Make sure that your Eclipse IDE is set up properly for EclipseSCADA development (again, see the first part of this document). Unzip the project andimport it into your Eclipse IDE via File → Import → Existing projects (select “copy intoworkspace”). Do not forget to actually set your Eclipse SCADA target definition as the targetplatform. You can find an example target platform (tank.target) in org.fortiss.ia.tankdemoor set it up on your own like shown in the screencast by Jürgen Rose (minute 1:28).

If you want to start your own new project, the first step is to create a new project for astandalone visual interface application as described in The definite guide.

Drawing visualisation elements

Eclipse SCADA organises basic visualisation elements (line, rectangle, triangle, polygon,. . . ) into symbols. Symbols group these basic visualisation elements into more complexelements, such as a tank, a pump or a valve. Besides vector elements, symbols can alsoinclude bitmap images (png, bmp, . . . ) and references to other symbols. A pump symbolcould for example be contructed from a circle and a bent line grouped together in a Stack-Container (Stack-Containers can be used to superimpose transparent symbols) as shownin figure 7. For another example, you can have a look at the textvalue symbol provided byEclipse SCADA (open textvalue.vi in the Visual Interface Model Editor).

You can add a symbol to your project by right clicking your project tree (project-name.resources.symbols in the package explorer) and selecting New → Other → VisualInterface Model. To add basic visualisation elements to the symbol, open the created *.vifile in the Visual Interface Model Editor and right click Symbol → New Child.

Generally Eclipse SCADA provides many different types of containers to group visuali-sation elements together (e.g. XY-Container, Border-Container, Figure-Container, Stack-Container . . . ) and form a symbol.

Symbols that represent a system on an operator screen are called “view” in Eclipse SCADAterms. In projectname.resources.views you can edit the different views your visualisationwill provide to the user. If you want to display a new view in the client, you have to registerit (described in The definite guide). In every view it is possible to include symbols (e.g. thevalve) by including the *.vi file. The included files will then be displayed in the specific viewin the client.

In the fluid level control demo, each symbol (e.g. the valve) has its own *.vi and *.js file,where visualisation and functionality is implemented, respectively. The various symbolsare then included into the main view via symbol references. It is also possible to create asingle view with a complex .vi file and an appropriate .js file.

The view for our fluid level control loop with a valve controlling the inflow of the tank, atank with a level indicator, a pump controlling the drain (manually controlled, acting as adisturbance) and a PID controller (automatically controlling the fill valve depending on themeasured level) is shown in figure 8.

14

Figure 7: Pump symbol in the VI Model Editor

Add properties to symbols

Another important feature is adding properties for different VI symbols via string-to-stringmaps. Using these key/value pairs, you can, for example, store names or IDs of symbols orother properties. I tried to keep the properties for all variables in the *.vi files as highlevel aspossible in the hierarchy of the *.vi files (most properties are in /resources/views/main.vi).Other properties are located in the appropriate symbol *.vi file referenced from the main.vifile.

An example for such properties can be seen in figure 9, which shows the VI model forthe “Automatic”/“Manual” radiobuttons in figure 8. The value mode on the Eclipse SCADAmaster server is accessed by storing its fully qualified name in property valueWriteTo.The name consists of 3 parts: prefix.variableName.suffix. The prefix is defined bythe hierarchy (in our case the levels level, feed_valve_control and pump) of the valueson the master server (take a look at figure 6). The suffix is determined by the type of thevalue. The type can be seen when you connect to the master server with ESAC.

A more complex example on how to use properties can be found in the singleNode anddoubleNode symbols, which display the percentage values (together with their header andlabels) that you see in figure 8. If you are looking for an example how they are referencedfrom main.vi, see the XY-Child main.ref.singleNode.valve.position there. These symbolsinclude (i.e. reference) a textValue symbol, whose item property is concatenated pro-grammatically from several parts (see figure 10). This is necessary because parts of thename are reused; Prefix, variableName and suffix are stored separately.

For more information about the concept behind the “On Create Properties” property, havea look at the discussion of onCreateProperties() in The definite guide (section 5.2.4.3:

15

Figure 8: Main view of the fluid level control demo

Life Cycle).

Before you actually start developing, take a look at the section “Tips for developing yourown VI client” on page 20.

Dynamic content

Eclipse SCADA does not only allow you to display symbols statically. You can add dynamicbehaviour to specific parts of your application. This is covered in the following part of thissection.

One of the most important functions of a SCADA system is to give the supervisor a goodoverview of the plant and its current state. Therefore, you have to update the values dis-played in the visualisation client, e.g. the speed of the pump or the fluid level in the tank. Toadd dynamic behaviour to your visualisation application, you can include JavaScript fileswith the symbols (*.vi files). Script modules can be added by right clicking the appropriate<Symbol> → New Child → Script Modules. In the properties of the added module, youhave to configure the path of the JavaScript file. An example can be found in textValue.vi,which includes the scripts textValue.js, colors.js and detailDialog.js.

Eclipse SCADA uses Rhino/Nashorn to integrate JavaScript into the existing Java environ-ment (Information about Nashorn on Youtube). One feature of Rhino/Nashorn is that youare able to call Java code directly from the JavaScript fragments.

16

Figure 9: Properties of symbols

Important scripting variables for using JavaScript within Eclipse SCADA are:

• controllerThe controller element is defined in org.eclipse.scada.vi.ui.draw2d/symbolContext.java.Its purpose is to make basic VI elements in the client accessible for JavaScript. Eachsymbol has its own controller class (take a look at org.eclipse.scada.vi.ui.draw2d/primitives),with own mutator/accessor functions, which can be used to manipulate the proper-ties of a symbol. An example is to set the text symbol label invisible as follows:

controller.getElement("label").setVisible(false);

• dataThe data element is defined in org.eclipse.scada.vi.ui.draw2d/symbolData.java. Itspurpose is, among other things, to give the client access to data values that are storedon the master server. The primary value of the variable tanklevel can, for example,be accessed – after it has been registered (see below) – in the following way:

data.getPrimaryValue("tanklevel");

For more information on the data variable visit The definite guide.

Additional information on these variables can be found in The definite guide in section5.2.4 Scripting. Other interesting variables that are not relevant in this example are theGSON parser, view manager and style generator.

With the variables described above, it is possible to access VI symbols and their propertiesand design the visualisation interface. What we cannot do until now is to react to inputs(may it be user input or updated values on the master server). For this purpose, EclipseSCADA provides event handlers.

Important events in the life cycle of a symbol are initialisation and disposal, as well as the

17

Figure 10: onCreateProperties() function of the symbol singleNode

update event, when values on the master change. More information on the event life cyclecan be found in The definite guide in section 5.2.4.3 Life Cycle.

To update a value that is stored on the master server the VI client is connected to, you haveto register the symbol (on the client) on the value (on the master server) first. This can bedone as follows:

controller.registerItem(itemName, itemID, connectionID);

After you have successfully registered the item, you can access its value with:

data.getPrimaryValue(itemName);

The getPrimaryValue() method returns a value of type Variant. To make sure it has theexpected type you can typecast it (for example to double) like this:

data.getPrimaryValue(itemName).asDouble(return_value_on_failure);

The return_value_on_failure is returned in case the value on the master server was

18

not successfully accessed. An example for registering and reading a value can be found inthe VI client code of the fluid level control demo under resources/symbols/valve.js in theinitValve() and updateValve() functions.

After the registration of an item, you can also access the attributes as follows:

data.getAttributeValue(itemName, attributeID);

For example, accessing the attribute alarm of the registered item level can be done likethis:

data.getAttributeValue("level", "alarm");

The visualisation client cannot only read, but also write values on the master server. Thevalues to be written do not have to be registered before. They can directly be overwrittenlike this:

controller.startWrite(connectionId, itemId, value);

An example for writing values to the master server can be found in the VI client code underresources/symbols/sliderHorizontal/sliderHori.js in function clickedSliderHori().

When a registered value changes on the server, the server will send an onUpdate eventwhich causes the JavaScript method registered on this event to be called. Registering ascript method on an event handler is done in the properties of the specific symbol (seefigure 11).

Figure 11: Registering script modules and event handlers

There are several other event handlers – which ones, depends on the symbol – which reactto user input (e.g. onClick(); onDoubleClick(); onMouseDrag(); onMouseHover();).

After designing the visualisation interface and adding functionality to it, you can start yourvisualisation application from within Eclipse or build a standalone client application fordeployment.

19

Start your visualisation application with Eclipse

• Start a master server on your own by right clicking master.profile.xml (masterconfigu-ration/output/master/master.profile.xml) → Run As → Equinox Application Profile.If the folder output does not exist, you have to run the productive.recipe file (by rightclicking productive.recipe→ Eclipse SCADA Configuration→ Run Production (de-fault)). Or skip this step and connect to an existing and running master server.

• Start the visualisation application client by right clicking plugin.xml (in your visualisa-tion project)→ Run As → Eclipse Application. The application should pop up. Loginwith your username and password. If you did not select the password credentials onyour own, the default username is admin with default password admin12. To openthe login dialog press Ctrl+L.

• Optional: Start ESAC and connect to the same master you connected your visuali-sation client to. More information on ESAC can be found in the Eclipse SCADA Wikiand in the screencast (minute 3:10). In this case ESAC is very useful for debugging,because you can monitor current values at the master.

Note: Accessing values on the master from the VI client is only possible after you login to the VI client. Before

the login, the values are all ‘null’.

Note: You can change the master your VI client connects to by editing the project/plugin.xml file (search for

the <context> .. </context> tags). Add a new login context for the master server you want to connect to.

Build a standalone visualisation client application

You can build a standalone visualisation client application with Maven for Windows(32/64 Bit), Linux (32/64 Bit) and Mac OS (64 Bit) by right-clicking projectname-product/pom.xml → Run As → Maven build. You can find the output (zip files) inpath/to/my.sample.application-product under target/product. You can also build your VIclient with Maven from the terminal, this is described in The definite guide in section8.1.6.

Tips for developing your own VI client

1. You can open *.vi files in 3 different ways in Eclipse SCADA:

a) with an XML editor in Eclipse (equivalent to EMF, but in XML-Style)

b) with the EMF editor (see figure 7) and

c) as a preview of the visualisation in the client (without the need of starting thewhole client application every time changes are made).

2. Enable debugging in the visualisation client by setting the VM argument vi.debugto true (shown in figure 12): right click *.product → Run As → Run Configura-tions. . .→ Arguments and add the parameter -Dvi.debug=true under VM argu-ments (additional system properties can be found in The definite guide) Once youhave enabled the debugging functions, you can for example reload your visualisationclient instead of starting it again and again for every change you make. To do this,right click the little cogwheel (which is only visible in the visualisation client when

20

debugging is enabled) in the top right corner and click reload. Other useful debuggingparameters are -Dscada.debug=true and -Ddebug=true.

Figure 12: Debugging parameters in the VI client

3. Disable and enable client connections to the master server (protocol variants: DA, AE,HD, CA) by opening the plugin.xml file and commenting out the appropriate connec-tion elements (<connection> .. </connection>) or adding new connections.

4. Rhino/Nashorn featuresUseful for debugging (even if it is not comfortable): Call Java methods directly fromJavaScript, for example: java.lang.System.out.println("Hello World!");

5. For receiving information about an event (click, double click, mouse over, . . . ), youcan use the event object. This object offers for example the x() and y() functions,which return the x and y coordinates of the event (e.g. position of a click). The clickedposition can be determined in an event handler, for example like this:

function clickedObject(){var xPos = event.x;

}

6. You can manipulate the position and dimension of a XY-Child with the functionssetPosition() and setDimension(), defined in packageorg.eclipse.scada.vi.ui.draw2d.primitives.XYChildController.java

21

General Eclipse SCADA troubleshooting tips

1. ‘Thousands’ of errors and warnings after cloning and importing Eclipse SCADAprojects

→ Clean (Project → Clean. . . ) and rebuild (Projects → Build All) your workspace.

2. JavaScript: “ItemId must not be null” (caused by type error) error on function call

controller.registerItem ( "test", controller.getProperty ("item" ), controller.getProperty("connection"));)

→ Typecast the value of item to String, e.g.:

controller.registerItem ( "test", String(controller.getProperty ("item" )), controller.getProperty("connection"));

3. VI client login finishes with the state LOOKUP and nothing happens

→ Try it again and/or restart the application.

4. Cannot type in VI client login window to enter username/password

→ Deselect all packages with *.rap.* in the launch configuration (right-clickapp.product file → Run Configurations → Plug-ins) and deselect include optionaldependencies (see figure 13).

Figure 13: Deselect *rap* packages in the run configuration

5. java.lang.RuntimeException: No application id has been found

22

→ Open the launch configurations and add required plugins (right-click app.productfile → run Configurations → Plug-ins → Add Required Plug-ins). This is the sameas in figure 13, but without removing the *.rap.* plugins.

6. Client connections (AE and HD) to the master server not available (see figure 14)

→ Disable HD and AE connection or connect your client to a master which supportsthe client with AE and HD information (see section “Tips for developing your own VIclient” on page 20).

Figure 14: HD and AE connection not available

7. Login with the VI client on the Master server not possible, even if it was possible a fewhours before with the same master and client (Error in Eclipse VI client console: ‘...kein Authentifizierungsmodul gefunden ...’)

→ Reboot your system. . . or run the recipe for the executable master model again:productive.recipe → Eclipse SCADA Configuration → Run Production (default).

23

8. Problem when configuring the master (error occurs when running the productive recipe):

master on node ’tankmodelsrv’ does not have a connection to endpointsorg.eclipse.scada.configuration.world.impl.EndpointImpl@60681236(shortDescription: null, name: ExternalDriver Endpoint: TankControl,portNumber: 9999) Failed to call method: "process"

→ Configure the drivers in world.esim of your master server (see figure 15).

Figure 15: Master properties in the ESIM

24

Notes

12015/10/17: [Changed Documentation] Downloading FORTE src changed for building FORTE with SFP22015/10/17: [Changed Documentation] New chapter for compiling versions of FORTE older than 1.7.0

List of Figures1 Test application for communication between FORTE and ESAC . . . . . . . . 72 FORTE and ESAC connected via SFP . . . . . . . . . . . . . . . . . . . . . . . . 83 Structure of the overall system . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 IEC 61499 application of the fluid level control demo . . . . . . . . . . . . . . 115 Eclipse SCADA Infrastructure Model of the master server . . . . . . . . . . . . 126 Eclipse SCADA Component Model of the master server . . . . . . . . . . . . . 137 Pump symbol in the VI Model Editor . . . . . . . . . . . . . . . . . . . . . . . . 158 Main view of the fluid level control demo . . . . . . . . . . . . . . . . . . . . . . 169 Properties of symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710 onCreateProperties() function of the symbol singleNode . . . . . . . . . . . . . 1811 Registering script modules and event handlers . . . . . . . . . . . . . . . . . . 1912 Debugging parameters in the VI client . . . . . . . . . . . . . . . . . . . . . . . 2113 Deselect *rap* packages in the run configuration . . . . . . . . . . . . . . . . . 2214 HD and AE connection not available . . . . . . . . . . . . . . . . . . . . . . . . 2315 Master properties in the ESIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

25