2. SCADA API

Module: typhoon.api.scada

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

Note

In case you try to use any other function then load_panel() before Panel file is loaded, 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")

After the Panel whose widgets you want to change is loaded, you can access a particular widget by using the Widget ID.

Note

To get the Widget ID open the Panel file in HIL SCADA, right-click on the desired widget and choose Copy Widget ID action.

Example:

from typhoon.api.scada import panel

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

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

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. 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.


#
# Properties names
#

PROP_NAME = "name"
PROP_HTML_NAME = "html_name"
PROP_NAME_POSITION = "name_position"
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_RED_RANGE = "red_range"
PROP_LED_COLOR = "led_color"
PROP_X_TITLE = "x_title"
PROP_Y_TITLE = "y_title"
PROP_Y_RANGE = "y_range"
PROP_X_RANGE = "x_range"
PROP_X_TITLE_ENABLED = "x_title_enabled"
PROP_Y_TITLE_ENABLED = "y_title_enabled"
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_IMAGE = "image"
PROP_IMAGE_SCALING = "image_scaling"
PROP_TEXT = "text"
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_SCOPE_ANALOG_SIGNALS = "scope_analog_signals"
PROP_CS_SCOPE_DIGITAL_SIGNALS = "scope_digital_signals"
PROP_CS_CAPTURE_ANALOG_SIGNALS = "capture_analog_signals"
PROP_CS_CAPTURE_DIGITAL_SIGNALS = "capture_digital_signals"
PROP_CS_SCOPE_TRIGGER = "scope_trigger"
PROP_CS_CAPTURE_TRIGGER = "capture_trigger"

2.2. API references

class ScadaAPI

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

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.

Example:

from typhoon.api.scada import panel

# load a Panel file
panel.load_panel(r"C:\scada_file.cus")
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.

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.

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 witch 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 widget_handle, prop_name or prop_value arguments are 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.

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 witch 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 widget_handle and prop_name arguments are invalid

  • ScadaAPIException – In case the widget does not have the property with given the prop_name

  • 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.

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

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.

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
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")