Object / Data References#

class icspacket.proto.iec61850.path.ObjectReference(logical_device: str, /, logical_node: str | None = None, *names: str)[source]#

IEC 61850 ACSI ObjectReference (See IEC 61850-7-2, §5.5.3.3).

In this library, an ObjectReference is the in-memory path through the ACSI class hierarchy: a chain of instance names - logical device, logical node, data object, optional sub-data objects, and finally a data attribute - joined together so that one call can address an object no matter how deep it sits in that hierarchy.

IEC 61850 Representation

Format: LDName/LNName.DoName.SubDoName.AttrName

/ marks the boundary between the logical device name (LDName) and the logical node name (LNName).
. chains together everything deeper than the logical node (data objects, sub-data objects, and attributes).

Example:

LD1/MMXU1.A.phsA.mag.f

MMS Representation

On the wire, the same reference is carried as a VisibleString of variable length (capped at 129 octets), with every . rewritten as $:

Example: LD1/MMXU1.A.phsA → LD1/MMXU1$A$phsA

Note

The MMS form inserts one extra segment - the functional constraint (FC) - between a logical node and its data objects.

ObjectReferences can be built directly:

>>> ObjectReference("LD1")
"LD1"

>>> ObjectReference("LD1", "MMXU1", "CO", "phsA")
"LD1/MMXU1.CO.phsA"

Or parsed from existing references:

from_string() → parses IEC 61850 notation with . separators.
from_mmsref() → parses MMS VisibleString with $ separators.

property ldname: str#

Return the logical device name (LDName).

>>> ref = ObjectReference("LD1", "MMXU1", "A")
>>> ref.ldname
'LD1'

property lnname: str | None#

Return the logical node name (LNName), or None if not present.

>>> ref = ObjectReference("LD1", "MMXU1", "A")
>>> ref.lnname
'MMXU1'
>>> ObjectReference("LD1").lnname is None
True

property lnclass: LN_Class | None#

Resolve the LN class from the LNName, if available.

>>> ref = ObjectReference("LD1", "MMXU1")
>>> ref.lnclass
LN_Class.MMXU

property lngroup: LN_Group | None#

Resolve the LN group from the first character of the LNName.

>>> ref = ObjectReference("LD1", "MMXU1")
>>> ref.lngroup
LN_Group.M

property parts: list[str]#

Return the hierarchical components of the reference as a list.

>>> ref = ObjectReference("LD1", "MMXU1", "A", "phsA")
>>> ref.parts
['LD1', 'MMXU1', 'A', 'phsA']

name(index: int) → str[source]#

Return the name of the component at the given hierarchy index.

>>> ref = ObjectReference("LD1", "MMXU1", "A", "phsA")
>>> ref.name(2)
'A'

classmethod from_mmsref(reference: str) → Self[source]#

Parse an ObjectReference from an MMS VisibleString reference.

>>> ObjectReference.from_mmsref("LD1/MMXU1$A$phsA")
'LD1/MMXU1.A.phsA'

classmethod from_string(reference: str) → Self[source]#

Parse an ObjectReference from an IEC 61850 style string.

>>> ObjectReference.from_string("LD1/MMXU1.A.phsA")
'LD1/MMXU1.A.phsA'

property mmsref: str#

Return the MMS VisibleString form (with $ separators).

>>> ref = ObjectReference("LD1", "MMXU1", "A", "phsA")
>>> ref.mmsref
'LD1/MMXU1$A$phsA'

property mms_name: ObjectName#

Return the MMS ObjectName corresponding to this reference.

>>> ref = ObjectReference("LD1", "MMXU1", "A")
>>> ref.mms_name
ObjectName(domain='LD1', item='MMXU1$A')

class icspacket.proto.iec61850.path.DataObjectReference(logical_device: str, /, logical_node: str, fc: str, *names: str)[source]#

An ObjectReference for a data object, with the applicable Functional Constraint folded into the path.

Format:

<LNVariableName>$<FC>$<LNDataObjectName>[$<SubDataObjectName>...]

Example (See IEC 61850-7-2, §5.5.3.3):

MMXU1$MX$A$phsA

This maps into an ObjectReference hierarchy:

>>> DataObjectReference("LD1", "MMXU1", "MX", "A", "phsA")
'LD1/MMXU1.MX.A.phsA'

property functional_constraint: FC#

Return the Functional Constraint (FC) of this DataObjectReference.

>>> ref = DataObjectReference("LD1", "MMXU1", "MX", "A", "phsA")
>>> ref.functional_constraint
FC.MX

property datname: str#

Return the data object name.

>>> ref = DataObjectReference("LD1", "MMXU1", "MX", "A", "phsA")
>>> ref.datname
'A'

change_fc(new_fc: FC) → DataObjectReference[source]#

Create a new DataObjectReference with a different functional constraint (FC).

This method is useful when the same logical node or data object needs to be addressed under a different constraint, such as switching from ST (status) to MX (measurand).

Added in version 0.2.4.

Parameters:: new_fc – The functional constraint to substitute into the reference.
Returns:: A new DataObjectReference instance with the updated FC.
Return type:: DataObjectReference

>>> dor = DataObjectReference("LD1", "LLN0", "ST", "Mod", "stVal")
>>> dor_fc_mx = dor.change_fc(FC.MX)
>>> str(dor_fc_mx)
'LD1/LLN0.MX.Mod.stVal'