sylo-plc-comms 0.1.0

package/scripts/opcua_tag_list.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""List OPC UA tags by recursively browsing the controller's Tags namespace.
+
+Read-only. Starts from the Objects folder and collects every Variable node
+whose NodeId is in the Tags namespace (Rockwell ns=2). Struct members and
+array elements appear as nested children and are flattened into a 'path'.
+
+Limits: --max-depth (default 4) and --max-nodes (default 2000) protect against
+runaway browse on large controllers.
+
+Usage:
+  py -3.12 opcua_tag_list.py --ip 10.1.200.45
+  py -3.12 opcua_tag_list.py --ip 10.1.200.45 --filter IA00 --max-nodes 500
+"""
+
+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,
+    tags_namespace_index,
+)
+
+
+async def collect(
+    node,
+    tags_ns: int,
+    path: list[str],
+    depth: int,
+    max_depth: int,
+    max_nodes: int,
+    flt: str,
+    out: list[dict],
+) -> None:
+    if len(out) >= max_nodes:
+        return
+    from asyncua import ua
+
+    node_id = node.nodeid
+    ns_idx = getattr(node_id, "NamespaceIndex", None)
+    try:
+        nc = await node.read_node_class()
+    except Exception:
+        nc = None
+    try:
+        bn = await node.read_browse_name()
+        bn_str = str(bn)
+    except Exception:
+        bn_str = str(node_id)
+    try:
+        dn = await node.read_display_name()
+        dn_str = str(dn)
+    except Exception:
+        dn_str = bn_str
+
+    cur_path = path + [bn_str]
+
+    # Only collect Variable nodes in the tags namespace
+    is_var = nc is not None and "Variable" in str(nc)
+    if is_var and ns_idx == tags_ns:
+        entry: dict[str, Any] = {
+            "node_id": str(node_id),
+            "browse_path": ".".join(cur_path),
+            "display_name": dn_str,
+            "node_class": str(nc),
+        }
+        try:
+            dt = await node.read_data_type()
+            entry["data_type"] = str(dt)
+        except Exception:
+            entry["data_type"] = None
+        try:
+            entry["value_rank"] = await node.read_value_rank()
+        except Exception:
+            pass
+        try:
+            # array dimensions
+            dims = await node.read_attribute(ua.Attributes.ArrayDimensions)
+            entry["array_dimensions"] = jsonable(dims.Value.Value if hasattr(dims, "Value") else None)
+        except Exception:
+            pass
+        # Identifier string (the tag path) for ns=2 string node ids
+        ident = getattr(node_id, "Identifier", None)
+        entry["tag"] = str(ident) if isinstance(ident, str) else None
+        if (not flt) or flt in (entry["tag"] or "").lower() or flt in bn_str.lower():
+            out.append(entry)
+        if len(out) >= max_nodes:
+            return
+
+    if depth >= max_depth:
+        return
+    try:
+        children = await node.get_children()
+    except Exception:
+        return
+    for ch in children:
+        await collect(ch, tags_ns, cur_path, depth + 1, max_depth, max_nodes, flt, out)
+        if len(out) >= max_nodes:
+            return
+
+
+async def run(endpoint: str, flt: str, max_depth: int, max_nodes: int) -> dict:
+    from asyncua import ua
+
+    client = await connect(endpoint)
+    try:
+        tags_ns = await tags_namespace_index(client)
+        if tags_ns is None:
+            emit_error("Could not determine the Tags namespace index on this server.")
+        root = client.get_node(ua.ObjectIds.ObjectsFolder)
+        out: list[dict] = []
+        await collect(root, tags_ns, [], 0, max_depth, max_nodes, flt, out)
+        return {
+            "ok": True,
+            "endpoint": endpoint,
+            "tags_namespace_index": tags_ns,
+            "tag_count": len(out),
+            "truncated": len(out) >= max_nodes,
+            "tags": out,
+        }
+    finally:
+        try:
+            await client.close()
+        except Exception:
+            pass
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="List OPC UA tags (browse Tags namespace)")
+    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("--filter", default="", help="Case-insensitive substring filter on tag/browse name")
+    parser.add_argument("--max-depth", type=int, default=4, help="Max browse depth (default 4)")
+    parser.add_argument("--max-nodes", type=int, default=2000, help="Cap on collected tag nodes (default 2000)")
+    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, args.filter.strip().lower(), args.max_depth, args.max_nodes))
+    except SystemExit:
+        raise
+    except Exception as exc:
+        emit_error(f"opcua_tag_list failed: {exc}")
+        return
+    emit(result)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/opcua_write.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Write one or many OPC UA nodes by node-id spec or tag path.
+
+GATED by the operator-managed download allowlist: the endpoint host IP must be
+present and enabled. Reuses the same allowlist as CIP project downloads / tag
+writes. The agent cannot write to a PLC not on the list, even with permission.
+
+Inputs: a JSON array of objects on stdin / --writes-json, each:
+  {"node": "ns=2;s=MyTag", "value": 42, "variant_type": "Int32"}
+  {"node": "MyTag", "value": true}            # bare name -> Tags ns; type inferred
+variant_type is optional; when omitted asyncua infers from the Python value
+(works for bool/int/float/str scalars). For arrays pass a list value and the
+node's existing array type is used.
+
+Usage:
+  echo '[{"node":"SafetyOneShot","value":7,"variant_type":"Int32"}]' | \
+    py -3.12 opcua_write.py --ip 10.1.200.45 --stdin
+  py -3.12 opcua_write.py --ip 10.1.200.45 --node SafetyOneShot --value 7 --variant-type Int32
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from typing import Any
+from urllib.parse import urlparse
+
+from _download_allowlist import load_allowlist
+from _json_out import emit, emit_error
+from _opcua_client import connect, default_endpoint, ensure_asyncua, jsonable, parse_node_id, tags_namespace_index
+
+
+def _host_ip(endpoint: str) -> str:
+    try:
+        return urlparse(endpoint).hostname or ""
+    except Exception:
+        return ""
+
+
+def _ip_allowed(ip: str) -> tuple[bool, str]:
+    if not ip:
+        return False, "Could not determine host IP from endpoint for allowlist check."
+    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 OPC UA tags to it."
+
+
+def _variant(value: Any, variant_type: str | None):
+    """Build an asyncua ua.Variant if variant_type is given, else return raw value."""
+    from asyncua import ua
+
+    if not variant_type:
+        return value
+    vt = getattr(ua.VariantType, variant_type, None)
+    if vt is None:
+        raise ValueError(f"Unknown VariantType: {variant_type}")
+    return ua.Variant(value, vt)
+
+
+async def write_one(client, spec: str, value: Any, variant_type: str | None, default_ns: int) -> dict:
+    try:
+        node = client.get_node(parse_node_id(spec, default_ns))
+    except Exception as exc:
+        return {"node": spec, "ok": False, "error": f"bad node id: {exc}"}
+    try:
+        var = _variant(value, variant_type)
+    except Exception as exc:
+        return {"node": spec, "ok": False, "error": str(exc)}
+    try:
+        await node.write_value(var)
+    except Exception as exc:
+        return {"node": spec, "ok": False, "error": str(exc)}
+    # Read-back for confirmation
+    readback = None
+    try:
+        readback = jsonable(await node.read_value())
+    except Exception:
+        pass
+    return {"node": spec, "ok": True, "error": None, "written": jsonable(value), "readback": readback}
+
+
+async def run(endpoint: str, writes: list[dict], default_ns: int) -> dict:
+    client = await connect(endpoint)
+    try:
+        results = []
+        for w in writes:
+            spec = str(w.get("node", "")).strip()
+            value = w.get("value")
+            vt = w.get("variant_type")
+            results.append(await write_one(client, spec, value, vt, default_ns))
+        ok = sum(1 for r in results if r["ok"])
+        return {
+            "ok": True,
+            "endpoint": endpoint,
+            "namespace": default_ns,
+            "requested": len(writes),
+            "succeeded": ok,
+            "failed": len(writes) - ok,
+            "results": results,
+        }
+    finally:
+        try:
+            await client.close()
+        except Exception:
+            pass
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Write OPC UA nodes (allowlist-gated)")
+    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="Single node spec (paired with --value)")
+    parser.add_argument("--value", default="", help="Single value (JSON-parsed if possible)")
+    parser.add_argument("--variant-type", default="", help="asyncua VariantType name (e.g. Int32, Boolean)")
+    parser.add_argument("--writes-json", default="", help="JSON array of {node,value,variant_type?}")
+    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)")
+    parser.add_argument("--dry-run", action="store_true", help="Validate writes but do not send")
+    args = parser.parse_args()
+
+    endpoint = args.endpoint.strip() or default_endpoint(args.ip, args.port)
+    if not endpoint:
+        emit_error("Provide --endpoint or --ip.")
+
+    allowed, reason = _ip_allowed(_host_ip(endpoint))
+    if not allowed:
+        emit_error(reason)
+
+    writes: list[dict] = []
+    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,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.node:
+        vraw = args.value
+        try:
+            val = json.loads(vraw) if vraw != "" else None
+        except json.JSONDecodeError:
+            val = vraw
+        writes.append({
+            "node": args.node,
+            "value": val,
+            "variant_type": (args.variant_type.strip() or None),
+        })
+
+    clean: list[dict] = []
+    for w in writes:
+        if not isinstance(w, dict) or not w.get("node"):
+            emit_error("Each write must be an object with a 'node' field.")
+            return
+        clean.append({
+            "node": str(w["node"]).strip(),
+            "value": w.get("value"),
+            "variant_type": (str(w.get("variant_type", "")).strip() or None) if w.get("variant_type") else None,
+        })
+    if not clean:
+        emit_error("No writes supplied. Use --node/--value, --writes-json, or --stdin.")
+
+    if args.dry_run:
+        emit({"ok": True, "endpoint": endpoint, "dry_run": True, "writes": clean})
+        return
+
+    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, clean, default_ns))
+    except SystemExit:
+        raise
+    except Exception as exc:
+        emit_error(f"opcua_write failed: {exc}")
+        return
+    emit(result)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/requirements.txt

@@ -0,0 +1,3 @@
+# sylo-plc-comms — CIP (ciplogix vendored wheel) + OPC UA (asyncua)
+# ciplogix installs from vendor/ciplogix/*.whl on demand; asyncua pip-installs on demand.
+asyncua>=2.0.0

package/vendor/ciplogix/README.md

@@ -0,0 +1,38 @@
+# ciplogix (vendored)
+
+Lightweight Allen-Bradley PLC communication over Ethernet/IP — a hardened fork of
+**pycomm3** used by LogicForge for **controller status / keyswitch reads** in the
+Download settings UI and the pre-download state check in `sdk_download_to_plc.py`.
+
+- **Source:** https://github.com/Yeti-Trix/ciplogix
+- **Wheel:** `ciplogix-1.1.0-py3-none-any.whl`
+- **License:** MIT (see upstream repo)
+- **Author:** Spencer Current (Yeti-Trix), built on pycomm3 by Ian Ottoway
+
+## Why it's here
+
+The Logix Designer SDK is heavy and requires opening a full `.acd` project just to
+ask a controller "are you there and what mode are you in." ciplogix answers that in
+one CIP Identity request (`get_plc_info()` → `info["keyswitch"]`), which is what
+the Download settings status column and the download pre-check use.
+
+The SDK is still the engine for the actual **download** (project push to
+controller). ciplogix is only used for **read-only status/mode**.
+
+## Install (handled by scripts)
+
+`plc_status.py` and `sdk_download_to_plc.py` pip-install this wheel into the
+SDK Python (3.12) on first run if `ciplogix` isn't importable. Its dependency
+`pycomm3` is pulled from PyPI automatically.
+
+## Keyswitch values
+
+`get_plc_info()["keyswitch"]` returns one of (Rockwell KB #28917):
+
+| Value           | Key position | Mode   |
+|-----------------|--------------|--------|
+| `REMOTE RUN`    | REM          | Run    |
+| `REMOTE PROG`   | REM          | Program|
+| `RUN`           | RUN (hard)   | Run    |
+| `PROG`          | PROG (hard)  | Program|
+| `UNKNOWN`       | —            | —      |