sylo-plc-comms 0.1.0

package/scripts/cip_tag_write.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Write one or many Logix tags to a PLC via ciplogix.
+
+GATED by the operator-managed download allowlist: the target IP must be present
+and enabled. This reuses the same allowlist as project downloads — it is the
+operator's explicit "this PLC is okay to touch" list. The agent cannot write to
+any IP not on it, even with operator permission, and never edits the allowlist.
+
+Inputs: a JSON array of {"tag": "...", "value": <json>} objects via --stdin,
+--writes-json, or a single --tag/--value pair.
+
+Usage:
+  echo '[{"tag":"MyDint","value":42}]' | py -3.12 cip_tag_write.py --ip 10.1.200.45 --stdin
+  py -3.12 cip_tag_write.py --ip 10.1.200.45 --tag MyDint --value 42
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from _cip_client import ensure_ciplogix, open_driver
+from _download_allowlist import load_allowlist
+from _json_out import emit, emit_error
+
+
+def _ip_allowed(ip: str) -> tuple[bool, str]:
+    al = load_allowlist()
+    for entry in al.get("ips", []):
+        if isinstance(entry, dict) and entry.get("ip") == ip:
+            if entry.get("enabled", True):
+                return True, "ok"
+            return False, f"IP {ip} is in the allowlist but disabled."
+    return False, f"IP {ip} is not in the allowlist. The agent cannot write tags to it."
+
+
+def _coerce_in(v: Any) -> Any:
+    """Best-effort JSON -> pycomm3 value coercion. pycomm3 accepts native types
+    directly; the main gotcha is that JSON bools arrive fine and ints/floats are
+    native. Strings for STRING tags must be str. We leave values as-is except
+    we keep bools as bool (JSON true/false) and pass lists through."""
+    return v
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Write Logix tags via ciplogix (allowlist-gated)")
+    parser.add_argument("--ip", required=True, help="Controller IPv4 address")
+    parser.add_argument("--tag", default="", help="Single tag name (paired with --value)")
+    parser.add_argument("--value", default="", help="Single tag value (parsed as JSON if possible)")
+    parser.add_argument("--writes-json", default="", help="JSON array of {tag,value} objects")
+    parser.add_argument("--stdin", action="store_true", help="Read JSON array of {tag,value} from stdin")
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Resolve and validate writes but do not send to the PLC",
+    )
+    args = parser.parse_args()
+
+    allowed, reason = _ip_allowed(args.ip)
+    if not allowed:
+        emit_error(reason)
+
+    writes: list[dict[str, Any]] = []
+    if args.stdin:
+        raw = sys.stdin.read().strip()
+        try:
+            parsed = json.loads(raw) if raw else []
+        except json.JSONDecodeError as exc:
+            emit_error(f"stdin is not valid JSON: {exc}")
+            return
+        if not isinstance(parsed, list):
+            emit_error("stdin JSON must be an array of {tag,value} objects.")
+            return
+        writes = parsed
+    if args.writes_json:
+        try:
+            parsed = json.loads(args.writes_json)
+        except json.JSONDecodeError as exc:
+            emit_error(f"--writes-json is not valid JSON: {exc}")
+            return
+        if isinstance(parsed, list):
+            writes.extend(parsed)
+        elif isinstance(parsed, dict):
+            writes.append(parsed)
+    if args.tag:
+        val: Any
+        vraw = args.value
+        try:
+            val = json.loads(vraw) if vraw != "" else None
+        except json.JSONDecodeError:
+            val = vraw  # treat as plain string
+        writes.append({"tag": args.tag, "value": val})
+
+    # Normalize
+    clean: list[tuple[str, Any]] = []
+    for w in writes:
+        if not isinstance(w, dict) or "tag" not in w:
+            emit_error("Each write must be an object with a 'tag' field.")
+            return
+        name = str(w["tag"]).strip()
+        if not name:
+            emit_error("Empty tag name in write list.")
+            return
+        clean.append((name, _coerce_in(w.get("value"))))
+
+    if not clean:
+        emit_error("No writes supplied. Use --tag/--value, --writes-json, or --stdin.")
+
+    if args.dry_run:
+        emit({
+            "ok": True,
+            "ip": args.ip,
+            "dry_run": True,
+            "writes": [{"tag": n, "value": v} for n, v in clean],
+        })
+        return
+
+    try:
+        ensure_ciplogix()
+    except Exception as exc:
+        emit_error(f"ciplogix setup failed: {exc}")
+
+    plc = open_driver(args.ip, init_tags=True)
+    try:
+        results: list[dict] = []
+        # ciplogix supports plc.write((tag, value), (tag, value), ...) multi-write
+        try:
+            resp = plc.write(*[(n, v) for n, v in clean])
+        except Exception as exc:
+            for n, v in clean:
+                results.append({"tag": n, "value": v, "ok": False, "error": str(exc)})
+            emit({"ok": True, "ip": args.ip, "results": results, "all_failed": True})
+            return
+
+        resp_list = resp if isinstance(resp, list) else [resp]
+        for (name, value), tag in zip(clean, resp_list):
+            err = None
+            try:
+                err = getattr(tag, "error", None)
+                if not err and getattr(tag, "status", None) not in (None, "", "Success"):
+                    err = str(getattr(tag, "status"))
+            except Exception:
+                pass
+            results.append({
+                "tag": name,
+                "value": value,
+                "ok": not err,
+                "error": err,
+            })
+        ok_count = sum(1 for r in results if r["ok"])
+        emit({
+            "ok": True,
+            "ip": args.ip,
+            "requested": len(clean),
+            "succeeded": ok_count,
+            "failed": len(clean) - ok_count,
+            "results": results,
+        })
+    finally:
+        try:
+            plc.close()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    main()

package/scripts/opcua_browse.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Browse an OPC UA address space node and return its children.
+
+Read-only. Default starting node is the root Objects folder. Pass a node-id
+spec (ns=2;s=... or bare name) to browse a specific node.
+
+Usage:
+  py -3.12 opcua_browse.py --ip 10.1.200.45
+  py -3.12 opcua_browse.py --ip 10.1.200.45 --node "ns=2;s=MyTag"
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+
+from _json_out import emit, emit_error
+from _opcua_client import (
+    connect,
+    default_endpoint,
+    ensure_asyncua,
+    jsonable,
+    parse_node_id,
+    tags_namespace_index,
+)
+
+
+async def run(endpoint: str, node_spec: str, default_ns: int) -> dict:
+    from asyncua import ua
+
+    client = await connect(endpoint)
+    try:
+        if node_spec:
+            node = client.get_node(parse_node_id(node_spec, default_ns))
+        else:
+            node = client.get_node(ua.ObjectIds.ObjectsFolder)
+
+        try:
+            children = await node.get_children()
+        except Exception as exc:
+            emit_error(f"browse failed for {node_spec or 'Objects'}: {exc}")
+
+        out_children = []
+        for ch in children:
+            entry = {
+                "node_id": str(ch.nodeid),
+                "browse_name": None,
+                "display_name": None,
+                "node_class": None,
+                "data_type": None,
+                "value": None,
+            }
+            try:
+                bn = await ch.read_browse_name()
+                entry["browse_name"] = str(bn)
+            except Exception:
+                pass
+            try:
+                dn = await ch.read_display_name()
+                entry["display_name"] = str(dn)
+            except Exception:
+                pass
+            try:
+                nc = await ch.read_node_class()
+                entry["node_class"] = str(nc)
+            except Exception:
+                pass
+            # If it's a Variable, grab data type + value
+            if entry["node_class"] and "Variable" in str(entry["node_class"]):
+                try:
+                    dt = await ch.read_data_type()
+                    entry["data_type"] = str(dt)
+                except Exception:
+                    pass
+                try:
+                    val = await ch.read_value()
+                    entry["value"] = jsonable(val)
+                except Exception:
+                    pass
+            out_children.append(entry)
+
+        return {
+            "ok": True,
+            "endpoint": endpoint,
+            "browsed_node": node_spec or "ObjectsFolder",
+            "child_count": len(out_children),
+            "children": out_children,
+        }
+    finally:
+        try:
+            await client.close()
+        except Exception:
+            pass
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Browse OPC UA address space (read-only)")
+    parser.add_argument("--endpoint", default="", help="Full opc.tcp:// endpoint (overrides --ip)")
+    parser.add_argument("--ip", default="", help="Controller IP")
+    parser.add_argument("--port", type=int, default=4840, help="OPC UA port (default 4840)")
+    parser.add_argument("--node", default="", help="Node-id spec to browse (default Objects folder)")
+    parser.add_argument(
+        "--namespace",
+        type=int,
+        default=None,
+        help="Default namespace index for bare node specs (auto: Tags namespace, else 2)",
+    )
+    args = parser.parse_args()
+
+    endpoint = args.endpoint.strip() or default_endpoint(args.ip, args.port)
+    if not endpoint:
+        emit_error("Provide --endpoint or --ip.")
+
+    async def resolve_ns() -> int:
+        if args.namespace is not None:
+            return args.namespace
+        client = await connect(endpoint)
+        try:
+            return await tags_namespace_index(client) or 2
+        finally:
+            try:
+                await client.close()
+            except Exception:
+                pass
+
+    try:
+        ensure_asyncua()
+        default_ns = asyncio.run(resolve_ns())
+        result = asyncio.run(run(endpoint, args.node.strip(), default_ns))
+    except SystemExit:
+        raise
+    except Exception as exc:
+        emit_error(f"opcua_browse failed: {exc}")
+        return
+    emit(result)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/opcua_read.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Read one or many OPC UA nodes by node-id spec or tag path.
+
+Accepts:
+  --nodes "ns=2;s=MyTag,MyOtherTag"      (bare names use Tags namespace, ns=2)
+  --nodes-json '["ns=2;s=MyTag","MyDint"]'
+  --stdin                                 (JSON array of specs)
+
+Returns per-node value + status. Uses asyncua read for each node.
+
+Usage:
+  py -3.12 opcua_read.py --ip 10.1.200.45 --nodes "SafetyOneShot,IA000105"
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from typing import Any
+
+from _json_out import emit, emit_error
+from _opcua_client import (
+    connect,
+    default_endpoint,
+    ensure_asyncua,
+    jsonable,
+    parse_node_id,
+    tags_namespace_index,
+)
+
+
+async def read_one(client, spec: str, default_ns: int) -> dict:
+    from asyncua import ua
+
+    try:
+        node = client.get_node(parse_node_id(spec, default_ns))
+    except Exception as exc:
+        return {"node": spec, "ok": False, "value": None, "error": f"bad node id: {exc}"}
+    try:
+        val = await node.read_value()
+    except Exception as exc:
+        return {"node": spec, "ok": False, "value": None, "error": str(exc)}
+    out: dict[str, Any] = {"node": spec, "ok": True, "value": jsonable(val), "error": None}
+    try:
+        dt = await node.read_data_type()
+        out["data_type"] = str(dt)
+    except Exception:
+        pass
+    try:
+        # Source timestamp for diagnostics
+        ts = await node.read_attribute(ua.Attributes.SourceTimestamp)
+        out["source_timestamp"] = jsonable(ts.Value.Value if hasattr(ts, "Value") else None)
+    except Exception:
+        pass
+    return out
+
+
+async def run(endpoint: str, specs: list[str], default_ns: int) -> dict:
+    client = await connect(endpoint)
+    try:
+        results = []
+        for s in specs:
+            results.append(await read_one(client, s, default_ns))
+        ok = sum(1 for r in results if r["ok"])
+        return {
+            "ok": True,
+            "endpoint": endpoint,
+            "namespace": default_ns,
+            "requested": len(specs),
+            "succeeded": ok,
+            "failed": len(specs) - ok,
+            "results": results,
+        }
+    finally:
+        try:
+            await client.close()
+        except Exception:
+            pass
+
+
+def main() -> None:
+    import json
+    import sys
+
+    parser = argparse.ArgumentParser(description="Read OPC UA nodes (read-only)")
+    parser.add_argument("--endpoint", default="", help="Full opc.tcp:// endpoint (overrides --ip)")
+    parser.add_argument("--ip", default="", help="Controller IP")
+    parser.add_argument("--port", type=int, default=4840, help="OPC UA port (default 4840)")
+    parser.add_argument("--nodes", default="", help="Comma-separated node-id specs / tag names")
+    parser.add_argument("--nodes-json", default="", help="JSON array of node-id specs")
+    parser.add_argument("--stdin", action="store_true", help="Read JSON array from stdin")
+    parser.add_argument("--namespace", type=int, default=None, help="Default ns for bare names (auto)")
+    args = parser.parse_args()
+
+    endpoint = args.endpoint.strip() or default_endpoint(args.ip, args.port)
+    if not endpoint:
+        emit_error("Provide --endpoint or --ip.")
+
+    specs: list[str] = []
+    if args.stdin:
+        raw = sys.stdin.read().strip()
+        try:
+            parsed = json.loads(raw) if raw else []
+        except json.JSONDecodeError as exc:
+            emit_error(f"stdin is not valid JSON: {exc}")
+            return
+        if not isinstance(parsed, list):
+            emit_error("stdin JSON must be an array of node specs.")
+            return
+        specs = [str(x).strip() for x in parsed if str(x).strip()]
+    if args.nodes_json:
+        try:
+            parsed = json.loads(args.nodes_json)
+        except json.JSONDecodeError as exc:
+            emit_error(f"--nodes-json is not valid JSON: {exc}")
+            return
+        specs.extend(str(x).strip() for x in parsed if str(x).strip())
+    if args.nodes:
+        specs.extend(x.strip() for x in args.nodes.split(",") if x.strip())
+    specs = [s for s in specs if s]
+    if not specs:
+        emit_error("No node specs supplied. Use --nodes, --nodes-json, or --stdin.")
+
+    async def resolve_ns() -> int:
+        if args.namespace is not None:
+            return args.namespace
+        client = await connect(endpoint)
+        try:
+            return await tags_namespace_index(client) or 2
+        finally:
+            try:
+                await client.close()
+            except Exception:
+                pass
+
+    try:
+        ensure_asyncua()
+        default_ns = asyncio.run(resolve_ns())
+        result = asyncio.run(run(endpoint, specs, default_ns))
+    except SystemExit:
+        raise
+    except Exception as exc:
+        emit_error(f"opcua_read failed: {exc}")
+        return
+    emit(result)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/opcua_status.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Probe an OPC UA server: endpoints, security policies, namespaces, server state.
+
+Read-only. Use to confirm the server is reachable and discover the tags
+namespace index before browse/read/write.
+
+Usage:
+  py -3.12 opcua_status.py --endpoint opc.tcp://10.1.200.45:4840
+  py -3.12 opcua_status.py --ip 10.1.200.45
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+
+from _json_out import emit, emit_error
+from _opcua_client import (
+    connect,
+    default_endpoint,
+    ensure_asyncua,
+    namespaces,
+    tags_namespace_index,
+    jsonable,
+)
+
+
+async def run(endpoint: str) -> dict:
+    client = await connect(endpoint)
+    try:
+        # Endpoints + security policies
+        endpoints = []
+        try:
+            eps = await client.get_endpoints()
+            for ep in eps:
+                endpoints.append({
+                    "endpoint": str(ep.EndpointUrl),
+                    "security_policy": str(ep.SecurityPolicyUri),
+                    "security_mode": str(ep.SecurityMode),
+                    "transport": str(ep.TransportPolicyUri) if ep.TransportPolicyUri else None,
+                    "user_identity_tokens": [
+                        str(t.PolicyId) for t in (ep.UserIdentityTokens or [])
+                    ],
+                })
+        except Exception as exc:
+            endpoints = [{"error": str(exc)}]
+
+        # Server state / status
+        server_state = None
+        server_status = None
+        try:
+            svr = client.get_server_node()
+            server_state = jsonable(await svr.get_child(["0:ServerStatus"]))
+        except Exception:
+            pass
+        try:
+            state_node = client.get_node("i=2259")  # Server_ServerStatus
+            server_status = jsonable(await state_node.read_value())
+        except Exception as exc:
+            server_status = {"error": str(exc)}
+
+        ns = await namespaces(client)
+        tags_ns = await tags_namespace_index(client)
+
+        return {
+            "ok": True,
+            "endpoint": endpoint,
+            "connected": True,
+            "endpoints": endpoints,
+            "namespaces": ns,
+            "tags_namespace_index": tags_ns,
+            "server_status": server_status,
+            "server_state": server_state,
+        }
+    finally:
+        try:
+            await client.close()
+        except Exception:
+            pass
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Probe an OPC UA server (read-only)")
+    parser.add_argument("--endpoint", default="", help="Full opc.tcp:// endpoint (overrides --ip)")
+    parser.add_argument("--ip", default="", help="Controller IP (default endpoint opc.tcp://IP:4840)")
+    parser.add_argument("--port", type=int, default=4840, help="OPC UA port (default 4840)")
+    args = parser.parse_args()
+
+    endpoint = args.endpoint.strip() or default_endpoint(args.ip, args.port)
+    if not endpoint:
+        emit_error("Provide --endpoint or --ip.")
+    try:
+        ensure_asyncua()
+        result = asyncio.run(run(endpoint))
+    except Exception as exc:
+        emit_error(f"opcua_status failed: {exc}")
+        return
+    emit(result)
+
+
+if __name__ == "__main__":
+    main()