@codesys/mcp-toolkit 2.2.0 → 2.3.0

package/watcher/mcp_devices.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+# Devices from CODESYS's device repository: search the installed device
+# descriptions (fieldbus masters and slaves, I/O modules) and add or plug one into
+# the device tree. Documented scripting API (device_repository, ScriptDeviceObject).
+# Offline only: nothing here goes online.
+#
+# Keep this file ASCII-only (IronPython 2.7 inside CODESYS).
+import mcp_ops
+import mcp_sim
+from mcp_ops import Ctx, OpError, _safe
+from mcp_compat import to_text
+
+import scriptengine as se
+
+
+def _desc(d):
+    did = _safe(lambda: d.device_id)
+    out = {
+        "name": to_text(_safe(lambda: d.name, "")),
+        "vendor": to_text(_safe(lambda: d.vendor, "")),
+        "description": to_text(_safe(lambda: d.description, "") or "")[:200],
+    }
+    if did is not None:
+        out["type"] = int(_safe(lambda: did.type, 0))
+        out["id"] = to_text(_safe(lambda: did.id, ""))
+        out["version"] = to_text(_safe(lambda: did.version, ""))
+    order = _safe(lambda: d.order_number)
+    if order:
+        out["order_number"] = to_text(order)
+    return out
+
+
+def op_devices_search(args):
+    repo = _safe(lambda: se.device_repository)
+    if repo is None:
+        raise OpError("unavailable", "This CODESYS has no device repository in scripting.")
+    text = args.get("text") or ""
+    found = repo.get_all_devices(name=text, source=None)
+    out = []
+    for d in found or []:
+        full = d
+        if not to_text(_safe(lambda: d.name, "") or ""):
+            did = _safe(lambda: d.device_id)
+            full = (_safe(lambda: repo.get_device(did)) if did is not None else None) or d
+        item = _desc(full)
+        if not item["name"]:
+            info = _safe(lambda: full.device_info)
+            item["name"] = to_text(_safe(lambda: info.name, "") or "")
+            item["vendor"] = item["vendor"] or to_text(_safe(lambda: info.vendor, "") or "")
+            item["description"] = item["description"] or to_text(_safe(lambda: info.description, "") or "")[:200]
+        out.append(item)
+        if len(out) >= int(args.get("limit") or 40):
+            break
+    return {"devices": out, "more": len(found or []) > len(out)}
+
+
+def op_devices_add(args):
+    c = Ctx()
+    parent = c.resolve(args["parent"])
+    if not _safe(lambda: parent.is_device, False):
+        raise OpError("bad_path", "%s is not a device (add devices under a device or a connector's device, e.g. '/Device')." % args["parent"])
+    how = args.get("how") or "add"
+    module = args.get("module")
+    if how == "plug":
+        parent.plug(args["name"], int(args["type"]), args["id"], args["version"], module)
+        dev = parent
+    else:
+        fn = parent.add if how == "add" else parent.insert
+        if how == "insert":
+            parent.insert(args["name"], int(args.get("index") or 0), int(args["type"]), args["id"], args["version"], module)
+        else:
+            fn(args["name"], int(args["type"]), args["id"], args["version"], module)
+        dev = None
+        for ch in parent.get_children(False):
+            if to_text(_safe(lambda: ch.get_name(), "")).lower() == args["name"].lower():
+                dev = ch
+        if dev is None:
+            raise OpError("codesys_error", "CODESYS added nothing named %s under %s." % (args["name"], args["parent"]))
+    return {"path": c.path_of(dev), "saved": c.save_if(args)}
+
+
+mcp_ops.OPS["devices.search"] = op_devices_search
+mcp_ops.OPS["devices.add"] = mcp_sim._locked(op_devices_add)

package/watcher/mcp_lang.py

@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+# What CODESYS's compiler knows about the code: the interface of any POU or type
+# (including FBs from compiled libraries, which the scripting API can't read),
+# and cross-references (where a name is read, written or called).
+#
+# Both use CODESYS's own services, reached through a plugin's APEnvironment:
+# LanguageModelMgr.FindSignaturesByName and CrossReferenceService. They work on the
+# compiled language model, so the application is built first when nothing is found.
+#
+# Keep this file ASCII-only (IronPython 2.7 inside CODESYS).
+import mcp_ops
+from mcp_ops import Ctx, OpError
+from mcp_compat import to_text
+
+_ENVS = ("_3S.CoDeSys.RecipeManObject.APEnvironment", "_3S.CoDeSys.VisualEditor.APEnvironment", "_3S.CoDeSys.SecurityManager.APEnvironment")
+_CACHE = {}
+
+
+def _find_type(name):
+    if name in _CACHE:
+        return _CACHE[name]
+    try:
+        from System import AppDomain
+    except ImportError:
+        raise OpError("unavailable", "CODESYS's language services need CODESYS (not available in this engine).")
+    found = None
+    for asm in AppDomain.CurrentDomain.GetAssemblies():
+        try:
+            found = asm.GetType(name)
+        except Exception:
+            found = None
+        if found is not None:
+            break
+    _CACHE[name] = found
+    return found
+
+
+def _service(prop):
+    try:
+        from System.Reflection import BindingFlags
+    except ImportError:
+        raise OpError("unavailable", "CODESYS's language services need CODESYS (not available in this engine).")
+    for tname in _ENVS:
+        t = _find_type(tname)
+        if t is None:
+            continue
+        p = t.GetProperty(prop, BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static)
+        if p is not None:
+            v = p.GetValue(None, None)
+            if v is not None:
+                return v
+    raise OpError("unavailable", "This CODESYS doesn't offer %s to scripts." % prop)
+
+
+def _get(o, name, default=None):
+    try:
+        return getattr(o, name)
+    except Exception:
+        try:
+            t = o.GetType()
+            for it in [t] + list(t.GetInterfaces()):
+                p = it.GetProperty(name)
+                if p is not None:
+                    return p.GetValue(o, None)
+        except Exception:
+            pass
+    return default
+
+
+def _caller(c):
+    """A POU of the application to resolve names from (its scope sees the libraries)."""
+    for ch in c.app.get_children(True):
+        try:
+            if ch.has_textual_declaration and "PROGRAM" in to_text(ch.textual_declaration.text).upper()[:200]:
+                return ch
+        except Exception:
+            pass
+    return c.app
+
+
+def _clean(s):
+    s = to_text(s or "").strip()
+    return " ".join(s.split()) if s else ""
+
+
+def _var(v, section):
+    attrs = [to_text(a) for a in (_get(v, "Attributes") or [])]
+    out = {"name": to_text(_get(v, "OrgName") or _get(v, "Name")), "type": to_text(_get(v, "Type")), "section": section}
+    comment = _clean(_get(v, "Comment")).lstrip("| ").strip()
+    if comment:
+        out["comment"] = comment
+    if "hide" in attrs:
+        out["hidden"] = True
+    init = _get(v, "Initial")
+    if init is not None:
+        out["init"] = to_text(init)
+    return out
+
+
+def _signature(lmm, c, sig):
+    ins = set(to_text(_get(v, "OrgName")) for v in (_get(sig, "Inputs") or []))
+    outs = set(to_text(_get(v, "OrgName")) for v in (_get(sig, "Outputs") or []))
+    variables = []
+    for v in lmm.GetAllVariables(sig, c.app.guid):
+        n = to_text(_get(v, "OrgName"))
+        variables.append(_var(v, "input" if n in ins else "output" if n in outs else "other"))
+    subs = []
+    try:
+        for s in sig.GetSubSignatures() or []:
+            subs.append(to_text(_get(s, "OrgName") or _get(s, "Name")))
+    except Exception:
+        pass
+    return {
+        "name": to_text(_get(sig, "OrgName") or _get(sig, "Name")),
+        "kind": to_text(_get(sig, "POUType")),
+        "library": to_text(_get(sig, "LibraryPath") or ""),
+        "comment": _clean(_get(sig, "Comment")),
+        "variables": variables,
+        "members": subs,
+    }
+
+
+def op_lang_signature(args):
+    c = Ctx()
+    lmm = _service("LanguageModelMgr")
+    caller = _caller(c)
+    built = False
+    out = []
+    for name in args["names"]:
+        sigs = lmm.FindSignaturesByName(c.proj.handle, c.app.guid, caller.guid, name)
+        if (sigs is None or len(sigs) == 0) and not built:
+            c.app.build()
+            built = True
+            sigs = lmm.FindSignaturesByName(c.proj.handle, c.app.guid, caller.guid, name)
+        if sigs is None or len(sigs) == 0:
+            out.append({"name": name, "error": "not found (check the spelling, and that the library is referenced)"})
+            continue
+        out.append(_signature(lmm, c, sigs[0]))
+    return {"signatures": out, "built": built}
+
+
+def op_lang_xref(args):
+    import System
+    from System import Guid
+    c = Ctx()
+    xs = _service("CrossReferenceService")
+    T = _find_type("_3S.CoDeSys.LanguageModelUtilities.CrossRefSearchType")
+    O = _find_type("_3S.CoDeSys.LanguageModelUtilities.CrossRefOccurence")
+    M = _find_type("_3S.CoDeSys.LanguageModelUtilities.CrossReferenceMatchType")
+    if T is None or O is None or M is None:
+        raise OpError("unavailable", "This CODESYS doesn't offer cross-references to scripts.")
+    if args.get("build", True):
+        c.app.build()
+    kind = {"variable": "Variables", "pou": "POUs", "type": "Types"}.get(args.get("kind") or "variable", "Variables")
+    try:
+        st = System.Enum.Parse(T, kind)
+    except Exception:
+        st = System.Enum.Parse(T, "Variables")
+    nodes = xs.GetCrossReferenceNodesWithinApplication(args["name"], "", Guid.Empty, st, System.Enum.Parse(O, "LanguageModel"), System.Enum.Parse(M, "Existing"), c.app.guid)
+    refs = []
+    for nd in nodes or []:
+        pos = _get(nd, "Position", 0) or 0
+        try:
+            pos = int(pos)
+        except Exception:
+            pos = 0
+        refs.append({
+            "access": to_text(_get(nd, "AccessText") or ""),
+            "pou": to_text(_get(nd, "POUName") or ""),
+            "location": to_text(_get(nd, "Location") or ""),
+            "text": _clean(_get(nd, "Text")),
+        })
+    return {"name": args["name"], "references": refs}
+
+
+mcp_ops.OPS.update({
+    "lang.signature": op_lang_signature,
+    "lang.xref": op_lang_xref,
+})

package/watcher/mcp_ops.py

@@ -542,6 +542,8 @@ def op_object_create(args):
         obj = parent.create_dut(name, dt)
     elif kind == "gvl":
         obj = parent.create_gvl(name)
+    elif kind == "persistent_vars":
+        obj = parent.create_persistentvars(name)
     elif kind == "folder":
         obj = parent.create_folder(name)
     else:
@@ -1097,7 +1099,7 @@ def _reflect_api(path):
 def op_api_probe(args):
     """The scripting API this CODESYS offers: member names of the main objects, the
     enums the watcher relies on, version-like values, and the object type GUIDs of
-    the open project with their kinds. For comparing service packs (docs/sp22-plan.md)."""
+    the open project with their kinds. For comparing service packs (docs/codesys-api-sp21-sp22.md)."""
     c = Ctx(require_project=False)
     objs = {"se": se, "system": _safe(lambda: se.system), "projects": _safe(lambda: se.projects), "project": c.proj, "application": c.app}
     samples = {}

package/watcher/mcp_trace.py

@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+# CODESYS Trace in the simulation: a trace object records variables every cycle of a
+# task; the data comes back as a table. Uses CODESYS's trace script driver
+# (se.trace.create, open_editor().download/start/save), only while CODESYS's own
+# simulation runs (mcp_sim checks the device is in simulation mode).
+#
+# Keep this file ASCII-only (IronPython 2.7 inside CODESYS).
+import os
+
+import mcp_ops
+import mcp_sim
+from mcp_ops import Ctx, OpError, name_of
+
+
+import scriptengine as se
+
+
+def _find(c, name):
+    for ch in c.app.get_children(True):
+        if name_of(ch).lower() == name.lower():
+            return ch
+    return None
+
+
+def _first_task(c):
+    for ch in c.app.get_children(True):
+        try:
+            if ch.is_task:
+                return ch
+        except Exception:
+            pass
+    return None
+
+
+def op_trace_setup(args):
+    c = Ctx()
+    if not hasattr(se, "trace"):
+        raise OpError("unavailable", "This CODESYS has no trace scripting.")
+    name = args["name"]
+    old = _find(c, name)
+    if old is not None:
+        old.remove()
+    task = args.get("task")
+    if not task:
+        t = _first_task(c)
+        if t is None:
+            raise OpError("not_found", "The application has no task to record in.")
+        task = name_of(t)
+    tr = se.trace.create(c.app, name, task)
+    for v in args["variables"]:
+        tv = tr.variable_list.add()
+        tv.variable_name = v
+    if args.get("every_n_cycles"):
+        try:
+            tr.every_n_cycles = int(args["every_n_cycles"])
+        except Exception:
+            pass
+    return {"name": name, "task": task, "variables": list(args["variables"]), "saved": c.save_if(args)}
+
+
+def op_trace_record(args):
+    c = Ctx()
+    mcp_sim._online()  # raises unless the simulation runs
+    obj = _find(c, args["name"])
+    if obj is None:
+        raise OpError("not_found", "No trace named %s. Set it up with trace_setup before starting the simulation." % args["name"])
+    if not hasattr(obj, "open_editor"):
+        raise OpError("unavailable", "%s is not a trace this CODESYS can record from a script." % args["name"])
+    ed = obj.open_editor()
+    ed.download()
+    ed.start()
+    mcp_sim._pause(int(args.get("ms") or 3000))
+    path = args["path"]
+    folder = os.path.dirname(path)
+    if folder and not os.path.isdir(folder):
+        os.makedirs(folder)
+    ed.save(path)
+    try:
+        ed.stop()
+    except Exception:
+        pass
+    return {"path": path}
+
+
+mcp_ops.OPS["trace.setup"] = mcp_sim._locked(op_trace_setup)
+mcp_ops.OPS["trace.record"] = op_trace_record
+# The visualization builder changes the project too: not while the simulation runs.
+for _op in ("visu.build", "visu.manager"):
+    if _op in mcp_ops.OPS:
+        mcp_ops.OPS[_op] = mcp_sim._locked(mcp_ops.OPS[_op])

package/watcher/mcp_ui.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+# --show-window extras: open the object a request just wrote in a CODESYS editor tab, so
+# the user sees the code arrive in the window instead of only the project tree.
+#
+# CODESYS's scripting API has no call for this. It uses CODESYS's own (undocumented) .NET
+# frame instead: IFrame.OpenEditorView, the call behind "Edit Object". Checked on CODESYS
+# V3.5 SP21 and SP22. Best-effort: a failure is only logged and never changes a result.
+#
+# Keep this file ASCII-only (IronPython 2.7 inside CODESYS).
+
+_CACHE = {}
+
+# Any plugin's APEnvironment exposes the engine (with its frame) and the object manager.
+_ENV_TYPES = ("_3S.CoDeSys.SecurityManager.APEnvironment", "_3S.CoDeSys.VisualEditor.APEnvironment")
+
+
+def _find_env():
+    from System import AppDomain
+    asms = list(AppDomain.CurrentDomain.GetAssemblies())
+    for name in _ENV_TYPES:
+        for asm in asms:
+            try:
+                t = asm.GetType(name)
+            except Exception:
+                t = None
+            if t is not None:
+                return t
+    return None
+
+
+def _env():
+    if "env" not in _CACHE:
+        try:
+            _CACHE["env"] = _find_env()
+        except Exception:
+            _CACHE["env"] = None
+    return _CACHE["env"]
+
+
+def open_editor(se, obj):
+    """Opens obj in its editor in the CODESYS window (or brings its tab forward).
+
+    Returns "opened", "fake" (the test engine) or "unavailable" (no frame found)."""
+    if hasattr(se, "FAKE"):
+        return "fake"
+    env = _env()
+    if env is None:
+        return "unavailable"
+    from System import Guid
+    engine = env.GetProperty("Engine").GetValue(None, None)
+    objects = env.GetProperty("ObjectMgr").GetValue(None, None)
+    stub = objects.GetMetaObjectStub(se.projects.primary.handle, obj.guid)
+    engine.Frame.OpenEditorView(stub, Guid.Empty, None)
+    return "opened"