Add IEC61850 docs

MatrixEditor · MatrixEditor · commit 77031028f51e · 2025-08-31T21:07:27.000+02:00
---

+ Fix some inconsistencies accross tools
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -84,23 +84,16 @@
                     "title": "MMS Utilities",
                     "url": "protocols/mms/examples",
                     "summary": "Manufacturing Message Specification tools",
-                    "children": [
-                        {
-                            "title": "MMS Client",
-                            "url": "examples/mms/client",
-                            "summary": "Interactive MMS client shell",
-                        },
-                        {
-                            "title": "MMS Utility",
-                            "url": "examples/mms/utility",
-                            "summary": "Utility commands for MMS peers",
-                        },
-                    ],
                 },
                 {
                     "title": "DNP3 Tools",
                     "url": "protocols/dnp3/examples",
                     "summary": "DNP3 utilities and tools",
+                },
+                {
+                    "title": "IED Enumeration Tool",
+                    "url": "protocols/iec61850/iedmap",
+                    "summary": "Logical Device enumeration and more",
                 }
             ],
         },
diff --git a/docs/source/getting-started/protocols.rst b/docs/source/getting-started/protocols.rst
@@ -15,6 +15,7 @@ Protocols Overview
     acse
     mms
     dnp3
+    iec61850
 
 
 **Protocol references**
@@ -64,8 +65,14 @@ Protocols Overview
 
 
     .. grid-item-card:: :octicon:`zap` DNP3.0 (IEEE 1815)
-        :link: mms_index
+        :link: dnp3_index
         :link-type: ref
 
         Distributed Network Protocol 3.0.
 
+    .. grid-item-card:: :octicon:`pulse` IEC 61850
+        :link: iec61850_api_index
+        :link-type: ref
+
+        Intelligent electronic devices using IEC 61850
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -44,6 +44,13 @@ and MacOS. Any other Python version is not officially supported::
     protocols/dnp3/dnp3dump
     protocols/dnp3/api
 
+.. toctree::
+    :caption: IEC 61850
+    :hidden:
+
+    protocols/iec61850/iedmap
+    protocols/iec61850/api
+
 .. toctree::
     :caption: MMS / ISO 9506
     :hidden:
diff --git a/docs/source/protocols/iec61850/_images/iedmap-enum-list.png b/docs/source/protocols/iec61850/_images/iedmap-enum-list.png
diff --git a/docs/source/protocols/iec61850/_images/iedmap-enum-values.png b/docs/source/protocols/iec61850/_images/iedmap-enum-values.png
diff --git a/docs/source/protocols/iec61850/_images/iedmap-enum1.png b/docs/source/protocols/iec61850/_images/iedmap-enum1.png
diff --git a/docs/source/protocols/iec61850/api.rst b/docs/source/protocols/iec61850/api.rst
@@ -0,0 +1,11 @@
+.. _iec61850_api_index:
+
+API Reference
+=============
+
+.. toctree::
+    :caption: Components
+
+    api_data_classes
+    api_path
+    api_client
diff --git a/docs/source/protocols/iec61850/api_client.rst b/docs/source/protocols/iec61850/api_client.rst
@@ -0,0 +1,14 @@
+.. _iec61850_api_client:
+
+
+IED Client
+==========
+
+.. note::
+
+    Operation related commands are not implemented yet.
+
+
+.. automodule:: icspacket.proto.iec61850.client
+    :members:
+    :undoc-members:
diff --git a/docs/source/protocols/iec61850/api_data_classes.rst b/docs/source/protocols/iec61850/api_data_classes.rst
@@ -0,0 +1,8 @@
+.. _iec61850_data_classes:
+
+Data Classes
+============
+
+.. automodule:: icspacket.proto.iec61850.classes
+    :members:
+    :undoc-members:
diff --git a/docs/source/protocols/iec61850/api_path.rst b/docs/source/protocols/iec61850/api_path.rst
@@ -0,0 +1,9 @@
+.. _iec61850_api_path:
+
+
+Object / Data References
+========================
+
+
+.. automodule:: icspacket.proto.iec61850.path
+    :members:
diff --git a/docs/source/protocols/iec61850/iedmap.rst b/docs/source/protocols/iec61850/iedmap.rst
@@ -0,0 +1,84 @@
+.. _iec61850_example_iedmap:
+
+Enumerating IEDs
+================
+
+The ``iedmap`` utility provides a structured way to **enumerate and inspect
+Intelligent Electronic Devices (IEDs)** using the IEC 61850 protocol together
+with MMS over TCP. It allows to traverse the hierarchical information model of
+an IED and extract details about its logical structure.
+
+
+IEC 61850 Background
+--------------------
+
+IEC 61850 defines a **layered data model** built around the following concepts:
+
+- **Logical Devices (LDs)**: Abstractions that represent major functional
+  groupings inside an IED - equivalent to MMS domain objects.
+- **Logical Nodes (LNs)**: Each LN represents a specific function (e.g.,
+  measurement, control, protection)
+- **Data Objects and Data Attributes**: Hierarchically organized information
+  points that carry actual values and metadata - equivalent to MMS named
+  variables and named variable lists.
+
+The result is a **tree of nodes, and variables** for a target logical device, which
+can be displayed in either structured or flat form.
+
+
+Usage
+-----
+
+.. code-block:: bash
+
+    iedmap [OPTIONS] <host> [-p <port>]
+
+Where ``<host>`` specifies the IED (IP address or hostname), and ``port``
+(default 102) is the MMS communication port.
+
+.. figure:: _images/iedmap-enum1.png
+    :align: center
+
+    Sample output that displays only nodes at depth zero.
+
+
+
+Output Options
+--------------
+
+The following arguments control how information is displayed:
+
+.. option:: -L, --list
+
+    Output all discovered nodes as a **flat list** rather than a hierarchical table/tree.
+
+    .. note::
+        This option does not respect the ``--maxdepth`` option.
+
+    .. figure:: _images/iedmap-enum-list.png
+        :align: center
+
+        List output of all logical nodes within the device or the selected node.
+
+
+
+.. option:: --maxdepth DEPTH
+
+  Limit the displayed hierarchy to a maximum **node depth**.
+
+.. option:: --no-path
+
+  Suppress the display of **fully qualified paths** for nodes.
+  Normally, paths such as ``LD1/MMXU1.A.phsA`` are shown.
+  With this option, only the node name is displayed.
+
+.. option:: -V, --values
+
+    Display the **current values** of nodes alongside their structure. This
+    requires additional MMS ``Read`` requests to retrieve DataObject or
+    DataAttribute values.
+
+    .. figure:: _images/iedmap-enum-values.png
+        :align: center
+
+
diff --git a/src/icspacket/examples/dnp3read.py b/src/icspacket/examples/dnp3read.py
@@ -104,8 +104,8 @@ def run(self, args):
         if apdu.iin is not None:
             if apdu.iin.no_func_code_support:
                 return logging.error(
-                    "Outstation does not support function code %s",
-                    FunctionCode.READ,
+                    "Outstation does not support function code %s for target",
+                    FunctionCode.READ.name,
                 )
 
         raw_objects = apdu.objects
diff --git a/src/icspacket/examples/iedmap.py b/src/icspacket/examples/iedmap.py
@@ -55,6 +55,7 @@ def __init__(self, client: IED_Client, args) -> None:
         self.datasets = []
         self.console = Console()
         self.with_values = args.values
+        self.no_path = args.no_path
         self.max_depth = args.maxdepth if args.maxdepth is not None else 100
         if args.node:
             self.nodes.append(args.node)
@@ -117,14 +118,14 @@ def dump_nodes(self, tree: Tree, nodes: list[str], is_data: bool = True):
             if "$" not in node:
                 label = str(node_ref.lnname)
                 ln_class = node_ref.lnclass
-                ln_group = node_ref.lngroup
                 if ln_class:
                     label = f"{label} ({ln_class.value})"
-                if ln_group:
-                    label = f"{label} - {ln_group.name}: {ln_group.value}"
 
-                label = label.ljust(100 - 8, ".")
-                subtree = tree.add(f"{label} {node_ref}")
+                if not self.no_path:
+                    label = label.ljust(100 - 8, ".")
+                    label = f"{label} {node_ref}"
+
+                subtree = tree.add(label)
                 trees[0] = subtree
                 continue
 
@@ -146,8 +147,11 @@ def dump_nodes(self, tree: Tree, nodes: list[str], is_data: bool = True):
                     if data_class:
                         label = f"{label}({data_class.value}) "
 
-                label = label.ljust(100 - (4 * (depth + 2)), ".")
-                text = Text(f"{label} {node_ref}")
+                if not self.no_path:
+                    label = label.ljust(100 - (4 * (depth + 2)), ".")
+                    label = f"{label} {node_ref}"
+
+                text = Text(label)
 
                 value = (
                     self.get_node_value(node_ref)
diff --git a/src/icspacket/examples/util/mms.py b/src/icspacket/examples/util/mms.py
@@ -283,6 +283,6 @@ def add_mms_connection_options(parser: ArgumentParser) -> None:
     conn_group = parser.add_argument_group("Connection Options","Specify transport layer settings and target host information")
     conn_group.add_argument("-p", "--port", type=int, help="TCP port of the target MMS server (default: 102)", default=102)
     conn_group.add_argument("--max-tpdu-size", type=int, metavar="SIZE", help="Maximum TPDU size to negotiate during COTP connection", default=TPDU_Size.SIZE_1024)
-    conn_group.add_argument("--timeout", type=float, metavar="SEC", help="Timeout in seconds for transport-level operations (default: None)", default=None)
+    conn_group.add_argument("--timeout", type=float, metavar="SEC", help="Timeout in seconds for transport-level operations (default: 10s)", default=10.0)
     conn_group.add_argument("host", type=str, help="Target host (IP address or hostname) to establish MMS connection")
     # fmt: on
diff --git a/src/icspacket/proto/dnp3/objects/variations.py b/src/icspacket/proto/dnp3/objects/variations.py
@@ -1911,7 +1911,7 @@ class DNP3ObjectG122V2:
 __variation_desc__[0][214] = "Device attributes - number of master-defined data sets"
 __variation_desc__[0][215] = "Device attributes - number of outstation-defined data sets"
 __variation_desc__[0][216] = "Device attributes - maximum number of binary output objects per"
-__variation_desc__[0][217] = "Device attributes - local timing accura cy"
+__variation_desc__[0][217] = "Device attributes - local timing accuracy"
 __variation_desc__[0][218] = "Device attributes - duration of time accuracy"
 __variation_desc__[0][219] = "Device attributes - support for analog output events"
 __variation_desc__[0][220] = "Device attributes - maximum analog o utput index"
@@ -1940,9 +1940,9 @@ class DNP3ObjectG122V2:
 __variation_desc__[0][243] = "Device attributes - device manufacturer's hardware version"
 __variation_desc__[0][245] = "Device attributes - user-assigned location name"
 __variation_desc__[0][246] = "Device attributes - user-assigned ID code/number"
-__variation_desc__[0][247] = "Device attributes - user-assigned devi ce name"
+__variation_desc__[0][247] = "Device attributes - user-assigned device name"
 __variation_desc__[0][248] = "Device attributes - device serial number"
-__variation_desc__[0][249] = "Device attributes - DNP3 subset and c onformance"
+__variation_desc__[0][249] = "Device attributes - DNP3 subset and conformance"
 __variation_desc__[0][250] = "Device attributes - device manufacturer's product name and model"
 __variation_desc__[0][252] = "Device attributes - device manufacturer's name"
 __variation_desc__[0][254] = "Device attributes - non-specific all attributes request"
diff --git a/src/icspacket/proto/iec61850/classes.py b/src/icspacket/proto/iec61850/classes.py
@@ -17,6 +17,8 @@
 
 
 class LN_Class(enum.Enum):  # IEC61850 7-4
+    """Logical Node (LN) classes"""
+
     ANCR = "Neutral current regulator"  # 5.9.2 LN
     ARCO = "Reactive power control"  # 5.9.3 LN
     ATCC = "Automatic tap changer controller"  # 5.9.4 LN
@@ -93,6 +95,8 @@ def from_lname(ln_name: str) -> "LN_Class | None":
 
 
 class LN_Group(enum.Enum):
+    """Logical Node (LN) groups"""
+
     # prefixed with G_
     A = "Automatic Control"
     C = "Supervisory control"
@@ -110,6 +114,8 @@ class LN_Group(enum.Enum):
 
 
 class DATA_Class(enum.Enum):
+    """Common DATA classes"""
+
     ACD = "Directional protection activation information"  # 7.3.7
     ACT = "Protection activation information"  # 7.3.6
     APC = "Controllable analogue process value"  # 7.5.8
@@ -160,7 +166,7 @@ def from_name(datname: str, /) -> "DATA_Class | None":
 
 
 class FC(enum.Enum):  # Functional Constraint
-    """Functional Constraint"""
+    """Functional Constraints"""
 
     BL = "Blocking"
     BR = "Buffered report"
diff --git a/src/icspacket/proto/mms/connection.py b/src/icspacket/proto/mms/connection.py
@@ -695,7 +695,7 @@ def write_variable(
         >>> var = VariableAccessItem(name=ObjectName(vmd_specific="SetPoint"))
         >>> data = Data()
         >>> data.integer = 42
-        >>> err = mms_conn.write_variable(var, data)
+        >>> err = mms_conn.write_variable(data, variable)
         >>> print("Write successful" if err is None else f"Failed: {err}")
 
         .. versionchanged:: 0.2.2
@@ -780,7 +780,7 @@ def variable_list_attributes(
         self, name: ObjectName, /
     ) -> GetNamedVariableListAttributes_Response:
         """
-        .. versionadded:: 0.2.3
+        .. versionadded:: 0.2.2
         """
         request = GetNamedVariableListAttributes_Request(name)
         service = ConfirmedServiceRequest(getNamedVariableListAttributes=request)
