opcua-tagmap 0.2.0__py3-none-any.whl

opcua_tagmap/browse.py

@@ -0,0 +1,128 @@
+"""Walk an OPC UA server's address space and collect its variables.
+
+All protocol work is asyncua's. This module only decides where to descend,
+when to stop, and what to record.
+"""
+
+import asyncio
+from typing import Iterable
+
+from asyncua import Client, ua
+
+from .model import TagNode
+
+DEFAULT_MAX_DEPTH = 12
+DEFAULT_MAX_NODES = 10_000
+
+# NodeId encodings, as the rest of the world writes them in config files.
+_ID_TYPE = {
+    ua.NodeIdType.Numeric: "i",
+    ua.NodeIdType.String: "s",
+    ua.NodeIdType.Guid: "g",
+    ua.NodeIdType.ByteString: "b",
+    ua.NodeIdType.TwoByte: "i",
+    ua.NodeIdType.FourByte: "i",
+}
+
+
+class BrowseResult:
+    def __init__(self, tags: list[TagNode], errors: list[str], truncated: bool):
+        self.tags = tags
+        self.errors = errors
+        self.truncated = truncated
+
+
+async def _read_datatype(node) -> str:
+    try:
+        variant = await node.read_data_type_as_variant_type()
+        return variant.name
+    except Exception:
+        return "Unknown"
+
+
+async def _walk(node, path: str, depth: int, state: dict, refs=ua.ObjectIds.HierarchicalReferences) -> None:
+    if depth > state["max_depth"] or len(state["tags"]) >= state["max_nodes"]:
+        if len(state["tags"]) >= state["max_nodes"]:
+            state["truncated"] = True
+        return
+
+    try:
+        children = await node.get_children(refs=refs)
+    except Exception as e:
+        # A permission error part-way down a real server must not abort the
+        # whole browse — record it and carry on with the rest of the tree.
+        state["errors"].append(f"{path}: {e}")
+        return
+
+    for child in children:
+        # Namespace 0 is reserved for the OPC UA standard: the Server object
+        # alone carries ~250 diagnostic nodes (MaxSessions, ServerCapabilities,
+        # RedundancySupport...). Machine tags always live in ns>=1, so without
+        # this the real tags are buried. --include-standard opts back in.
+        if state["skip_standard"] and child.nodeid.NamespaceIndex == 0:
+            continue
+
+        try:
+            name = (await child.read_browse_name()).Name
+            node_class = await child.read_node_class()
+        except Exception as e:
+            state["errors"].append(f"{path}: {e}")
+            continue
+
+        child_path = f"{path}/{name}"
+
+        if node_class == ua.NodeClass.Variable:
+            if len(state["tags"]) >= state["max_nodes"]:
+                state["truncated"] = True
+                return
+            nid = child.nodeid
+            state["tags"].append(TagNode(
+                browse_path=child_path,
+                display_name=name,
+                namespace=nid.NamespaceIndex,
+                identifier_type=_ID_TYPE.get(nid.NodeIdType, "s"),
+                identifier=str(nid.Identifier),
+                datatype=await _read_datatype(child),
+            ))
+            # A structured variable carries its members as component variables (this is how an
+            # S7-1500 or a CODESYS controller exposes a STRUCT or an array of STRUCT). Follow
+            # HasComponent only: properties such as EURange describe the variable, they are not tags.
+            await _walk(child, child_path, depth + 1, state, refs=ua.ObjectIds.HasComponent)
+        elif node_class == ua.NodeClass.Object:
+            await _walk(child, child_path, depth + 1, state)
+
+
+async def browse(endpoint: str,
+                 root: str | None = None,
+                 max_depth: int = DEFAULT_MAX_DEPTH,
+                 max_nodes: int = DEFAULT_MAX_NODES,
+                 timeout: float = 10.0,
+                 skip_standard: bool = True) -> BrowseResult:
+    """Collect every Variable under `root` (default: the Objects folder).
+
+    `root` may be a NodeId string such as "ns=2;s=ProtectionPanel" to start
+    part-way down a large server.
+
+    `skip_standard` drops the OPC UA standard namespace (ns=0), which is what
+    makes the output about the machine rather than about the server.
+    """
+    state = {"tags": [], "errors": [], "truncated": False,
+             "max_depth": max_depth, "max_nodes": max_nodes,
+             "skip_standard": skip_standard}
+
+    client = Client(url=endpoint, timeout=timeout)
+    async with client:
+        if root:
+            start = client.get_node(root)
+            start_path = (await start.read_browse_name()).Name
+        else:
+            start = client.nodes.objects
+            start_path = "Objects"
+        await _walk(start, start_path, 0, state)
+
+    state["tags"].sort(key=lambda t: t.browse_path)
+    return BrowseResult(state["tags"], state["errors"], state["truncated"])
+
+
+def browse_sync(*args, **kwargs) -> BrowseResult:
+    return asyncio.run(browse(*args, **kwargs))

opcua_tagmap/cli.py

@@ -0,0 +1,150 @@
+"""Command line entry point.
+
+    opcua-tagmap browse opc.tcp://plc:4840
+    opcua-tagmap gen telegraf opc.tcp://plc:4840 --include 'Objects/Plant1/*/MV*'
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .browse import DEFAULT_MAX_DEPTH, DEFAULT_MAX_NODES, browse_sync
+from .emit import table, telegraf, testcases
+from .globmatch import filter_tags
+
+
+def _add_common(parser: argparse.ArgumentParser, with_out: bool = True) -> None:
+    parser.add_argument("endpoint", help="opc.tcp://host:port/path")
+    parser.add_argument("--root", default=None,
+                        help='start below this NodeId, e.g. "ns=2;s=Plant1"')
+    parser.add_argument("--include", action="append", default=[], metavar="GLOB",
+                        help="keep browse paths matching this pattern (repeatable)")
+    parser.add_argument("--exclude", action="append", default=[], metavar="GLOB",
+                        help="drop browse paths matching this pattern (repeatable)")
+    parser.add_argument("--max-depth", type=int, default=DEFAULT_MAX_DEPTH)
+    parser.add_argument("--max-nodes", type=int, default=DEFAULT_MAX_NODES)
+    parser.add_argument("--timeout", type=float, default=10.0)
+    parser.add_argument("--include-standard", action="store_true",
+                        help="also include the OPC UA standard namespace "
+                             "(ns=0) — the server's own diagnostic tree, "
+                             "roughly 250 nodes, excluded by default")
+    if with_out:
+        parser.add_argument("--out", default=None,
+                            help="write here instead of stdout")
+
+
+def _collect(args):
+    """Browse, filter, and fail loudly if nothing survived."""
+    result = browse_sync(args.endpoint, root=args.root,
+                         max_depth=args.max_depth, max_nodes=args.max_nodes,
+                         timeout=args.timeout,
+                         skip_standard=not args.include_standard)
+
+    for err in result.errors:
+        print(f"warning: could not browse {err}", file=sys.stderr)
+    if result.truncated:
+        print(f"warning: stopped at --max-nodes {args.max_nodes}; "
+              "output is incomplete", file=sys.stderr)
+
+    tags = filter_tags(result.tags, args.include, args.exclude)
+
+    if not tags:
+        # Emitting an empty config would look like success and silently
+        # collect nothing. Say so and exit non-zero.
+        if result.tags and (args.include or args.exclude):
+            print(f"error: no nodes matched. {len(result.tags)} variable(s) "
+                  "found on the server but every one was filtered out.",
+                  file=sys.stderr)
+        else:
+            print("error: no variables found on the server.", file=sys.stderr)
+        sys.exit(1)
+
+    return tags
+
+
+def _write(text: str, out: str | None) -> None:
+    if out:
+        Path(out).write_text(text, encoding="utf-8")
+        print(f"wrote {out}", file=sys.stderr)
+    else:
+        sys.stdout.write(text)
+
+
+def _write_testcases(tags, args) -> int:
+    """Write one stub per numeric tag, never clobbering filled-in work."""
+    stubs, skipped = testcases.plan(tags, args.endpoint)
+
+    for tag, reason in skipped:
+        print(f"skipped {tag.display_name}: {reason}", file=sys.stderr)
+
+    if not stubs:
+        print("error: no numeric variables among the matched tags, so there "
+              "is nothing a min/max spec could check.", file=sys.stderr)
+        return 1
+
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    written = kept = 0
+    for filename, text in stubs:
+        path = out_dir / filename
+        if path.exists() and not args.overwrite:
+            kept += 1
+            continue
+        path.write_text(text, encoding="utf-8")
+        written += 1
+
+    print(f"wrote {written} stub(s) to {out_dir}/", file=sys.stderr)
+    if kept:
+        print(f"left {kept} existing file(s) alone — pass --overwrite to "
+              "replace them", file=sys.stderr)
+    if written:
+        print("every stub needs a limit before it means anything: "
+              "uncomment min/max and fill in the real number.", file=sys.stderr)
+    return 0
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="opcua-tagmap", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_browse = sub.add_parser("browse", help="list the variables on a server")
+    p_browse.add_argument("--format", choices=["text", "csv", "json"],
+                          default="text")
+    _add_common(p_browse)
+
+    p_gen = sub.add_parser("gen", help="generate collector configuration")
+    gen_sub = p_gen.add_subparsers(dest="target", required=True)
+    p_telegraf = gen_sub.add_parser("telegraf", help="Telegraf [[inputs.opcua]]")
+    p_telegraf.add_argument("--input-name", default="opcua",
+                            help="value for the Telegraf input `name` field")
+    _add_common(p_telegraf)
+
+    p_tc = gen_sub.add_parser(
+        "testcases",
+        help="test-case stubs, one YAML file per numeric tag")
+    p_tc.add_argument("--out-dir", default="test_cases", metavar="DIR",
+                      help="directory to write stubs into (default: test_cases)")
+    p_tc.add_argument("--overwrite", action="store_true",
+                      help="replace stubs that already exist — this discards "
+                           "limits you have filled in, so it is off by default")
+    _add_common(p_tc, with_out=False)
+
+    args = parser.parse_args(argv)
+    tags = _collect(args)
+
+    if args.command == "browse":
+        renderer = {"text": table.to_text, "csv": table.to_csv,
+                    "json": table.to_json}[args.format]
+        _write(renderer(tags), args.out)
+    elif args.target == "testcases":
+        return _write_testcases(tags, args)
+    else:
+        _write(telegraf.render(tags, args.endpoint, args.input_name), args.out)
+
+    print(f"{len(tags)} node(s)", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

opcua_tagmap/emit/table.py

@@ -0,0 +1,35 @@
+"""Plain tag inventory: CSV or JSON.
+
+Useful on its own — a commissioning engineer wants the list of what is on the
+server regardless of which platform, if any, will collect it.
+"""
+
+import csv
+import io
+import json
+
+from ..model import FIELDS, TagNode
+
+
+def to_csv(tags: list[TagNode]) -> str:
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=FIELDS, lineterminator="\n")
+    writer.writeheader()
+    for tag in tags:
+        writer.writerow(tag.as_dict())
+    return buf.getvalue()
+
+
+def to_json(tags: list[TagNode]) -> str:
+    return json.dumps([t.as_dict() for t in tags], indent=2) + "\n"
+
+
+def to_text(tags: list[TagNode]) -> str:
+    """Aligned columns for reading in a terminal."""
+    if not tags:
+        return ""
+    width = max(len(t.browse_path) for t in tags)
+    return "".join(
+        f"{t.browse_path:<{width}}  {t.node_id:<28}  {t.datatype}\n"
+        for t in tags
+    )

opcua_tagmap/emit/telegraf.py

@@ -0,0 +1,68 @@
+"""Render discovered tags as a Telegraf `[[inputs.opcua]]` block.
+
+Pure: takes a list of TagNode, returns text. No network, no files.
+"""
+
+from ..model import TagNode
+
+# Telegraf reads these as strings even though they are numbers/enums.
+_HEADER = """\
+# Generated by opcua-tagmap. {count} node(s) from {endpoint}
+[[inputs.opcua]]
+  name = "{name}"
+  endpoint = "{endpoint}"
+  connect_timeout = "10s"
+  request_timeout = "5s"
+  security_policy = "None"
+  security_mode = "None"
+  auth_method = "Anonymous"
+"""
+
+_NODE = """
+  [[inputs.opcua.nodes]]
+    name = "{name}"
+    namespace = "{namespace}"
+    identifier_type = "{identifier_type}"
+    identifier = "{identifier}"
+"""
+
+
+def _toml_escape(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def field_names(tags: list[TagNode]) -> list[str]:
+    """One Telegraf field name per tag, unique within the block.
+
+    Telegraf refuses a config in which two nodes share a name. Plants reuse names all the time
+    (every control loop has a PV), so a name that occurs more than once gets its parents in front:
+    PV -> TIC101_PV, and the whole path below Objects if that is still not unique.
+    """
+    def tail(tag: TagNode, n: int) -> str:
+        parts = tag.browse_path.split("/")
+        parts = parts[1:] if len(parts) > 1 else parts          # drop the leading "Objects"
+        return "_".join(parts[-n:] if n else parts)
+
+    names = [t.display_name for t in tags]
+    for n in (2, 3, 0):
+        counts = {x: names.count(x) for x in set(names)}
+        if all(c == 1 for c in counts.values()):
+            break
+        names = [tail(t, n) if counts[name] > 1 else name for t, name in zip(tags, names)]
+    return names
+
+
+def render(tags: list[TagNode], endpoint: str, name: str = "opcua") -> str:
+    """Build a complete, paste-able Telegraf input block."""
+    out = [_HEADER.format(count=len(tags), endpoint=_toml_escape(endpoint),
+                          name=_toml_escape(name))]
+
+    for tag, field in zip(tags, field_names(tags)):
+        out.append(_NODE.format(
+            name=_toml_escape(field),
+            namespace=tag.namespace,
+            identifier_type=tag.identifier_type,
+            identifier=_toml_escape(tag.identifier),
+        ))
+
+    return "".join(out)

opcua_tagmap/emit/testcases.py

@@ -0,0 +1,125 @@
+"""Render discovered tags as test-case stubs.
+
+The output is the YAML shape read by opc-ua-test-automation-pipeline: one file
+per numeric tag, with the structure filled in and every limit left blank.
+
+The blanks are the point. This module must never guess a limit — a plausible
+invented number produces a test that passes for no reason, which is worse than
+having no test at all. Limits come from a datasheet and a person.
+
+Pure: takes TagNode objects, returns text. No network, no files.
+"""
+
+from ..model import TagNode
+
+# OPC UA variant type names that a min/max spec can actually be applied to.
+NUMERIC_TYPES = frozenset({
+    "Double", "Float",
+    "SByte", "Byte",
+    "Int16", "UInt16", "Int32", "UInt32", "Int64", "UInt64",
+})
+
+# Industrial tag names usually carry their unit as a suffix. This is a
+# convenience only, and the generated file says so.
+_UNIT_SUFFIXES = [
+    ("_mbar", "mbar"), ("_bar", "bar"), ("_kPa", "kPa"), ("_Pa", "Pa"),
+    ("_mV", "mV"), ("_V", "V"), ("_mA", "mA"), ("_A", "A"),
+    ("_kW", "kW"), ("_W", "W"), ("_kWh", "kWh"),
+    ("_ms", "ms"), ("_s", "s"), ("_Hz", "Hz"),
+    ("_rpm", "rpm"), ("_C", "C"), ("_K", "K"),
+    ("_pct", "%"), ("_mm", "mm"), ("_m", "m"), ("_l", "l"),
+]
+
+_TEMPLATE = """\
+# Generated by opcua-tagmap from {endpoint}
+#
+# This is a STUB. It will not judge anything until you give it a limit:
+# uncomment min and/or max under `spec` and put the real number there,
+# taken from the datasheet or the machine specification.
+#
+# If this variable does not need a test, delete this file.
+
+test_id: {test_id}
+title: TODO - what is being proven about {display_name}?
+author: TODO
+hypothesis: >
+  TODO - what do you believe is true, and why does it matter?
+procedure:
+  - TODO - how is the machine driven while this is measured?
+  - Sample {display_name} for the duration of that event.
+
+variable: {display_name}
+node_id: {node_id}          # {browse_path}
+
+# Only check while something else is happening - e.g. only during an inrush,
+# or only while the motor runs. Delete both lines to check the whole run.
+# condition_variable: TODO
+# condition_min: 0.0
+
+spec:
+  # min:{units_min_pad}     # lower limit, if there is one
+  # max:{units_min_pad}     # upper limit, if there is one
+  units: {units}{units_comment}
+
+expected_result: >
+  TODO - state the pass condition in one sentence.
+on_failure: >
+  TODO - if this fails, what should someone go and look at?
+"""
+
+
+def is_numeric(tag: TagNode) -> bool:
+    """True when a min/max spec can be applied to this tag."""
+    return tag.datatype in NUMERIC_TYPES
+
+
+def guess_units(display_name: str) -> tuple[str, bool]:
+    """Best-effort unit from a tag-name suffix.
+
+    Returns (units, guessed). `guessed` is False when nothing matched, so the
+    caller can mark the field as needing attention rather than silently
+    asserting a unit that is not there.
+    """
+    for suffix, unit in _UNIT_SUFFIXES:
+        if display_name.endswith(suffix):
+            return unit, True
+    return "TODO", False
+
+
+def stub_filename(tag: TagNode) -> str:
+    """File name for a tag's stub, safe on every platform."""
+    safe = "".join(c if (c.isalnum() or c in "-_") else "_"
+                   for c in tag.display_name)
+    return f"TC-{safe}.yaml"
+
+
+def render(tag: TagNode, endpoint: str) -> str:
+    """Build one test-case stub. Limits are left blank deliberately."""
+    units, guessed = guess_units(tag.display_name)
+    return _TEMPLATE.format(
+        endpoint=endpoint,
+        test_id=f"TC-{tag.display_name}",
+        display_name=tag.display_name,
+        node_id=tag.node_id,
+        browse_path=tag.browse_path,
+        units=units,
+        units_comment="" if guessed else "   # could not infer from the name",
+        units_min_pad="",
+    )
+
+
+def plan(tags: list[TagNode], endpoint: str) -> tuple[list, list]:
+    """Split tags into stubs to write and tags that cannot have one.
+
+    Returns (stubs, skipped) where stubs is a list of (filename, text) and
+    skipped is a list of (tag, reason).
+    """
+    stubs, skipped = [], []
+    for tag in tags:
+        if is_numeric(tag):
+            stubs.append((stub_filename(tag), render(tag, endpoint)))
+        else:
+            skipped.append(
+                (tag, f"{tag.datatype} - a min/max spec cannot express it")
+            )
+    return stubs, skipped

opcua_tagmap/globmatch.py

@@ -0,0 +1,98 @@
+"""Glob matching over browse paths.
+
+This is the piece Telegraf users keep asking for (influxdata/telegraf#18529):
+say `Objects/Plant1/*/MV*` instead of listing four hundred nodes by hand.
+
+Segment-aware, so `*` stops at a `/`:
+
+    *           any run of characters within one segment
+    ?           one character within one segment
+    [abc]       character class; [!abc] negates
+    **          any number of whole segments, including none
+
+Pure functions — no OPC UA, no I/O, no network.
+"""
+
+import re
+from typing import Iterable
+
+from .model import TagNode
+
+
+def translate(pattern: str) -> str:
+    """Glob pattern -> anchored regex source."""
+    out: list[str] = []
+    i, n = 0, len(pattern)
+
+    while i < n:
+        c = pattern[i]
+
+        if c == "*":
+            if pattern[i:i + 2] == "**":
+                i += 2
+                # `**/` and a trailing `**` both mean "zero or more segments"
+                if pattern[i:i + 1] == "/":
+                    i += 1
+                    out.append("(?:[^/]*/)*")
+                else:
+                    out.append(".*")
+            else:
+                out.append("[^/]*")
+                i += 1
+
+        elif c == "?":
+            out.append("[^/]")
+            i += 1
+
+        elif c == "[":
+            j = i + 1
+            if j < n and pattern[j] in "!^":
+                j += 1
+            if j < n and pattern[j] == "]":  # a ] right after [ is a literal
+                j += 1
+            while j < n and pattern[j] != "]":
+                j += 1
+            if j >= n:  # unclosed bracket: treat as a literal [
+                out.append(re.escape(c))
+                i += 1
+            else:
+                inner = pattern[i + 1:j]
+                if inner[:1] in ("!", "^"):
+                    inner = "^" + inner[1:]
+                out.append("[" + inner.replace("\\", "\\\\") + "]")
+                i = j + 1
+
+        else:
+            out.append(re.escape(c))
+            i += 1
+
+    return "^" + "".join(out) + "$"
+
+
+def compile_patterns(patterns: Iterable[str]) -> list[re.Pattern]:
+    return [re.compile(translate(p)) for p in patterns]
+
+
+def matches_any(path: str, compiled: list[re.Pattern]) -> bool:
+    return any(rx.match(path) for rx in compiled)
+
+
+def filter_tags(tags: Iterable[TagNode],
+                include: Iterable[str] | None = None,
+                exclude: Iterable[str] | None = None) -> list[TagNode]:
+    """Keep tags matching any include pattern, then drop any matching exclude.
+
+    No include patterns means keep everything — the common case of wanting the
+    whole server.
+    """
+    inc = compile_patterns(include or [])
+    exc = compile_patterns(exclude or [])
+
+    kept = []
+    for tag in tags:
+        if inc and not matches_any(tag.browse_path, inc):
+            continue
+        if exc and matches_any(tag.browse_path, exc):
+            continue
+        kept.append(tag)
+    return kept

opcua_tagmap/model.py

@@ -0,0 +1,37 @@
+"""The one data structure everything else passes around."""
+
+from dataclasses import dataclass, asdict
+
+
+@dataclass(frozen=True)
+class TagNode:
+    """A single readable variable found on an OPC UA server.
+
+    `browse_path` is the human-readable route to the node, slash separated and
+    starting at Objects — e.g. "Objects/ProtectionPanel/CoilVoltage_V". It is
+    what glob patterns match against, and what a person recognises.
+
+    The NodeId trio (`namespace`, `identifier_type`, `identifier`) is what
+    every downstream collector actually needs in its config.
+    """
+
+    browse_path: str
+    display_name: str
+    namespace: int
+    identifier_type: str  # "s" string, "i" numeric, "g" guid, "b" bytestring
+    identifier: str
+    datatype: str  # variant type name: Double, String, Boolean, ...
+
+    @property
+    def node_id(self) -> str:
+        """Canonical OPC UA NodeId string, e.g. ns=2;s=CoilVoltage_V."""
+        return f"ns={self.namespace};{self.identifier_type}={self.identifier}"
+
+    def as_dict(self) -> dict:
+        d = asdict(self)
+        d["node_id"] = self.node_id
+        return d
+
+
+FIELDS = ["browse_path", "display_name", "namespace", "identifier_type",
+          "identifier", "datatype", "node_id"]

opcua_tagmap-0.2.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: opcua-tagmap
+Version: 0.2.0
+Summary: Browse an OPC UA server and generate a tag inventory, a static Telegraf config or test-case stubs
+Author: Suleman Ali
+License: MIT
+Project-URL: Homepage, https://github.com/sulemanali5760/opcua-tagmap
+Project-URL: Issues, https://github.com/sulemanali5760/opcua-tagmap/issues
+Keywords: opcua,opc-ua,telegraf,iiot,plc,industrial,automation,tags,discovery
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncua>=1.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pyyaml>=6; extra == "dev"
+Dynamic: license-file
+
+# opcua-tagmap
+
+[![CI](https://github.com/sulemanali5760/opcua-tagmap/actions/workflows/ci.yml/badge.svg)](https://github.com/sulemanali5760/opcua-tagmap/actions/workflows/ci.yml)
+
+Browse an OPC UA server, filter the tags you want with glob patterns, and get
+a tag inventory (CSV/JSON), a static Telegraf config, or test-case stubs.
+
+It does not collect, store or display anything — Telegraf, InfluxDB, Grafana,
+ThingsBoard and Node-RED already do that well. This works *before* them:
+turning a PLC's address space into files you can read, review and version.
+
+## The problem
+
+Pointing any IIoT collector at a real machine means enumerating every node:
+
+```toml
+[[inputs.opcua.nodes]]
+  name = "host_MV01"
+  namespace = "2"
+  identifier_type = "s"
+  identifier = "Plant.Device1.MV01"
+
+# ... repeated for MV02 ... MV99, by hand
+```
+
+Telegraf's own issue [#18529](https://github.com/influxdata/telegraf/issues/18529)
+called browse-based discovery *"one of the most requested features for
+large-scale OPC-UA deployments"*. ThingsBoard users hit the same wall
+([#9594](https://github.com/thingsboard/thingsboard/issues/9594)).
+
+### Telegraf has this built in now
+
+That issue was closed in May 2026: Telegraf merged browse-based discovery with
+glob patterns (`[inputs.opcua.browse]`, pull request
+[#18831](https://github.com/influxdata/telegraf/pull/18831)); releases from
+1.39.0 (June 2026) on were published after that merge. **If you run a current
+Telegraf and want it to discover nodes by itself at start-up, use that, not this tool.**
+
+What `opcua-tagmap` is still for:
+
+- **A static config you can review.** The generated file lists every node, so a
+  change on the PLC shows up as a diff in version control instead of silently
+  changing what is collected.
+- **Older Telegraf versions** that do not have the browse section.
+- **A tag inventory** as CSV or JSON for commissioning documents, independent of any collector.
+- **Test-case stubs** for acceptance tests (below).
+
+## Install
+
+With internet:
+
+```bash
+pip install https://github.com/sulemanali5760/opcua-tagmap/releases/download/v0.2.0/opcua_tagmap-0.2.0-py3-none-any.whl
+```
+
+Without internet (a plant PC, a commissioning laptop on the machine network): download the offline bundle
+for your system from the [latest release](https://github.com/sulemanali5760/opcua-tagmap/releases/latest), carry
+it over on a USB stick, unzip it and run inside the folder:
+
+```bash
+python -m pip install --no-index --find-links . opcua-tagmap
+```
+
+The bundle holds this tool and every package it needs; nothing is downloaded. Each bundle is installed in a
+clean environment and started once before it is published. Python 3.11 or newer. Not on PyPI yet.
+
+## Use
+
+See what is on a server:
+
+```bash
+opcua-tagmap browse opc.tcp://192.168.0.10:4840
+```
+
+```
+Objects/ProtectionPanel/CoilVoltage_V    ns=2;s=CoilVoltage_V     Double
+Objects/ProtectionPanel/ContactorState   ns=2;s=ContactorState    String
+Objects/ProtectionPanel/CurrentDraw_A    ns=2;s=CurrentDraw_A     Double
+...
+```
+
+Generate a Telegraf input for a subset:
+
+```bash
+opcua-tagmap gen telegraf opc.tcp://192.168.0.10:4840 \
+  --include 'Objects/Plant1/*/MV*' \
+  --out telegraf.conf
+```
+
+Scaffold acceptance tests for a whole panel:
+
+```bash
+opcua-tagmap gen testcases opc.tcp://192.168.0.10:4840 \
+  --include 'Objects/ProtectionPanel/*' \
+  --out-dir test_cases/
+```
+
+```
+skipped ContactorState: String - a min/max spec cannot express it
+skipped FaultFlag: Boolean - a min/max spec cannot express it
+wrote 5 stub(s) to test_cases/
+every stub needs a limit before it means anything: uncomment min/max and fill in the real number.
+```
+
+One YAML file per numeric tag, in the format
+[opc-ua-test-automation-pipeline](https://github.com/sulemanali5760/opc-ua-test-automation-pipeline)
+reads. On a machine with a hundred tags, this turns *write a hundred files*
+into *delete the eighty-five you do not care about and fill in fifteen numbers*.
+
+**It never guesses a limit.** A generated stub has `min` and `max` commented
+out, so it cannot pass or fail until someone opens a datasheet and types the
+real number. An invented limit produces a test that passes for no reason,
+which is worse than having no test.
+
+Re-running is safe: files that already exist are left alone, so adding a tag
+next month gives you only the new stubs. `--overwrite` forces the issue.
+
+Export the inventory for a commissioning document:
+
+```bash
+opcua-tagmap browse opc.tcp://192.168.0.10:4840 --format csv --out tags.csv
+```
+
+## Names in the Telegraf output
+
+Telegraf rejects a config in which two nodes share a name, and plants reuse
+names all the time (every control loop has a `PV`). A name that occurs more
+than once gets its parent in front: `PV` becomes `TIC101_PV` and `TI102_PV`;
+names that are already unique are left alone.
+
+## Structured variables
+
+Members of a structured variable are listed too (`Recipe/Setpoint`,
+`Recipe/Duration`): this is how controllers expose a STRUCT. Properties that
+only describe a variable, such as `EURange` or `EngineeringUnits`, are not tags
+and are left out.
+
+## Glob patterns
+
+Matched against the browse path, and segment-aware — `*` stops at a `/`:
+
+| Pattern | Matches |
+|---|---|
+| `Objects/Plant1/*/MV*` | any `MV…` one level under any child of `Plant1` |
+| `Objects/**/Temperature` | `Temperature` at any depth |
+| `Objects/Panel/MV0?` | `MV01`, `MV02`, … but not `MV012` |
+| `Objects/Panel/MV[01]1` | `MV01` and `MV11` |
+
+`--include` is a union — repeat it. `--exclude` is applied afterwards.
+No `--include` means every variable on the server.
+
+## Options
+
+| Flag | Purpose |
+|---|---|
+| `--root ns=2;s=Plant1` | start part-way down instead of at Objects |
+| `--max-depth`, `--max-nodes` | stop a huge server from running away |
+| `--include-standard` | also return the OPC UA standard namespace (see below) |
+| `--format text\|csv\|json` | `browse` output shape |
+| `--out FILE` | write to a file instead of stdout |
+
+**Namespace 0 is excluded by default.** Every OPC UA server exposes a standard
+`Server` object — roughly 250 diagnostic nodes like `MaxSessions`,
+`ServerCapabilities` and `RedundancySupport`. Browsing a small demo server
+raw returns 255 nodes, of which 7 are the machine. Since the standard
+namespace is always ns=0 and machine tags always live in ns≥1, ns=0 is dropped
+unless you ask for it with `--include-standard`.
+
+If a pattern matches nothing, the tool **exits non-zero and writes no file**,
+rather than handing you a valid-looking config that collects nothing.
+
+Nodes that cannot be browsed — permissions, for instance — are reported as
+warnings on stderr and the rest of the tree is still walked.
+
+## Roadmap
+
+- `gen thingsboard` — IoT Gateway `opcua.json`
+- `gen nodered` — flow JSON
+- `gen ditto` — Eclipse Ditto Thing JSON
+- diff two browses: which tags appeared or vanished between machine revisions
+
+## What is tested
+
+CI runs the unit tests, then the whole tool against a simulated OPC UA server
+with a known address space, asserting that a browse finds exactly its seven
+variables, that the generated TOML parses and carries all seven NodeIds, that
+`Objects/ProtectionPanel/C*` selects exactly four, and that a pattern matching
+nothing fails instead of writing an empty config.
+
+A second test server, started inside `pytest`, covers what the panel simulator
+does not have: two objects with a variable of the same name, and a structured
+variable with member variables and a property.
+
+**No security yet.** The tool connects anonymously without encryption, and the
+generated Telegraf block says so (`security_policy = "None"`). A server that
+only accepts encrypted or logged-in sessions cannot be browsed with it; to find
+out what such a server wants, see
+[opcua-doctor](https://github.com/sulemanali5760/opcua-doctor).
+
+**Not yet verified against a real PLC.** The simulator is
+[`asyncua`](https://github.com/FreeOpcUa/opcua-asyncio)-based and well behaved;
+real servers have deeper trees, permission boundaries and vendor quirks in
+NodeId encoding. If you run it against real hardware, an issue describing what
+happened is genuinely useful.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

opcua_tagmap-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+opcua_tagmap/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+opcua_tagmap/browse.py,sha256=51m2TtjlS5yEf7V0Oheqa6vw_as4Z2rWDIaKjktKay4,4696
+opcua_tagmap/cli.py,sha256=28g11TNlQzx24RUxP1KR5XUMrysmg9ID7iM6nR0K2SY,6013
+opcua_tagmap/globmatch.py,sha256=sPvthiPRup2BuqUOHBxkiIakd2YPWfY-0hpAhMF6jKQ,2911
+opcua_tagmap/model.py,sha256=HADQe29EmT0hE4kDFgRdpCzKIKD23Xoe0zB0xTmSZ7U,1237
+opcua_tagmap/emit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+opcua_tagmap/emit/table.py,sha256=BgB3pWVWlRObQBWmwYP1bs4K-wAvMsfbZN5NbKHVvFg,914
+opcua_tagmap/emit/telegraf.py,sha256=qdpovLTKFXZ2gNgfkhIFv_UcsKtrGgIHa76uLn-6_TI,2275
+opcua_tagmap/emit/testcases.py,sha256=ms5qumlfd0LH5FSx0LsskN9rfPrYu_5ufY7Uf_EFLSI,4314
+opcua_tagmap-0.2.0.dist-info/licenses/LICENSE,sha256=icYzgdETaqO4KDzmh6wTqZ6M9i2omUy6Wyx8DX5YZbw,1068
+opcua_tagmap-0.2.0.dist-info/METADATA,sha256=aPvZ7ZA7FVBX2lYBpyGD8IvqkxprTVos_yyiA-1cxpg,9189
+opcua_tagmap-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+opcua_tagmap-0.2.0.dist-info/entry_points.txt,sha256=j8f0p9YWUDEKpXDSJNvVwHKq1BArlL8Oid_zBqYhnQM,55
+opcua_tagmap-0.2.0.dist-info/top_level.txt,sha256=sqgLxTWMKvtzP77P06m2COwOILvHEn3JQ8EIkpJma1Q,13
+opcua_tagmap-0.2.0.dist-info/RECORD,,

opcua_tagmap-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

opcua_tagmap-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opcua-tagmap = opcua_tagmap.cli:main

opcua_tagmap-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleman Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opcua_tagmap-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+opcua_tagmap