Scripts

For more advanced dynamic runtime behaviour, we can write scripts (actually Rules are a thin layer on top of scripts). With scripts we can write arbitrary logic that can dynamically manipulate just about any combination of properties for a widget.

Yamcs Studio supports two dynamic languages: JavaScript and Python. Both languages can be used to the same effect, and are available without any external dependencies. As of now, there is no advanced editor support bundled with Yamcs Studio though, so scripts are edited with a plain text editor.

Additional, both from JavaScript and Python scripts, Java code can called from within the script by importing the desired Java packages.

Create a script for a widget

  1. Edit the Scripts property to pop up this dialog.

Attach a Script

  1. Clicking the plus icon gives allows to select one or more scripts that will be executed. A script definition can be embedded in the display which is an acceptable solution for simple scripts. Else scripts are defined in their own javascript or python file, stored in the project workspace.

  2. In the In the right Input PVs table add your input PV(s). The script(s) will be triggered when the PV receives an udpate. At least one PV must be set as Trigger for the script to be executed.

  3. The Options tab provides some options for specific cases:

    • Skip executes triggered by PVs’ first value. will prevent the execution of the sript on the first update of the PVs.
    • Execute anyway even if some PVs are diconnected: by default the scripts are not executed if some of the input PVs are disconnected.
    • Do not execute the script if erro was detected: by default if an execution of the script fails, the scrip is executed again when a PV update is received.

Access Widgets

To access and control the widgets of the OPI displays, two special objects are defined by the CSStudio layer: widget and display. This section contains the related documentation.

widget object

The widget to which a script is attached can be accessed in the script via widget object. Widget object provides the methods to get or set any of its properties, store external objects or provide special methods for a particular widget.

display object

The widget controller of the display is accessible in all scripts as display object. To get the controller of any widget in the display, you can call its method getWidget(name). For example:

display.getWidget("myLabel").setPropertyValue("x", 20); //set x position of the widget myLabel to 20.

Common methods to all widgets

  • getPropertyValue(prop_id)
  • setPropertyValue(prop_id, value)
  • setPropertyValue(prop_id, value, forceFire)
  • getPVByName(pvName)
  • setVar(varName, varValue)
  • getVar(name)
  • getMacroValue(macroName)
  • executeAction(index)
  • setEnabled(enable)
  • setVisible(visible)
  • setX(x)
  • setY(y)
  • setWidth(width)
  • setHeight(height)

Common methods to all container widgets

Container widgets includes Display, Grouping Container, Linking Container and Tabbed Container.

  • getChild(name)
  • getWidget(name)
  • addChild(model)
  • addChildToRight(model)
  • addChildToBottom(model)
  • removeChildByName(name)
  • removeChild(widget)
  • removeChild(index)
  • removeAllChildren()
  • performAutosize()
  • getValue()
  • setValue()

Common methods to all PV widgets

Any widget that has PV Name property is PV widget. For example, Text Update, Combo Box, XY Graph and so on.

  • getPV()
  • getPV(pvPropId)
  • getValue()
  • setValue(value)
  • setValueInUIThread(value)

Access PV

pvs object

The input PVs for a script can be accessed in script via pvs object. The order of the input PVs in the configuation list is preserved in pvs. pvs[0] is the first input pv. If you have N input PVs, pvs[N-1] is the last input PV.

You may also able to get the PV attached to a PV widget via widget.getPV().

In script, you can read/write PV or get its timestamp or severity via the utility APIs provided in PVUtil

triggerPV object

The PV that triggers the execution of the script can be accessed via triggerPV object. When there are more than one trigger PV for a script and you need to know this execution is triggered by which PV, you can use this object. For example,


if(triggerPV == pvs[1])
    ConsoleUtil.writeInfo("I'm triggered by the second input PV.");

Examples:

  1. Get double value from PV

var value = PVUtil.getDouble(pvs[0]);
widget.setPropertyValue("start_angle", value);
  1. Write PV Value If writing a PV is forbidden by PV security, an exception will be thrown and shown in console. The method PV.setValue(data) accepts Double, Double[], Integer, String.

pvs[0].setValue(0);
  1. Get severity of PV

                var RED = ColorFontUtil.RED;
                var ORANGE = ColorFontUtil.getColorFromRGB(255,255,0);
                var GREEN = ColorFontUtil.getColorFromHSB(120.0,1.0,1.0);
                var PINK = ColorFontUtil.PINK;

                var severity = PVUtil.getSeverity(pvs[0]);
                var color;

                switch(severity){
                    case 0:  //OK
                        color = GREEN;
                        break;
                    case 1:  //MAJOR
                        color = RED;
                        break;
                    case 2:  //MINOR
                        color = ORANGE;
                        break;
                    case -1:  //INVALID
                    default:
                        color = PINK;
                }

                widget.setPropertyValue("foreground_color",color);

Scripts Default Packages

To ease the implementation of scripts, a number of APIs are provided in the packages org.csstudio.opibuilder.scriptUtil and org.yamcs.studio.script. Those packages are imported by default in each stript and there is no need to import them at the begining of a script.

This section lists the methods available in the package org.yamcs.studio.script via the following class:

  • Yamcs

via the package org.csstudio.opibuilder.scriptUtil, provided by the CSStudio layer, in the following classes:

  • PVUtil
  • ColorFontUtil
  • DataUtil
  • ScriptUtil
  • FileUtil
  • WidgetUtil
  • GUIUtil
  • ConsoleUtil

Yamcs

Method Summary

Modifier and Type Method and Description
static void
issueCommand(java.lang.String commandSource)
Issue a telecommand via the current Yamcs instance.
Usage example: Yamcs.issueCommand('/YSS/SIMULATOR/SWITCH_VOLTAGE_ON(voltage_num: 1)')

PVUtil

The utility class to facilitate Javascript programming for PV operation.

Method Summary

Modifier and Type Method and Description
static org.csstudio.simplepv.IPV
createPV(java.lang.String name,
        org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)
Create a PV and start it.
static double
getDouble(org.csstudio.simplepv.IPV pv)
Try to get a double number from the PV.
static double
getDouble(org.csstudio.simplepv.IPV pv,
         int index)
Try to get a double-typed array element from the Value.
static double[]
getDoubleArray(org.csstudio.simplepv.IPV pv)
Try to get a double-typed array from the pv.
static java.lang.String
getFullString(org.csstudio.simplepv.IPV pv)
Get the full info from the pv in this format
static java.lang.String[]
getLabels(org.csstudio.simplepv.IPV pv)
Get the list of Enum values
static java.lang.Long
getLong(org.csstudio.simplepv.IPV pv)
Try to get a long integer number from the PV.
static long[]
getLongArray(org.csstudio.simplepv.IPV pv)
Try to get an integer-typed array from the pv.
static int
getSeverity(org.csstudio.simplepv.IPV pv)
Get severity of the pv as an integer value.
static java.lang.String
getSeverityString(org.csstudio.simplepv.IPV pv)
Get severity of the PV as a string.
static double
getSize(org.csstudio.simplepv.IPV pv)
Get the size of the pv's value
static java.lang.String
getStatus(org.csstudio.simplepv.IPV pv)
Get the status text that might describe the severity.
static java.lang.String
getString(org.csstudio.simplepv.IPV pv)
Converts the given pv's value into a string representation.
static java.lang.String[]
getStringArray(org.csstudio.simplepv.IPV pv)
Get string array from pv.
static double
getTimeInMilliseconds(org.csstudio.simplepv.IPV pv)
Get milliseconds since epoch, i.e.
static java.lang.String
getTimeString(org.csstudio.simplepv.IPV pv)
Get the timestamp string of the pv
static java.lang.String
getTimeString(org.csstudio.simplepv.IPV pv,
             java.lang.String formatPattern)
Get the timestamp string of the pv
static void
writePV(java.lang.String pvName,
       java.lang.Object value)
Write a PV in a background job.
static void
writePV(java.lang.String pvName,
       java.lang.Object value,
       int timeout)
Write a PV in a background job.

ColorFontUtil

Utility class to facilitate Javascript programming for color operation.

Field Summary

Modifier and Type Field and Description
static org.eclipse.swt.graphics.RGB
BLACK
the color of black
static org.eclipse.swt.graphics.RGB
BLUE
the color of blue
static org.eclipse.swt.graphics.RGB
CYAN
the color of cyan
static org.eclipse.swt.graphics.RGB
DARK_GRAY
the color of dark gray
static org.eclipse.swt.graphics.RGB
GRAY
the color of gray
static org.eclipse.swt.graphics.RGB
GREEN
the color of green
static org.eclipse.swt.graphics.RGB
LIGHT_BLUE
the color of light blue
static org.eclipse.swt.graphics.RGB
ORANGE
the color of orange
static org.eclipse.swt.graphics.RGB
PINK
the color of pink
static org.eclipse.swt.graphics.RGB
PURPLE
the color of orange
static org.eclipse.swt.graphics.RGB
RED
the color of red
static org.eclipse.swt.graphics.RGB
WHITE
the color of white
static org.eclipse.swt.graphics.RGB
YELLOW
the color of yellow

Method Summary

Modifier and Type Method and Description
static org.eclipse.swt.graphics.RGB
getColorFromHSB(float hue,
               float saturation,
               float brightness)
Get a color with the given hue, saturation, and brightness.
static org.eclipse.swt.graphics.RGB
getColorFromRGB(int red,
               int green,
               int blue)
Get a color with the given red, green and blue values.
static org.eclipse.swt.graphics.FontData
getFont(java.lang.String name,
       int height,
       int style)
Get a new font data given a font name, the height of the desired font in points, and a font style.

DataUtil

Utility class to facilitate Javascript programming for data operation.

Method Summary

Modifier and Type Method and Description
static double[]
createDoubleArray(int size)
Create a new double array with given size.
static int[]
createIntArray(int size)
Create a new int array with given size.
static org.csstudio.opibuilder.util.MacrosInput
createMacrosInput(boolean include_parent_macros)
Create a MacrosInput, which can be used as the macros input for a container widget or display.
static double[]
toJavaDoubleArray(org.mozilla.javascript.NativeArray jsArray)
Convert JavaScript array to Java double array.
static int[]
toJavaIntArray(org.mozilla.javascript.NativeArray jsArray)
Convert JavaScript array to Java int array.

ScriptUtil

The utility class to facilitate OPI script programming.

Method Summary

Modifier and Type Method and Description
static void
closeCurrentOPI</strong>()
Close current active OPI.
static void
execInUI</strong>(java.lang.Runnable runnable,org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)
Execute a runnable in UI thread.
static void
executeEclipseCommand</strong>(java.lang.String commandId)
Execute an Eclipse command.
static void
executeSystemCommand</strong>(java.lang.String command,int wait)
Executing a system or shell command.
static org.osgi.framework.Version
getBOYVersion</strong>()
 
static boolean
isMobile</strong>()
If the current OPI is running on Mobile device.
static boolean
isMobile</strong>(org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)
If the current OPI is running on Mobile device.
static boolean
isWebOPI</strong>()
 
static void
makeElogEntry</strong>(java.lang.String filePath)
                                        
static void
makeLogbookEntry</strong>(java.lang.String text, java.lang.String filePath)
Pop up a logbook dialog to make a logbook entry.
static void
openOPI</strong>(org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget,
                                            java.lang.String opiPath, int target,
                                            org.csstudio.opibuilder.util.MacrosInput macrosInput)
Open an OPI.

FileUtil

The Utility class to help file operating.

Method Summary

Modifier and Type Method and Description
static java.io.InputStream
getInputStreamFromFile(java.lang.String filePath,
                      org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)
Return an
InputStream
of the file on the specified path.
static org.jdom.Element
loadXMLFile(java.lang.String filePath)
Load the root element of an XML file.
static org.jdom.Element
loadXMLFile(java.lang.String filePath,
           org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)
Load the root element of an XML file.
static void
openFile(java.lang.String filePath,
        org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)
Open a file in default editor.
static java.lang.String
openFileDialog(boolean inWorkspace)
Open a file select dialog.
static void
openWebPage(java.lang.String link)
Open a web page.
static void
playWavFile(java.lang.String filePath,
           org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)
Play a .wav file.
static java.lang.String
readTextFile(java.lang.String filePath)
Read a text file.
static java.lang.String
readTextFile(java.lang.String filePath,
            org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)
Read a text file.
static java.lang.String
saveFileDialog(boolean inWorkspace)
Open a file save dialog.
static java.lang.String
workspacePathToSysPath(java.lang.String workspacePath)
Convert a workspace path to system path.
static void
writeTextFile(java.lang.String filePath,
             boolean inWorkspace,
             org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget,
             java.lang.String text,
             boolean append)
Write a text file.
static void
writeTextFile(java.lang.String filePath,
             boolean inWorkspace,
             java.lang.String text,
             boolean append)
Write a text file.

WidgetUtil

The Utility Class to help managing widgets.

Method Summary

Modifier and Type Method and Description
static org.csstudio.opibuilder.model.AbstractWidgetModel
createWidgetModel(java.lang.String widgetTypeID)
Create a new widget model with the give widget type ID.

GUIUtil

The utility class to facilitate script programming in GUI operation.

Method Summary

Modifier and Type Method and Description
static void
compactMode()
Enter or exit compact mode.
static void
fullScreen()
Enter or exit full screen.
static boolean
openConfirmDialog(java.lang.String dialogMessage)
Open a dialog to ask for confirmation.
static boolean
openPasswordDialog(java.lang.String dialogMessage,
                  java.lang.String password)
Open a password dialog to allow user to input password.

ConsoleUtil

The Utility Class to help write information to CSS console.

Method Summary

Modifier and Type Method and Description
static void
writeError(java.lang.String message)
Write Error information to CSS console.
static void
writeInfo(java.lang.String message)
Write information to CSS console.
static void
writeString(java.lang.String string)
Write pure string to CSS console without any extra headers in black color.
static void
writeString(java.lang.String string,
           int red,
           int green,
           int blue)
Write pure string to CSS console in specified color.
static void
writeWarning(java.lang.String message)
Write Warning information to CSS console.

Examples

Some examples of display scripts are provided below, covering some common use cases: