-
Notifications
You must be signed in to change notification settings - Fork 95
Display Builder Compatibility
Display tools for EPICS include MEDM, EDM, CS-Studio BOY, the Display Builder, and more. They all use different source code, are based on different graphics libraries, and use different file formats, naturally limiting their compatibility. For various reasons, you might be interested in transitioning from one tool to another. Keep in mind, though, that the transition from MEDM, EDM, BOY to the Display Builder is unlikely to be the last and only update that a long-running site will have to perform. For example, you might also want to access Display Builder files not only in a full-featured desktop runtime but also via a a web runtime.
The Display Builder was implemented with compatibility in mind:
- The
*.bobfiles use an XML format with comparably compact and generic tag notations. Instead of for example usingtypeId="org.csstudio.opibuilder.widgets.Label", which suggests that this file is specific to one tool, it uses justtype="Label". - Widgets are designed to be single-purpose. Compared to BOY, the
LEDhas been replaced by a binary LED widget and a separate Multi-State LED. The BOYXYGraphhas been replaced by several more specific plotting widgets. The file selection option of the text entry is now a separate File Selector widget.
Generic file formats and widgets with a specific meaning will be easier to translate into the next tool.
The Display Builder includes converters from MEDM and EDM, see online help for details on how to invoke them.
It can directly open most BOY *.opi files, and a large number of BOY displays will simply "work"
without modifications. If adjustments are necessary, open the *.opi file in the Display Builder editor,
modify as desired, and save the file. The display will be saved in the *.bob file format.
It is not necessary to delete the old *.opi file. When opening a file, the Display Builder will check for
both a *.bob and *.opi file, preferring the former.
By keeping the *.opi file, you can thus continue to use BOY while transitioning those files that require
editing.
The following comments on specific widgets and functionalities are meant to help with the transition to the Display Builder and also guide you to create displays that will be easier to port to the next tool.
Still, an automated, perfect conversion will never be possible. Each site needs to decide if or when it is advantegeous to transition to a new tool, or if it is more viable to stay with the existing tool.
Try to use the appropriate widget, and adjust as few properties as necessary.
For example, pick a Label widget and set its text to show a static text.
Pick a Text Update widget and set its pv_name to display the current value of that PV,
formatted based on information from the PV (precision, units, ..),
with an alarm indication.
If the PV was not configured to provide precision, units etc., it is tempting to configure this on the Text Update widget, but such details differ between tools, so it's best to fix the PV configuration. Likewise, different tools may offer different ways to indicate alarms, but for long-term maintainability it's best to leave the alarm indication settings at their default.
Both BOY and the Display Builder allow sites to add their own widget types. When importing BOY displays into the Display Builder, you might see warnings about unsupported widget types when the BOY display contained a widget that is not available, for example because it was a site-specific widget that has not been implemented, yet.
In comparison, the situation is similar to the rapid evolution of cell phones. While each new type of smartphone can import your basic list of contacts (name, address, phone number), features like custom ring tones or the app you wrote to mange your contacts on the PalmPilot won't transfer. So stick to the basics.
Display Builder widgets consistently indicate PV alarms via a border around the widget. The border changes not only color but also line style to be recognizable by users with color vision deficiency. The alarm sensitive border is by default enabled but can be disabled via a widget property.
Other display tools (EDM, BOY) might have allowed alternate alarm indications, for example an alarm sensitive foreground color, background color, 'blinking' colors etc. The display builder does not support these because using just a color would be insufficient for color vision deficient users, and inconsistent alarm indications result in, well, inconsistent displays.
Instead of configuring the specific font settings, try to select one of the predefined fonts. Some BOY screens used Labels with a rule or script to update the text. Better use a Text Update with a PV.
Some BOY displays misused Text Update widgets as labels by leaving the pv_name empty and
instead directly configuring the text. On import, the Display Builder will convert these
into Label widgets with a warning
Replacing TextUpdate Widget
'Text Update_69' (textupdate)
with 'text' but no 'pv_name'
with a Label
The BOY version had options to support File/Directory or Date/Time selection. In the Display Builder, the Text Entry widget is focused on plain texts. There is a separate File Selector widget. Legacy displays that used the Text Entry with the file option are translated into a pair of Text Entry and File Selector widgets.
Like the Text Entry widget in BOY, the current Text Entry implementation requires confirmation via Enter.
In its normal state, the widget displays the current value of a PV.
When you click the widget or type anything into the widget, it enters an 'active' state, just like the legacy implementation, except that the active state is now also indicated by a different background color.
The widget will stop displaying received PV updates so you can edit without interruptions. Press Enter to confirm and write the entered value to the PV. Press Escape, Tab, or click elsewhere to abort editing and revert to the idle state of displaying the current PV value.
For example, assume the current value is 98 and you want to enter the value 101.
Click on the widget, type 1, 0, 1 and then Enter.
If we instead sent everything that's typed right away, the value of the PV would be 98 (initial value), then 1 (you entered "1"), followed by 10 (you added the "0" to the "1") and finally 101, which could be problematic if we assume that the PV controls for example a motor.
Moving a motor from 98 to 101 mm is what you wanted; instead it hunted from 98 to 1, then 10, then 101.
By entering an active state that allows editing and then sending the desired value on confirmation, we avoid erroneous intermediate value updates.
The Spinner widget contains a text field with similar behavior.
BOY included just one LED widget type but with different functionality based on the number of states.
The Display Builder converts LEDs with two states into the new LED widget,
which has two states ('off', 'on') and can handle boolean PVs, check the bit of a numeric PV, or check for zero vs. non-zero values of numeric PVs.
BOY LEDs with more than two states are converted into the new MultiStateLED widget which has N states
and can handle numeric or enumerated PVs.
Some legacy displays contain LEDs with rules to update the widget color, i.e. both the primary PV and a rule driven by a second PV influence the LED color. Ideally, logic to summarize both PVs is added to the IOC, providing a plain PV that can directly drive an LED or MultiStateLED with just one primary PV.
See Display Builder Plot Compatibility.
See Display Builder Table Compatibility.
The Display Builder can handle the BOY "Tabbing Container", resulting in the same functionality of a tabbed container where the content of each tab is immediately available.
It is, however, often sufficient and much more efficient to use the new Navigation Tabs
widget where the tabs switch between different embedded displays,
running only one of them at a time,
replacing the content as tabs are selected.
Consider updating converted displays with "Tabs" with "Navigation Tabs".
The Display Builder supports only absolute or relative links. Several EPICS display tools support a search path for locating related displays, embedded displays, symbol files etc. While this can be convenient in the short term, it tends to create a maintenance issue because it is often unclear which file will be used, especially if the same file exists at different locations along the search path. Links in HTML pages, on the other hand, require absolute or relative links, which has proven to be very successful, so the same approach was chosen for the Display Builder.
This does not mean that you need to place all displays into just one folder. You may organize your displays hierarchically, for example as
/home/controls/displays/main.bob
/home/controls/displays/motors/overview.bob
/home/controls/displays/motors/template.bob
/home/controls/displays/vacuum/overview.bob
/home/controls/displays/vacuum/segment1.bob
/home/controls/displays/vacuum/segment2.bob
You can also use soft links to make "motors" point to some specific version of motor displays which are located elsewhere in the file system.
You are encouraged to use relative links whenever possible, because this will allow
relocating a complete directory tree.
For instance, a link from the main display to the vacuum overview should use vacuum/overview.bob.
Relative links will also allow accessing the same files both
locally via file links like /home/controls/displays/... and remotely via http://display_file_server.site.org/controlroom/displays/....
When configuring a related display or embedded display or image file name, the display editor
will try to turn the file path that you select in the file browser into a link that is relative
to the edited display. Depending on the operating system, the default file selector dialog
might automatically expand symbolic links or otherwise adjust the path, which is not always
helpful. The display editor allows you to manually enter or adjust the path,
which might be necessary if the value obtained from a file selector dialog does not meet
your intention of for example using symbolic links.
Actions can open other displays, execute external commands etc. Actions are primarily used with the Action Button widget, where pressing the button at runtime invokes the action.
For compatibility with legacy tools actions can also be assigned to other widgets, where they will then appear in the context menu. While BOY would in some cases trigger such actions from a plain mouse click, this is not supported for several reasons:
-
In a control system display, the widget functionality needs to be obvious. A button will do something when clicked. This is not a video game where one should try to click on everything just in case there's some hidden functionality there.
-
When for example the icon of a valve supports a direct "on click" action as in BOY, the results can be unexpected and dangerous. Will the click simply open a detail screen? Will it open/close the valve? A designated action button with labels like "Open", "Close", "Detail" avoids surprises.
-
Quite a few widgets already react to the primary mouse button click, for example a text entry widget will start editing.
If a hidden action needs to be assigned to a click on some region, an action button with the 'transparent' option selected can be placed over that region. Its usage, however, is discouraged for the reasons mentioned above. Support for this behavior is not guaranteed in all implementations, for example the web runtime. If you end up with many displays that have transparent i.e. invisible buttons and operators need to guess where they can click, you may want to look for professional help.
The "Grouping Container" in BOY clipped its content. The new "Group" doesn't. It establishes a group of widgets which may be helpful in the editor to allow moving them as a whole, and it can also add an optional line or box with label around widgets to visually group content, but otherwise all content is shown, not clipped.
This is a design decision based on finding many auto-converted EDM and BOY screens with groups that contained erroneous widgets. These widget had accidentally been added to groups via drag/drop or copy/paste operations, ending up to the far right or bottom of a group to be clipped. Since they were hidden, nobody noticed them. At runtime, though, they caused unnecessary PV traffic, or warnings because of undefined macros or unresolved PVs.
The display builder thus doesn't clip group content. To not show a widget in a group, simply don't include it in a group.
The "Linking Container" in BOY is now called "Embedded Display". Functionality is similar with a few different details.
Embedded content is loaded in background threads. While BOY would freeze the UI until all linking container content has been resolved, the Embedded Display content is loaded in background threads.
As a corollary to handling the embedded content in background threads, the content is a "black box". The embedded display widget itself starts out empty. As its content is resolved, it will be displayed. This might be fast when the content is loaded from a local file. It might take longer via remote file systems, or never happen in case of errors. The main display has no knowledge of the embedded content. In the editor, one cannot "snap" to widgets inside an embedded container. At runtime, scripts in the parent display cannot access the embedded content.
The suggested "Resize Behavior" option is "No Resize", the default, because text and line widths
in resized content tends to look out of place compared to the parent display.
When selecting to resize either the content or the container, note that this is based on the
size declared by the content, i.e. the "Width" and "Height" settings of the embedded display.
BOY ignored the declared size and instead computed the convex hull of the content.
Honoring the declared size avoids surprises and allows you to for example add some empty space around
the widgets in the content. When embedding existing BOY *.opi content,
you might have to adjust its "Width" and "Height" settings that BOY ignored to get the desired
resize behavior.
Both BOY and the Display Builder support macros with the same $(MACRO_NAME) syntax
in similar places, but there are subtle differences.
The Display Builder sees macros as a collection of name/value settings without any specific order, while BOY keeps macros as a list of name/value settings. The Display Builder evaluates macros when they are used, while BOY expanded macros earlier. These implementations are based on different assumptions about the frequency of macro definition vs. use and related optimizations.
For example, assume macros A=1 and B=$(A).
The Display Builder keeps these as A=1 and B=$(A), or B=$(A) and A=1, again the order doesn't matter.
When some widget finally uses $(B), it's expanded to the value of B, i.e. $(A), which then expands to 1.
BOY would expand macros at some time between definition and use. So the example macros changed into A=1 and B=1, in that order, with the value of B already resolved.
To the end user, the behavior is the same with one exception. BOY allows circular re-definition of macros.
Assume A=1, B=2 in a top-level display. An embedded display then defines SAVE=$(A), A=$(B), B=$(SAVE). In BOY, the embedded content ends up with A=2, B=1, SAVE=1, i.e. the values of A and B are swapped, and there is a leftover SAVE macro.
In the Display Builder, the embedded content ends up with SAVE=$(A), A=$(B), B=$(SAVE). When trying to evaluate $(A), this expands to $(B), which then resolves to $(SAVE), then $(A) and so on, creating an infinite loop that will be detected and the macro evaluation stops.
Such displays will have to be updated to remove circular macro re-definitions.
BOY macro definition include an option to not include parent macros. This was originally provided to be compatible with EDM, but when neither the original EDM developer nor any local BOY user could come up with a use case for not including parent macros, this option was omitted. Macros in the Display Builder thus behave like environment variables, child widgets always inherit parent macros which they can redefine or ignore, but not drop.
Finally, the Display Builder will fall back to environment variables when resolving macros.
When for example resolving $(USER) but no USER macro has been defined, it will fall back
to a $(USER) environment variable.
See Display Builder Script Compatibility.
Rules are more portable than scripts, but they are still a special feature of BOY and the Display Builder that might not be supported by the next tool. Existing BOY rules may refer to widget properties that do not map to Display Builder widget properties.
Some BOY screens contained 'monitoring' widgets without a 'pv_name', then updating the 'pv_value' from a rule or script. Such displays should be updated to use a proper PV, i.e. set the 'pv_name' which then updates the 'pv_value'.