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 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
widget_handle
,prop_name
orprop_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 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
widget_handle
andprop_name
arguments are invalidScadaAPIException – 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")
-