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"
#
# 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_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"
2.2. API references¶
-
class
ScadaAPI
¶ SCADA API (Application Programming Interface) allows interfacing to the underlying HIL SCADA model.
-
create_widget
(widget_type, parent=None, name=None, position=None)¶ Creates new widget using provided widget type inside the group like widget specified by
parent
. Ifparent
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 constantsparent (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.
- 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.
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_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 callingsave_panel_as()
function. After Panel is saved withsave_panel_as()
it can be saved later by using regularsave_panel()
function.- Returns
None
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()
-
copy
(src_handle, dst_handle=None, name=None, position=None)¶ Copies widget identified by
src_handle
to Group like widget identified bydst_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.
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.
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)
-
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 constantsNote
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 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
.
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 constantsNote
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 any of arguments is 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. 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.
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")
-