IED Client¶

class icspacket.proto.iec61850.client.ACSI_Class(*values)[source]¶

Enumeration of ACSI class models as per IEC 61850.

Each entry defines a mapping from the abstract ACSI model into the concrete MMS object class that is used for encoding.

DATA = 'DataObject'¶

DATA_SET = 'DataSet'¶

BRCB = 'BufferedReportControlBlock'¶

URCB = 'UnbufferedReportControlBlock'¶

LCB = 'LogControlBlock'¶

LOG = 'SettingGroupControlBlock'¶

SGCB = 'Log'¶

GoCB = 'GooseControlBlock'¶

GsCB = 'GSSEControlBlock'¶

MSVCB = 'MulticastSampledValueControlBlock'¶

USVCB = 'UnicastSampledValueControlBlock'¶

object_class() → basicObjectClass_VALUES[source]¶

Map the ACSI class to its corresponding MMS BasicObjectClassType.

Returns:: The MMS object class type.
Return type:: BasicObjectClassType

class icspacket.proto.iec61850.client.IED_Client(address: tuple[str, int] | None = None, conn: MMS_Connection | None = None)[source]¶

IEC 61850 Intelligent Electronic Device (IED) client implementation that provides access to ACSI services mapped to MMS.

This class abstracts MMS connection handling and exposes ACSI services such as retrieving server directories, logical device directories, logical node directories, and reading/writing values of DataObjects.

A client may either be initialized with an existing MMS_Connection or can establish its own association to a remote MMS peer.

>>> with IED_Client(("127.0.0.1", 102)) as client:
...     devices = client.get_server_directory()
...     for dev in devices:
...         print(dev)

Additional support for control objects and operations is provided:

>>> with IED_Client(("127.0.0.1", 102)) as client:
...     co = client.get_control_object(node_ref)
...     client.operate(co, True) # direct control

Parameters:

address (tuple[str, int] | None) – Optional IP/port tuple for automatic association.
conn (MMS_Connection | None) – Pre-established MMS connection, if available.

Changed in version 0.2.4: Added support for control objects/operations.

property mms_conn: MMS_Connection¶

Return the active MMS connection object.

Returns:: The established MMS connection.
Return type:: MMS_Connection
Raises:: ConnectionNotEstablished – If no MMS connection is available.

register_unconfirmed_cb(cb: Callable[[MMS_Connection, UnconfirmedService], None]) → None[source]¶

Parameters:: cb (UnconfirmedServiceCallback) – The callback to register.

associate(address: tuple[str, int] | None = None) → None[source]¶

Establish an association with a remote MMS server.

Parameters:: address (tuple[str, int] | None) – The address (IP, port) of the remote peer.

release() → None[source]¶: Release the MMS association if active.

get_server_directory() → list[ObjectReference][source]¶

Retrieve the list of logical devices available on the server.

Maps ACSI GetServerDirectory MMS GetNameList.

Returns:: A list of logical device references.
Return type:: list[ObjectReference]

>>> client.get_server_directory()
["LD1", "LD2"]

get_server_file_directory() → list[DirectoryEntry][source]¶

Retrieve the list of files stored on the server.

Maps ACSI FileDirectory MMS FileDirectory.

Returns:: List of file directory entries.
Return type:: list[DirectoryEntry]

get_logical_device_directory(ld_name: str | ObjectReference, /) → list[ObjectReference][source]¶

Retrieve the list of logical nodes inside a logical device.

Maps ACSI GetLogicalDeviceDirectory MMS GetNameList.

Parameters:: ld_name (str | ObjectReference) – Logical device name or reference.
Returns:: List of logical node references.
Return type:: list[ObjectReference]

get_logical_node_directory(lnref: ObjectReference, /, acsi_class: ACSI_Class | None = None) → list[ObjectReference][source]¶

Retrieve the data objects of a logical node.

Maps ACSI GetLogicalNodeDirectory MMS GetNameList.

Parameters:

lnref (ObjectReference) – Reference to the logical node.
acsi_class (ACSI_Class | None) – Optional ACSI class filter.

Returns:

List of child object references.

Return type:

list[ObjectReference]

>>> ln = ObjectReference("LD1", "MMXU1")
>>> client.get_logical_node_directory(ln)
["LD1/MMXU1.A.phsA", "LD1/MMXU1.A.phsB"]

get_all_data_values(lnref: ObjectReference, /) → AccessResult[source]¶

Read all data values of a logical node.

Maps ACSI GetAllDataValues MMS Read.

Parameters:: lnref (ObjectReference) – Reference to the logical node.
Returns:: Access result containing all values.
Return type:: AccessResult
Raises:: ValueError – If multiple results are returned.

get_data_values(datref: ObjectReference, /) → AccessResult[source]¶

Read the value of a DataObject or DataAttribute.

Maps ACSI GetDataValues MMS Read.

Parameters:: datref (ObjectReference) – DataObject reference.
Returns:: Access result for the object.
Return type:: AccessResult

set_data_values(datref: ObjectReference, /, value: Data) → DataAccessError | None[source]¶

Write the value of a DataObject or DataAttribute.

Maps ACSI SetDataValues MMS Write.

Parameters:

datref (ObjectReference) – DataObject reference.
value (Data) – Value to be written.

Returns:

Error code if write fails, otherwise None.

Return type:

DataAccessError | None

get_data_directory(datref: ObjectReference, /) → GetVariableAccessAttributes_Response[source]¶

Retrieve the attributes of a DataObject.

Maps ACSI GetDataDirectory MMS GetVariableAccessAttributes.

Parameters:: datref (ObjectReference) – DataObject reference.
Returns:: Variable access attributes.
Return type:: GetVariableAccessAttributes_Response

get_data_definition(datref: ObjectReference, /) → GetVariableAccessAttributes_Response¶

Retrieve the attributes of a DataObject.

Maps ACSI GetDataDirectory MMS GetVariableAccessAttributes.

Parameters:: datref (ObjectReference) – DataObject reference.
Returns:: Variable access attributes.
Return type:: GetVariableAccessAttributes_Response

get_dataset_values(datref: ObjectReference, /) → list[AccessResult][source]¶

Retrieve all values of a data set.

Maps ACSI GetDataSetValues MMS Read.

Parameters:: datref (ObjectReference) – DataSet reference.
Returns:: List of access results for each element.
Return type:: list[AccessResult]

set_dataset_values(datref: ObjectReference, values: list[Data], /) → DataAccessError | None[source]¶

Write values to a data set.

Maps ACSI SetDataSetValues MMS Write.

Parameters:

datref (ObjectReference) – DataSet reference.
values (list[Data]) – List of data values to write.

Returns:

Error code if write fails, otherwise None.

Return type:

DataAccessError | None

get_dataset_directory(datref: ObjectReference, /) → list[Member_TYPE][source]¶

Retrieve the directory of a data set.

Maps ACSI GetDataSetDirectory MMS VariableListAttributes.

Parameters:: datref (ObjectReference) – DataSet reference.
Returns:: List of variables contained in the dataset.
Return type:: list[NamedVariableSpecificationItem]

control(target: DataObjectReference, /) → ControlObject[source]¶

Retrieve a ControlObject for the given data object reference.

This method reads the ctlModel attribute of the target and uses the associated type description to construct a ControlObject.

Added in version 0.2.4.

Parameters:: target (DataObjectReference) – Data object reference to the control object.
Returns:: Initialized control object instance.
Return type:: ControlObject
Raises:: ConnectionError – If retrieving the control model fails.

select(co: ControlObject, /) → DataAccessError | None[source]¶

Perform the Select (SBO) operation on a control object.

This method only works with ControlObject instances using the SBO_NORMAL model. It reads the SBO attribute to perform the selection.

Added in version 0.2.4.

Parameters:: co (ControlObject) – Control object to select.
Returns:: Access error if selection fails, or None on success.
Return type:: DataAccessError | None
Raises:: ValueError – If the control object does not use SBO_NORMAL.

select_with_value(co: ControlObject, /, ctl_val: Any, oper_time: Timestamp | None = None) → DataAccessError | None[source]¶

Perform the SelectWithValue operation (SBOw) for an enhanced control object.

Only supported for ControlObject instances with the SBO_ENHANCED model. Writes the provided ctl_val and optional operation timestamp to the SBOw attribute.

Added in version 0.2.4.

Parameters:

co (ControlObject) – Control object to select with value.
ctl_val (Any) – Control value to write.
oper_time (Timestamp | None) – Optional timestamp for the operation.

Returns:

Access error if selection fails, or None on success.

Return type:

DataAccessError | None

Raises:

ValueError – If the control object does not use SBO_ENHANCED.
MMSServiceError – If the MMS write operation fails.

operate(co: ControlObject, /, ctl_val: Any, oper_time: Timestamp | None = None)[source]¶

Execute a control operation on a ControlObject.

Writes the provided control value to the Oper attribute. Supports all models of control objects.

Added in version 0.2.4.

Parameters:

co (ControlObject) – Control object to operate.
ctl_val (Any) – Control value to write.
oper_time (Timestamp | None) – Optional timestamp for the operation.

Raises:

MMSServiceError – If the MMS write operation fails.

cancel(co: ControlObject, /, ctl_val: Any, oper_time: Timestamp | None = None)[source]¶

Cancel a previously issued control operation.

Writes the control value to the Cancel attribute without performing interlock or synchrocheck.

Added in version 0.2.4.

Parameters:

co (ControlObject) – Control object to cancel.
ctl_val (Any) – Control value for cancellation.
oper_time (Timestamp | None) – Optional timestamp for the cancellation.

Raises:

MMSServiceError – If the MMS write operation fails.

await_command_termination() → InformationReport[source]¶

Block until a control command terminates and an unconfirmed report is received.

Continuously reads unconfirmed PDUs until an InformationReport is received.

Added in version 0.2.4.

Returns:: The unconfirmed MMS InformationReport containing the control result.
Return type:: InformationReport