Subscribe to DeepL Pro to translate larger documents.

Visit www.DeepL.com/pro for more information.

Software Manual
Foundation Centers of Reference in Innovative Technologies Financier
of Studies and Projects
Micro and Small Business Support Service
National Council for Scientific and Technological Development

ScadaBR 0.7
Open-Source Supervision and Control System

Software Manual
October 2010

2/70
Summary

1. Introduction.............................................................................................................................................. 5
1.1. About the document .................................................................................................................... 5
1.2. SCADA Systems ............................................................................................................................ 5
1.3. ScadaBR ........................................................................................................................................... 6
2. Installation ................................................................................................................................................ 7
2.1. JDK (Java Development Kit) .................................................................................................... 7
2.1.1. Installing the JDK................................................................................................................ 7
2.1.2. Configuring the JAVA_HOME............................................................................................ 7
2.2. Installing ScadaBR manually ................................................................................................... 8
2.3. Installing ScadaBR via the Installer ...................................................................................... 8
3. Operating ScadaBR ............................................................................................................................... 9
3.1. Presentation.................................................................................................................................... 9
3.1.1. Main Menu ................................................................................................................................... 9
3.1.2. Data Types .................................................................................................................................. 9
3.1.3. Data sources............................................................................................................................ 10
3.1.4. Data points............................................................................................................................... 11
3.1.5. Monitoring................................................................................................................................. 11
3.1.6. Control ....................................................................................................................................... 12
3.1.7. Events ........................................................................................................................................ 12
3.1.8. Application Icons .................................................................................................................... 12
3.1.9. Alarm Sounds .......................................................................................................................... 13
3.1.10. Graphics .................................................................................................................................. 14
3.2. Adding Data Sources and Data Points............................................................................... 15
3.3. Viewing the Data: Watch List and Charts ........................................................................ 17
3.4. Setting Events ............................................................................................................................ 20
3.5. Graphic Representations ........................................................................................................ 22
4. Data Sources ........................................................................................................................................ 25
4.1. Modbus .......................................................................................................................................... 25
4.1.1. Overview ............................................................................................................................. 25
4.1.2. Basic Configuration ......................................................................................................... 25
4.1.3. Data Point Configuration ............................................................................................... 27
4.2. OPC DA .......................................................................................................................................... 28

3/70
 4.2.1. Overview ............................................................................................................................. 28
4.2.2. Basic Setup .............................................................................................................................. 28
4.2.3. Data Point Setup .................................................................................................................... 28
5. Reports.................................................................................................................................................... 30
5.1. Introduction ................................................................................................................................. 30
5.2. Generating reports in ScadaBR ............................................................................................ 30
5.2.1. Setting up a New Report Template................................................................................. 30
5.2.2. Report Scheduling .................................................................................................................. 31
5.2.3. Sending reports via e-mail ................................................................................................. 31
5.2.4. Model Management ............................................................................................................... 33
5.2.5. Report Queue .......................................................................................................................... 33
5.3. Generating reports using third-party software .............................................................. 34
5.3.1. Pentaho: Configuring the ScadaBR database ............................................................. 34
5.3.2. Pentaho: Report Creation Example ................................................................................ 38
5.3.3. iReport: Setting up ScadaBR's database ...................................................................... 45
5.3.4. iReport: Selecting the database data to be used ...................................................... 48
6. Scripts ..................................................................................................................................................... 50
6.1. Introduction ................................................................................................................................. 50
6.2. Creating Data Source and Data Points.............................................................................. 50
6.3. 6.3 Creating a Meta Data Source and its Data Points ................................................. 55
6.4. Creating Point Links.................................................................................................................. 61
7. Watchdog ............................................................................................................................................... 62
7.1. How it works ................................................................................................................................ 62
7.2. Configuration ............................................................................................................................... 62
7.3. How to run ................................................................................................................................... 63
8. Tips ........................................................................................................................................................... 64
8.1. How to change the database? .............................................................................................. 64
9. Glossary .................................................................................................................................................. 66

4/70
1. Introduction

1.1. About the document

This tutorial is intended to assist users in using the ScadaBR software. Additional
information about the features available in the software can be found in the main menu
by clicking on the icon .
More specific information about each feature is also available in the configuration
screens of each one by clicking on the similar icon .

1.2. SCADA Systems

SCADA stands for Supervisory Control And Data Acquisition. SCADA systems serve as an
interface between the operator and processes of all kinds, such as industrial machines,
automatic controllers, and sensors of all kinds. SCADA systems can be used to build
everything from simple sensing and automation applications, to the famous "Control
Panels" in power generation and distribution companies, traffic control centers, and so
on.
A typical SCADA must offer communication drivers with equipment, a continuous data
logger, and a graphical user interface, known as "HMI" or Human Machine Interface. The
HMI provides graphical elements such as buttons, icons, and displays, representing the
actual process that is being monitored or controlled. Among some of the most commonly
used functions in SCADA systems are:
- Generating graphs and reports with the process history;
- Alarm detection and event logging in automated systems;
- Process control including remote sending of parameters and set-points, activation and
command of equipment;
- Use of scripting languages for developing automation logic ("recipes").

5/70
1.3. ScadaBR

The ScadaBR software is developed in an open-source model, with a free license. All the
documentation and the source code are available, being also allowed to modify and re-
distribute the software if necessary.
ScadaBR is a Java-based cross-platform application, meaning that PCs running Windows,
Linux, and other operating systems can run the software from an application server
(Apache Tomcat being the default choice).
When running the application, it can be accessed from an Internet browser, preferably
Firefox or Chrome. ScadaBR's main interface is easy to use and already offers
visualization of variables, graphics, statistics, protocol configuration, alarms,
construction of HMI-like screens, and a number of configuration options.
After configuring the communication protocols with the equipment and defining the
variables (inputs and outputs, or "tags") of an automated application, it is possible to
build Web operator interfaces using the browser itself. It is also possible to create
custom applications, in any modern programming language, from the source code
provided or from its "web-services" API.
In our site you can find a demonstration video that covers examples with the basic
functionalities of ScadaBR.

6/70
2. Installation

2.1. JDK (Java Development Kit)

Tomcat requires a JDK on your system, with the JAVA_HOME environment variable
properly declared. Make sure that you have a JDK 1.6 (or greater) installed on your
system and that the JAVA_HOME variable is set correctly by typing: java -version in a
console.

2.1.1. Installing the JDK

Download the JDK from Sun's website:

(http://java.sun.com/javase/downloads/index.jsp).
Follow the standard installation instructions.

2.1.2. Configuring the JAVA_HOME

- In Windows XP or 2000
Navigate: Control Panel □ System □ Advanced □ Environment Variables.
Click add and enter JAVA_HOME with the address of the JDK installation directory.
Start a console and enter java -version to make sure everything worked correctly.

- In Windows Vista or 7, navigate: Control Panel □ System and security □ System

□ Advanced System Settings □ Advanced □ Environment Variables Click add and
enter JAVA_HOME with the address of the JDK installation directory.
Start a console and enter java -version to make sure everything worked correctly.

- In Linux
In Ubuntu, edit the .bashrc file (in /home/<youruser>/), inserting the line:
export JAVA_HOME=<address of the JDK installation directory>

7/70
Close the console, open it again and enter java -version to make sure everything worked
correctly.

2.2. Installing ScadaBR manually

Download the latest version of Apache Tomcat from the official website
(http://tomcat.apache.org/).
Extract the files to a directory of your choice "<tomcat-home>".
Run the file startup.bat (Windows) or startup.sh (Linux) from the <tomcat- home>/bin/
directory to start Tomcat.
In a browser, enter the address: localhost:8080/. If the Tomcat configuration page
starts, it is correctly configured. Otherwise, make sure that all the previous steps
(especially the installation of the JDK and the configuration of the JAVA_HOME variable)
have been carried out correctly.
To stop Tomcat, run shutdown.bat (Windows) or shutdown.sh
(Linux) directory <tomcat-home>/bin/ to start Tomcat.
Make o download from file ScadaBR.war
(http://www.scadabr.org.br/?q=webfm).
Place this file in the <tomcat-home>/webapps/ directory. Start
Tomcat.
In a browser, enter the address:
localhost:8080/ScadaBR/ (username: "admin" password: "admin").

2.3. Installing ScadaBR via Installer

To install ScadaBR via installer, download the file ScadaBR-Win- Installer_<ver>.exe and run it.
Follow the steps by clicking Next...
At the end of the steps, click Install.

Note 1: It is recommended to uninstall all Tomcat already installed on the machine

before using the ScadaBR installer.
Note 2: On Windows Vista and Windows 7, you must run the installer in administrator
mode by right-clicking on the file and selecting Run as administrator.

8/70
3. Operating ScadaBR

3.1. Presentation

3.1.1. Main Menu

The functionality in this application is accessed by the controls in the header. Depending
on your user account permissions, various icons will be displayed below the application
logo. When the mouse cursor hovers over an icon, a text balloon will be displayed with a
short description of the functionality of that icon. In addition to the control icons, the
right-hand side of the header shows the name of the user that is logged into the system.
When your application has an active alarm, a flag icon ( ) will flash and a description
of the alarm will be associated near the center of the header. The color of the flag will
indicate the severity of the alarm:
• Information
• Urgent
• Reviewer
• Risk of Life
You can click on the icon or description to display the list of active alarms.

3.1.2. Data Types

Five data types are supported:

• Binary (or Boolean) values can have only two states, referred to in the system
with the values zero (0) and one (1). You can use converters to display the binary
values in any labels needed, such as "on/off", "high/low", "started/stopped", etc.
• Multiple State Values have multiple distinct states. By this approach, the binary
type is a particular case of a multiple state. Values are primitively represented as
integers (e.g. 0, 1, 2, 7, ...), but, as with binary values it is possible to assign
labels to each value, such as "on/off/deactivated", "heating/cooling/off", or any
others.

9/70
 • Numeric (or analog) values are decimal values represented in the system with a
floating point variable. Examples of numeric values are temperature, humidity,
price, and altitude. Text renderers can be used to determine display
characteristics like number of decimal places, thousand separations (with periods
or commas), display of suffixes (°F, kW/h, moles, etc.). Track renderers can be
used to convert ranges of values into text labels.
• Alphanumeric values are simply strings of characters, like the O/S description of
an SNMP font.
• Values in Images are binary representations of image data. They are stored in
files on the host server's file system (not in the database) and are held in
memory. Renderers can be used to create scaled images, such as thumbnails, for
display.

3.1.3. Data sources

Data sources are a fundamental part of the operation of this application. A data source is
a "place" from which data is received. Virtually anything can be a data source, as long as
the communication protocol is supported by the application. Some examples:
• If you have a Modbus network accessible via RS232, RS485, TCP/IP, or UDP/IP,
you can create a Modbus data source that will "poll" the network at a defined
interval.
• If you have equipment or applications that can send data over HTTP, you can
start a data source HTTP receiver that will listen for incoming connections and
send the data to the appropriate points.
• For hardware that supports SNMP, start an SNMP data source. Values can be
polled at set intervals, or traps can be received for on-exception reporting.
• Data can be read from and updated in an SQL database external to the system.
• Data can be generated randomly or predictively using a Virtual data source.
Data values received or collected by a data source are stored in data points.

10/70
3.1.4. Data points

A data point is a collection of associated historical values. For example, a particular point
might be a temperature reading for a room, while another point might be the humidity
reading for the same room. Points can also be control values, such as an indicator to
turn a piece of equipment on or off.
There are many attributes that are used to control the behavior of points. Initially there
is the concept of a point locator. Locators are used by data sources to determine how to
"find" the data for the particular point. For example, an SQL data source has attributes
including where to find the database instance; point locators for the data source indicate
the name of the table and fields where specific values can be found. The logical
separation of data source and data point depends on the communication protocol in
question.
Attributes of data points can also determine many other aspects of the point, such as its
name, how it should be recorded (all data, only value changes, or none), how long to
keep the data, how to format the data for display, and how to graph the values.
You can also configure data points with value detectors, which are used to detect
conditions of interest in the points' values, such as whether the value has been too high
for too long, is too low, changes frequently, does not change, etc.
Points can be arranged in a hierarchy, or tree, to simplify their management and display
using the Hierarchy feature.

3.1.5. Monitoring

Monitoring points within the system can be done in two ways. You can use a watch list to
create dynamic lists of points with their values, last update times, and graphs of
historical information (if the point configuration allows). Values and graphics are updated
in real time without having to refresh the browser window. Graphs of multiple points can
also be displayed on demand.
It is also possible to create graphical representations of points by using drag and drop
functionality to position graphical representations of points over an arbitrary background
image. Animated images can be used to create a visualization

11/70
highly dynamic system behavior, and like watch lists, values are represented in real time
without requiring a browser refresh. These views can be marked as "public" so that they
can be used on public web sites.

3.1.6. Control

Control of external systems can be achieved for points that can be "set" (or that allow
writing or output). A setable point can be "set" to a user-defined value, such as a
thermostat setting or a switch control for a piece of equipment. Both watch lists and
graphical views provide simple means of determining the entry of a value. The point
locator for a "setable" point determines how the data source sets the value in the
external equipment.

3.1.7. Events

An event is the occurrence of a condition defined in the system. There are both system-
defined and user-defined events. System-defined events include data source operation
errors, user logins, and system startup and shutdown. User-defined events include value
detectors, scheduled events, and compound events that detect conditions on multiple
points using logical arguments. There are also "autidate events" that occur when users
make changes (additions, modifications, and deletions) that affect objects at runtime,
including data sources, data points, value detectors, scheduled events, compound
events, and event handlers.
Once an event has been detected, it is handled by handlers. An event handler is a user-
defined behavior that should be executed when a particular event occurs, such as
sending email or "setting" the value to a setpoint.

3.1.8. Application Icons

• Data source
• Data point
• Chart

12/70
 • Set point
• Watch list
• Graphic Representation
• Update
• Value Detector
• Composite Event
• Scheduled Event
• Event handlers
• Alarm
• User
• User Comment
• Report
• Sending Lists
• Publisher
• Notice
• Logout

3.1.9. Alarm Sounds

ScadaBR can play sounds when alarms are active. By definition, alarm sounds are
played for urgent, critical and life threatening alarms and not for information alarms, but
alarm sounds can be defined individually. To enable particular alarm sounds, valid files
in mp3 format must be placed in:

• <ScadaBR_home>/audio/information.mp3
• <ScadaBR_home>/audio/urgent.mp3
• <ScadaBR_home>/audio/critical.mp3
• <ScadaBR_home>/audio/lifesafety.mp3

To disable a sound, remove the associated sound file. A collection of sounds can be
found in the <ScadaBR_home>/audio/lib folder.

13/70
3.1.10. Graphics

ScadaBR contains a small graphics library that can be found in the folder
<ScadaBR_home>/graphics. Each sub-folder contains all the images in that image
definition and an optional properties file called info.txt. This properties file contains
name/value pairs for the following attributes (all optional):

• name: The name that will be used to describe the image in the user interface. If
not provided, the image defaults to the folder name.
• width: The width of the image. By default, all images are the same size. If not
provided, the width of the first image will be used.
• height: The height of the image. By default, all images are the same size. If not
provided, the height of the first image will be used.
• text.x: The position of text relative to the left border of the image, in pixels. If
not provided, the default value is 5.
• text.y: The position of text relative to the upper border of the image, in pixels. If
not provided, the default value is 5.

Once an image definition is used in the views the folder should not be renamed! The
folder name is used internally as the identifier of the image definition.
Image files are arranged alphabetically by name and are case sensitive. Name/value
pairs are separated by '='. Lines beginning with '#' are considered comments.
Thumbs.db' files are ignored. Compressed files (zip, gz, tar, etc) cannot be used because
the image files must be accessed by the web server. Image definitions are loaded at
system startup, so any changes require a reboot.
For future versions of ScadaBR to have more graphics, please provide the graphics you
create for the ScadaBR project.

14/70
3.2. Adding Data Sources and Data Points

This topic shows an example of creating Data Sources and Data Points. For didactic
purposes, a Virtual Data Source was created, which is a simulated data source.
From the main menu, choose the DataSources option .
Select the Virtual Data Source type from the list and click on the Add icon .
Fill in as below and save your settings.

When saving the data source, the options for including data points will be enabled. Click
on Add and fill in as below and save your settings.

15/70
Add a few more stitches of different types.

Now enable all the points by clicking on the icons on each of them and also enable
the data source .

16/70
3.3. Viewing the data: Watch List and Graphs

Now that you have your data sources and data points registered in the system, you can
view them. In the main menu, choose the Watch List option .
The registered data points are on the left. To monitor their values,
click on each one to add it to the current watch list.

17/70
You can access and edit more information about each data point by clicking on Data
Point Details . Click on the cited icon for the numerical data point and look at its
history and the graph of its values.

18/70
You can still edit the text rendering properties. In your watch list,
click Data point details .
On the next screen, click Edit data point .
In the Text Rendering Properties area, you have different rendering options. For example, with
the settings in the figure below:

19/70
We changed the rendering of the data point from:

To:

3.4. Defining Events

In your watch list, click on Data point details . On the

next screen, click Edit data point .

20/70
In the Event Detectors list, select "Lower Limit" and click A d d
to add a new detector.
Fill in the fields as below and click the Save button on the lower right side of the screen.

That's it. Now the system will inform you (in the "Alarms" screen, in the main menu)
every time the value of your data point goes below the minimum limit (22) for more
than 5 seconds.

21/70
3.5. Representations Graphics

To create more elaborate visualizations of the data, we can build "Graphical

Representations". In the main menu, choose the Graphical Representation option.
Click on New representation .
Choose a name for your first representation, click on Choose File, select an image,
confirm and click Upload Image.

In the components list, select Simple Data point and click Add component to representation
to add it.

22/70
Navigate to the added icon above the picture and click on the second option: Edit point
component settings.

Choose one of your registered points from the list and save your settings.

Add other components, associate them with your registered data points, and place
them on the screen.
Click on the "Save" button.

23/70
24/70
4. Data Sources
4.1. Modbus

4.1.1. Overview

The Modbus data source is used to acquire data either from a modbus device accessible
via an I/P network - it can be on a local or intranet network, or anywhere on the
Internet - (Modbus IP), or from a local modbus network accessible via RS232 or RS485
(Modbus Serial). The access control mechanism is either master-slave or client-server.

4.1.2. Basic Configuration

The Name field defines the name of the data source, and can be any description. The
Update Period determines how often the data is requested from the Modbus device. The
Timeout and Retries fields determine the system behavior in case a request fails. The
data source waits for a response for the time (in milliseconds) defined as timeout. If no
response is received, the data source will retry as many times as defined in retries.
The Contiguous batches only option can be used to specify that the modbus
implementation should not attempt to optimize requests for different values into a single
request. Enabling this option will cause the implementation to only perform requests for
multiple values when those values form a continuous space in the register.
You can scan slave nodes on the network using the Node scan feature. This feature
iterates over slaves 1 to 240, sending each one a ReadExceptionStatus (operation code
7). If a response is received (considering the timeout and retries settings), the node is
considered available. Note that not all devices support this operation code, so false-
negatives are possible.
The Create slave monitor points field causes "slave monitors" to be created
automatically. A "slave monitor" is a binary point that

25/70
indicates the current state of a slave. If a poll request to a slave fails due to timeout or
an error, the slave is considered off line. These points can be used for control like any
other point.

• Modbus IP

Three Transport types are supported. Check your equipment documentation to

determine which configuration can be used.
The TCP setup uses a new TCP socket every poll. The defined number of retries applies
when connection exceptions occur during socket opening. The timeout used for the
connection depends on whether the TCP stack is being used.
The TCP with keep-alive configuration creates a TCP connection on the first poll, which is
left open for re-use. If the connection is closed for some reason, a new one is created
when needed. The behavior for connection exceptions for this option is the same as for
TCP. This is the recommended configuration for most users, since it provides efficient
and robust communication while avoiding many of the configuration problems typical
with UDP.
The UDP configuration uses UDP packets for communication. This configuration provides
the highest network efficiency, but typically requires a higher network configuration,
since both ScadaBR and the equipment need to be visible on the network (as opposed to
TCP, in which ScadaBR can be protected by a firewall.
The Host and Port settings determine how to find the Modbus device on the network.
The host can be either a domain name or an IP address.

• Modbus Serial

Serial communication is controlled with the Baud Rate, Flow control in, Flow control
out, Data bits, Stop bits, and Parity values. The Echo can be used with t h e RS485
network if appropriate.
The Encoding value determines how Modbus requests are formatted. Most equipment
uses RTU formatted messages. Check your Modbus device documentation to determine
how to configure this field.

26/70
4.1.3. Data Point Configuration

Both serial and IP networks use the same point attributes. The Slave id is the id that the
Modbus node was configured w i t h and is a number between 1 and 240.
The Register range determines in which of the four ranges the value will be found.
Consult your equipment documentation to determine which one to use.

• Coil status represents the hexadecimal range 0x00000 to 0x0FFFF. Each register
contains a single, configurable bit. Values in this range are always Binary.
• Input status represents the hexadecimal range 0x10000 to 0x1FFFF. Each
register contains a single, read-only bit. Values in this range are always Binary.
• Holding register represents the hexadecimal range 0x40000 to 0x4FFFF. Each
register has 2 bytes (or one "word") and is configurable. Values in this range can
be Binary or Numeric depending on the other settings.
• Input register represents the hexadecimal range 0x30000 to 0x3FFFF. Each
register is 2 bytes long (or one "word") and is read-only. Values in this range can
be Binary or Numeric, depending on the other settings.

Coil status and Input status values are always Binary. However, Modbus vendors are
often very creative in the ways that the Holding and Input registers are used. The
Modbus data type field reflects the various ways in which data can be encoded. Consult
the documentation for your Modbus equipment to determine the appropriate
configuration.
Specific values are located in the Offset configuration. This field is a 0-indexed value,
which means that its count starts at 0. Some Modbus vendors provide documentation in
which it is 1-indexed, in which the count starts at
1. Therefore, it is sometimes necessary to subtract 1 from the documented index to
determine the 0-indexed offset. When the registers include their ranges, for example
written as 0x30001, 1-indexed is typically implied. The Bit field is used when binary
values are encoded in bits from individual registers.
The Settable field can be used to make a point, which normally would be configurable
(according to its range), non-configurable.
The Multiplier and Additive fields can be used when trivial conversions of

27/70
values are required. Numerical values read from the grid are calculated as follows: (raw
value) * multiplier + additive. The reverse is applied when a numeric value is written to
the grid.

4.2. OPC DA

4.2.1. Overview

The OPC DA (OPC Data Access) specification is the first of a group of specifications
known as the OPC Specifications, and was born out of the collaboration of several
leading automation equipment suppliers worldwide working in cooperation with
Microsoft.
Originally based on the OLE COM (component object model) and DCOM (distributed
component object model) technologies, the specification defines a standard set of
objects, interfaces, and methods for use in process control and manufacturing
automation applications to facilitate interoperability. COM/DCOM technologies provide
the framework for software to be developed. Today there are hundreds of OPC DA
servers and clients.

4.2.2. Basic Configuration

The Name field defines the name of the data source, and can be any description. The
Update Period determines how often the data is requested from the OPC DA server.
The Host, Domain, User and Password fields define the address and the "credentials" of
the server to be used. After filling these fields, click Refresh, and a list with the available
servers at the defined address will be created.

4.2.3. Data Point Configuration

After selecting the OPC DA server, click List Tags in the box to the right of the data
source settings. The tags available on the server will be listed, along with their types,
whether they are configurable or not, and a checkbox in the Add column.
To add them as data points, simply check the desired tags and then

28/70
click Add Tags. The selected tags will appear in a box below the data source settings and can be
enabled or disabled.
Note 1: Before adding the tags, it is necessary to save the data source.
Note 2: Tags added that have been previously added will appear in the duplicate list.

29/70
5. Reports

5.1. Introduction

ScadaBR has its own report generator, besides being compatible with the main custom
report generators.
This item will cover the two ways of generating reports from ScadaBR.

5.2. Generating reports in ScadaBR

5.2.1. Setting up a New Report Template

From the main menu, choose the Reports option .

Report templates provide a definition of how to create report instances. To add a new
report template, click New Report .

On this screen, you must define the template for the report:

The Model Name is used as a visual reference of the model. It is recommended to use a
unique name for each model.
Use the Data points list to select the points that should be included in the report. To add
data points, select the desired point from the list and click the icon . To remove an
existing point, click the icon associated with the point.
The Date Range value is used to determine a time range used for
filter values that will be used in the report.

30/70
5.2.2. Report Scheduling

Reports can be "scheduled" to be generated automatically. Use the Run every...

selection to determine a simple time event from which the report will be generated, or
define a routine according to the cron pattern for more specific control (see the "Cron
patterns" documentation for more information). Time events occur at the beginning of
the period covered. A Runtime Delay can be applied if the data expected for the report
tends to be collected after the absolute runtime of the report.

5.2.3. Sending reports by e-mail

Although reports cannot be explicitly shared by the system, they can be implicitly shared
by creating an email mailing list to which the system will send instances of generated
reports. The content of this email is the same as the content of the "report graph"
window opened in the Reports panel. To include the CSV-formatted export file in the
email, select the Include data table box.
Select the Email Recipients to whom to send the email with the report. The recipients
can be mailing lists, system users, or typed email addresses. Click the Send test email
icon to send a test message to the selected recipients.
Important: Report instances sent via email are automatically deleted after they are sent.

31/70
32/70
5.2.4. Model Management

To save a report template click the icon in the upper right corner of the template
creation panel. To delete an existing template, click the icon . To generate a report
immediately from a template, click "Run Now". Note that
some report templates can include a large amount of information and,
Because of this, they can take some time to generate. Thus, all reports are generated
asynchronously from the user interface. When an icon is clicked, the report instance will
be included in a queue where the user can monitor its progress.

5.2.5. Report Queue

The Report Queue lists all report instances for the given user. This list is not updated
automatically. An update can be invoked by clicking . Some events, however, will also
invoke an update of this list, such as the generation of a report.
Report instances in any state will be listed, whether complete or running. The columns of
the list will reflect the current state of the instance.
The columns in the list have the following definitions:
• Report name: the name inherited from the report template. Once the instance is
created, the report name does not change even if the template name changes.
• Start of execution: the point in time when the instance started to be generated.
• Execution duration: how long the instance generation took.
• From: the time from which the records were selected
• To: the time until which the records were selected.
• Records: the total number of selected records.
The Do Not Discard box allows users to prevent important report instances from being
discarded (see the "Other Settings" documentation for more information about the
report discarding process). This feature should only be used when strictly necessary, as
report instances can consume considerable amounts of storage.

33/70
The final column of the table provides controls for managing instances. The icon starts the
download of a CSV file with the report data, for import into
spreadsheet software. The icon opens a new browser window displaying report instance
information, statistical data, and a graphical image of the report data. Clicking the icon
deletes the report instance.
Particularly large report instances can take some time to be
deleted.

5.3. Generating reports using third-party software from .

5.3.1. Pentaho: Configuring the ScadaBR database

After downloading the DPO, simply unzip the file and run the file report-designer.bat on
Windows or report-designer.sh on Linux that will be inside the unzipped folder.
The program's start screen will open.

34/70
Go to File -> New, to create a new Report.
Now it is time to create a DataSource. The DataSource will be the source of the data used in the
Report.
In this example MySQL will be used as DataSource. To use Apacha Derby, simply
change the Connection Type.
Then go to Data □ Add Data Source □ JDBC

35/70
Now we create a new Connection, just click on the "+" icon next to Edit Security

36/70
Configure as shown above and click OK.
There, now everything is configured and the database can be used. The Report configuration is
drag-and-drop.
This way, you simply choose what you want to add to the palette, drag and drop it onto the
Report.

37/70
5.3.2. Pentaho: Report Creation Example

In this topic a step-by-step approach to creating a basic report is presented:

Creating a New Report

Configure MySQL as DataSource using the ScadaBR database as previously placed
Create the Queries that will be used in the progress of the Report:
Queries are the tables that will be available from the database. To create a new Query,
look to the right side of the Main Window and go to the "Data" tab:

Double click on the selected Data Set and then we add a Query.
The first Query we create is to get the name of the DataSource and the number of
DataPoints belonging to the DataSource:

38/70
Click OK.
The second is to get the user data from the ScadaBR system:

39/70
And finally, the third is to get the data from the DataPoints:

40/70
The previous Query was created for DataPoint 1, but two more Queries are created for
the other DataPoints by simply changing the number of the desired data point in the
Query to: where dataPointId = <DesiredDataPoint>

41/70
The Report layout is configured as follows:
The Layout is subdivided into: Page Header, Report Header, Details, Report Footer, Page
Footer. We start with the Page Header.

In this part we add a "label" to write "Report" and an "image" to put ScadaBR's image.
To add it just pull the desired item from the palette and drop it on the desired location.

Report Header

In this part we add two labels, one for "DataSource:" and another for "Amount of
DataPoints:" and select from the previously created Query the name of the DataSource
and the amount of datapoints.

Details

42/70
In this part we add three Sub-Reports. The Sub-Report is added because in each Report
only one Query is allowed to be used, so to use more Queries we add Sub-Reports.

In this Sub-Report 5 labels are added: Quantity, Sum, Maximum, Minimum and

Average. Data from Query DataPoint1 is also added.

In this Sub-Report 5 labels are added: Quantity, Sum, Maximum, Minimum and Average.
Data from Query DataPoint2 is also added.

43/70
In this Sub-Report five labels are added: Quantity, Sum, Maximum, Minimum and
Average. Data from Query DataPoint3 is also added.

Report Footer
In this part we add a Sub-Report.

In this Sub-Report three labels are added: Username, Email and Phone. Username Query data
is also added.

Page Footer

In this part we add a "label".

To see a preview of the report, click the icon highlighted with an X.

44/70
5.3.3. iReport: Setting up ScadaBR's database

Note: If you are using Derby, you need to add the lib derby.jar
(ScadaBR\WebContent\WEB-INF\lib\derby.jar) to iReport's Classpath, in Tools >
Options, on the Classpath tab, Add JAR.
Select the Report Datasources option.

45/70
Click New.
Choose the Database JDBC connection option.

Define a name (e.g. ScadaBR).

- If you use MySQL

Under JDBC Driver, choose "MySQL(com.mysql.jdbc.Driver)"
Under JDBC URL, enter: jdbc:mysql://localhost/mango
- If you use Derby
In JDBC Driver, type: org.apache.derby.jdbc.EmbeddedDriver
In JDBC URL, type: jdbc:derby:<location of your tomcat>/bin/mangoDB

46/70
Leave the JDBC URL Wizard fields blank.
Fill in the Username and Password fields according to your database configuration.

To verify that you have set it up correctly, click Test. If the message
Connection test successful is shown, the base is now ready for use.

47/70
5.3.4. iReport: Selecting the database data to be used

Choose Report Query

In the Report query tab, you can directly type in the query you want, or click on the
Query.... button
In Query... you can build the query visually, choosing the tables, creating clauses and selecting
the fields you want to retrieve.

Once the query is set up, click Read Fields. The selected fields will appear in the table
below, with their types already defined.

48/70
You can click Preview data to verify that the data returned is indeed what you want.
Click OK, and the fields will be added to the report's Fields list and can be used.

49/70
6. Scripts

6.1. Introduction

To create scrips in ScadaBR, the Meta Data Source is used. It gets its name because of
its ability to combine existing points into new ones. Instead of getting its information
from an external source, it uses values from other points and allows manipulation in
arbitrary ways by the user.
To learn more about scripting functionalities in ScadaBR, look for Help, in the Meta Data
Source menu.
Below is an example of how to create a basic script.

6.2. Creating the Data Source and the Data Points

In this example, we create 1 Virtual Data Source: Home and 9 Data Points: Rain,
Weather, Dehumidifier, Humidity, Fireplace, Light, Sun, Temperature and Fan.

50/70
Data Point Rain

Data Point Climate

51/70
Data Point Dehumidifier

Data Point Humidity

52/70
Data Point Lareira

Data Point Light

53/70
Data Point Sol

Data Point Temperature

54/70
Data Point Fan

6.3. 6.3 Creating a Meta Data Source and its Data Points

Now we are going to add the Scripts. To do this, we add 1 Meta Data Source and 5 Data
Points: Script_Climate, Script_Decumidifier, Script_Fireplace, Script_Light and
Script_Fan.

55/70
Script_Climate

Under Datatype, choose Alphanumeric. Under Script Context, choose the datapoints
Home - Temperature and Home - Humidity and then click the icon to add them to the
script. In the Var field, choose the name by which the datapoint will be referenced in the
script. In this example we have defined temp_var and humi_var for temperature and
humidity respectively.

In the Script field enter the following code :

a = "Hot and Humid Climate";

b = "Hot and Dry Climate";
c = "Cold and Humid Climate";
d = "Cold and Dry Climate";
e = "Current Weather";

if (temp_var.value > 25 && humi_var.value > 80 )

56/70
 e = a;
if (temp_var.value > 25 && humi_var.value < 80 )
e = b;
if (temp_var.value < 25 && humi_var.value > 80 )
e = c;
if (temp_var.value < 25 && humi_var.value < 80 )
e = d;
return e;

Dehumidifier_Script

Under Data Type, choose Binary. Under Script Context, choose the datapoints Home -
Humidity and then click the icon to add it to the script. In the Var field, set humi_var
to humidity.

In the Script field enter the following code :

57/70
if(humi_var.value > 80)
return true;
return false;

Fireplace Script

Under Data Type, choose Binary. Under Script Context, choose the datapoints House -
Temperature and then click on the icon to add it to the script. In the Var field, set
temp_var to humidity.

In the Script field enter the following code :

if(temp_var.value < 10)

return true;
return false;

58/70
Script_Light

Under Datatype, choose Binary. Under Script Context, choose the datapoints House -
Sun and then click on the icon to add it to the script. In the Var field, you have set
sol_var to humidity.

In the Script field enter the following code :

if(sol_var.value == false)
return true;
return false;

59/70
Fan Script

Under Data Type, choose Binary. Under Script Context, choose the datapoints House -
Temperature and then click the icon to add it to the script. In the Var field, set
temp_var to humidity.

In the Script field enter the following code :

if(temp_var.value > 25 )
return true;
return false;

60/70
6.4. Creating Point Links

After inserting the Data Points and the Scripts we will insert the Point Links. They will
make the "link" between the Script output and the Data Point you want to act on. Thus,
t h e input of the Point Link is the Script and the output is the desired Data Point.
5 Point Links have been added, 1 for each Script, e.g. for "Weather" and
"Script_Weather":

NOTE : In all Point Links in the Script field is added :

return source.value;

After everyone has been added, the Point Links page looks like this:

Ready, now just check the operation in the Watch List. Verify that with the change of the
states of some Data Points others are changed.

61/70
7. Watchdog

7.1. How works

The watchdog will periodically check the status of ScadaBR via the getStatus method of
its SOAP API. If the ststus indicates a failure, the system will restart Tomcat in order to
correct it.
The watchdog will terminate after a specified number of consecutive attempts to restart
Tomcat.
Note: If the machine's operating system is Microsoft Windows, it is necessary to define
the environment variable CATALINA_HOME, which points to the directory where
ScadaBR is located. For example, if ScadaBR is installed in the directory C:\ScadaBR
Program Files, the variable CATALINA_HOME would be set to:
set CATALINA_HOME=C:\Archiv~1\ScadaBR

7.2. Configuration

To set up the watchdog, edit the config.properties file. All settings have default values
that will be used if the file or parameter in question is not specified.
1. Set up the watchdog in the config.properties file. All settings have default values
that will be used if the file or parameter in question is not specified.
• api.address: ScadaBR's API address.
• catalina.home: Base folder of the Tomcat installation where ScadaBR runs. If not
provided, watchdog will use the environment variable CATALINA_HOME (if set).
• watchdog.period: Period in seconds that the watchdog will check the ScadaBR
status. Its minimum value is 30 seconds and its default value is 60 seconds.
• watchdog.retries: Maximum number of consecutive retries with which
watchdog will restart Tomcat in order to recover ScadaBR.

62/70
 • watchdog.fileLogging: to enable or disable file logging (log.txt).

7.3. How to run

If you have installed it in the default ScadaBR directory, it is not necessary to edit
config.properties (watchdog configuration file).
If you have installed it in another directory please edit the config.properties file with the
following change:
Change the catalina.home path to the location where ScadaBR was installed:
Example of default directory path:
catalina.home=C:\ScadaBR
IMPORTANT: Don't forget to leave two backslashes between the address names! To start
the watchdog open a command prompt in the folder where you installed ScadaBR and
type:
java -jar watchdog

IMPORTANT:
- In Windows, never forget to leave two backslashes between the address
names:
- Use CATALINA_HOME without spaces
- Use JAVA_HOME without spaces

63/70
8. Tips
8.1. How to change the database?

ScadaBR currently supports two database management systems: MySQL and Derby.
The ScadaBR.war file comes by default configured with Derby for user friendliness
reasons, since it runs embedded and does not require DBMS installation or configuration
of parameters such as login and password.
Changing the data for the database used is planned to be done during the "building" of
the system, but if necessary, you can change it in another way from the war file
provided:

Unzip the ScadaBR.war file into any <scadabr> directory (you can rename the file to
ScadaBR.zip and then extract it, if desired).
Open the file with a text editor:
<scadabr>/WEB-INF/classes/env.properties and edit it as desired:

MySQL*:
db.type=mysql
db.url=jdbc:mysql://localhost/scadabr
db.username=root
db.password=
db.pool.maxActive=10
db.pool.maxIdle=10

* Attention: to use MySQL, a bank with the name "scadabr" must be created before
starting ScadaBR. (only the bank, the tables are created automatically by the system)

Derby (default):
db.type=derby
db.url=<bd_folder>**

64/70
db.username=
db.password=

** The folder where the database will be located. It can be a relative path, such as:
../scadabrDB/.

Save the file, compress the entire <scadabr> folder back into one file
ScadaBR.war and perform the installation.

65/70
9. Glossary
A
• A&E - "Alarms and Events".
• Alarms - Occurrences, usually asynchronous, of a measurement value outside
pre-set limits, or events that require operator attention (e.g. viewing and
"acknowledging" the alarm). Alarms usually have an associated criticality level,
for example "0 = warning" up to "5 = critical alert".
• API - Application Programming Interface, a set of specifications that allows
different software (or different modules of a software) to communicate with each
other.
B
• Batch - Also known as Recipe or Batch, is a sequence of actions to be performed
sequentially to obtain a given result in a manufacturing process. For example: a
chemical recipe specifying reaction steps, distillation, filling and emptying of
tanks, etc. In this case, each different "compound" or production volume has a
different recipe.
• Builder - see HMI Builder
C
• Configurator - in the context of SCADA systems we are calling "configurator" an
application, with a user interface (not just configuration files), that allows you to
set protocol communication parameters, tag settings, logger sampling periods,
and so on.
• Custom App (or custom application) - any application external to the SCADA that
communicates with it by getting data or sending commands through a
standardized API. For example, a new HMI, an advanced historian, or some third-
party application such as an ERP, BI (Business Intelligence), and so on.

D
• DA - Data Access - the common name given to reading tags or sending
commands. "DA usually occurs at a high level, in contrast to IO which

66/70
 occurs at the low level; in this way, the DA references physical variables by the
name of the TAG, and not in terms of registers or bus addressing.
• DA Server - Software that translates the high-level requests into requests for the
protocol drivers; the DA server may have additional functions like caching
(keeping the last value in memory) or buffering (allowing non-blocking IO by
managing high-speed queues, for example).
• Datalogger - Data logger, produces "time-series" to be recorded in a system as a
DBMS (database).
• Driver - A software component that implements a communication protocol and
must be compatible with the development API defined for the DA Server.
E
• Events - are occurrences in the supervised plant that do not necessarily represent
a numerical value, occurring asynchronously and "pushed", that is, starting from
the devices towards the software that supervises them. Examples of events would
be "motor stage 1 started", "steady state operation reached", "protection relay
XYZ-14 triggered". Events differ from alarms in that they do not have an
associated criticality, nor do they require operator action.
• EPA - Enhanced Performance Architecture.
F
G
H
• HDA - History Data Access, a set of functionalities related to the analysis of
recorded data. It usually refers to an HDA API as a set of standardized methods
for extracting time series by entering the desired tag name, the start period, and
the end period; it can also offer functionalities such as extraction of
maximum/minimums, averages, and so on.
• Historian - Software capable of working with large volumes of data, acting as an
advanced datalogger with features such as data compression, deadband storage,
etc.

67/70
 • HMI - Human Machine Interface, operator interface where you can view data
through graphical or numerical indicators, and also send commands to the
equipment such as changing a set-point, for example.
• HMI Builder - Development interface where a system integrator can graphically
(in the "wysiwyg" style) develop HMI screens, adding components such as
indicators, plots, and command buttons.
I
• IDE - Integrated Development Environment, is a development environment
(similar to Visual Studio or Eclipse, for example) where a system integrator finds
both HMI Builder and Configurator functionalities, allowing him to develop all
aspects of a complete SCADA application.
• IEC - International Electrotechnical Commission.
• I/O - Input/Output or Input and Output. We use this term to identify low-level
communication operations, or at the protocol level (such as Modbus, Profibus,
Fieldbus, etc.) At the I/O level the definitions peculiar to each protocol are
important, such as the physical representation of the data (integer, double,
byte[]), communication rates (baud rate), port identifier or network addressing,
unlike the DA layer that "abstracts" this information.
J
K
L
M
• Module - A ScadaBR module is the name given to a software component that has
a well-defined "macro" function, such as: History Module, Alarm Module, Batch &
Scripting Module, and so on, communicating with the rest of the system through
the ScadaBR Middleware.
• Processing Module - a software component capable of processing large volumes
of information and generating new results from it, for example: averaging two
temperatures to generate a "third" temperature, or identifying behavior patterns
(specific waveforms, for example) and executing an external process.

68/70
 • Middleware - a set of specifications or software especially dedicated to the
function of Interoperability, that is, communication between various software
components.
• ScadaBR Middleware - a set of API's for communication in the DA, HDA and A&E
contexts, allowing different ScadaBR modules to communicate with each other
and/or with external software. The ScadaBR Middleware should "abstract" from
low-level issues (I/O), operating system or programming language, being as
"neutral" as possible.
N
O
• OPC - OLE for Process Control, a standard industrial automation middleware
widely adopted in industries worldwide; it has DA, HDA, A&E and other API's,
implemented over microsoft DCOM technology. It has a data model that describes
common components and operations in the manufacturing environment.
• OSI - Open System Interconnection.
P
• Protocol - Communication standardization specifying physical layer, transport,
data model, and packet format in the communication between equipment and the
PC where the SCADA software runs.
• Poll - A "request-response" communication format where each new piece of data
is requested by the consumer.
• Push - Push data format where the producer sends data sequentially
(synchronously or asynchronously) to the consumer.
Q
R
• Real-Time - Real-time requirements refer to the fact that there may be a
requirement that a particular communication or processing operation takes place
in a deterministic time slice, tolerating no delays.
S
• SCADA - Supervisory Control and Data Acquisition.
• Scripting -Ability to insert computational logic into SCADA, acting on certain tags
based on the value of others. For example, "if tank level above 3 meters, open
valve at 70%". Usually scripts are defined

69/70
 in high-level interpreted languages (such as basic, javascript), or standardized
graphical languages for the industrial environment (such as ladder, grafcet)
T
• Tag - a variable of the supervised system. A tag has a name (unique system-wide
identifier) by which it is referenced from all modules, "hiding" low-level details
regarding the protocol or device. Examples of Tags would be "temperature1",
"voltage_alternator", "tank_level_A" and so on. Tags can be "read" (get last value
with timestamp) or "written" (send command or set-point to devices). Tags can
implement several data types like numeric integer, floating-point, string, boolean
on/off, 8-bit binary, 16-bit and so on.
• Tempo-Real - see Real-Time
U
V
W
X
Y
Z

70/70