Skip to main content

opcua-tagmap

CI PyPI

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:

[[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 called browse-based discovery "one of the most requested features for large-scale OPC-UA deployments". ThingsBoard users hit the same wall (#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); 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

pip install opcua-tagmap

Without internet (a plant PC, a commissioning laptop on the machine network): download the offline bundle for your system from the latest release, carry it over on a USB stick, unzip it and run inside the folder:

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.

Use

See what is on a server:

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:

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:

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 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:

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
--security-policy, --security-mode secure channel, e.g. Basic256Sha256 + SignAndEncrypt
--cert-dir DIR client certificate folder (default pki); created on first use
--server-cert FILE the server's certificate (.der), so its identity is checked
--user NAME log in; the password comes from the OPCUA_PASSWORD environment variable

Secured servers

Most production servers (an S7-1500 with security on, for one) refuse anonymous, unencrypted sessions. Browse them like this:

export OPCUA_PASSWORD='...'          # never on the command line
opcua-tagmap browse opc.tcp://plc:4840 \
  --security-policy Basic256Sha256 --security-mode SignAndEncrypt \
  --server-cert plc_cert.der --user operator

On first use the tool creates pki/client_cert.der. The server rejects it (BadCertificateUntrusted) until someone moves it to the server's trusted list; that is the server's protection working, not a bug.

gen telegraf with the same flags writes a block with the matching security settings, auth_method = "UserName" and password = "${OPCUA_PASSWORD}", so the password stays out of the file. Telegraf creates its own key pair on first start; the server must trust that certificate too. Telegraf's OPC UA input only supports Basic256Sha256 among the current policies, so the tool refuses to write a config for the Aes* policies instead of writing one that cannot connect.

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.

A third test server accepts only Basic256Sha256 + SignAndEncrypt with a user login: the tool browses it with certificate and login, is refused without them (No matching endpoints) and with a wrong password (BadUserAccessDenied), and the Telegraf block it writes for that server parses and holds no password. If a secured server refuses you and the reason is unclear, see opcua-doctor.

Not yet verified against a real PLC. The simulator is asyncua-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.

Metadata

Release files for opcua-tagmap 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opcua-tagmap 0.3.0
File Size Uploaded Provenance Actions
opcua_tagmap-0.3.0.tar.gz 25.6 kB With provenance Details for opcua_tagmap-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opcua-tagmap 0.3.0
File Interpreter ABI Platform Actions
opcua_tagmap-0.3.0-py3-none-any.whl Python 3 none any Details for opcua_tagmap-0.3.0-py3-none-any.whl

Total release size: 45.5 kB

Release files / opcua_tagmap-0.3.0.tar.gz

Download URL opcua_tagmap-0.3.0.tar.gz
Size 25.6 kB
Tags Source
SHA-256 checksum
How to use checksums
51f86dc8a66e174102b1a4f149b51e26acdd53e865c5074fd470dc27d743d7ed
BLAKE2b-256 checksum
How to use checksums
30b3fe2b78ca99e80e284920a5c8148e7991c2184db8ddf45d76e84602650c04
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / opcua_tagmap-0.3.0-py3-none-any.whl

Download URL opcua_tagmap-0.3.0-py3-none-any.whl
Size 19.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b51ffd14a70f8875cda7811ebc0694f684a4c907bf0f8598cc177775df6718ed
BLAKE2b-256 checksum
How to use checksums
558b0158663610b35c0280a3c917e34e3a158fb6db0e35f41f3aa1b234cdbe97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for opcua-tagmap 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for opcua_tagmap-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page