2. SCADA API¶

Module: typhoon.api.scada

SCADA API is a collection of functions/methods that can be used for changing widget parameters. To use SCADA API to change widget parameters, you must first load the HIL SCADA Panel file.

Note

In case you try to use any other function then load_panel() before the Panel file is loaded, a ScadaAPIException will be raised. The same exception will be raised in case any error occurs in any SCADA API function.

Example:

from typhoon.api.scada import panel

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

You can access a particular widget by using the Widget ID or the Widget FQN (Fully Qualified Name) once its respective Panel has loaded.

Note

To get the Widget ID or Widget FQN (Fully Qualified Name), open the Panel file in HIL SCADA, right-click on the desired widget, and choose either the Copy Widget ID or Copy Widget Fully Qualified Name action.

Example:

from typhoon.api.scada import panel

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

# get the widget handle by using a Widget ID
widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

# or get the same widget handle by using a Widget FQN
widget_handle = panel.get_widget_by_fqn("Sub-Panel.Gauge")

Once the desired widget is acquired, its properties can be changed.

Note

Not all widget properties can be changed by SCADA API. For detailed information witch properties can be changed for a specific widget, please consult the Available Widget Properties section.

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const
from typhoon.api.scada.exception import ScadaAPIException

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

# get the widget handle
widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

# change the widget name
panel.set_property_value(widget_handle,
                         api_const.PROP_NAME,
                         "New widget name")

# in case we try to change an unsupported property or a new property
# value is not valid ``ScadaAPIException`` will be raised
try:
    # the new property value is invalid
    panel.set_property_value(widget_handle,
                             api_const.PROP_NAME,
                             [56, 28, 89])
except ScadaAPIException as ex:
    print(ex)

After you finish modifying the Panel and the Panel’s widget, the loaded Panel can be saved to an existing Panel file or as a new Panel file.

Complete example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const
from typhoon.api.scada.exception import ScadaAPIException

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

# get the widget handle whose properties you want to change
widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

# change the widget name
panel.set_property_value(widget_handle,
                         api_const.PROP_NAME,
                         "New widget name")

# in case we try to change an unsupported property or a new property
# value is not valid ``ScadaAPIException`` will be raised
try:
    # the new property value is invalid
    panel.set_property_value(widget_handle,
                             api_const.PROP_NAME,
                             [56, 28, 89])
except ScadaAPIException as ex:
    print(ex)

# save changes to the existing Panel file...
panel.save_panel()

# ...or save changes to a new Panel file
panel.save_panel_as(r"C:\new_scada_file.cus")

2.1. WidgetHandle¶

WidgetHandle is an object used as a connection between SCADA API and a real SCADA Widget, serving as widget identifier. It is used as an argument in nearly all SCADA API functions to identify the widget that we want to create, change, or delete.

This object contains few attributes that can be used in various places in SCADA API:

item_type (str): SCADA Widget type
item_fqid (str): SCADA Widget ID
item_name (str): SCADA Widget name
item_fqn (str): SCADA Widget fully qualified name (FQN)
item_parent_id (str): SCADA Widget parent ID
item_parent_fqn (str): SCADA Widget parent fully qualified name (FQN)

2.2. SCADA API constants¶

Module: typhoon.api.scada.const

Various SCADA API methods expect predefined constants for some of their parameters.

Below is a listing (Python module) of all constants which are used in SCADA API methods.

#

PROP_NAME = "name"
PROP_HTML_NAME = "html_name"
PROP_NAME_POSITION = "name_position"
PROP_LABEL = "label"
PROP_USE_LABEL = "use_label"
PROP_FQN = "fully_qualified_name"
PROP_DESCRIPTION = "description"
PROP_PANEL_INIT = "panel_init_code"
PROP_PANEL_LOCK = "panel_locked"
PROP_POSITION = "position"
PROP_SIZE = "size"
PROP_APPEARANCE = "appearance"
PROP_SIGNALS = "signals"
PROP_STREAMING_SIGNALS = "streaming_signals"
PROP_DATA_TYPE = "data_type"
PROP_EXPRESSION = "expression_code"
PROP_UPDATE_RATE = "update_rate"
PROP_TIME_WINDOW = "time_window"
PROP_UNIT = "unit"
PROP_AUTO_UNIT = "auto_unit_assign"
PROP_BG_COLOR = "bg_color"
PROP_PANEL_BG_COLOR = "panel_bg_color"
PROP_BG_TYPE = "bg_type"
PROP_USE_AS_BG = "use_as_bg"
PROP_RANGE = "range"
PROP_USE_COLOR_RANGE = "use_color_range"
PROP_WARNING_RANGE = "warning_range"
PROP_CRITICAL_RANGE = "critical_range"
PROP_GREEN_RANGE = "green_range"
PROP_ORANGE_RANGE = "orange_range"
PROP_DECIMALS = "decimals"
PROP_SCALING_FACTOR = "scaling_factor"
PROP_STREAMING_AN_SIG_SCALING = "streaming_analog_signals_scaling"
PROP_AN_SIG_SCALING = "analog_signals_scaling"
PROP_RED_RANGE = "red_range"
PROP_LED_COLOR = "led_color"
PROP_X_TITLE = "x_title"
PROP_Y_TITLE = "y_title"
PROP_X_TITLE_ENABLED = "x_title_enabled"
PROP_Y_TITLE_ENABLED = "y_title_enabled"
PROP_CUSTOM_X_TITLE = "custom_x_title"
PROP_CUSTOM_Y_TITLE = "custom_y_title"
PROP_CUSTOM_X_TITLE_ENABLED = "custom_x_title_enabled"
PROP_CUSTOM_Y_TITLE_ENABLED = "custom_y_title_enabled"
PROP_X_RANGE = "x_range"
PROP_Y_RANGE = "y_range"
PROP_AUTO_SCALE_ENABLED = "autoscale_enabled"
PROP_X_AUTO_SCALE_ENABLED = "x_axis_autoscale_enabled"
PROP_Y_AUTO_SCALE_ENABLED = "Y_axis_autoscale_enabled"
PROP_LEGEND_ENABLED = "legend_enabled"
PROP_REF_CURVE_ENABLED = "ref_curves_enabled"
PROP_REF_CURVE = "ref_curves_code"
PROP_PV_PANEL = "pv_panel"
PROP_LINE_STYLE = "line_style"
PROP_PLOT_RANGE = "plot_range"
PROP_PHASORS_SETTINGS = "phasors_settings"
PROP_BARS_SETTINGS = "bars_settings"
PROP_ON_USE_ENABLED = "on_use_enabled"
PROP_ON_USE = "on_use_code"
PROP_ON_START_ENABLED = "on_start_enabled"
PROP_ON_START = "on_start_code"
PROP_ON_START_SOURCE = "on_start_code_source"
PROP_ON_TIMER_ENABLED = "on_timer_enabled"
PROP_ON_TIMER = "on_timer_code"
PROP_ON_TIMER_RATE = "on_timer_rate"
PROP_ON_STOP_ENABLED = "on_stop_enabled"
PROP_ON_STOP = "on_stop_code"
PROP_COMBO_VALUES = "values"
PROP_VALUE_TYPE = "value_type"
PROP_INPUT_WIDTH = "input_width"
PROP_STEP = "step"
PROP_USE_PANEL_DIR = "use_panel_dir"
PROP_LOG_FILE_DIR = "log_file_dir"
PROP_LOG_FILE = "log_file"
PROP_LOG_FILE_FORMAT = "log_file_format"
PROP_USE_SUFFIX = "use_suffix"
PROP_LOGGING_ON_START = "start_logging_on_start"
PROP_USE_SLOWER_UPDATE_RATE = "use_slower_update_rate"
PROP_SLOWER_UPDATE_RATE = "slower_update_rate"
PROP_CONNECTION_IDENTIFIER = "connection_identifier"
PROP_SERIAL_PORT_SETTINGS = "serial_port_settings"
PROP_SERIAL_PORT_NAME = "serial_port_name"
PROP_GROUP_NAMESPACE = "group_namespace"
PROP_COLLAPSED = "collapsed"
PROP_USE_IMAGE = "use_image"
PROP_IMAGE = "image"
PROP_IMAGE_SCALING = "image_scaling"
PROP_TEXT = "text"
PROP_SUB_PANEL_MODE = "sub_panel_mode"
PROP_MODEL_COMP_TYPES = "model_components_types"
PROP_MODEL_COMP = "model_component"
PROP_WIDGET_VALUE = "widget_value"
PROP_CS_STATE = "state"
PROP_CS_CAPTURE_TIME_INTERVAL = "time_interval"
PROP_CS_CAPTURE_SAMPLE_RATE = "sample_rate"
PROP_CS_SCOPE_TIME_BASE = "time_base"
PROP_CS_CAPTURE_BG = "capture_background"
PROP_CS_SCOPE_BG = "scope_background"
PROP_CS_CAPTURE_LEGEND = "capture_legend"
PROP_CS_SCOPE_LEGEND = "scope_legend"
PROP_CS_CAPTURE_LAYOUT = "capture_layout"
PROP_CS_SCOPE_LAYOUT = "scope_layout"
PROP_CS_CAPTURE_SIGNALS = "capture_signals"
PROP_CS_SCOPE_SIGNALS = "scope_signals"
PROP_CS_SCOPE_TRIGGER = "scope_trigger"
PROP_CS_CAPTURE_TRIGGER = "capture_trigger"
PROP_CS_ACTIVE_CAPTURE_PRESET = "active_capture_preset"
PROP_CS_ACTIVE_SCOPE_PRESET = "active_scope_preset"

#
# Widget actions
#

ACT_CS_FORCE_TRIGGER = "force_trigger"
ACT_CS_ENABLE_TRIGGER = "enable_trigger"
ACT_CS_STOP_CAPTURE = "stop_capture"
ACT_CS_EXPORT_DATA = "export_data"

#
# Widget types
#

WT_MACRO = "Macro"
WT_BUTTON_MACRO = "MacroButton"
WT_TEXT_MACRO = "TextBoxMacro"
WT_COMBO_MACRO = "ComboBoxMacro"
WT_CHECKBOX_MACRO = "CheckBoxMacro"
WT_SLIDER_MACRO = "SliderMacro"
WT_KNOB_MACRO = "KnobMacro"

WT_GAUGE = "Gauge"
WT_DIGITAL = "DigitalDisplay"
WT_TEXT = "TextDisplay"
WT_LED = "LedDisplay"
WT_TRACE = "TraceDisplay"
WT_PV = "PVDisplay"
WT_XY_GRAPH = "XYGraphDisplay"
WT_PHASOR_GRAPH = "PhasorGraphDisplay"
WT_BAR_GRAPH = "BarGraphDisplay"

WT_GROUP = "Group"
WT_SUB_PANEL = "SubPanel"
WT_LIBRARY_CATEGORY = "LibraryCategory"
WT_TEXT_NOTE = "TextNote"
WT_IMAGE = "Image"
WT_SERIAL_COMM = "SerialComm"
WT_CAPTURE_SCOPE = "Capture/Scope"

WT_SIGNAL_DATA_LOGGER = "SignalDataLogger"
WT_STREAMING_DATA_LOGGER = "StreamingSignalDataLogger"

WT_FREQUENCY_RESPONSE = "FrequencyResponse"

# Capture/Scope signal types
CS_SIG_T_A = "Analog"
CS_SIG_T_D = "Digital"
CS_SIG_T_V = "Virtual"

2.3. SCADA API in HIL SCADA¶

HIL SCADA supports a subset of SCADA API functions, mainly for changing Panel widget properties and executing actions which are near identical to manual GUI actions.

The following functions are available:

get_widget_by_id()
get_widget_by_fqn()
set_property_value()
get_property_value()
execute_action()

Note

The functions listed above can be used in all handlers (Action Widgets) and Expression scripts (Monitoring Widgets), including the Panel and the local namespace (group-like widgets) initialization scripts.

Note

SCADA API is imported into the HIL SCADA namespace as panel

Note

It is not recommended to change a widget’s parameters from multiple places (handlers, expression scripts…) at the same time.

Note

The number of widgets which have support for the execute_action() function is currently limited. More information can be found in the Available Widget Actions documentation.

The function expects two mandatory arguments - widget_handle and action_name.

It can also receive other optional keyword arguments (arg_name=arg_value) - this depends on the implementation of each widget.

Below you can find an example of changing the widget’s name and executing an action:

# store the widget id
w_id = "484d3a86ffcf11e9956de0d55e6b2045"

# get the widget that needs to be changed (in this case the Capture/Scope widget)
wh = panel.get_widget_by_id(w_id)

# change the widget's properties
panel.set_property_value(wh,
                         prop_name=api_const.PROP_NAME,
                         prop_value="New name")


# executing the "force_trigger" action (api_const.ACT_CS_FORCE_TRIGGER)
panel.execute_action(widget_handle=wh,
                     action_name=api_const.ACT_CS_FORCE_TRIGGER)

2.4. API references ¶

class ScadaAPI¶

SCADA API (Application Programming Interface) allows interfacing to the underlying HIL SCADA model.

add_library_path(library_path, add_subdirs=False, persist=False)¶

Add path to library search path. Added path will be treated as temporarily path (persist=False). In case you want to save it, set persist=True.

Parameters:

library_path (str) – Directory path where library files are located.
add_subdirs (bool) – Search in subdirectories for library files.
persist (bool) – Make library path change permanent.

Returns:

None

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel

# Add new path to library search path.
panel.add_library_path(r"C:\new_library_dir")

# reload library after search path is modified
panel.reload_libraries()

create_widget(widget_type, parent=None, name=None, position=None, link_to_model_comp=None)¶

Creates new widget using provided widget type inside the group like widget specified by parent. If parent is not specified main Panel’s canvas will be used as a parent.

Parameters:

widget_type (str) – type of widget that need to be created. The list of all widget type names can be found in the typhoon.api.scada.const module or listed in the section SCADA API constants
parent (WidgetHandle) – parent group like widget where this widget need to be created and added.
name (str) – name of the widget.
position (list or tuple) – list[x, y] coordinates where new widget need to be positioned after it is created.
link_to_model_comp (str) –
Fully qualified name (FQN) of Schematic Model component that we want to connect to created Library Widget.

Note

Specifying this argument only has effect if a Library widget is created and that Library widget is configured to be connected to Model component.

Returns:

handle to the created widget.

Return type:

Widget handle (WidgetHandle)

Raises:

ScadaAPIException – in case any of arguments is invalid.
ScadaAPIException – in case Panel is not specified.
ScadaAPIException – in case parent widget with given id cannot be found in loaded Panel.
ScadaAPIException – in case widget cannot be created for some reason

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const

# create new blank Panel
panel.create_new_panel()

# create Group widget on the main/root canvas
group_handle = panel.create_widget(widget_type=api_const.WT_GROUP,
                                   parent=None,
                                   name="Group for other widgets",
                                   position=[0, 200])

# create Digital display inside Group widget
dig_d_handle = panel.create_widget(widget_type=api_const.WT_DIGITAL,
                                   parent=group_handle,
                                   name="Digital Display",
                                   position=[20, 20])

#
# Create Library widget and connect it to Inductor 'Lc' Schematic component
#

# Add directory where libraries are located to library search path.
panel.add_library_path(r"C:\new_library_dir")

# reload library
panel.reload_libraries()

# create new blank Panel
panel.create_new_panel()

# create 'Group' Library widget from Widget Library 'Lib1'
group_handle = panel.create_widget(widget_type="Lib1/Group",
                                   parent=None,
                                   name="Group Library Widget",
                                   position=[0, 200],
                                   link_to_model_comp="Lc")

create_new_panel()¶

Creates new empty Panel in memory.

Note

In case Panel is created and not loaded with load_panel(), for first time it can be only saved by calling save_panel_as() function. After Panel is saved with save_panel_as() it can be saved later by using regular save_panel() function.

Returns:: None

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const

# create new blank Panel
panel.create_new_panel()

# create Digital display on the main/root canvas
dig_d_handle = panel.create_widget(widget_type=api_const.WT_DIGITAL,
                                   parent=None,
                                   name="Digital Display",
                                   position=[20, 20])

# save panel to file for the first time
panel.save_panel_as(r"C:\panel.cus")

#
# create or change something on Panel...
#

# now Panel can be saved to specified Panel file
panel.save_panel()

create_new_library_panel(library_name, library_description='')¶

Creates new empty Library Panel in memory.

Parameters:

library_name (str) – name of the Widget Library
library_description (str) – short description

Note

In case Library Panel is created and not loaded with load_library_panel() for first time it can be only saved by calling save_panel_as() function. After Panel is saved with save_panel_as() it can be saved later with regular save_panel() function.

Returns:: None
Raises:: ScadaAPIException – in case any of arguments are invalid

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const

# create new blank Library Panel
panel.create_new_library_panel(library_name="Lib1",
                               library_description="My simple library")

# create Group that will become Library Widget candidate
group_handle = panel.create_widget(widget_type=api_const.WT_GROUP,
                                   parent=None,
                                   name="Group",
                                   position=[20, 20])

# create Digital display inside Group
dig_d_handle = panel.create_widget(widget_type=api_const.WT_DIGITAL,
                                   parent=group_handle,
                                   name="Digital Display",
                                   position=[20, 20])

# save Library Panel to file for the first time
panel.save_panel_as(r"C:\lib1.wlib")

#
# create or change something in Library Panel...
#

# now Library Panel can be saved to specified Library Panel file
panel.save_panel()

copy(src_handle, dst_handle=None, name=None, position=None)¶

Copies widget identified by src_handle to Group like widget: identified by dst_handle.

Note

Source widget and all its child widgets (in case source widget is Group like widget) will be copied to destination widget.

Parameters:

src_handle (WidgetHandle) – Handle of widget that need to be copied.
dst_handle (WidgetHandle) –
Handle to Group like widget where source widget need to be copied.

Note

In case dst_handle is None, source widget will be copied to main (root) Panel’s canvas.
name (str) – new name of copied widget.
position (list or tuple) – list[x, y] coordinates where new copied widget need to be positioned.

Returns:

flatten list that: contains handles of all copied widgets.

Return type:

List of copied widgets (List[WidgetHandle])

Raises:

ScadaAPIException – in case any of arguments is invalid.
ScadaAPIException – in case destination widget is not Group like widget.
ScadaAPIException – in case Panel is not specified.
ScadaAPIException – in case source or destination widget with given id cannot be found in loaded Panel.

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const

# Create new panel
panel.create_new_panel()

# create widget on the main/root canvas
group_handle = panel.create_widget(widget_type=api_const.WT_GROUP,
                                   parent=None,
                                   name="Group for other widgets",
                                   position=[0, 200])

# create Digital display on the main/root canvas
dig_d_handle = panel.create_widget(widget_type=api_const.WT_DIGITAL,
                                   parent=None,
                                   name="Digital Display",
                                   position=[20, 20])

# copy Digital display to the Group widget
# `copied_widgets` is list with copy of digital display
copied_widgets = panel.copy(src_handle=dig_d_handle,
                            dst_handle=group_handle,
                            name="New name",
                            position=(0, 304))

# copy Group widget to main canvas
# `copied_widgets` is list with copies of Group widget and
# Digital display inside it
copied_widgets = panel.copy(src_handle=group_handle,
                            dst_handle=None,
                            name="New name",
                            position=(0, 304))

delete_widget(widget_handle)¶

Deletes widget from the loaded or created Panel.

Parameters:

widget_handle (WidgetHandle) – Handle of the widget that need to be deleted.

Returns:

None

Raises:

ScadaAPIException – in case widget_handle argument is invalid.
ScadaAPIException – in case Panel is not specified.
ScadaAPIException – in case widget with given id cannot be found in loaded Panel.

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const

# Create new panel
panel.create_new_panel()

# create Group widget on the main/root canvas
group_handle = panel.create_widget(widget_type=api_const.WT_GROUP,
                                   parent=None,
                                   name="Group for other widgets",
                                   position=[0, 200])

# delete Group widget
panel.delete_widget(group_handle)

execute_action(widget_handle, action_name, **params)¶

Executes an action of a widget, if the widget is found by widget handle on the panel.

Note

This function can only be used in HIL SCADA. For a detailed list of executable actions for each widget, please consult the Available Widget Actions documentation.

Parameters:

widget_handle (WidgetHandle) – widget handle object
action_name (str) – name of the action which needs to be executed (all action_name constants are listed in the typhoon.api.scada.const module or listed in the section SCADA API constants)
params (dict) – optional parameters of the action

Returns:

None

Raises:

ScadaAPIException – in case widget_handle or action_name arguments are invalid
ScadaAPIException – in case the widget doesn’t have the passed action_name action
ScadaAPIException – in case Panel is not specified
ScadaAPIException – in case widget with given id cannot be found in loaded Panel

Availability:

macro scripts
signal monitoring expressions

Example:

# Note: execute_action() can only be called in HIL SCADA!

# get the handle of the widget whose actions you want to execute
widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

# executing the "export_data" action (api_const.ACT_CS_EXPORT_DATA)
# the captured data will be exported in the default (png) format
panel.execute_action(widget_handle=wh,
                     action_name=api_const.ACT_CS_EXPORT_DATA)

reload_libraries()¶

Reload all libraries which are found in library search path.

Note

After libraries are reloaded and there is the opened Panel that has a Library widgets, it is recommended to reopen Panel again in order to load up to date Library widgets.

Returns:: None
Raises:: ScadaAPIException – when there is error during library reloading.

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel

# Add new path to library search path.
panel.add_library_path(r"C:\new_library_dir")

# reload library after search path is modified
panel.reload_libraries()

remove_library_path(library_path, persist=False)¶

Remove path from library search path.

Parameters:

library_path (str) – Library path to remove.
persist (bool) – Make library path change permanent after library path is removed.

Returns:

None

Availability:

standalone scripts

Raises:: ScadaAPIException – when given path cannot be found in library registry search path.

Example:

from typhoon.api.scada import panel

# Remove path from library search path.
panel.remove_library_path(r"C:\new_library_dir")

# reload library after search path is modified
panel.reload_libraries()

load_panel(panel_file)¶

Load the provided HIL SCADA Panel (.cus) file.

Parameters:

panel_file (str) – full path to the HIL SCADA Panel (.cus) file.

Returns:

None

Raises:

ScadaAPIException – In case panel_file argument is invalid.
ScadaAPIException – In case provided Panel file cannot be opened.

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

load_library_panel(library_panel_file)¶

Load provided HIL SCADA Widget Library (.wlib) file.

Parameters:

library_panel_file (str) – full path to the HIL SCADA Widget Library (.wlib) file.

Returns:

None

Raises:

ScadaAPIException – In case library_panel_file argument is invalid.
ScadaAPIException – in case provided Library Panel file cannot be opened.

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel

# load a Library Panel file.
panel.load_library_panel(r"C:\lib1.wlib")

save_panel()¶

Save currently opened Panel to the same Panel file.

Returns:

None

Raises:

ScadaAPIException – In case the Panel file is not opened.
ScadaAPIException – In case the opened Panel cannot be saved.

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

#
# change something...
#

# save changes to the existing file ("C:\scada_file.cus")
panel.save_panel()

save_panel_as(save_to)¶

Save the currently opened Panel to a new Panel file.

Parameters:

save_to (str) – full path where opened Panel need to be saved.

Returns:

None

Raises:

ScadaAPIException – In case the Panel file is not opened.
ScadaAPIException – In case save_to argument is invalid.
ScadaAPIException – In case the opened Panel cannot be saved.

Availability:

standalone scripts

Example:

from typhoon.api.scada import panel

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

#
# change something...
#

# save changes to a new Panel file ("C:\new_scada_file.cus")
panel.save_panel()

set_property_value(widget_handle, prop_name, prop_value)¶

Set a new value for the widget property.

Parameters:

widget_handle (WidgetHandle) – The widget handle used as a widget identifier.
prop_name (str) –
The name of property that you want to change. The list of all property names can be found in the typhoon.api.scada.const module or listed in the section SCADA API constants

Note

Not all widget properties can be changed by SCADA API. For detailed information which properties can be changed for a specific widget, please consult Available Widget Properties section.
prop_value (object) –
A new property value that need to be set.

Note

Type of value that need to be set depends of which property is being changed. More details can be found in the Available Widget Properties section.

Returns:

None

Raises:

ScadaAPIException – In case the Panel file is not opened.
ScadaAPIException – In case any of arguments is invalid.
ScadaAPIException – In case the widget identified by widget_handle cannot be found in opened Panel.
ScadaAPIException – In case widget doesn’t have property with given prop_name.
ScadaAPIException – In case property is read only and cannot be changed.

Availability:

standalone scripts
macro scripts
signal monitoring expressions

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

# get the handle of the widget whose properties you want to change
widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

# change the widget name by using the handle as the widget identifier
panel.set_property_value(widget_handle,
                         api_const.PROP_NAME,
                         "New widget name")

get_property_value(widget_handle, prop_name)¶

Returns the value of a given property for the given widget handle.

Parameters:

widget_handle (WidgetHandle) – The widget handle used as a widget identifier.
prop_name (str) –
The name of a property. The list of all property names can be found in typhoon.api.scada.const module or listed in the section SCADA API constants

Note

Not all widget properties can be changed by SCADA API. For detailed information which properties can be changed for a specific widget, please consult Available Widget Properties section.

Returns:

value can be arbitrary type: depending of the type of widget and property. More details can be found in the Available Widget Properties section.

Return type:

property value (object)

Raises:

ScadaAPIException – In case any of arguments is invalid.
ScadaAPIException – In case the widget does not have the property with given the prop_name.
ScadaAPIException – In case property is write only and cannot be read.
ScadaAPIException – In case the Panel is not specified.
ScadaAPIException – In case the widget identified by the widget_handle cannot be found in the opened Panel.

Availability:

standalone scripts
macro scripts
signal monitoring expressions

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

# get the handle of the widget whose properties you want to change
widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

# change the widget name by using the handle as a widget identifier
panel.set_property_value(widget_handle,
                         api_const.PROP_NAME,
                         "New widget name")

# get the widget name by using the handle as a widget identifier
widget_name = panel.get_property_value(widget_handle,
                                       api_const.PROP_NAME)

get_widget_by_id(widget_id)¶

Returns the widget handle for the widget with a given widget ID.

Parameters:

widget_id (str) – Widget ID. Widget ID can be acquired from WidgetHandle item_fqid attribute (widget_handle_object.item_fqid).

Returns:

A handle to the widget with the: given widget_id that can be used as a widget identifier.

Return type:

handle to widget (WidgetHandle)

Raises:

ScadaAPIException – In case the Panel file is not opened.
ScadaAPIException – In case the widget_id argument is invalid.
ScadaAPIException – In case the widget with the given id cannot be found in the loaded Panel.

Availability:

standalone scripts
macro scripts
signal monitoring expressions

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

# get the handle of the widget whose properties you want to change
# 'widget_handle' is used as the widget identifier in other functions and
# it also contains ID ('widget_handle.item_fqid') and type ('widget_handle.item_type')
# of widget that is identified by this handle.
widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

# change the widget name by using the handle as the widget identifier
panel.set_property_value(widget_handle,
                         api_const.PROP_NAME,
                         "New widget name")

get_widget_by_fqn(widget_fqn, parent=None)¶

Returns widget handle for widget with given widget fully qualified name (FQN).

Parameters:

widget_fqn (str) – Widget fully qualified name
parent (WidgetHandle) – parent group like widget where widget with given widget_fqn will be searched. In case parent is specified, given widget_fqn will be used as relative fully qualified name (relative from given parent).

Returns:

handle to widget with given widget FQN

Return type:

WidgetHandle

Raises:

ScadaAPIException – In case any argument is invalid
ScadaAPIException – in case widget with given fully qualified name cannot be found in loaded Panel
ScadaAPIException – in case parent widget with given WidgetHandle cannot be found in loaded Panel
ScadaAPIException – in case Panel is not specified

Availability:

standalone scripts
macro scripts
signal monitoring expressions

Example:

from typhoon.api.scada import panel
import typhoon.api.scada.const as api_const

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")

#
# Get the handle of the widget by using its fully qualified name (FQN)
#

# 'widget_handle' is used as the widget identifier in other functions and
# it also contains ID ('widget_handle.item_fqid'), type ('widget_handle.item_type'),
# widget name ('widget_handle.item_name') and widget FQN ('widget_handle.item_fqn')
# of widget that is identified by this handle.

# In this example widget 'Gauge' that has three parent widgets has FQN:
# "P1.P2.P3.Gauge"
widget_handle = panel.get_widget_by_fqn("P1.P2.P3.Gauge")

#
# In case we want to search for the same widget but relative from parent 'P2'

# find a parent
parent_handle = panel.get_widget_by_fqn("P1.P2")

# we give a parent handle and relative FQN to given parent.
# If absolute FQN is 'P1.P2.P3.Gauge' relative FQN from parent 'P2' is:
# 'P3.Gauge'
widget_handle = panel.get_widget_by_fqn("P3.Gauge", parent=parent_handle)

get_library_paths()¶

Get a list of the library search paths.

Returns:: list with user library paths
Return type:: library paths (list)

Availability:

standalone scripts

2. SCADA API¶

2.1. WidgetHandle¶

2.2. SCADA API constants¶

2.3. SCADA API in HIL SCADA¶

2.4. API references ¶

Table of Contents

Previous topic

Next topic

This Page

2. SCADA API¶

2.1. WidgetHandle¶

2.2. SCADA API constants¶

2.3. SCADA API in HIL SCADA¶

2.4. API references¶

2.4. API references ¶