Object / Data References¶

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

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

An ObjectReference uniquely identifies instances in the ACSI class hierarchy (logical devices, logical nodes, data objects, sub-data objects, and data attributes). It is constructed by concatenating all instance names in the hierarchy.

IEC 61850 Representation

Format: LDName/LNName.DoName.SubDoName.AttrName

/ separates the logical device name (LDName) from the logical node name (LNName).
. separates deeper hierarchical levels (data objects, sub-data objects, attributes).

Example:

LD1/MMXU1.A.phsA.mag.f

MMS Representation*

In MMS, ObjectReferences are encoded as a variable-length VisibleString:

Maximum length: 129 octets
. (dot) separators are replaced with $ (dollar).
Example: LD1/MMXU1.A.phsA → LD1/MMXU1$A$phsA

Note

The MMS representation contains an extra 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]¶

Specialized ObjectReference for data objects with Functional Constraints.

Format:

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

Example (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'