IED Client#

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

Enumeration of ACSI class models according to 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]

create_dataset(datref: ObjectReference, members: list[ObjectReference | DataObjectReference], /) → None[source]#

Dynamically create a data set.

Maps ACSI CreateDataSet MMS DefineNamedVariableList.

Added in version 0.3.0.

Parameters:

datref (ObjectReference) – DataSet reference to create.
members (list[ObjectReference | DataObjectReference]) – References of the DataObjects/DataAttributes to include in the data set.

Raises:

MMSServiceError – If the peer rejects the creation request (e.g. the name already exists or the server does not support dynamic data set creation).

delete_dataset(datref: ObjectReference, /) → bool[source]#

Dynamically delete a data set.

Maps ACSI DeleteDataSet MMS DeleteNamedVariableList.

Added in version 0.3.0.

Parameters:: datref (ObjectReference) – DataSet reference to delete.
Returns:: True if the data set was deleted, False otherwise.
Return type:: bool

Configure and enable a Report Control Block (BRCB/URCB).

Maps ACSI Report SetRCBValues (per attribute) followed by a RptEna=True write MMS Write.

Only the most frequently needed configuration attributes are handled here (DatSet, RptID, TrgOps, IntgPd). Regardless of which of those are set, RptEna is always written last, according to IEC 61850-8-1, so that the block is fully configured before the server starts reporting from it. When general_interrogation is requested, GI=True is written as a final step once reporting has been enabled.

Added in version 0.3.0.

Parameters:

rcb_ref (ObjectReference) – Reference to the report control block, e.g. LLN0.RP.EventsRCB01.
dataset (ObjectReference | str | None) – Data set reference to attach to the RCB.
rpt_id (str | None) – Report identifier to configure.
trg_ops (dict[int, bool] | bytes | None) – Trigger conditions bit string, e.g. {1: True, 4: True} for data-change and integrity.
integrity_period (int | None) – Integrity period in milliseconds.
general_interrogation (bool) – If True, trigger a general interrogation after enabling reporting.

Raises:

MMSServiceError – If a configuration write is rejected by the peer.

disable_reporting(rcb_ref: ObjectReference, /) → None[source]#

Disable a previously enabled Report Control Block.

Maps ACSI Report SetRCBValues (RptEna=False) MMS Write.

Added in version 0.3.0.

Parameters:: rcb_ref (ObjectReference) – Reference to the report control block.

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