SCL Class Reference

Common SCL-file manipulation class. More...

Inheritance diagram for SCL:

Public Member Functions
def	from_artifact (cls, str artifact_id)
	Load SCL contents from an Artifact. More...
def	__init__ (self, file_path=None, edition=None, init_empty=False)
def	detect_edition (self, raise_on_unknown=False)
	Detect SCL-file edition. More...
def	to_string (self, pretty_print=True)
	Return SCL object contents as string. More...
def	toString (self, pretty_print=True)
	Alias for to_string function. More...
def	load_from_string (self, scl_str)
	Load SCL contents from string. More...
def	load_from_artifact (self, artifact_str)
	Load SCL contents from string obtained from Artifact. More...
def	write_to_file (self, save_path)
	Write SCL contents to file. More...
def	get_string_snippet_by_line_num (self, line_num, neighbours=0, mark_line=False)
	Get SCL source code snippet by line number. More...
def	validate (self, override_edition=None)
	Validate SCL-file. More...
def	get_ld_by_ldname (self, ldName)
	Get LDevice element by ldName. More...
def	get_ldevice_by_ldname (self, ldName)
	Alias for SCL.get_ld_by_ldname() More...
def	get_iedName_by_ldName (self, ldName)
	Get IED.name attribute by ldName. More...
def	get_ldInst_by_ldName (self, ldName)
	Get LDevice.inst attribute by specified ldName. More...
def	get_ied_by_name (self, iedName, dom=None)
	Get IED element by name attribute. More...
def	get_ln_element_by_ref (self, str ln_ref)
	Get LN/LN0 element by LN Reference. More...
def	add_new_type_to_templates (self, str str_element)
	Adds a new type to the DataTypeTemplates list. More...
int	add_new_object_to_LnType (self, ln_path, str_element)
	Adds a new object type to an existing Logical Node Type. More...
int	add_new_node_to_any_ln (self, str ln_path, str str_element)
	Adds a data object to an existing Logical Node. More...
def	get_dai_by_ref (self, object_reference)
	Retrieves a DAI element by its reference. More...
def	get_doi_by_ref (self, str object_reference)
	Retrieves a DOI element by its reference. More...
def	get_doType_by_doiRef (self, str object_reference)
	Retrieves a DOType element by the DOI reference path. More...
def	get_cdc_by_doiRef (self, str object_reference)
	Retrieve the CDC type associated with a specific DOI reference. More...
def	get_daType_by_daiRef (self, str object_reference)
	Retrieves a DAType element by the DAI reference path. More...
str	get_btype_by_dai_ref (self, str object_reference)
def	get_attributes_with_values (self)
	Get list of data attributes with values set. More...
def	get_da_val_regex_by_daiRef (self, object_reference)
	Returns a regular expression for validating the value of a data attribute by its reference. More...
def	get_Substation_list (self)
	Get list of Substation elements. More...
def	get_ied_list (self, bool server_only=False, bool with_gse_only=False, bool with_smv_only=False)
	Get list of IED elements. More...
def	get_ied_name_list (self, bool server_only=False, bool with_gse_only=False, bool with_smv_only=False)
	Get list of IED names. More...
str	get_ied_name (self, int ied_num=0)
	Get the name of an IED by its number in the file. More...
def	get_ied_access_point_list (self, str ied_name, bool with_server_only=False, allow_serverat=False)
	Get list of AccessPoint elements for a specified IED. More...
def	get_ied_access_point_name_list (self, str ied_name, bool with_server_only=False, allow_serverat=False)
	Get list of AccessPoint names for a specified IED. More...
def	get_ied_access_point_server (self, str ied_name, str ap_name)
	Get Server element for specified IED and AccessPoint. More...
def	get_ied_access_point_server_tuple (self, str ied_name, str ap_name)
	Get IED and AccessPoint names as a tuple for a specified Server element. More...
def	get_connected_ap_by_name (self, str ied_name, str ap_name)
	Retrieve a ConnectedAP element by its IED and AccessPoint names. More...
def	get_connected_ap_by_access_point (self, access_point)
	Get the ConnectedAP element corresponding to the given AccessPoint. More...
def	get_connected_ap_subnetwork (self, connected_ap)
	Get the SubNetwork element to which the ConnectedAP is connected. More...
def	get_connected_ap_subnet (self, connected_ap)
	Alias for get_connected_ap_subnetwork(). More...
def	get_ap_with_ip_list (self)
	Get list of ConnectedAP elements with IP addresses. More...
def	get_connected_ap_ip (self, et.Element connect_ap)
	Retrieve the IP address of a ConnectedAP element. More...
def	get_ap_ip (self, str ied_name, str ap_name)
	Retrieve the IP address of a specific AccessPoint. More...
def	get_context_object (self, str ied_name=None, str ap_name=None, str ld_inst=None, str ln_name=None)
	Get the etree.Element based on the selected search context: IED, LDevice, or LN (LN0). More...
def	get_dataset_list (self, str ied_name=None, str ap_name=None, str ld_inst=None, str ln_name=None)
	Get a list of DataSet elements. More...
def	get_dataset_names_list (self, ied_name=None, ap_name=None, ld_inst=None, ln_name=None, ref_type=ReferenceType.ObjectReference)
	Get a list of ObjectReferences for DataSet elements within the specified search context. More...
def	get_urcb_list (self, ied_name=None, ap_name=None, ld_inst=None, ln_name=None)
	Get a list of Unbuffered ReportControl blocks. More...
def	get_brcb_list (self, ied_name=None, ap_name=None, ld_inst=None, ln_name=None)
	Get a list of Buffered ReportControl blocks. More...
def	get_rcb_list (self, ied_name=None, ap_name=None, ld_inst=None, ln_name=None)
	Get a list of ReportControl elements. More...
def	get_rcb_dataset (self, rcb)
	Get the DataSet element for the given ReportControl. More...
def	get_rcb_fcda_list (self, rcb)
	Retrieve the list of FCDA elements associated with a specified RCB. More...
def	get_urcb_dataset (self, urcb)
	Alias for get_rcb_dataset(). More...
def	get_brcb_dataset (self, brcb)
	Alias for get_rcb_dataset(). More...
def	get_lcb_list (self, ied_name=None, ap_name=None, ld_inst=None, ln_name=None)
	Get a list of LogControl elements. More...
def	get_gocb_list (self, ied_name=None, ap_name=None, ld_inst=None)
	Get a list of GSEControl elements. More...
def	get_gocb_dataset (self, gocb)
	Get the DataSet element for the given GSEControl. More...
def	get_msvcb_list (self, ied_name=None, ap_name=None, ld_inst=None)
	Get a list of Multicast SampledValueControl (MSVCB) elements. More...
def	get_msvcb_dataset (self, msvcb)
	Get the DataSet element for the given MSVCB. More...
def	get_cb_refs_list (self, cb_type, ied_name=None, ap_name=None, ld_inst=None, ln_name=None, ref_type=ReferenceType.ObjectReference)
	Get a list of references for specified Control Block (CB) type. More...
def	get_urcb_refs_list (self, ied_name=None, ap_name=None, ld_inst=None, ln_name=None, ref_type=ReferenceType.ObjectReference)
	Get a list of references for Unbuffered ReportControl blocks (URCB). More...
def	get_brcb_refs_list (self, ied_name=None, ap_name=None, ld_inst=None, ln_name=None, ref_type=ReferenceType.ObjectReference)
	Get a list of references for Buffered ReportControl blocks (BRCB). More...
def	get_lcb_refs_list (self, ied_name=None, ap_name=None, ld_inst=None, ln_name=None, ref_type=ReferenceType.ObjectReference)
	Get a list of references for LogControl blocks (LCB). More...
def	get_gocb_refs_list (self, ied_name=None, ap_name=None, ld_inst=None, ref_type=ReferenceType.ObjectReference)
	Get a list of references for GSEControl blocks (GoCB). More...
def	get_msvcb_refs_list (self, ied_name=None, ap_name=None, ld_inst=None, ref_type=ReferenceType.ObjectReference)
	Get a list of references for Multicast SampledValueControl blocks (MSVCB). More...
def	get_dataset_by_ref (self, dataset_reference)
	Get the DataSet element by its reference. More...
def	get_cb_by_ref (self, cb_type, cb_reference)
	Get the Control Block (CB) element by its type and reference. More...
def	get_gocb_by_ref (self, cb_reference)
	Get the GSEControl block by its reference. More...
def	get_msvcb_by_ref (self, cb_reference)
	Get the Multicast SampledValueControl block by its reference. More...
def	get_ld_name_list (self, ied_name=None)
	Get a list of LDName strings. More...
def	get_ln_element_list (self, str ied_name=None, str ld_inst=None, str ld_name=None, bool exclude_ln0=False)
	Get list of LN elements. More...
def	get_ln_ref_list (self, ld_name)
	Get LN reference list. More...
def	get_type_definition_recursive (self, element, parent_path="")
	Get the data type structure for an element as MMS ObjectReference paths. More...
def	get_da_mms_ref_list (self, ln_ref)
	Get a list of data attributes in MMS reference format for the given logical node. More...
def	get_full_datamodel_mms_refs (self, ied_name=None)
	Get the complete data model of the device in MMS variable format. More...
def	get_inputs_extref_list (self)
	Get all Inputs/ExtRef elements. More...
def	get_fcda_from_mmsref (self, mms_ref)
	Get the FCDA element from an MMS reference. More...
def	get_gse_for_gocb (self, gocb)
	Get the GSE element from the Communications section for the specified GSEControl. More...
def	get_smv_for_mscvb (self, msvcb)
	Get the SMV element from the Communications section for the specified SampledValueControl. More...
def	get_subnetwork_list (self)
	Get list of SubNetwork elements. More...
def	get_subnetwork_by_name (self, str name)
	Get Subnetwork element by name. More...
def	get_subnetwork_name_list (self)
	Get list of SubNetwork names. More...
def	get_subnetwork_connected_ap_list (self, subnetwork_name=None, subnetwork=None)
	Get list of ConnectedAP elements for a Subnetwork. More...
def	get_subnetwork_connected_server_list (self, subnetwork_name=None, subnetwork=None)
	Get the list of connected servers in a Subnetwork. More...
def	get_subnetwork_connected_server_ap_tuple_list (self, subnetwork_name=None, subnetwork=None)
	Get a list of tuples containing IED names and Access Point names of connected servers in a Subnetwork. More...
def	select_ied (self, **kwargs)
	Select an IED based on specified criteria. More...
def	append_scl (self, scl)
	Append a CID file to the current SCD. More...
def	remove_gocb (self, go_cb_ref, preserve_communications=False)
	Remove the GSEControl element by reference. More...
def	remove_msvcb (self, msv_cb_ref, preserve_communications=False)
	Remove the SampledValueControl element by reference. More...
def	move_gse_smv_elements (self, str iedName, str srcApName, str trgtApName)
	Moves GSE and SMV elements between ConnectedAPs. More...
def	check_ldNs_defined (self)
	Проверка наличия объекта данных NamPlt.ldNs во всех LLN0. More...
def	check_lnNs_defined (self)
	Check for the presence of NamPlt.ldNs data objects in all LLN0 elements. More...
def	check_dataNs_defined (self)
	Check the correctness of dataNs assignment. More...
def	check_cdcNs_defined (self)
	Check the correctness of cdcNs assignment. More...
def	check_originalSclVersion_is (self, originalSclVersion)
	Check if the originalSclVersion attribute is correctly set. More...
def	check_originalSclRevision_is (self, originalSclRevision)
	Check if the originalSclRevision attribute is correctly set. More...
def	check_xmlns_is (self, xmlns)
	Check the value of the xmlns attribute of the root SCL element. More...
def	check_xsi_is (self, xsi)
	Check the value of the xmlns:xsi attribute of the root SCL element. More...
def	check_lln0_configRev_defined (self)
	Check the presence of the configRev attribute (DAI) in all LLN0.NamPlt elements. More...
def	check_value_list_match_type (self, dai_value_reference_list)
	Check if attribute values match their specified types. More...
def	validate_xml_declaration (self)
	Verify that the file contains a valid XML declaration according to the standard requirements. More...
def	validate_utf8_encoding (self)
	Perform encoding validation to check if the file is UTF-8 encoded. More...
def	check_datasets_consistency (self)
	Check the consistency of all datasets. More...
def	fix_triggers (self, bool dchg=True, bool qchg=True, bool dupd=True)
def	get_fcda_by_extref (self, et_extref)
	Find the corresponding FCDA for a given ExtRef. More...
def	check_ied_has_preconfigured_urcb (self)
	Check for the presence of preconfigured unbuffered report control blocks (URCB) in the ICD. More...
def	check_ied_has_preconfigured_brcb (self)
	Check for the presence of preconfigured buffered report control blocks (BRCB) in the ICD. More...
def	check_ied_has_preconfigured_lcb (self)
	Check for the presence of preconfigured log control blocks (LCB) in the ICD. More...
def	check_ied_has_preconfigured_gocb (self)
	Check for the presence of preconfigured GOOSE control blocks (GoCB) in the ICD. More...
def	check_ied_has_preconfigured_msvcb (self)
	Check for the presence of preconfigured multicast SV control blocks (MSVCB) in the ICD. More...

Public Attributes
	file_path
	dom
	namespaces
	default_namespace
	original_string
	edition

Static Public Attributes
dictionary	BTYPE_REGEX_DICT
int	iterations = 0

Detailed Description

Common SCL-file manipulation class.

The SCL class provides a variety of functions for manipulating SCL files, including specialized classes like SSD, ICD, and SCD that inherit from the SCL class and offer file-type-specific functionalities.

Typically, the SCL class is initialized with an existing SCL file that can be loaded from a file path as shown in the example below.

Example usage of SCL class:

scl = SCL("path/to/scl/file")

The SCL class defaults to using Edition 2 of the SCL specification. If you need to work with SCL files of other editions, such as Edition 1 or Edition 2.1, you can specify the edition when initializing the class. The edition identifiers must be passed as strings, not integers.

scl = SCL("path/to/scl/file", edition="1")

To select an SCL file directly from the filesystem using a graphical dialog, the Dialog class offers convenient functions for file selection, as shown below:

scd_filepath = Dialog.open_scl_file()
scl = SCL(scd_filepath)

For more information on SCL-related dialogs, refer to the Dialog class documentation.

You can instantiate multiple SCL objects simultaneously to manipulate different SCL files, including file comparison.

scl1 = SCL("path/to/scl/file1")
scl2 = SCL("path/to/scl/file2")

Note

When initialized with an SCL file path, the SCL class parses the file and creates an XML DOM model for further use. No additional operations, such as validation, are performed by default. To validate an SCL file against its schema, you must explicitly call the validate() method within your test script if required.

Constructor & Destructor Documentation

__init__()

def __init__	(		self,
			file_path = None,
			edition = None,
			init_empty = False
	)

Member Function Documentation

add_new_node_to_any_ln()

int add_new_node_to_any_ln	(		self,
		str	ln_path,
		str	str_element
	)

Adds a data object to an existing Logical Node.

This function adds a data object to an existing Logical Node. It matches the logical node path using a regex, retrieves the logical node element, and appends the new object if conditions are met. The position of the new object in the Logical Node is determined based on predefined lists of elements.

Parameters

ln_path	The logical node path.
str_element	The string variable of the element to be added.

Exceptions

Exception

Raised if the logical node reference is incorrect, the logical node element is not found, or the specified object is already defined in the SCL file.

Returns

1 if the addition is successful, 0 if the element already exists, -1 in case of an error.

add_new_object_to_LnType()

int add_new_object_to_LnType	(		self,
			ln_path,
			str_element
	)

Adds a new object type to an existing Logical Node Type.

This function adds a new object type to an existing Logical Node Type. It matches the logical node path using a regex, retrieves the logical node element, and appends the new element if conditions are met.

Parameters

ln_path	The logical node path.
str_element	The string variable of the type to be added.

Exceptions

Exception

Raised if the logical node reference is incorrect, the logical node element is not found, or the Logical Node Type is not found in DataTypeTemplates.

Returns

1 if the addition is successful, 0 if the element already exists, -1 in case of an error, None if the logical node path does not match or the logical node element is not found.

add_new_type_to_templates()

def add_new_type_to_templates	(		self,
		str	str_element
	)

Adds a new type to the DataTypeTemplates list.

This function attempts to add a new type (LNodeType, DOType, DAType, EnumType) to the DataTypeTemplates list. It first checks if the element already exists in the list. If it does not, it adds the new type and returns 1. If the element already exists, it returns 0. If an error occurs during the addition process, it returns -1.

Parameters

str_element

The string variable of the element to be added.

Returns

1 if the addition is successful, 0 if the element already exists, -1 in case of an error.

append_scl()

def append_scl	(		self,
			scl
	)

Append a CID file to the current SCD.

This function appends a CID file to the current SCD. It performs several checks and operations including verifying that the CID file has only one IED, ensuring that the SCD does not already contain an IED with the same name, checking SCL version/revision compatibility, renaming DataTypes, and copying DataTypes, IED, and SubNetworks.

Parameters

scl	The CID file to append.

Exceptions

SclElementNotFound	Raised if the CID file contains no IED.
TooManySclElements	Raised if the CID file contains more than one IED.
DuplicateSclElement	Raised if the SCD file already contains an IED with the same name.
NotSupported	Raised if the CID file has a different SCL version/revision than the SCD.

Returns

None

check_cdcNs_defined()

def check_cdcNs_defined

(

self

)

Check the correctness of cdcNs assignment.

This function checks the correctness of cdcNs assignments. It retrieves all cdcNs values from the document and ensures they are valid according to the standard CDC namespaces.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

check_dataNs_defined()

def check_dataNs_defined

(

self

)

Check the correctness of dataNs assignment.

This function checks the correctness of dataNs assignments. It examines all logical nodes, skips those outside the standard namespace, and ensures that each data object either matches the standard NSD or has a valid dataNs value.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

check_datasets_consistency()

def check_datasets_consistency

(

self

)

Check the consistency of all datasets.

This function checks the consistency of all datasets. It verifies that all FCDA attributes within each dataset reference existing DO/SDO, DA/BDA elements in the device model.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

check_ied_has_preconfigured_brcb()

def check_ied_has_preconfigured_brcb

(

self

)

Check for the presence of preconfigured buffered report control blocks (BRCB) in the ICD.

This function checks for the presence of preconfigured buffered report control blocks (BRCB) in the ICD. It verifies if any BRCB references exist and logs messages accordingly.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult, SCL.get_brcb_refs_list()

check_ied_has_preconfigured_gocb()

def check_ied_has_preconfigured_gocb

(

self

)

Check for the presence of preconfigured GOOSE control blocks (GoCB) in the ICD.

This function checks for the presence of preconfigured GOOSE control blocks (GoCB) in the ICD. It verifies if any GoCB references exist and logs messages accordingly.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult, SCL.get_gocb_refs_list()

check_ied_has_preconfigured_lcb()

def check_ied_has_preconfigured_lcb

(

self

)

Check for the presence of preconfigured log control blocks (LCB) in the ICD.

This function checks for the presence of preconfigured log control blocks (LCB) in the ICD. It verifies if any LCB references exist and logs messages accordingly.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult, SCL.get_lcb_refs_list()

check_ied_has_preconfigured_msvcb()

def check_ied_has_preconfigured_msvcb

(

self

)

Check for the presence of preconfigured multicast SV control blocks (MSVCB) in the ICD.

This function checks for the presence of preconfigured multicast SV control blocks (MSVCB) in the ICD. It verifies if any MSVCB references exist and logs messages accordingly.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult, SCL.get_msvcb_refs_list()

check_ied_has_preconfigured_urcb()

def check_ied_has_preconfigured_urcb

(

self

)

Check for the presence of preconfigured unbuffered report control blocks (URCB) in the ICD.

This function checks for the presence of preconfigured unbuffered report control blocks (URCB) in the ICD. It verifies if any URCB references exist and logs messages accordingly.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult, SCL.get_urcb_refs_list()

check_ldNs_defined()

def check_ldNs_defined

(

self

)

Проверка наличия объекта данных NamPlt.ldNs во всех LLN0.

check_lln0_configRev_defined()

def check_lln0_configRev_defined

(

self

)

Check the presence of the configRev attribute (DAI) in all LLN0.NamPlt elements.

This function checks the presence of the configRev attribute (DAI) in all LLN0.NamPlt elements. It verifies that the attribute exists and has a non-null value in all logical devices.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

check_lnNs_defined()

def check_lnNs_defined

(

self

)

Check for the presence of NamPlt.ldNs data objects in all LLN0 elements.

This function checks for the presence of the NamPlt.ldNs data object in all LLN0 elements within the logical devices. It logs messages and errors based on the findings and returns a TestResult object indicating the success or failure of the test.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

check_originalSclRevision_is()

def check_originalSclRevision_is	(		self,
			originalSclRevision
	)

Check if the originalSclRevision attribute is correctly set.

This function checks if the originalSclRevision attribute is correctly set for all IED elements in the document. It verifies that the attribute value matches the provided revision.

Parameters

originalSclRevision

The expected value of the originalSclRevision attribute.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

check_originalSclVersion_is()

def check_originalSclVersion_is	(		self,
			originalSclVersion
	)

Check if the originalSclVersion attribute is correctly set.

This function checks if the originalSclVersion attribute is correctly set for all IED elements in the document. It verifies that the attribute value matches the provided version.

Parameters

originalSclVersion

The expected value of the originalSclVersion attribute.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

check_value_list_match_type()

def check_value_list_match_type	(		self,
			dai_value_reference_list
	)

Check if attribute values match their specified types.

This function checks if the values of attributes match their specified types by using regular expressions. It iterates over a list of attribute-value references, validates each value against its type, and logs messages and errors based on the result.

Parameters

dai_value_reference_list

A list of dictionaries containing 'value' and 'reference' keys representing the attribute values and their references.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

check_xmlns_is()

def check_xmlns_is	(		self,
			xmlns
	)

Check the value of the xmlns attribute of the root SCL element.

This function checks if the value of the xmlns attribute of the root SCL element matches the provided value. It logs messages and errors based on the result of the comparison.

Parameters

xmlns

The expected value of the xmlns attribute.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

check_xsi_is()

def check_xsi_is	(		self,
			xsi
	)

Check the value of the xmlns:xsi attribute of the root SCL element.

This function checks if the value of the xmlns:xsi attribute of the root SCL element matches the provided value. It logs messages and errors based on the result of the comparison.

Parameters

xsi	The expected value of the xmlns:xsi attribute.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

detect_edition()

def detect_edition	(		self,
			raise_on_unknown = False
	)

Detect SCL-file edition.

Automatically detects loaded SCL-file edition

Parameters

raise_on_unknown

Boolean flag to specify if an exception should be raised for unknown editions (default: False)

Exceptions

Exception

Raised if the SCL file edition is unknown and raise_on_unknown is True

Returns

The detected edition as a string

fix_triggers()

def fix_triggers	(		self,
		bool	dchg = True,
		bool	qchg = True,
		bool	dupd = True
	)

from_artifact()

def from_artifact	(		cls,
		str	artifact_id
	)

Load SCL contents from an Artifact.

This class method loads the contents of an SCL document from a string obtained via an Artifact, identified by the provided artifact_id. The method initializes an SCL instance with the content of the artifact and parses it as an XML document.

Parameters

artifact_id

The ID of the Artifact from which the SCL document will be loaded.

Returns

An instance of the SCL class loaded with the content of the specified Artifact.

See also

TestEngine.get_artifact

get_ap_ip()

def get_ap_ip	(		self,
		str	ied_name,
		str	ap_name
	)

Retrieve the IP address of a specific AccessPoint.

This function extracts the IP address associated with a specified AccessPoint in the given IED. It first locates the corresponding ConnectedAP element using the provided IED and AccessPoint names, then retrieves the IP address from the ConnectedAP element.

Parameters

ied_name	The name of the IED containing the AccessPoint.
ap_name	The name of the AccessPoint whose IP address is to be retrieved.

Returns

The IP address as a string.

Exceptions

Raises

an exception if the `ConnectedAP` or its IP address cannot be found.

See also

get_connected_ap_by_name, get_connected_ap_ip

get_ap_with_ip_list()

def get_ap_with_ip_list

(

self

)

Get list of ConnectedAP elements with IP addresses.

This function retrieves a list of ConnectedAP elements that have IP addresses. It searches the document object model (DOM) for P elements with a type attribute equal to "IP" and then collects their grandparent ConnectedAP elements.

Returns

A list of ConnectedAP elements (etree.Element) with IP addresses.

get_attributes_with_values()

def get_attributes_with_values

(

self

)

Get list of data attributes with values set.

Returns a list of attributes for which the Val element exists. If the document object model (DOM) is not built, it initializes the DOM. The function then finds all Val elements and collects their values and references into a list.

Returns

A list of dictionaries, each containing the 'value' of the Val element and its 'reference'.

get_brcb_dataset()

def get_brcb_dataset	(		self,
			brcb
	)

Alias for get_rcb_dataset().

This function is an alias for get_rcb_dataset(). It returns the DataSet element for the given Buffered ReportControl block (BRCB).

Parameters

brcb	The Buffered ReportControl block (BRCB) element.

Returns

The DataSet element for the given BRCB.

See also

SCL.get_rcb_dataset()

get_brcb_list()

def get_brcb_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ln_name = None
	)

Get a list of Buffered ReportControl blocks.

This function returns a list of Buffered ReportControl blocks. It first builds the DOM if it is not already built, then retrieves the context object based on the provided IED, LDevice, and LN (LN0) names. Finally, it searches for ReportControl elements within the context object using XPath, filtering by the buffered attribute set to "true".

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).

Returns

A list of Buffered ReportControl blocks.

See also

SCL.get_context_object()

get_brcb_refs_list()

def get_brcb_refs_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ln_name = None,
			ref_type = ReferenceType.ObjectReference
	)

Get a list of references for Buffered ReportControl blocks (BRCB).

This function returns a list of ObjectReferences for Buffered ReportControl blocks (BRCB) within the given context of IED, LDevice, and LN (LN0). It uses the get_cb_refs_list method to generate the list of references.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).
ref_type	The type of reference, default is ReferenceType.ObjectReference.

Returns

A list of ObjectReferences for Buffered ReportControl blocks (BRCB).

See also

SCL.get_cb_refs_list()

get_btype_by_dai_ref()

str get_btype_by_dai_ref	(		self,
		str	object_reference
	)

get_cb_by_ref()

def get_cb_by_ref	(		self,
			cb_type,
			cb_reference
	)

Get the Control Block (CB) element by its type and reference.

This function returns the Control Block (CB) element based on its type and reference. It parses the reference to extract the LDName, LNName, and cbName, and then retrieves the corresponding CB element.

Parameters

cb_type	The type of the Control Block (CB), which can be "RCB", "BRCB", "URCB", "GoCB", "MSVCB", "LCB", or "DataSet".
cb_reference	The reference to the Control Block.

Returns

The Control Block element corresponding to the provided type and reference, or None if not found.

See also

SCL.get_ld_by_ldname(), SCL.get_LN_element_by_name(), SCL.get_element_by_attribute()

get_cb_refs_list()

def get_cb_refs_list	(		self,
			cb_type,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ln_name = None,
			ref_type = ReferenceType.ObjectReference
	)

Get a list of references for specified Control Block (CB) type.

This function returns a list of references for the specified Control Block (CB) type within the given context of IED, LDevice, and LN (LN0). It retrieves the list of CB elements based on the provided type and context, and then generates references for each CB element.

Parameters

cb_type	The type of Control Block (CB), which can be "BRCB", "URCB", "GoCB", "MSVCB", or "LCB".
ied_name	The name of the IED.
ap_name	The name of the AccessPoint.
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).
ref_type	The type of reference, default is ReferenceType.ObjectReference.

Returns

A list of references for the specified Control Block (CB) type.

See also

SCL.get_brcb_list(), SCL.get_urcb_list(), SCL.get_gocb_list(), SCL.get_msvcb_list(), SCL.get_lcb_list()

get_cdc_by_doiRef()

def get_cdc_by_doiRef	(		self,
		str	object_reference
	)

Retrieve the CDC type associated with a specific DOI reference.

This function retrieves the Common Data Class (CDC) type associated with a specified Data Object Instance Reference (DOI reference). It uses the DOI reference to locate the corresponding DOType in the SCL file and extracts the cdc attribute from it.

Parameters

object_reference

The DOI reference for which the CDC type is to be retrieved.

Returns

The CDC type as a string.

Exceptions

Raises

an assertion error if the `DOType` cannot be found for the provided DOI reference.

See also

get_doType_by_doiRef

get_connected_ap_by_access_point()

def get_connected_ap_by_access_point	(		self,
			access_point
	)

Get the ConnectedAP element corresponding to the given AccessPoint.

This function retrieves the ConnectedAP element that corresponds to the given AccessPoint element. It extracts the name of the AccessPoint and its parent IED, then searches the document object model (DOM) for the ConnectedAP element with matching iedName and apName attributes.

Parameters

access_point

The AccessPoint element within the IED.

Exceptions

Exception	Raised if the ConnectedAP element is not found.
AttributeError	Raised if the AccessPoint element does not have a name attribute.

Returns

The ConnectedAP element (etree.Element).

get_connected_ap_by_name()

def get_connected_ap_by_name	(		self,
		str	ied_name,
		str	ap_name
	)

Retrieve a ConnectedAP element by its IED and AccessPoint names.

This function searches the SCL DOM for a ConnectedAP element matching the specified IED name (ied_name) and AccessPoint name (ap_name). If exactly one matching element is found, it is returned. If no matching element is found or multiple elements match, an exception is raised.

Parameters

ied_name	The name of the IED to search for.
ap_name	The name of the AccessPoint to search for.

Returns

The ConnectedAP element that matches the provided names.

Exceptions

Raises

an exception if no matching element or multiple elements are found.

See also

get_one_or_raise

get_connected_ap_ip()

def get_connected_ap_ip	(		self,
		et.Element	connect_ap
	)

Retrieve the IP address of a ConnectedAP element.

This function extracts the IP address from a given ConnectedAP element. It searches for the P element with the type attribute set to "IP" and retrieves its text value. If no such element exists or multiple elements match, an exception is raised.

Parameters

connect_ap

The ConnectedAP element from which the IP address is to be extracted.

Returns

The IP address as a string.

Exceptions

Raises

an exception if no IP address is found or if multiple IP addresses exist.

See also

get_one_or_raise

get_connected_ap_subnet()

def get_connected_ap_subnet	(		self,
			connected_ap
	)

Alias for get_connected_ap_subnetwork().

This function is an alias for get_connected_ap_subnetwork(). It returns the SubNetwork element that the given ConnectedAP element is connected to by retrieving its parent element.

Deprecated:

This method is deprecated and shall be removed. Use get_connected_ap_subnetwork() instead.

Parameters

connected_ap

The ConnectedAP element (etree.Element).

Returns

The SubNetwork element (etree.Element).

get_connected_ap_subnetwork()

def get_connected_ap_subnetwork	(		self,
			connected_ap
	)

Get the SubNetwork element to which the ConnectedAP is connected.

This function returns the SubNetwork element that the given ConnectedAP element is connected to by retrieving its parent element.

Parameters

connected_ap

The ConnectedAP element (etree.Element).

Returns

The SubNetwork element (etree.Element).

get_context_object()

def get_context_object	(		self,
		str	ied_name = None,
		str	ap_name = None,
		str	ld_inst = None,
		str	ln_name = None
	)

Get the etree.Element based on the selected search context: IED, LDevice, or LN (LN0).

This function returns an etree.Element depending on the specified search context, which can be IED, LDevice, or LN (LN0). It first builds the DOM if it is not already built, and then navigates through the DOM based on the provided context parameters.

Parameters

ied_name	The name of the IED.
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).

Returns

The etree.Element based on the search context.

get_da_mms_ref_list()

def get_da_mms_ref_list	(		self,
			ln_ref
	)

Get a list of data attributes in MMS reference format for the given logical node.

This function returns a list of data attributes in MMS reference format for the given logical node. It retrieves the logical node element by its reference and then uses the get_type_definition_recursive method to generate the list of MMS references.

Parameters

ln_ref

The reference to the logical node.

Returns

A list of data attributes in MMS reference format for the given logical node.

See also

SCL.get_ln_element_by_ref(), SCL.get_type_definition_recursive()

get_da_val_regex_by_daiRef()

def get_da_val_regex_by_daiRef	(		self,
			object_reference
	)

Returns a regular expression for validating the value of a data attribute by its reference.

This function retrieves the Data Attribute Type (DAType) element by the reference path to the Data Attribute Instance (DAI) and then determines the appropriate regular expression for validating the value based on the basic type (bType) of the DAType. If the bType is 'Enum', it retrieves the corresponding EnumType and gets the regex for it. If the bType is in the predefined dictionary of types, it returns the corresponding regex. Otherwise, it returns "UNKNOWN TYPE".

Parameters

object_reference

The reference to the DAI in the format: LDName/LNName.DOI[.SDIseq].DAI.

Returns

A regular expression for validating the value of the data attribute, or "UNKNOWN TYPE" if the type is not recognized.

get_dai_by_ref()

def get_dai_by_ref	(		self,
			object_reference
	)

Retrieves a DAI element by its reference.

This function retrieves a Data Attribute Instance (DAI) element by its reference in the format LDName/LNName.DOI[.SDIseq].DAI. It uses regex to parse the reference and then traverses the hierarchical structure to locate the specified DAI element.

Parameters

object_reference

The reference to the attribute in the format: LDName/LNName.DOI[.SDIseq].DAI.

Exceptions

Exception

Raised if the object reference format does not match the expected pattern.

Returns

The DAI element (etree.Element) if found, otherwise None.

get_dataset_by_ref()

def get_dataset_by_ref	(		self,
			dataset_reference
	)

Get the DataSet element by its reference.

This function returns the DataSet element corresponding to the provided reference. It uses the get_cb_by_ref method to retrieve the DataSet element.

Parameters

dataset_reference

The reference to the DataSet.

Returns

The DataSet element corresponding to the provided reference.

See also

SCL.get_cb_by_ref()

get_dataset_list()

def get_dataset_list	(		self,
		str	ied_name = None,
		str	ap_name = None,
		str	ld_inst = None,
		str	ln_name = None
	)

Get a list of DataSet elements.

This function returns a list of DataSet elements. It first builds the DOM if it is not already built, then retrieves the context object based on the provided IED, LDevice, and LN (LN0) names. Finally, it searches for DataSet elements within the context object using XPath.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).

Returns

A list of DataSet elements.

See also

SCL.get_context_object()

get_dataset_names_list()

def get_dataset_names_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ln_name = None,
			ref_type = ReferenceType.ObjectReference
	)

Get a list of ObjectReferences for DataSet elements within the specified search context.

This function returns a list of ObjectReferences for DataSet elements within the specified search context of ied_name, ld_inst, and ln_name. If only ied_name is defined, it returns all DataSet references within the specified IED. If both ied_name and ld_inst are defined, the context is limited to the specified LDevice within the IED. If ln_name is also provided, the context is further limited to the specified LN/LN0.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).
ref_type	The type of reference, default is ReferenceType.ObjectReference.

Returns

A list of ObjectReferences for DataSet elements within the search context.

See also

SCL.get_dataset_list() ReferenceType

get_daType_by_daiRef()

def get_daType_by_daiRef	(		self,
		str	object_reference
	)

Retrieves a DAType element by the DAI reference path.

This function retrieves a Data Attribute Type (DAType) element by the reference path to the Data Attribute Instance (DAI). It uses regex to parse the reference and then traverses the hierarchical structure to locate the specified DAType element.

Parameters

object_reference

The reference to the DAI in the format: LDName/LNName.DOI[.SDIseq].DAI.

Exceptions

Exception

Raised if the object reference format does not match the expected pattern.

Returns

The DAType element (etree.Element) if found, otherwise None.

get_doi_by_ref()

def get_doi_by_ref	(		self,
		str	object_reference
	)

Retrieves a DOI element by its reference.

This function retrieves a Data Object Instance (DOI) element by its reference in the format LDName/LNName.DOI. It uses regex to parse the reference and then traverses the hierarchical structure to locate the specified DOI element.

Parameters

object_reference

The reference to the attribute in the format: LDName/LNName.DOI.

Exceptions

Exception

Raised if the object reference format does not match the expected pattern.

Returns

The DOI element (etree.Element) if found, otherwise None.

get_doType_by_doiRef()

def get_doType_by_doiRef	(		self,
		str	object_reference
	)

Retrieves a DOType element by the DOI reference path.

This function retrieves a Data Object Type (DOType) element by the reference path to the Data Object Instance (DOI). It uses regex to parse the reference and then traverses the hierarchical structure to locate the specified DOType element.

Parameters

object_reference

The reference to the DAI in the format: LDName/LNName.DOI[.SDIseq].

Exceptions

Exception

Raised if the object reference format does not match the expected pattern.

Returns

The DOType element (etree.Element) if found, otherwise None.

get_fcda_by_extref()

def get_fcda_by_extref	(		self,
			et_extref
	)

Find the corresponding FCDA for a given ExtRef.

This function searches for the corresponding FCDA (Functional Constraint Data Attribute) for a given ExtRef (External Reference). It constructs an XPath query based on the attributes of the ExtRef and retrieves the matching FCDA element.

Parameters

et_extref

An element representing the ExtRef.

Returns

The matching FCDA element, or None if no match is found.

get_fcda_from_mmsref()

def get_fcda_from_mmsref	(		self,
			mms_ref
	)

Get the FCDA element from an MMS reference.

This function returns the FCDA element for the given MMS reference. It parses the reference to extract the LDName, LNName, DOName, DAName, and functional constraint (FC), then constructs the FCDA element accordingly.

Parameters

mms_ref

The MMS reference string in the format LDName/ObjectReference.

Returns

The FCDA element corresponding to the provided MMS reference.

See also

SCL.get_iedName_by_ldName(), SCL.get_ldInst_by_ldName()

get_full_datamodel_mms_refs()

def get_full_datamodel_mms_refs	(		self,
			ied_name = None
	)

Get the complete data model of the device in MMS variable format.

This function returns the complete data model of the device in MMS variable format. It retrieves the list of logical device names for the specified IED, then for each logical device, it retrieves the list of logical node references and constructs the data model using the get_type_definition_recursive method.

Parameters

ied_name

The name of the IED. If None, retrieves the data model for all IEDs.

Returns

A list of data model attributes in MMS variable format.

See also

SCL.get_ld_name_list(), SCL.get_ln_ref_list(), SCL.get_ln_element_by_ref(), SCL.get_type_definition_recursive()

Reimplemented in RSD.

get_gocb_by_ref()

def get_gocb_by_ref	(		self,
			cb_reference
	)

Get the GSEControl block by its reference.

This function returns the GSEControl block based on the provided reference. It uses the get_cb_by_ref method to retrieve the GSEControl element.

Parameters

cb_reference

The reference to the Control Block in the SCL format (IEDnameLDinst/LLN0.GoCBname).

Returns

The GSEControl element.

See also

SCL.get_cb_by_ref()

get_gocb_dataset()

def get_gocb_dataset	(		self,
			gocb
	)

Get the DataSet element for the given GSEControl.

This function returns the DataSet element for the given GSEControl element. It retrieves the DataSet using the private method _get_cb_dataset.

Parameters

gocb	The GSEControl element.

Exceptions

IndexError

Raised if the DataSet with the specified name is not found.

Returns

The DataSet element, or None if the element is not found.

See also

SCL._get_cb_dataset()

get_gocb_list()

def get_gocb_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None
	)

Get a list of GSEControl elements.

This function returns a list of GSEControl elements. It retrieves the context object based on the provided IED and LDevice names. Finally, it searches for GSEControl elements within the context object using XPath.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.

Returns

A list of GSEControl elements.

See also

SCL.get_context_object()

get_gocb_refs_list()

def get_gocb_refs_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ref_type = ReferenceType.ObjectReference
	)

Get a list of references for GSEControl blocks (GoCB).

This function returns a list of ObjectReferences for GSEControl blocks (GoCB) within the given context of IED and LDevice. It uses the get_cb_refs_list method to generate the list of references.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint.
ld_inst	The instance of the LDevice.
ref_type	The type of reference, default is ReferenceType.ObjectReference.

Returns

A list of ObjectReferences for GSEControl blocks (GoCB).

See also

SCL.get_cb_refs_list()

get_gse_for_gocb()

def get_gse_for_gocb	(		self,
			gocb
	)

Get the GSE element from the Communications section for the specified GSEControl.

This function returns the GSE element from the Communications section for the given GSEControl. It uses the _get_communication_params_for_cb method to retrieve the GSE element.

Parameters

gocb	The GSEControl element.

Exceptions

Exception

Raised if the control block is not a SampledValueControl or GSEControl.

Returns

The GSE element corresponding to the given GSEControl.

See also

SCL._get_communication_params_for_cb()

get_ied_access_point_list()

def get_ied_access_point_list	(		self,
		str	ied_name,
		bool	with_server_only = False,
			allow_serverat = False
	)

Get list of AccessPoint elements for a specified IED.

This function retrieves a list of AccessPoint elements for the IED with the specified name. It uses XPath to find the AccessPoint elements within the IED.

Parameters

ied_name	The name of the IED.
with_server_only	Flag to select only access points with Server element.
allow_serverat	Flag to add access points with ServerAt elements as well.

Exceptions

Exception

Raised if the IED with the specified name is not found.

Returns

A list of AccessPoint elements (etree.Element) in the IED, or an empty list if none are found.

get_ied_access_point_name_list()

def get_ied_access_point_name_list	(		self,
		str	ied_name,
		bool	with_server_only = False,
			allow_serverat = False
	)

Get list of AccessPoint names for a specified IED.

This function retrieves a list of AccessPoint names for the IED with the specified name. It first gets the list of AccessPoint elements and then extracts the "name" attribute from each element.

Parameters

ied_name	The name of the IED.
with_server_only	Flag to select only access points with Server element.
allow_serverat	Flag to add access points with ServerAt elements as well.

Exceptions

Exception	Raised if the IED with the specified name is not found.
AttributeError	Raised if the "name" attribute is not found in an AccessPoint element.

Returns

A list of AccessPoint names, or an empty list if none are found.

get_ied_access_point_server()

def get_ied_access_point_server	(		self,
		str	ied_name,
		str	ap_name
	)

Get Server element for specified IED and AccessPoint.

Retrieves the Server element for a given IED and AccessPoint name. If the Server element is not directly found, it attempts to find the Server via ServerAt element.

Parameters

ied_name	Name of the IED.
ap_name	Name of the AccessPoint.

Exceptions

Exception

Raised if the ServerAt element references an AccessPoint with no server.

Returns

Server element if found, otherwise None.

get_ied_access_point_server_tuple()

def get_ied_access_point_server_tuple	(		self,
		str	ied_name,
		str	ap_name
	)

Get IED and AccessPoint names as a tuple for a specified Server element.

This function retrieves the Server element for a given IED and AccessPoint name, then returns the IED and AccessPoint names as a tuple. If the Server element is not directly found, it attempts to locate it through the ServerAt element.

Parameters

ied_name	Name of the IED.
ap_name	Name of the AccessPoint.

Exceptions

Exception

Raised if the ServerAt element references an AccessPoint with no server.

Returns

A tuple containing the IED name and AccessPoint name.

get_ied_by_name()

def get_ied_by_name	(		self,
			iedName,
			dom = None
	)

Get IED element by name attribute.

Returns IED element (etree.Element) defined by iedName attribute.

Deprecated:

The dom parameter is deprecated and shall not be used in this context. The attribute is left for backwards compatibility.

Parameters

iedName	name attribute of the IED of interest.
dom	SCL DOM object. By default the DOM object of the SCL is used.

Returns

IED element (etree.Element)

get_ied_list()

def get_ied_list	(		self,
		bool	server_only = False,
		bool	with_gse_only = False,
		bool	with_smv_only = False
	)

Get list of IED elements.

This function retrieves a list of all IED elements from the document object model (DOM) using XPath.

Parameters

server_only	Flag to select only IEDs containing at least one Server. Default = False
with_gse_only	Flag to select only IEDs containing at least one GSEControl. Default = False
with_smv_only	Flag to select only IEDs containing at least one SampledValueControl. Default = False

Returns

A list of IED elements (etree.Element).

get_ied_name()

str get_ied_name	(		self,
		int	ied_num = 0
	)

Get the name of an IED by its number in the file.

This function retrieves the name of an IED based on its position (number) in the file. It first gets the list of IED names and then returns the name at the specified index.

Parameters

ied_num

The position (number) of the IED in the file. Default is 0.

Returns

The name of the IED at the specified position.

get_ied_name_list()

def get_ied_name_list	(		self,
		bool	server_only = False,
		bool	with_gse_only = False,
		bool	with_smv_only = False
	)

Get list of IED names.

This function retrieves a list of all IED names by first obtaining the list of IED elements and then extracting the "name" attribute from each element.

Parameters

server_only	Flag to select only IEDs containing at least one Server. Default = False
with_gse_only	Flag to select only IEDs containing at least one GSEControl. Default = False
with_smv_only	Flag to select only IEDs containing at least one SampledValueControl. Default = False

Returns

A list of IED names.

get_iedName_by_ldName()

def get_iedName_by_ldName	(		self,
			ldName
	)

Get IED.name attribute by ldName.

Returns name attribue of an IED by specified ldName

Parameters

ldName

Logical Device Name (concatenation of IED.name and LDevice.inst attributes

Returns

name attribute of an IED element

See also

SCL.get_ldInst_by_ldName() SCL.get_ldevice_by_ldname()

get_inputs_extref_list()

def get_inputs_extref_list

(

self

)

Get all Inputs/ExtRef elements.

This function returns all Inputs/ExtRef elements in the document. It uses XPath to search for all ExtRef elements within Inputs.

Returns

A list of all Inputs/ExtRef elements.

get_lcb_list()

def get_lcb_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ln_name = None
	)

Get a list of LogControl elements.

This function returns a list of LogControl elements. It retrieves the context object based on the provided IED, LDevice, and LN (LN0) names. Finally, it searches for LogControl elements within the context object using XPath.

Parameters

ied_name	The name of the IED.
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).

Returns

A list of LogControl elements.

See also

SCL.get_context_object()

get_lcb_refs_list()

def get_lcb_refs_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ln_name = None,
			ref_type = ReferenceType.ObjectReference
	)

Get a list of references for LogControl blocks (LCB).

This function returns a list of ObjectReferences for LogControl blocks (LCB) within the given context of IED, LDevice, and LN (LN0). It uses the get_cb_refs_list method to generate the list of references.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).
ref_type	The type of reference, default is ReferenceType.ObjectReference.

Returns

A list of ObjectReferences for LogControl blocks (LCB).

See also

SCL.get_cb_refs_list()

get_ld_by_ldname()

def get_ld_by_ldname	(		self,
			ldName
	)

Get LDevice element by ldName.

Returns Logical Device SCL element (LDevice) specified by ldName parameter. Note that ldName in accordance with IEC 61850 is the concatenation of iedName and ldInst attributes.

Parameters

ldName

Logical Device Name (concatenation of IED.name and LDevice.inst attributes)

Returns

LDevice element (etree.Element)

get_ld_name_list()

def get_ld_name_list	(		self,
			ied_name = None
	)

Get a list of LDName strings.

This function returns a list of LDName strings. If an IED name is provided, it retrieves the list of LDevice elements within the specified IED. If no IED name is provided, it retrieves all LDevice elements in the DOM. It then constructs the LDName strings by combining the IED name and the LDevice instance.

Parameters

ied_name

The name of the IED. If None, retrieves all LDevice elements.

Returns

A list of LDName strings.

get_ldevice_by_ldname()

def get_ldevice_by_ldname	(		self,
			ldName
	)

Alias for SCL.get_ld_by_ldname()

Parameters

ldName

Logical device name

get_ldInst_by_ldName()

def get_ldInst_by_ldName	(		self,
			ldName
	)

Get LDevice.inst attribute by specified ldName.

Returns inst attribute of an LDevice element specified by ldName parameter.

Parameters

ldName

Logical Device Name (concatenation of IED.name and LDevice.inst attributes

Returns

inst attribute of an LDevice element

get_ln_element_by_ref()

def get_ln_element_by_ref	(		self,
		str	ln_ref
	)

Get LN/LN0 element by LN Reference.

Returns LN or LN0 element by LN reference ln_ref

Parameters

ln_ref

Logical Node reference as SCL object reference in the following format: ldName/LLN0 or ldName/prefixCLASSinst (eg. AAA1PROT/OcpPTOC1).

Exceptions

Exception

Incorrect lnReference if `ln_ref` mismatches _LNREF_REGEX

Returns

LN or LN0 element (etree.Element)

get_ln_element_list()

def get_ln_element_list	(		self,
		str	ied_name = None,
		str	ld_inst = None,
		str	ld_name = None,
		bool	exclude_ln0 = False
	)

Get list of LN elements.

This function returns a list of LN elements as etree.Element. It allows retrieval of LN elements from the SCL file based on the provided IED name, LDevice instance, and LDevice name. Optionally, it can exclude LN0 elements.

Parameters

ied_name	The name of the IED.
ld_inst	The instance of the LDevice.
ld_name	The name of the LDevice.
exclude_ln0	A boolean to exclude LN0 elements from the list.

Exceptions

Exception

Raised if parameters are defined incorrectly.

Returns

A list of LN elements as etree.Element.

get_ln_ref_list()

def get_ln_ref_list	(		self,
			ld_name
	)

Get LN reference list.

This function returns a list of references to LNs in the specified ld_name logical device. It retrieves the logical device by its name and then gathers references for both LN0 and LN elements.

Parameters

ld_name

The name of the logical device.

Returns

A list of references to LNs in the specified logical device.

See also

SCL.get_ld_by_ldname()

get_msvcb_by_ref()

def get_msvcb_by_ref	(		self,
			cb_reference
	)

Get the Multicast SampledValueControl block by its reference.

This function returns the Multicast SampledValueControl block based on the provided reference. It uses the get_cb_by_ref method to retrieve the Multicast SampledValueControl element.

Parameters

cb_reference

The reference to the Control Block in the SCL format (IEDnameLDinst/LLN0.SVControlName).

Returns

The SampledValueControl element.

See also

SCL.get_cb_by_ref()

get_msvcb_dataset()

def get_msvcb_dataset	(		self,
			msvcb
	)

Get the DataSet element for the given MSVCB.

This function returns the DataSet element for the given Multicast Sampled Values Control Block (MSVCB). It retrieves the DataSet using the private method _get_cb_dataset.

Parameters

msvcb

The SampledValueControl element representing the MSVCB.

Exceptions

IndexError

Raised if the DataSet with the specified name is not found.

Returns

The DataSet element, or None if the element is not found.

See also

SCL._get_cb_dataset()

get_msvcb_list()

def get_msvcb_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None
	)

Get a list of Multicast SampledValueControl (MSVCB) elements.

This function returns a list of SampledValueControl elements that represent Multicast Sampled Values Control Blocks (MSVCB). It retrieves the context object based on the provided IED and LDevice names. Finally, it searches for SampledValueControl elements with the multicast attribute set to "true" or not present, within the context object using XPath.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.

Returns

A list of Multicast Sampled Values Control Block (MSVCB) elements.

See also

SCL.get_context_object()

get_msvcb_refs_list()

def get_msvcb_refs_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ref_type = ReferenceType.ObjectReference
	)

Get a list of references for Multicast SampledValueControl blocks (MSVCB).

This function returns a list of ObjectReferences for Multicast Sampled Values Control Blocks (MSVCB) within the given context of IED and LDevice. It uses the get_cb_refs_list method to generate the list of references.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.
ref_type	The type of reference, default is ReferenceType.ObjectReference.

Returns

A list of ObjectReferences for SampledValueControl blocks (MSVCB).

See also

SCL.get_cb_refs_list()

get_rcb_dataset()

def get_rcb_dataset	(		self,
			rcb
	)

Get the DataSet element for the given ReportControl.

This function returns the DataSet element for the given ReportControl element. It retrieves the DataSet using the private method _get_cb_dataset.

Parameters

rcb	The ReportControl element.

Exceptions

IndexError

Raised if the DataSet with the specified name is not found.

Returns

The DataSet element, or None if the element is not found.

See also

SCL._get_cb_dataset()

get_rcb_fcda_list()

def get_rcb_fcda_list	(		self,
			rcb
	)

Retrieve the list of FCDA elements associated with a specified RCB.

This function retrieves the list of Functional Constraint Data Attributes (FCDAs) associated with a specified Report Control Block (RCB). It first identifies the dataset linked to the RCB and then extracts the FCDA elements from the dataset.

Parameters

rcb	The Report Control Block (RCB) element for which the associated FCDA list is required.

Returns

A list of FCDA elements associated with the specified RCB.

Exceptions

Raises

an exception if the dataset reference or FCDA elements cannot be retrieved.

See also

get_rcb_dataset

get_rcb_list()

def get_rcb_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ln_name = None
	)

Get a list of ReportControl elements.

This function returns a list of ReportControl elements. It first builds the DOM if it is not already built, then retrieves the context object based on the provided IED, LDevice, and LN (LN0) names. Finally, it searches for ReportControl elements within the context object using XPath.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).

Returns

A list of ReportControl elements.

See also

SCL.get_context_object()

get_smv_for_mscvb()

def get_smv_for_mscvb	(		self,
			msvcb
	)

Get the SMV element from the Communications section for the specified SampledValueControl.

This function returns the SMV element from the Communications section for the given SampledValueControl. It uses the _get_communication_params_for_cb method to retrieve the SMV element.

Parameters

msvcb

The SampledValueControl element.

Exceptions

Exception

Raised if the control block is not a SampledValueControl or GSEControl.

Returns

The SMV element corresponding to the given SampledValueControl.

See also

SCL._get_communication_params_for_cb()

get_string_snippet_by_line_num()

def get_string_snippet_by_line_num	(		self,
			line_num,
			neighbours = 0,
			mark_line = False
	)

Get SCL source code snippet by line number.

Returns SCL source code from original SCL-file from specified line_num. The neighbour parameter allows to add lines before and after selected for more context. The mark_line flag allows to mark the line of interest.

Parameters

line_num	the line number of a line to be returned.
neighbours	(default = 0) number of lines before and after line_num to be returned in the snippet
mark_line	(default = False) set mark >> in front of the line of interest.

Returns

A text block with requested line and neighbour lines if specified.

get_subnetwork_by_name()

def get_subnetwork_by_name	(		self,
		str	name
	)

Get Subnetwork element by name.

Retrieves the Subnetwork element with the specified name.

Parameters

name	The name of the Subnetwork to retrieve.

Returns

The Subnetwork element with the specified name.

get_subnetwork_connected_ap_list()

def get_subnetwork_connected_ap_list	(		self,
			subnetwork_name = None,
			subnetwork = None
	)

Get list of ConnectedAP elements for a Subnetwork.

Retrieves a list of ConnectedAP elements for a specified Subnetwork. Either subnetwork_name or subnetwork must be provided.

Parameters

subnetwork_name	Name of the Subnetwork.
subnetwork	Subnetwork element.

Exceptions

AttributeError

Raised if neither subnetwork_name nor subnetwork is provided.

Returns

List of ConnectedAP elements.

get_subnetwork_connected_server_ap_tuple_list()

def get_subnetwork_connected_server_ap_tuple_list	(		self,
			subnetwork_name = None,
			subnetwork = None
	)

Get a list of tuples containing IED names and Access Point names of connected servers in a Subnetwork.

Retrieves a list of tuples where each tuple contains the IED name and the Access Point name for servers connected to a specified Subnetwork. The search can be performed either by the Subnetwork name or by the Subnetwork element itself.

Parameters

subnetwork_name	The name of the Subnetwork (optional if subnetwork is provided).
subnetwork	The Subnetwork element (optional if subnetwork_name is provided).

Returns

A list of tuples, each containing the IED name and Access Point name of connected servers.

get_subnetwork_connected_server_list()

def get_subnetwork_connected_server_list	(		self,
			subnetwork_name = None,
			subnetwork = None
	)

Get the list of connected servers in a Subnetwork.

Retrieves the list of servers connected to a specified Subnetwork. This function searches for servers connected to the Subnetwork either by the Subnetwork name or by the Subnetwork element itself.

Parameters

subnetwork_name	The name of the Subnetwork (if subnetwork is not provided).
subnetwork	The Subnetwork element (if subnetwork_name is not provided).

Returns

A list of servers connected to the specified Subnetwork.

get_subnetwork_list()

def get_subnetwork_list

(

self

)

Get list of SubNetwork elements.

Retrieves all SubNetwork elements from the SCL file.

Returns

List of SubNetwork elements.

get_subnetwork_name_list()

def get_subnetwork_name_list

(

self

)

Get list of SubNetwork names.

Retrieves the names of all SubNetwork elements from the SCL file.

Returns

List of SubNetwork names as strings.

get_Substation_list()

def get_Substation_list

(

self

)

Get list of Substation elements.

This function retrieves a list of all Substation elements from the document object model (DOM) using XPath.

Returns

A list of Substation elements (etree.Element).

get_type_definition_recursive()

def get_type_definition_recursive	(		self,
			element,
			parent_path = ""
	)

Get the data type structure for an element as MMS ObjectReference paths.

This function returns the data type structure for a given element as a list of paths in the MMS ObjectReference format. It recursively processes the element and its children, constructing the paths based on the element type and attributes.

Parameters

element	The element for which to get the data type structure.
parent_path	The base path for constructing the ObjectReference paths.

Returns

A list of paths in the MMS ObjectReference format.

Reimplemented in RSD.

get_urcb_dataset()

def get_urcb_dataset	(		self,
			urcb
	)

Alias for get_rcb_dataset().

This function is an alias for get_rcb_dataset(). It returns the DataSet element for the given Unbuffered ReportControl block (URCB).

Parameters

urcb	The Unbuffered ReportControl block (URCB) element.

Returns

The DataSet element for the given URCB.

See also

SCL.get_rcb_dataset()

get_urcb_list()

def get_urcb_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ln_name = None
	)

Get a list of Unbuffered ReportControl blocks.

This function returns a list of Unbuffered ReportControl blocks. It first builds the DOM if it is not already built, then retrieves the context object based on the provided IED, LDevice, and LN (LN0) names. Finally, it searches for ReportControl elements within the context object using XPath, filtering by the buffered attribute set to "false".

Parameters

ied_name	The name of the IED.
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).

Returns

A list of Unbuffered ReportControl blocks.

See also

SCL.get_context_object()

get_urcb_refs_list()

def get_urcb_refs_list	(		self,
			ied_name = None,
			ap_name = None,
			ld_inst = None,
			ln_name = None,
			ref_type = ReferenceType.ObjectReference
	)

Get a list of references for Unbuffered ReportControl blocks (URCB).

This function returns a list of ObjectReferences for Unbuffered ReportControl blocks (URCB) within the given context of IED, LDevice, and LN (LN0). It uses the get_cb_refs_list method to generate the list of references.

Parameters

ied_name	The name of the IED.
ap_name	The name of the AccessPoint
ld_inst	The instance of the LDevice.
ln_name	The name of the LN (LN0).
ref_type	The type of reference, default is ReferenceType.ObjectReference.

Returns

A list of ObjectReferences for Unbuffered ReportControl blocks (URCB).

See also

SCL.get_cb_refs_list()

load_from_artifact()

def load_from_artifact	(		self,
			artifact_str
	)

Load SCL contents from string obtained from Artifact.

Load SCL contents from string obtained from Artifact specified by artifact_str parameter.

Parameters

artifact_str

string representation of SCL-file contents obtained from Artifact.

load_from_string()

def load_from_string	(		self,
			scl_str
	)

Load SCL contents from string.

Load SCL contents from string specified by scl_str parameter.

Parameters

scl_str

string representation of SCL-file contents.

move_gse_smv_elements()

def move_gse_smv_elements	(		self,
		str	iedName,
		str	srcApName,
		str	trgtApName
	)

Moves GSE and SMV elements between ConnectedAPs.

This function moves GSE and SMV elements from the source ConnectedAP to the target ConnectedAP within the same IED. The GSE and SMV elements are transferred by updating the XML structure of the SCL file. If the source or target ConnectedAP elements are not found, the operation is aborted without any changes.

Parameters

iedName	The name of the IED in which the source and target ConnectedAPs reside.
srcApName	The AccessPoint name of the source ConnectedAP.
trgtApName	The AccessPoint name of the target ConnectedAP.

Note

The function does not modify the XML if the source or target ConnectedAP elements are not found.

remove_gocb()

def remove_gocb	(		self,
			go_cb_ref,
			preserve_communications = False
	)

Remove the GSEControl element by reference.

This function removes the GSEControl element by the specified reference. It can optionally preserve the corresponding GSE element in the Communications section.

Parameters

go_cb_ref	The reference to the GOOSE control block in SCL format.
preserve_communications	A boolean indicating whether to preserve (not remove) the GSE element in the Communications section.

Exceptions

Exception	Raised if the GOOSE control block is not found.
AttributeError	Raised if the name or inst attribute is not found in GSEControl, LDevice, AccessPoint, or IED.

Returns

0 if successful, -1 if there is an error.

See also

SCL._remove_cb()

remove_msvcb()

def remove_msvcb	(		self,
			msv_cb_ref,
			preserve_communications = False
	)

Remove the SampledValueControl element by reference.

This function removes the SampledValueControl element by the specified reference. It can optionally preserve the corresponding SMV element in the Communications section.

Parameters

msv_cb_ref	The reference to the Sampled Value control block in SCL format.
preserve_communications	A boolean indicating whether to preserve (not remove) the SMV element in the Communications section.

Exceptions

Exception	Raised if the SampledValueControl block is not found.
AttributeError	Raised if the name or inst attribute is not found in SampledValueControl, LDevice, AccessPoint, or IED.

Returns

0 if successful, -1 if there is an error.

See also

SCL._remove_cb()

select_ied()

def select_ied	(		self,
		**	kwargs
	)

Select an IED based on specified criteria.

This function allows the user to select an IED from the SCL file based on specified criteria, such as server-only, with GSE, or with SMV. If no matching IEDs are found, an exception is raised. The user is presented with a selection dialog to choose an IED from the available list.

Parameters

server_only	Boolean flag to filter IEDs with server functionality only.
with_gse_only	Boolean flag to filter IEDs with GSE functionality only.
with_smv_only	Boolean flag to filter IEDs with SMV functionality only.

Exceptions

SclElementNotFound	Raised when no IEDs match the specified criteria in the SCL file.
CancelledByUser	Raised when the user cancels the operation by not selecting an IED.

Returns

The name of the selected IED as a string.

to_string()

def to_string	(		self,
			pretty_print = True
	)

Return SCL object contents as string.

Returns SCL DOM object to string.

Parameters

pretty_print

DEPRECATED. Stringified SCL file is always returned pretty-printed

toString()

def toString	(		self,
			pretty_print = True
	)

Alias for to_string function.

Provides an alias for the to_string function to maintain consistency in method naming conventions.

Parameters

pretty_print

Boolean flag to specify if the output should be pretty-printed (default: True)

See also

SCL.to_string()

validate()

def validate	(		self,
			override_edition = None
	)

Validate SCL-file.

The function allows to validate the SCL-file associated with the SCL instance. By default, validation is performed against the default XML-schema, which has been chosen during the initialization of the SCL class.

scl = SCL("path/to/scl/file1") # initializes SCL file with default (Edition 2) schema.
res = scl.validate() # performs validation against Edition 2 schema.

It is also possible to validate the SCL-file against a schema other than the default. In that case, the override_edition parameter has to be passed to the function.

scl = SCL("path/to/scl/file1") # initializes SCL file with default (Edition 2) schema.
res = scl.validate(override_edition="2.1") # performs validation against Edition 2.1 schema.

Parameters

override_edition

passes str-type SCL-edition number to the validator, allowed editions are: "1", "2", "2.1".

Returns

SclValidationResult Validation result is wrapped into a SclValidationResult class instance. For more information, refer to the SclValidationResult class description.

See also

SCL SclValidationResult

validate_utf8_encoding()

def validate_utf8_encoding

(

self

)

Perform encoding validation to check if the file is UTF-8 encoded.

This function checks if the file is UTF-8 encoded. It reads the file in binary mode and uses the find_utf8_errors function to detect any encoding errors.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

validate_xml_declaration()

def validate_xml_declaration

(

self

)

Verify that the file contains a valid XML declaration according to the standard requirements.

This function checks if the XML declaration in the file matches one of the standard requirements. It validates the first line of the file against a list of acceptable XML declarations.

Returns

A TestResult object containing the result of the test, log messages, and error messages.

See also

TestResult

write_to_file()

def write_to_file	(		self,
			save_path
	)

Write SCL contents to file.

Writes SCL contents to file scpecified by save_path parameter.

Parameters

save_path

full filepath where SCL-file shall be saved including filename.

See also

Dialog.save_scd_file() Dialog.save_icd_file() Dialog.save_iid_file()

Member Data Documentation

BTYPE_REGEX_DICT

dictionary BTYPE_REGEX_DICT

static

Initial value:

=  {
        "BOOLEAN": r'^(True|False|true|false)$',
        "INT8": r'^-?(\d{1,2}|-?1[0-1]{1}\d{2}|-12[0-8]{1}|12[0-7]{1})$',
        "INT16": r'^(-?\d{1,4}|-?[1-2]\d{4}|-?3[0-1]\d{3}|-?32[0-6]\d{2}\-?327[0-5]\d|-3276[0-8]|3276[0-7])$',
        "INT32": r'^(-?\d{1,9}|-?1\d{9}|-?20\d{8}|-?21[0-3]\d{7}|-?214[0-6]\d{6}|-?2147[0-3]\d{5}|-?21474[0-7]\d{4}|-?214748[012]\d{4}|-?2147483[0-5]\d{3}|-?21474836[0-3]\d{2}|214748364[0-7]|-214748364[0-8])$',
        "INT64": r'^-?\d{1,19}$', # FIXME: INT64_REGEX
        "INT8U": r'^(\d{1,2}|1\d{2}|2[0-4]{1}[0-9]{1}|25[0-5]{1})$',
        "INT16U": r'^\d{1,5}$',  # FIXME: INT16U_REGEX
        "INT24U": r'^\d{1,8}$', # FIXME: INT24U_REGEX
        "INT32U": r'^\d{1,10}$', # FIXME: INT32U_REGEX
        "INT64U": r'^\d{1,19}$', # FIXME: INT64U_REGEX
        "FLOAT32": r'^[-+]?[0-9]*[.,][0-9]+(?:[eE][-+]?[0-9]+)?$', # FIXME: FLOAT32_REGEX
        "FLOAT64": r'^[-+]?[0-9]*[.,][0-9]+(?:[eE][-+]?[0-9]+)?$', # FIXME: FLOAT64_REGEX
        "VisString32": r'^([^\n\r\t\0\v]{1,32})$',
        "VisString64": r'^([^\n\r\t\0\v]{1,64})$',
        "VisString65": r'^([^\n\r\t\0\v]{1,65})$',
        "VisString128": r'^([^\n\r\t\0\v]{1,128})$',
        "VisString128": r'^([^\n\r\t\0\v]{1,128})$',
        "VisString255": r'^([^\n\r\t\0\v]{1,255})$',
        "Dbpos": r'^(intermediate-state|off|on|bad-state)$',
    }

default_namespace

default_namespace

dom

dom

edition

edition

file_path

file_path

iterations

int iterations = 0

static

namespaces

namespaces

original_string

original_string