Updating documentation for new release

---

+ Fix some typos in iedctrl.py

Author: MatrixEditor

docs/source/index.rst

@@ -53,6 +53,7 @@ and MacOS. Any other Python version is not officially supported::
     :hidden:
 
     protocols/iec61850/iedmap
+    protocols/iec61850/iedctrl
     protocols/iec61850/api
 
 .. toctree::

docs/source/protocols/iec61850/api.rst

@@ -8,6 +8,7 @@ API Reference
 
     api_data_classes
     api_path
+    api_control
     api_client
     api_goose
     api_sv

docs/source/protocols/iec61850/api_client.rst

@@ -4,11 +4,6 @@
 IED Client
 ==========
 
-.. note::
-
-    Operation related commands are not implemented yet.
-
-
 .. automodule:: icspacket.proto.iec61850.client
     :members:
     :undoc-members:

docs/source/protocols/iec61850/api_control.rst

@@ -0,0 +1,9 @@
+.. _iec61850_api_control:
+
+
+Control / Operation
+===================
+
+
+.. automodule:: icspacket.proto.iec61850.control
+    :members:

docs/source/protocols/iec61850/iedctrl.rst

@@ -0,0 +1,48 @@
+.. _iec61850_example_iedctrl:
+
+Operating on IEDs
+=================
+
+`iedctrl` is a command-line utility to perform control operations on IEC61850 IEDs.
+Supports selecting, operating, and optionally querying values after execution.
+
+Usage
+-----
+
+.. code-block::
+
+    ied_operate.py -t [LDName/]LNName.[FC].DataName --value VALUE [--check] <host>
+    ied_operate.py -t [LDName/]LNName.[FC].DataName --toggle [--check] <host>
+
+
+Examples
+--------
+
+Operate a control object with a specific value:
+
+.. code-block::
+
+    iedctrl.py -t 'simpleIOGenericIO/GGIO1.SPCSO3' --value true --check 127.0.0.1
+    [I] Associating MMS environment with peer 127.0.0.1:102...
+    [I] Control model for node: DIRECT_ENHANCED
+    [I] Value will be changed to: True
+    [I] Successfully completed operation on SPCSO3!
+    Current value: TRUE
+
+Toggle a boolean control object:
+
+.. code-block::
+
+    iedctrl.py -t 'simpleIOGenericIO/GGIO1.SPCSO4' --toggle --check 127.0.0.1
+    [I] Associating MMS environment with peer 127.0.0.1:102...
+    [I] Control model for node: SBO_ENHANCED
+    [I] Value will be changed from FALSE -> TRUE
+    [I] Successfully completed operation on SPCSO4!
+    Current value: TRUE
+
+Notes
+-----
+
+- The ``target`` argument supports specifying logical device (LD), logical node (LN), functional constraint (FC), and data name. If the LD is omitted, the default LD will be queried first.
+- JSON is used to represent structured values. Files containing JSON can also be passed instead of inline JSON strings.
+- The ``--check`` option ensures the tool reads back the value after the control operation to verify success.

docs/source/protocols/iec61850/iedmap.rst

@@ -31,7 +31,7 @@ Usage
 
 .. code-block:: bash
 
-    iedmap [OPTIONS] <host> [-p <port>]
+    iedmap.py [OPTIONS] <host> [-p <port>]
 
 Where ``<host>`` specifies the IED (IP address or hostname), and ``port``
 (default 102) is the MMS communication port.

src/icspacket/examples/iedctrl.py

@@ -45,11 +45,12 @@ def cli2data(value: str) -> Any | None:
                 doc = json.load(fp)
         else:
             doc = json.loads(value)
-            if "value" in doc:
-                doc = doc["value"]
     except json.JSONDecodeError as e:
         logging.error(f"Invalid JSON value format: {value!r} - {e}")
         return None
+
+    if isinstance(doc, dict) and "value" in doc:
+        doc = doc["value"]
     return doc
 
 
@@ -64,7 +65,7 @@ def cli_main():
     group = parser.add_argument_group("Target Options")
     group.add_argument("-t", "--target", metavar="[LDName/]LNName.[FC].DataName", default=None, help=(
         "Target data node to control. If missing the logical device (LDName), the service will first be \n"
-        "queried for the default logical node (LNName) and then the data node (DataName) will be used. \n"
+        "queried for the default logical device and then the data node (DataName) will be used. \n"
         "Functional Constrains (FC) is optional as this will always be the CO (Control)."
     ), required=True)
     group.add_argument("--check", action="store_true", help="Queries the value after successful operation.")