CS-Studio Display Builder
Tutorial presented:
Spring 2017 EPICS Collaboration Meeting at KURRI, Osaka, Japan
Megan Grodowitz,
Kay Kasemir (kasemir@ornl.gov)

Overview• Display Builder replaces OPI Builder (BOY) in CS-Studio– Built on Eclipse plugin framework as both a user interface and IDE– Editor to to create user interfaces– Runtime execute user interfaces– Backward compatible, can import most *.opi files– 30+ widget types at this time••••

Simple data read/write widgets like gauges and input fields
Complex interactive widgets like custom graphs or a web browser
Structural and design widgets like text labels, images, and groups
Customize widgets for your site using widget style classes– Scripting support for custom behaviors– Integrated with other CS-Studio tools, e.g. Data Browser

Examples: SNS Accelerator

Imported *.opi displays

Examples: SNS Instruments

Imported *.opi displays

More Examples• Scan UI• Interactive Alignment
New *.bob displays

CS-Studio•

Display Builder is a component ofControl System Studio– http://controlsystemstudio.org/•••

CS-studio can be downloaded from the location
above, or through one of the site specificdownload areas
CS-Studio will run on any Windows/Linux/OSX
with a supported version of Java
This tutorial is based on a Linux virtual machine
image running the SNS version of CS-StudioGetting Around in CS-Studio•

On Linux, launch CS-Studio with the “css” command–•

If you see a welcome screen, close it using the small ‘X’ in thecorner of the panel

Default Perspective

All of the sub-windows in Eclipse are called Panels––•

Click to selectperspective

CSS should open up in the default “CS-Studio” Perspective–•

A dialog will pop up and ask which workspace to use. For now,
leave it as the default selection

Navigator panel

This screen has one open panel: The Navigator
Panels can be dragged around and rearranged as you work on a
project

Perspectives define a set layout of panels and controls for agiven type of work––

Right click on perspective name to select “Reset”
Display Editor Perspective
•
•
•

–

Right click to
select “Reset”

Open Display Editor perspective with the perspective
selection button
We will be in this perspective for the entire tutorial
Sets up editor area with navigator, outline, and properties
panels arranged around it.

Display Runtime Perspective•••

We will not need this perspective during the tutorial
Does not include file navigator and other tools
Meant to be open in production once “Top Displays” havebeen defined

Display Editor PerspectiveDisplay Editor Setup•

Open the “Display Editor” perspective•

Install display builder examples– We will be in this perspective during thetutorial– Use the top menus to select CS-Studio ->Utilities -> Install Samples– Select “Display Builder” and hit OK– This will download a number of examples tolook at for ideas and techniques– This has already been done in the tutorial
VMDisplay Editor: Basics• Focus on function: Edit and Run displays connected to PVs• Common control system elements should be as easy as 1-2-3:
1.
2.
3.

Drag and drop a “Text Update” widget onto your display in the editor
Assign an EPICS process variable (PV) to your widget in the editor
Hit “Run” and see your display in the runtime

What you will get:PV value with units as text
PV severity reflected in border color
PV name and value shown in tool-tip
Indication of‘disconnected’state via a pink borderWalkthrough: My first display•

Create new Display

Select File -> NewThis will open a “Select a Wizard” dialog
Choose Display Editor -> New Display
Click Next
Name the file “my_display.bob” andchoose the /CSS container– Click Finish
Navigator shows files and directories
–
–
–
–
–

Editor shows
the display weare working on

Outline shows all widgets withcurrent selection highlighted
Drag widgets
from thepalette onto
the display

Propertiesof thecurrent
selection

My First Display: Add Some Widgets•

Add a ramp value with text output
–
–
–

•

Add a toggle button to input a value
–
–
–

•

•

L-Click and hold to grab and drag a “Text Update” widget from the palette
onto the display
With the new widget selected, slect the “PV Name” field in the properties
and type “sim://ramp(1,10,1)”This means to add a value that counts to 10 at 1 second intervals (more on
sim PVs later)
Drag a “Boolean Button” widget onto the display
Select “PV Name” and type “loc://test”
This makes the boolean button write to a user defined local variable called
test. It toggles one bit of the variable between 1 and 0.

Add an LED to read from the test variable–––

Drag an “LED” widget onto the display
Select “PV Name” and type “loc://test”
This makes the LED light up when any bit in the test variable is non-zero––File ->Save
OR Ctrl-S

Save FileMy First Display:
How to Runa) Hit the Run button on the control barb) OR right click inside the display and“Execute Display” (will also save)c) OR Right click on my_display.bob -> OpenWith -> Display Runtimed) OR execute in standalone runtime,outside of CS-Studio

Runtime panel will open to the rightside, over the properties panel– Watch your ramp value count to 10– The ramp value will show a single solid
outline for warning and double outline
for severe at the high and low end of its
range– Click the button to turn the LED on andoff by changing the value of “test”

Arranging Panels for Display Testing••••

By default the runtime panel
opens on the right side, but canbe re-arranged.
Drag the runtime down to thebottom below the editor
Make some change to yourdisplay in the editor
Right click on the display in theeditor, select “Execute Display”– The display file will be saved– The runtime display will update

Right click andExecute

Runtime will
update withchanges fromthe editor

Editor: Using the Widget Palette•

Add widget to display:•

Widgets are arranged by sectiona) Drag widget from palette into editorb) Select widget in palette, then ‘rubberband’ location and size ineditor

–
–
–
–
–
–

•

Graphics are static images
Monitors change in response to changes in a connected PV (readonly)
Controls make changes to PVs, and may also change in response tochanges in the PV (read and write)
Plots are more complex images based on PV values
Structures are used to make more advanced display elements, suchas groups of widgets or embedded displays
And then some miscellaneous elements…

Hover the mouse over a widget to see a description tooltip

Editor: Customizing Widget Properties•

Properties panel allows
editing widget attributes––

Opens automatically in
Editor Perspective
If it is closed, to open it:•••

Properties change depending on which
widget is selected
–
–

•
•

Reset Editor Perspective
OR Click Window -> Show
View -> PropertiesClass
definedproperties
are greyed
out

Click on the display file name to see fileproperties
Click on the background of the display to see
display properties

Widget class defines property defaults (moreon classes later)
Properties panel is dynamic. For example,
changing number of states in multistate LED
will add more fields to edit state attributes

Properties for N=2
states appear

Editor: Manipulating Widgets• Select and in editor using left click and drag• Resize in editor by left click and drag edges ofoutline box• Use alignment tools to help witharrangements– Grid– Snap to Grid
– Snap to Geometry (sides and sizes of otherwidgets)– Arrange group of widgets•

Arrange front to back

– Use alignment tools for widget ordering– OR select widget in outline••

Right click for context menu and hotkey combos
alt+up or alt-down to move forward or backGrid, Snap

Ordering

Align selected group

PV Names and Examples•

ca://some_pv_name– EPICS Channel Access PV•

some_pv_name– Typically same, since “ca://” is the default•

sim://sine– Simulated PV. Read online help for details•

loc://x(4)– Local PV. Read online help for details•

pva://x– EPICS V4 pvAccess•

mqtt://x– MQTT PV

Editor: Drag and Drop Text••

CS-Studio includes drag and drop functionality––

Text can be dropped into display
Prompt will ask about Widget type–

Make a new text file in Eclipse

Exercise: A file full of process variable names
•
•

–
–
–
–

•

File -> New then select General -> File
Name the file pv_names.txt and select /CSS parent folder

Arrange text file below Display Editor panel
Type some lines of text to be PV names
Drag text from file into display editor, it will give
prompt for widget type
Make a text update widget

What happens when we run with this text update
widget assigned to our unqualified PV name?
––

The default PV type is channel access (ca://)This txt update will show the PV disconnected, unless
you typed a PV name that is reachable from your
Disconnected PV at runtime
tutorial machine using channel accessEditor: Widget Behaviors•••

Widget behaviors allow control over more complex functionality–

Later exercises will cover these in more detail––

Widgets can have assigned actions
Usually for button press–

Widgets can have arbitrary scripts attached to them that alter widget properties
Rules are a safe way to generate common script actions

Actions

Rules and Scripts•

Tooltips•

Alarm Border•–Set the text that appears when hovering over a widget––

Only for widgets that can have a PV assigned to them
Disable or enable border for alarm states––

This is used for multi-choice widgets like a combo box
To get items from an enum PV type, assign the PV to the widget and set “Itemfrom..” to true

Items, Items from…

•

Enabled•

Other Behaviors…

–

Only for widgets with mouse press functionality (buttons, checkbox, etc)––

Various widgets have behaviors regarding limits, min/max values, etc
Behaviors with “from…” indicate whether to get these values from the connected
PV or not

Access Online Help
• Searchable online help isincluded• Help -> Help Contents

Runtime Panel•

The runtime panel opens when we
execute a display
–
–
–

•

With the Display Builder examples
installed, navigate to Display Builder-> 01_main.bob
Right click and select Open With ->Display Runtime
Resize the main runtime panel sothat the scroll bars disappear and all
the buttons are visible

Navigation–––

Click buttons to open new displayswith examples
Use the forward and back arrows tonavigate between screens
Right click on a button to choose toopen in (New tab) or (New
workbench window)

Right click on widgets forruntime context menu

Runtime: Tooltip & Context Menu••

From the main example screen, click “TextUpdate” button
Tooltip––

Hover over any of the text update fields to see atooltip for the widget
PV info for widgets with connected PV
General info for other widgets

–
–
–
–
–
–

Get info for a given widget (i) -> debugging help
Reload Display
Open Display in editor
Send email (if configured for your site)
Send to Logbook (if configured for your site)
Possibly other functions…

–•

Context Menu (right click on any widget)Runtime: Send PV to other CSS Tools• Display Builder is
integrated with other CSStudio tools…
• Probe tool

– Right-click, select Process
Variable -> Probe• Databrowser– Right click, select Process
Variable -> Data Browser

Exercise: Grouping Container•

Using the my_display.bob that we started
earlier, group the LED and boolean button
so that they can be manipulated as a unit.
– Under “Structure” in the widget palette, draga “Group” widget onto the display– Drag the LED into the group– Drag the boolean button into the group– The group will highlight when widgets areadded, and the outline will reflect the new
structure– Select the group and use the properties
change the name to “Button Group” and thestyle to “Title Bar”
– Right click and “Execute Display” to see thegroup in the runtime and click the buttonDragwidgets to
group

Drag
group todisplay

Exercise: Macros and Containers•

Display Builder supports macros–––

Notate as $(macro) or ${macro}
Can be used for any widget property
Often used as PV name or partial PV name
•
•

•
•

•

$(pv)
$(pvprefix)_setpoint–

Can also be used for numeric or boolean properties as long as value is number resp. “true”/”false”

–
–
–
–
–

Preferences
OpenDisplayAction
EmbeddedWidget
DisplayModelGroupWidget––

Make a new display (“sub_display.bob”) using macros for widget properties
Add two embedded displays to “my_display.bob” with different macro definitions for sub display widgets

Utility of this comes from building a display using macros, then making several instances of thisdisplay with different macro definitions
Macros can be defined at various levels, and are resolved in the following precedence:

For the next exercise:Exercise: Macros and Containers•

Create a new display file–––

File -> New, then Display Builder -> New Display
Name it “sub_display.bob” in folder /CSS
Delete all widgets except for the title label, change it from“My Display” to “Mini Display”•••

set “PV Name”=$(pv)Under behaviors, set:•

“Limits from…”=false

Add a linear meter from the monitors section of thepalette––Set “PV Name”=$(pv)Under behaviors, set:•••

Delete widgets using backspace (ctrl-delete on OSX)
Set label text in the “Text” field of properties

Add a scaled slider from the controls section of thepalette––•TIP: To change the text that appears on the
tab at the top of the display in the editor,
click somewhere on the background to get
the properties panel for the display, thenchange the name to “Sub Display”“Limits from…”=false“Unit from PV”=false

Right click and “Execute Display” to save the file andsee the sub display in the runtime

Widgets will show disconnected PV when
we execute the sub display without
macros definedExercise: Macros and Containers••

Open “my_display.bob” in the editor
Add the Sub Display:– Drag an “Embedded Display” from the palette– With the embedded display widget selected:• Set the “Resize Behavior” to “Size content to fit
widget”• Click the “…” button next to the File property• Navigate to /CSS/sub_display.bob in the fileselection dialog• Click OK•

Oh no! The sub display is very small inside theembedded display widget– Each display has a width and height in pixels– We will need to set the sub display size
boundaries more tightly around the widgets

This isn’tright…

Exercise: Macros and Containers••••

Open “sub_display.bob” in theeditorClick on the background to get thedisplay properties panel
Change width and height until thered outline is tight around thewidgets
Return to “my_display.bob”– Right click -> “Reload Display”

Reloading display will pullin the changes from the
sub display

Exercise: Macros and Containers•

Add a second embedded display widget
below the first– Set the file to “sub_display.bob”– Set resize behavior to “Size content to fit
widget”•

Select the top embedded display:•

Select the bottom embedded display•

Right click and “Execute Display”– Click the “Macros” property button– Enter a macro with name “pv” and value“loc://test1– Click “Macros”– Enter a macro with name “pv” and value“sim://ramp(1,10,1)
Ramp pv is read only, so
the slider in the bottom
display is greyed out

The slider in the top mini
display will change the test1
local variable, and move thebar in that display

Exercise: Action and
Menu Buttons•

Add an action button to change the value of the test1
variable––––

Drag an action button from the controls widget palette to
the display
Click the Actions property button to open Actions dialog
Use the “Add” dropdown to select “Write PV”
Enter:••••

Menu buttons are action buttons with multiple actions–

Drag another action button to the display
Click the Actions property button to open Actions dialog
Use “Add” to add two actions, as above, where one action
sets test1 to 50, and one sets test1 to 75
Set the “Text” widget property to “Set Test1 Value”–

Use the buttons to set the value in the top mini display

–
–
–

•

Description: Test1 = 20
PV Name: loc://test1
Value: 20

Right click and “Execute Display”

Exercise: Make awidget class file•••Widget classes provide support for creating astandardized style for displays
Design the widget properties once, in a class definition
file, then use them many times
Define a new class file:
–
–
–
–

•

Create a new display file, File -> New,
then Display Editor -> New Display
For the file name, enter “my_classes.bcf”
The .bcf extension indicates a class file
The file icon in the navigator will reflect that this is a classfile type

Override the default TITLE class
–
–
–
–
–
–
–

•

Widget name in the classeditor is the class namefor this set of widget
properties

Select the title “My Display”
The properties panel in the .bcf file editor works
differently than in the .bob file editor
Checkboxes indicate which properties are set by the class
Set the widget name to “TITLE”
Change the “Foreground” property to a light yellow color
Change the “Transparent” property to false
Check the box next to the “Background” property, thenset it to a dark grey color

Save the file “my_classes.bcf”

Check boxes only appear
in class file editor. Checka property to have theclass define that property

Exercise: Make awidget class file•

Tell CS-Studio to use your class file

– Open preferences: Edit -> Preferences– Navigate to CSS Applications ->Display -> Display Builder– Find the line “Widget Class Files”– Add your class file to the end of the list•••

Separate files with semi-colons
Use the path /CSS/my_classes.bcf

Update your display to see changes– Open “mydisplay.bob” in the editor– Select the top label that says “My
Display”, make sure the class is set to“TITLE”– Right click and select “Re-load Widget
Classes”– The properties of the widget change tomatch the class style

Exercise: Widget Classes• Class files– Can override classes or define entirely new ones

• One could design a “BLUE LED” in a class file
• Once the .bcf class file is loaded, “BLUE LED” will appear in the class dropdown
for LEDs in the display editor for .bob files– Are resolved in the order they are listed• You could have a “master.bcf”, then override certain settings in another file,“control_room1.bcf”• Classes– Are applied to widgets when CS-Studio starts up– Are applied to widgets when the display is reloaded– Are applied to widgets when the widget classes are reloadedRules, Scripts• Ideally, just add Widgets to the display, configure sizeand PV Name.
Such ‘simple’ displays will be easy to maintain, canlater be translated to the next display tool
• Scripts, triggered by PV updates, canModify any property of any PV
Add widgets
Call any of the internal CS-Studio code
– Will be harder to understand and maintainExercise: Rules•••

Rules are a guided way to safely
generate scripts tied to widgets
Scripts generally use some type ofinternal logic to determine a widget
property
Exercise: Make a button invisible when
it is not needed––––

Open the “my_display.bob”
Select the action button “Test1=20”
Click the “Rules” property button to
open the Rules definition dialog
Click “Add” next to “Rule Name”•

Set rule name to “Disappear”•

Select “visible”••

Enter “loc://test1”
Leave the trigger checkbox checked••

Enter “pv0 == 20”
Set value to “false”–

Use the Property ID dropdown–

Click “Add” next to “PV Name”––

Click “Add” next to “Boolean
Expression”
Click OK•

Exercise: Rules

To see the rule in action, right click on the display
and “Execute Display”––•

Push the “Test1=20” button
The button will disappear until you change the value
to something other than 20 using the other button or
the slider

What was going on with the pv0 in the boolean
expression? What does this rule mean?
–
–
–
–
–
–

In the Rules dialog, select “Show Script” to see thepython script that runs for this button
Each PV that we enter can be accessed using its
index, starting at 0
If we use the “pv0” accessor, that will return anumeric (float) value for the 0th pv in our pv list forthis rule -> loc://test1
We could alternatively use “pvStr0” to access this
pv’s string value, or “pvSev0” to get its severity status
Since we selected the “visible” property from thedropdown, the rule generates the script to change
this value
Try adding and changing rules and pvs to look at
different script outcomes

Button appears
when this value is
not 20Scripting…
• As seen in rules, widgets can have scripts tied
to them• Scripting behavior is more advanced topic• See Help and examples to get started scripting• Use Scripts widget property to attach Python
or JavaScriptRuntime Perspective Configuration••

As mentioned earlier, there is a
“Display Runtime” perspective that ismeant to be used in production
Configure the “Top Displays” available
in runtime perspective– Select Edit -> Preferences– Navigate to CSS Applications -> Display ->Display Builder– Locate the “Top Displays” area
– Copy/paste the XML for the existing top
display– Change the “name” to Tutorial– Change the “file” to /CSS/my_display.bob

Runtime Perspective•••

Open the “Display Runtime”
perspective in CS-StudioOpen your display by selecting
File -> Top Displays -> Tutorial
Top Displays can also beaccessed with the toolbar

Navigator, editor toolbar
items, outline, andproperties do not appear in
Runtime Perspective.
This arrangement is meant
for production deployment

Click to selectperspective

Backward Compatibility: OPI Files• Display Editor can read *.opi files– Right click on .opi and select Open With -> Display Editor– Most widgets will work, screens need to be checked– Scripts will need to be updated• When the file is saved from display editor, it will save in new *.bob
format• Can maintain both files– Will execute the *.bob file if both *.bob and *.opi exist– Scripts can check if they are running in BOY or Display Builder and takedifferent actions depending on runtime environment• See examples -> script_util -> portable.pyFor more information…
• CS-Studio is an open source
collaborative project• http://controlsystemstudio.org/