TiaCommander
Siemens TIA Portal MCP server — AI-assisted PLC programming. 19 tools, 230 actions.
Open source Open in the app JSON README (API)
About
Siemens TIA Portal MCP server — AI-assisted PLC programming. 19 tools, 230 actions.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- a4webdev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 3.42.0
- Stars
- 34
- Forks
- 3
- Last push
- 2026-09-07T12:38:50Z
- Repository state
- ativo
- License
- NOASSERTION
- Added
- 2026-09-07 16:05:12
- Updated
- 2026-09-07 16:05:12
- Origin id
io.github.a4webdev/tiacommander-mcp
README
# TiaCommander — MCP Server for Siemens TIA Portal
| | |
|---|---|
| **Version** | 3.42.0 |
| **Protocol** | MCP 2024-11-05 (stdio) |
| **Runtime** | .NET Framework 4.8 |
| **TIA Portal** | V17 – V20 (Openness API, tested on V19) |
| **License** | Proprietary (free beta) |
**New in this release:** a new `technology_objects` tool — 15 actions for listing and reading technology objects, changing parameters, structural edits, export/import, and connecting an object to its hardware; per-project PLC credentials with a new Credentials tab in the Manager — a project's own password is tried first, a global one is the fallback; transactional block overwrites — the block is exported before the import and restored if the import fails, and overwrites no longer lose attributes, block numbers or folder placement; and compiler results that list only real diagnostics, so totals always match the compiler's own count. Dozens more fixes and improvements since v3.15.2 — see `CHANGELOG.md` for the full list.
*\*V17 through V20 are supported for project work. V16 and older are detected and refused with a clear message. Only V19 is fully tested; the others are expected to work as TIA Portal maintains backward-compatible Openness APIs across versions.*
---
## Overview
TiaCommander is an MCP server that connects AI assistants to Siemens TIA Portal via the Openness API. It enables AI-assisted PLC programming, project management, library operations, hardware configuration, cross-reference analysis, and deployment — all through natural language.
**Tested AI clients:** Claude Desktop, Claude Code, VS Code (Copilot), Cursor, Windsurf, Codex CLI, Gemini CLI.
**19 tools, 230 actions** covering the full TIA Portal project lifecycle.
| Tool | What it does |
|---|---|
| `admin` | Server administration, usage stats, export storage |
| `alarm_text` | Alarm texts and text lists, XLSX import / export |
| `blocks_read` | Read, inspect and export FB / FC / OB / DB blocks (XML, SCL) |
| `blocks_write` | Create and import blocks (SCL, LAD, FBD, STL) |
| `db` | Global and instance data-block members and values |
| `diagnostics` | Connection setup, online / offline compare, PLC state |
| `download_upload` | Compile-checked download to / upload from the PLC |
| `folders` | Navigate and organise the project-tree groups |
| `get_info` | Server capabilities and version |
| `hardware` | Device, rack / slot, network and I/O configuration |
| `library` | Master copies, library types, versioned instantiation |
| `live_data` | Live values and CPU diagnostics from the running controller |
| `open_manager` | Open the TiaCommander Manager window |
| `session` | Open, save, archive and switch projects; connection lifecycle |
| `tag` | PLC tag tables: create, edit, search, address assignment |
| `technology_objects` | Axes and other technology objects: read, tune, connect to hardware |
| `udt` | User-defined types: create, edit members, import / export |
| `watch` | Watch and force tables |
| `xref` | Cross-references: callers, unused blocks, orphaned instance DBs |
---
## What's in the download?
```
TiaCommander-v3.42.0-portable/
├── bridge/ ← Live PLC data helper (S7CommPlus / TLS)
│ ├── libcrypto-3-x64.dll
│ ├── libssl-3-x64.dll
│ ├── S7CommPlusDriver.dll
│ ├── TiaCommander.S7Bridge.exe
│ ├── TiaCommander.S7Classic.dll
│ └── zlib.net.dll
├── data/
│ └── exports/ ← Export output folders
│ ├── alarm_text/
│ ├── hardware/
│ ├── tag/
│ └── watch/
├── docs/
│ ├── configs/
│ │ ├── claude_code.txt
│ │ ├── claude_desktop_config.json
│ │ ├── codex_cli_config.toml
│ │ ├── cursor_mcp.json
│ │ ├── gemini_cli_settings.json
│ │ ├── generic_stdio.json
│ │ ├── vscode_copilot_mcp.json
│ │ └── windsurf_mcp_config.json
│ ├── 1-QUICKSTART.md
│ ├── KNOWN_LIMITATIONS.md
│ ├── LICENSE.txt
│ ├── README.md
│ └── THIRD-PARTY.md
├── help/
│ ├── github-offline.html
│ └── readme-offline.html
├── licenses/ ← Full third-party licence texts
│ ├── Apache-2.0.txt
│ ├── BSD-3-Clause.txt
│ ├── GPL-3.0.txt
│ ├── LGPL-3.0.txt
│ ├── Microsoft-WebView2-SDK.txt
│ ├── MIT.txt
│ └── Polyform-Noncommercial-1.0.0.txt
├── Resources/
│ ├── logoBlack.png
│ └── tiacommander.png
├── runtimes/ ← WebView2 native loaders
│ ├── win-x64/native/WebView2Loader.dll
│ ├── win-x86/native/WebView2Loader.dll
│ └── win-arm64/native/WebView2Loader.dll
├── Templates/ ← Block XML, alarm & diagnostics templates
│ ├── diagnostics/
│ │ ├── TC_Diag_1200.xml
│ │ └── TC_DiagOB.xml
│ ├── Fb.xml
│ ├── Fc.xml
│ ├── GlobalDb.xml
│ ├── Ob.xml
│ ├── Ob_FBD.xml
│ ├── Ob_LAD.xml
│ ├── Ob_SCL.xml
│ └── TextListTemplate.xlsx
├── x64/ ← SQLite native library (64-bit)
│ └── SQLite.Interop.dll
├── x86/ ← SQLite native library (32-bit)
│ └── SQLite.Interop.dll
├── CHANGELOG.md
├── EPPlus.dll
├── EPPlus.Interfaces.dll
├── icon.png
├── manifest.json
├── Microsoft.Bcl.AsyncInterfaces.dll
├── Microsoft.IO.RecyclableMemoryStream.dll
├── Microsoft.Web.WebView2.Core.dll
├── Microsoft.Web.WebView2.WinForms.dll
├── System.Buffers.dll
├── System.ComponentModel.Annotations.dll
├── System.Data.SQLite.dll
├── System.IO.Pipelines.dll
├── System.Memory.dll
├── System.Numerics.Vectors.dll
├── System.Runtime.CompilerServices.Unsafe.dll
├── System.Security.Cryptography.Xml.dll
├── System.Text.Encodings.Web.dll
├── System.Text.Json.dll
├── System.Threading.Tasks.Extensions.dll
├── THIRD-PARTY-NOTICES.md
├── TiaCommander.exe ← MCP server + Manager GUI
└── TiaCommander.exe.config
```
No installer, no registry changes, no system modifications. Extract, configure, and run. Download the latest `.zip` from [GitHub Releases](https://github.com/a4webdev/tiacommander-mcp/releases).
**Claude Desktop users:** Download the `.mcpb` bundle from [Releases](https://github.com/a4webdev/tiacommander-mcp/releases/latest) and install via Settings → Extensions → Advanced Settings → Install Extension. No config file editing needed. See the [Quick Start Guide](docs/1-QUICKSTART.md) for details.
> **Prerequisite:** [Siemens TIA Portal](https://www.siemens.com/tia-portal) V17 or later must be installed on your machine with the **Openness** component enabled. TiaCommander loads Siemens Openness libraries directly from your TIA Portal installation at runtime. Without TIA Portal, the server starts in **degraded mode** with limited functionality and guides you through setup.
---
## Why this tool exists?
First things first — we are software developers and automation engineers who use Siemens products daily — in our own facilities, at client sites, and in every project that needs industrial automation. We love it. With Siemens, it's simple — it just works. Every time. All the time.
During years of hands-on programming, wiring, testing, debugging and making things happen with Siemens PLCs, we have built TiaCommander just for our own internal needs. That's the honest reason why it exists — we built it for ourselves, and we find it awesome. It speeds things up tenfold, sometimes twentyfold, and sometimes more — until you ask yourself: how the hell were we getting things done before?!
You can get full project context through your AI assistant in under a minute. Create any block in seconds — SCL, LAD, FBD, DB — get interface structures, build multi-instance DBs, run cross-references, compile, debug, retrieve errors, and a lot more.
Every tool you see in the tool map below is built from what we actually need or use in our daily operations with Siemens PLCs. Whether you're working with S7-1200 or S7-1500 series — it doesn't matter. If Siemens TIA Portal supports it, you can use TiaCommander to manage it.
Now that we're making this tool public — we're genuinely keen on what features you're missing for your development workflow. Don't be shy — submit a feature request, file a bug report, or just tell us what you think. As an Engineer to Engineer — we read every line of feedback.
Enjoy TiaCommander.
---
## Architecture
```
AI Clients
Claude Desktop / Code · Cursor · VS Code / Copilot · Windsurf · Codex CLI · Gemini CLI
│
│ JSON-RPC 2.0 · stdio
▼
TiaCommander MCP Server
19 tools · 230 actions · standalone I/O · .NET Framework 4.8
│
│ Siemens Openness API
▼
TIA Portal (V17 – V20*, tested on V19)
│
▼
S7-1200 · S7-1500 · S7-300 · S7-400 · ET 200
```
---
## Tool Map
| Tool / Action | # | Description |
|---|---|---|
| **`admin`** | **13** | **Server administration** |
| `clear_exports` | | (optional olderThanHours=24) Delete expired exports. |
| `delete_export` | | (exportId) Delete a single export. |
| `get_device_profiles` | | All unique devices seen by the server. |
| `get_export` | | (exportId; optional offset, length, raw=false) Retrieve export content with paging. raw=true returns content only, no metadata header. |
| `get_recent_errors` | | (optional count=10) Last N failed tool calls with device/firmware context. |
| `get_system_info` | | OS, .NET version, TIA Portal version, process uptime. |
| `get_stats` | | (optional top_n=20) Call statistics per tool+action, sorted by total calls. |
| `get_version` | | Server version, DB path, DB size. |
| `list_exports` | | (optional tool, limit=20) Recent export results stored in export DB. |
| `open_file` | | (filePath) Open a file using the Windows default application (Excel for .xlsx, browser for .html, etc.). Use after any export action to let the user inspect results immediately. |
| `reset_device_catalog` | | Clear local device catalog and re-dump from TIA Portal if connected. |
| `save_export` | | (exportId, outputPath) Save export content to a file. Auto-decodes base64 for binary formats (XLSX). After saving, ask the user if they want to open the file (use admin action=open_file). |
| `search_device_catalog` | | (optional filter, limit=50) Search installed TIA hardware catalog from local DB. No TIA Portal needed. Use for hardware reference lookups (order numbers, CPU models, compatible modules). |
| **`alarm_text`** | **15** | **Alarm texts & text lists** |
| `add_entries` | | (deviceName, textlistName, entries[]) Add entries to a text list. Each entry: {from, to, text}. |
| `create_textlist` | | (deviceName, textlistName; optional listRange=Decimal, comment, entries[]) Create new text list. Works on empty devices (auto-seeds via template). Optionally populate with entries in one call. |
| `delete_entries` | | (deviceName, textlistName, fromValues[]) Delete entries by From value. |
| `delete_textlist` | | (deviceName, textlistName) Delete a user text list. System text lists rejected. |
| `export_alarm_classes` | | (deviceName, outputPath) Export alarm class definitions. After export, ask the user if they want to open the file (use admin action=open_file). |
| `export_alarm_data` | | (deviceName, format:csv\|xlsx; optional scope:alarm_texts\|textlists\|alarm_classes, outputPath, includeInfoText) Export alarm data to CSV or XLSX for documentation. Defaults to exports_root\alarm_text\. After export, ask the user if they want to open the file (use admin action=open_file). |
| `export_alarm_texts` | | (deviceName, outputPath; optional includeInfoText) Export alarm instance texts to XLSX. After export, ask the user if they want to open the file (use admin action=open_file). |
| `export_textlists` | | (deviceName, outputPath; optional textListNames[]) Export text lists to XLSX. All if no filter. After export, ask the user if they want to open the file (use admin action=open_file). |
| `get_entries` | | (deviceName, textlistName) Read all entries for a text list. |
| `import_alarm_classes` | | (deviceName, filePath) Import alarm class definitions. |
| `import_alarm_texts` | | (deviceName, filePath) Import alarm instance texts from XLSX. |
| `import_textlists` | | (deviceName, filePath; optional overwrite) Import text lists from XLSX. |
| `list_textlists` | | (deviceName) List system and user text lists with name, ID, range. |
| `update_entries` | | (deviceName, textlistName, entries[]) Update entries by From value. Each entry: {from, to?, text?}. |
| `update_textlist_comment` | | (deviceName, textlistName, newComment) Update text list comment directly. |
| **`blocks_read`** | **17** | **Read & export blocks** |
| `check_consistency` | | (deviceName) M10: IsConsistent flag can lag compile — use compile_all output instead. |
| `compile_all` | | (deviceName) Compile all. Run early to resolve F6. Slow first run (~30-60s). |
| `compile_block` | | (deviceName, blockName) Compile one block. |
| `export_all_xml` | | (deviceName, outputDirectory) All blocks as .xml files. M5: arg is 'outputDirectory' not 'outputPath'. After export, ask the user if they want to open the output directory (use admin action=open_file). |
| `export_source` | | (deviceName, blockName; optional outputPath, returnInline, outputDirectory) SCL/STL source. With outputPath it goes to disk (M3: it must be a DIRECTORY); omit it and returnInline applies. LAD/FBD return empty. After export, ask the user if they want to open the file (use admin action=open_file). |
| `export_xml_file` | | (deviceName, blockName; optional outputPath, returnInline, outputDirectory) Block XML. With outputPath it goes to disk; omit it and returnInline applies. After export, ask the user if they want to open the file (use admin action=open_file). |
| `export_xml_inline` | | (deviceName, blockName) Parsed XML summary. F6 applies. |
| `get_all_interfaces_summary` | | (deviceName) Member counts per section for all blocks. |
| `get_compiler_errors` | | (deviceName) Error-only filter. Same M8 recompile quirk. |
| `get_compiler_messages` | | (deviceName) M8: triggers fresh compile. Prefer compile_all output if just compiled. |
| `get_details` | | (deviceName, blockName) Type, number, language, interface size, consistency. |
| `get_edit_capabilities` | | (deviceName, blockName; optional networkIndex) #232 P0: THE DISCOVERY CALL. Per network: its OWN compile-unit language (the block-level one is misleading on mixed-language blocks), whether the rung model round-trips it, which write actions apply, and the fallback route when none do. One call instead of a dozen scattered hints. Costs ONE export - measured: there is no object-model per-network re... |
| `get_element_pins` | | (deviceName, blockName, networkIndex; optional elementUId or elementIndex) The 'look before you wire' card: for a Call or instruction Part, every pin with section, EXPECTED data type (read live from the callee interface / instance structure) and current wiring (operand + its resolved type, or UNWIRED OpenCon). Without a selector: lists the network's elements with UIds. Use BEFORE blocks_write u... |
| `get_interface` | | (deviceName, blockName) Full interface sections. F6: flakes on inconsistent blocks — compile_all first. |
| `get_network` | | (deviceName, blockName, networkIndex; optional includeUIds) #171 rung editor READ side: reconstructs the network's flat Parts+Wires graph into a JSON rung model - EXACTLY the vocabulary create_block networks[].rungs accepts (contacts/parallelBranches/box/output/call, plus enFrom for ENO-cascaded call chains). Output: {title, comment, editable, rungs[], unmodelled[]}. editable=true means the mod... |
| `get_xml_raw` | | (deviceName, blockName) Raw XML string. F6 applies. |
| `list` | | (deviceName; optional typeFilter:all\|code\|OB\|FB\|FC\|DB\|GlobalDB\|InstanceDB, includeInstanceDbs) Compact block table. |
| **`blocks_write`** | **26** | **Create & import blocks** |
| `add_interface_member` | | (deviceName, blockName, section, memberName, dataType; optional startValue, comment, confirm) #171 interface editor: add a member to an FB/FC/OB interface section (Input, Output, InOut, Static, Temp, Constant). BLAST RADIUS is computed FIRST (xref callers whose call sites go out of date + the FB's instance DBs + the #183 reinitializeDataBlocks warning: download resets actual values of affected ... |
| `add_multi_instance_member` | | (deviceName, parentFB, memberName, innerType; optional onCollision=fail\|replace) Add typed static member to FB. innerType must exist in device or project.ProjectLibrary. |
| `add_network` | | (deviceName, blockName; optional position, title, comment) Insert empty network at position (default: end). LAD/FBD only — SCL blocks have a single compilation unit and do not support multiple networks. Use populate_network / insert_rung to add logic afterward. |
| `copy_block` | | (deviceName, blockName, newName; optional targetFolder, createParents=false) Duplicate a block under a new name (block names are PLC-WIDE unique, so newName is mandatory and checked recursively). targetFolder omitted = copy lands next to the source block. The copy gets the next free number of its type. Source block is never modified. OFFLINE required. |
| `create_block` | | (deviceName, blockName, blockType:FB\|FC\|OB, language; optional blockNumber, interface, sclCode, networks, blockTitle, blockComment, author, version, memoryLayout, secondaryType, overwrite, targetFolder, createParents) Full block creation with custom interface and logic. blockNumber auto-assigned if omitted — ONLY for genuinely new blocks. When using overwrite=true to update an existing block (e... |
| `create_fb` | | (deviceName, fbName; optional fbNumber, language:LAD\|SCL\|FBD (STL not supported - Openness limitation), author, version, autoCompile=true, targetFolder, createParents=false) New FB. Number auto-assigned if omitted. Auto-compiles and returns errors. targetFolder ('Motors/Drives' syntax) creates the block directly inside that folder; missing folders are an ERROR unless createParents=true. |
| `create_fc` | | (deviceName, fcName; optional fcNumber, language, returnType=Void, author, version, autoCompile=true, targetFolder, createParents=false) New FC. Number auto-assigned if omitted. Auto-compiles and returns errors. targetFolder as in create_fb. |
| `create_ob` | | (deviceName, obName; optional obNumber, language, author, version, autoCompile=true, targetFolder, createParents=false) New OB. Number auto-assigned if omitted (starts at 123). obNumber=1 allowed; 2-122 reserved. Auto-compiles and returns errors. targetFolder as in create_fb. |
| `delete_block` | | (deviceName, blockName; optional force=false) Delete any block. Instance DBs rejected unless force=true (useful for orphaned instance DBs). |
| `delete_interface_member` | | (deviceName, blockName, memberName; optional section, confirm) Remove an interface member. Same blast-radius confirm gate. Logic still referencing the member will fail compile - check first with xref get_references. |
| `delete_network` | | (deviceName, blockName, networkIndex) Remove network by 0-based index. Refuses if last network. LAD/FBD only. |
| `delete_rung` | | (deviceName, blockName, networkIndex, rungIndex; optional expectTitle) Remove rung rungIndex. Refuses when the NEXT rung chains (enFrom) from the deleted one - retarget or delete the tail first. |
| `delete_scl_statement` | | (deviceName, blockName, networkIndex, statementIndex, matchText) #232 P0: remove ONE statement from an SCL network, in one call. Read the statements first with blocks_read action=get_network, which lists them 0-based with whitespace-normalised text. matchText is MANDATORY and is compared against the statement AT statementIndex before anything is modified - indexes shift under every edit, so an ... |
| `import_xml_file` | | (deviceName, filePath; optional overwrite, autoCompile=true, targetFolder, createParents=false) Import from XML file. Auto-compiles and returns errors. Preferred for large payloads. targetFolder as in import_xml_inline. OVERWRITE IS A WHOLE-OBJECT REPLACE, NOT A MERGE: with overwrite=true, any element ABSENT from your document is RESET to its default rather than preserved (ImportOptions.Overrid... |
| `import_xml_inline` | | (deviceName, xmlContent; optional overwrite, autoCompile=true, targetFolder, createParents=false) Import block from XML string. Auto-compiles and returns errors. Large payloads (12KB+) verified. targetFolder imports into that folder; without it, overwrite=true auto-targets the folder the existing block already lives in (owning-group import). OVERWRITE IS A WHOLE-OBJECT REPLACE, NOT A MERGE: wit... |
| `insert_rung` | | (deviceName, blockName, networkIndex, rung; optional position, expectTitle) #171 rung editor: insert ONE rung (create_block rung vocabulary: contacts/parallelBranches/box/output OR call{blockName,blockType,instanceDB,scope,pins}, optional enFrom for eno chaining) into an EXISTING LAD network at position (default: append). The network must be fully modelled (get_network editable=true) - refused ... |
| `move_block` | | (deviceName, blockName, targetFolder; optional createParents=false) Move a block into another folder ('' or '/' = container root). Openness V19 has NO native move — this is export -> delete -> import into the target group, with automatic restore to the original folder if the import fails. Verified by re-resolution and recompiled afterwards. OFFLINE required. |
| `populate_network` | | (deviceName, blockName, networkIndex, rungs; optional overwriteExisting, expectTitle) Fill a network with a rungs[] array (create_block networks[].rungs vocabulary incl. enFrom chains). Empty networks (fresh add_network) populate directly; non-empty networks require overwriteExisting=true AND full modelling (get_network first to preserve content). #164-style pre-import validation with JSON-path... |
| `remove_multi_instance_member` | | (deviceName, parentFB, memberName) Remove static multi-instance member. |
| `rename_block` | | (deviceName, blockName; optional newName, newNumber) Rename/renumber. Does NOT auto-cascade to callers. |
| `replace_network` | | (deviceName, blockName, networkIndex; optional title, comment) Replace network title/comment. LAD/FBD only — sclCode not supported (SCL XML is tokenized; use create_block with overwrite=true to rebuild SCL blocks). |
| `split_network` | | (deviceName, blockName, networkIndex, splitBefore[], titles[]) #232 P0: cut ONE SCL network into several at statement boundaries, each with its own title. splitBefore lists the statement indexes at which a new network BEGINS: [2,4] on a 6-statement network gives three networks of 0-1, 2-3, 4-5. titles[] must have exactly one MORE entry than splitBefore and is never defaulted. A PARTITION, not a... |
| `update_interface_member` | | (deviceName, blockName, memberName; optional section, newName, newDataType, newStartValue, newComment, confirm) Update or RENAME (newName) an interface member. Section omitted = searched in all sections; miss lists members per section. Same blast-radius confirm gate. Empty-string newStartValue/newComment removes. |
| `update_network` | | (deviceName, blockName, networkIndex; optional title, comment) Update network title/comment (0-based index). |
| `update_network_element` | | (deviceName, blockName, networkIndex, elementUId or elementIndex; optional newInstance, newTarget, pinWires) Surgical editing of Call elements in LAD/FBD. newInstance: swap instance DB. newTarget: retarget to different FB/FC (regenerates parameters, preserves matching wires). pinWires: JSON object mapping pin names to new operands — TYPE-CHECKED before any mutation against the pin's declared ty... |
| `update_rung` | | (deviceName, blockName, networkIndex, rungIndex, rung; optional expectTitle) Replace rung rungIndex with the given rung object. Same modelled-network requirement and renumbering caveat as insert_rung. |
| **`db`** | **11** | **Data block management** |
| `add_member` | | (deviceName, dbName, memberName, dataType; optional comment, initialValue) Add member to global DB. Supports all types including arrays (e.g. Array[0..9] of Int) and UDT refs. Global DBs only — instance DBs rejected. |
| `create` | | (deviceName, dbName; optional dbNumber, author, version, memoryLayout, targetFolder, createParents) New global DB. Number auto-assigned if omitted. targetFolder ('Motors/Drives' syntax) creates the DB directly inside that folder; missing folders are an ERROR unless createParents=true. For instance DBs, use create_instance_db instead. |
| `create_instance_db` | | (deviceName, dbName, instanceOfName; optional dbNumber) Create instance DB for an FB. TIA auto-populates interface from the FB. instanceOfName must be an existing FB. Number auto-assigned if omitted. |
| `delete` | | (deviceName, dbName) Delete DB. Rejects instance DBs (delete owning FB instead). |
| `delete_member` | | (deviceName, dbName, memberName) Remove member from global DB. Refuses last member. |
| `get_member` | | (deviceName, dbName, path; optional depth=2) #171 instance-data READ at ANY depth: dotted member path into nested multi-instance chains, instruction instances, UDT/struct members (e.g. 'modbus.BWTT-RR8_Instance.mb_addr'). Card shows type, start value(s) incl. per-array-element, comment, children to depth. Works on GLOBAL and INSTANCE DBs (exception: system-block iDBs cannot be exported). Member... |
| `get_structure` | | (deviceName, dbName) Full member list with types, start values, attributes via XML export. Flat list (no nesting hierarchy). |
| `list` | | (deviceName) All global and instance DBs. Names are qualified 'Folder/Sub/Name' paths (#185). |
| `set_start_value` | | (deviceName, dbName, path, value \| values{path:value,...}) #171 instance-data WRITE at ANY depth, on global AND instance DBs (start values only, never structure - the multi-instance config surface, e.g. a station call's mb_addr default inside the poll DB). Array elements via [index] on the LAST segment ('Cfg_HwId[3]'). Values are TIA literals as strings ('33', 'TRUE', 'T#2S', '16#00FF'). ALL pa... |
| `update_member` | | (deviceName, dbName, memberName; optional newDataType, newStartValue, newComment) Update member properties. At least one field required. Start values preserved on type change unless newStartValue explicitly provided. If TIA rejects due to type/value mismatch, provide a compatible newStartValue. Consecutive member edits can leave the DB export-inconsistent — the tool auto-compiles and retries ON... |
| `update_member_comment` | | (deviceName, dbName, memberName, newComment) Shortcut for comment-only update. CRITICAL: arg is 'newComment', NOT 'comment'. |
| **`diagnostics`** | **7** | **PLC diagnostics & connection** |
| `compare_online_offline` | | (deviceName) Compare all software objects (blocks, tags, UDTs, technology objects) between the offline project and online PLC. Auto-connects if offline. Read-only. Returns per-item status: Identical/Different/Only on PLC/Only in project. |
| `configure_connection` | | (deviceName, pcInterfaceName, confirm; optional targetIp, skipConfirm=false) Sets up the download connection programmatically. targetIp defaults to the device's project-configured IP from the hardware config — omit it in the normal case; pass it only to target a different address (e.g. from scan_devices). Creates a ConfigurationAddress inside the TargetInterface, then applies the configuration.... |
| `get_device_ip` | | (deviceName) Read-only. Reports the device's project-configured IP (the default target for configure_connection and download_to_device) plus every network interface with IP/mask/subnet. Call this to answer 'which IP does this PLC use' from the project — no network scan needed. |
| `get_plc_status` | | (deviceName) CONNECTION state (Online/Offline/NotReachable/Protected/...), whether the download connection is configured, AND the CPU's ACTUAL operating state, READ LIVE. RUN/STOP is absent from the engineering API entirely, so the state is obtained via live_data: this action resolves the IP of the device you NAMED, opens a live-data session if one is free, confirms the CPU's identity against t... |
| `go_offline` | | (deviceName) Disconnect from PLC. |
| `go_online` | | (deviceName) Connect to PLC via OnlineProvider. Run download_check first (silently) to verify interface is configured. |
| `scan_devices` | | (optional deviceName) Read-only network scan. Discovers accessible PLCs via GetAccessibleDevices(). Returns IP, DeviceSeries, MAC, Name per PcInterface, each ANNOTATED [IN PROJECT: <device>] or [NOT IN THIS PROJECT]. With deviceName: scans via DownloadProvider. Without: scans via StationUploadProvider (project scope). No confirmation needed. SCOPE: this is a layer-2 PROFINET DCP broadcast — it ... |
| **`download_upload`** | **4** | **Download / upload to PLC** |
| `download_check` | | (deviceName) Silent pre-flight. Call this BEFORE any download or go_online. Do not output text before calling. Verdicts: READY (all gates verified incl. compile), NOT READY (a gate FAILED — relay the issue), COMPILE UNVERIFIED (compile gate could not run, e.g. device is online — NOT a pass; download_to_device still compiles offline itself, but the check did not verify it). |
| `download_to_device` | | (deviceName, confirm; optional mode=software_changes, stopModules=false, startAfterDownload=true, reinitializeDataBlocks=false, pcInterfaceName) DESTRUCTIVE. Mandatory compile pre-check. confirm='I understand this will modify the PLC'. mode: software_changes\|software\|hardware_software\|hardware. pcInterfaceName selects which network adapter to route through (from scan_devices results). hardware/... |
| `upload_check` | | Silent pre-flight. Call this BEFORE any upload. Do not output text before calling. If result shows READY, proceed to upload_station. If NOT READY, relay the issue to the user. |
| `upload_station` | | (modeName, pcInterfaceName, confirm; optional addressIndex=0, readPassword, writePassword) DESTRUCTIVE TO PROJECT (adds device). confirm='I understand this will add a device to the project'. |
| **`folders`** | **5** | **Project-tree folders (groups)** |
| `create_folder` | | (deviceName, container, path; optional createParents=false) Create the folder at path. Nested paths use '/' (e.g. 'Motors/Drives'). Missing intermediate folders are an ERROR unless createParents=true — never created silently. |
| `delete_folder` | | (deviceName, container, path; optional deleteContents=false, confirm) DESTRUCTIVE. Empty folder deletes immediately. Non-empty requires BOTH deleteContents=true AND confirm containing 'I understand' — deletion permanently removes ALL contained items and subfolders. |
| `find` | | (deviceName, container, query; optional path, typeFilter, caseSensitive=false) Glob search across the WHOLE container: * matches any sequence, ? one character (e.g. 'mb_*', '*HMI*'). Returns Name [key=value, ...] (same envelope and per-container keys as get_tree) + folder location per match; capped at 200 with explicit truncation. get_tree answers SHAPE, find answers IDENTITY - use find when y... |
| `get_tree` | | (deviceName, container; optional path, nested=true, includeItems=false, depth=0 unlimited (1 = immediate children), typeFilter, limit) ONE-call tree view: folders with item/subfolder counts, plus contained items when includeItems=true. Item lines use ONE envelope on every container: Name [key=value, key=value] with keys lowercase, comma-space separated, inapplicable keys omitted. Keys per cont... |
| `rename_folder` | | (deviceName, container, path, newName) Works on technology_objects only. On the other five containers (program_blocks, tag_tables, udts, watch_tables, external_sources) the folder Name is get-only in Openness V19 and this returns Error: RenameFailed with the AccessMode - rename those in the TIA Portal UI. There is no move API on any of them. (#231 correction 14: the previous text called this a ... |
| **`get_info`** | **-** | **Server information** |
| **`hardware`** | **14** | **Hardware configuration** |
| `compile_all` | | Compile all HW. M4: 'Not compilable' = nothing needed recompiling (not an error). |
| `compile_device` | | (deviceName) F1: NullReferenceException — use compile_all instead. |
| `dump_catalog` | | Dump full TIA Portal hardware catalog (~11K entries) to local DB. Runs automatically on first TIA connection or TIA version change. Manual trigger for HSP updates. |
| `export_csv` | | (outputPath) Device list to CSV. After export, ask the user if they want to open the file (use admin action=open_file). |
| `export_hardware_map` | | (format:csv\|xlsx; optional deviceName, outputPath) Export raw CAx/AML hardware data for a device as flat table. Shows everything Siemens exports: rack, CPU, sub-items, signal modules, channels, addresses, tags. Single sheet. Defaults to exports_root/hardware/. Filename: {ProjectName}_{PLCName}_hardware_map_{timestamp}.{ext}. After export, ask the user if they want to open the file (use admin ac... |
| `export_io_map` | | (format:csv\|xlsx; optional deviceName, outputPath) Export complete device I/O map combining rack/slot topology with tag assignments. XLSX: one sheet per slot + summary. CSV: flat combined. Omit deviceName to export all devices (one file each). Defaults to exports_root/hardware/. Filename: {ProjectName}_{PLCName}_io_map_{timestamp}.{ext}. After export, ask the user if they want to open the file ... |
| `export_xlsx` | | (outputPath) Device list to Excel. After export, ask the user if they want to open the file (use admin action=open_file). |
| `get_device` | | (deviceName) Detailed config for one device. |
| `get_full_config` | | Complete hardware config for all devices. |
| `get_io_map` | | Full I/O address map across all devices/modules. |
| `get_network` | | Subnets, nodes, IO systems across project. |
| `get_rack_slot_details` | | (deviceName) Rack/slot topology with I/O address assignments. |
| `search_catalog` | | (filter) Live real-time search of TIA Portal hardware catalog. Requires TIA Portal running. Capped at 50 results. |
| `set_network_config` | | (deviceName, confirm; optional ipAddress, subnetMask, useRouter, routerAddress, ipProtocolSelection, useIsoProtocol, pnDeviceNameAutoGeneration, stationName, pnDeviceName) Set network config on a device's PROFINET interface. pnDeviceName sets the PROFINET device name directly (auto-disables auto-generation). stationName renames the device. Modifies project config only — download to PLC required... |
| **`library`** | **29** | **Library management** |
| `add_to_multi_instance_fb` | | (deviceName, parentFB, memberName, path; optional library='project', version, onCollision=fail\|replace) Resolve library type + delegate to blocks_write add_multi_instance_member. Type must be seeded via instantiate_library_type first. |
| `archive_global_library` | | (libraryName; optional targetDirectory, targetName, mode=Compressed) Create .zal19 archive. targetDirectory defaults to configured archives root — do NOT pass targetDirectory unless user explicitly specifies a different path. If archives root is not configured, direct user to open_manager → Paths tab to set it. |
| `close_global_library` | | (libraryName) Close loaded global library. |
| `compare_to_target` | | (targetLibrary; optional library='project', includeIdentical=false) Compare libraries: only_in_source, only_in_target, differs, identical. Read-only. |
| `create_global_library` | | (name; optional targetDirectory) Create new empty .al19. targetDirectory defaults to configured libraries root — do NOT pass targetDirectory unless user explicitly specifies a different path. If libraries root is not configured, direct user to open_manager → Paths tab to set it. Opens in ReadWrite. Call save_global_library to persist. |
| `create_library_folder` | | (folderPath; optional library='project', typeFilter=master_copies\|types) Create subfolder (idempotent, auto-creates intermediates). typeFilter picks the section: master_copies (default) or types. A read-only global library is refused with that reason. |
| `delete_library_folder` | | (folderPath; optional library='project', recursive=false, typeFilter=master_copies\|types) Delete subfolder from the named section. Non-empty refused unless recursive=true. |
| `delete_master_copy` | | (path; optional library='project') Delete by full slash-path. |
| `delete_unused_types` | | (optional library='project', path, mode=preserve_default\|delete_all, dryRun=true, confirm) Remove types with zero instances. dryRun=true default; set false + confirm to execute. |
| `export_type_xml` | | (library, path, outputPath; optional version, overwrite=false) Export type version to XML file. After export, ask the user if they want to open the file (use admin action=open_file). |
| `find` | | (library, query; optional path, typeFilter:all\|types\|master_copies, caseSensitive=false, limit) Glob search (* and ?). Recursive walk, cap 500 matches with loud NOTICE on truncation; matches carry the same envelope as get_tree. Scope with path on huge libraries. section was REMOVED (use typeFilter). |
| `get_info` | | (library) Metadata: edit mode, version, author, item counts, root folders. |
| `get_master_copy` | | (library, path) Master copy metadata plus a CONTENT MANIFEST: Contents (N) with one row per wrapped object and a friendly kind. A master copy carries no dependencies - publish referenced blocks and UDTs separately. No XML body is available: MasterCopy has no Export method in V19 Openness (#231 H11). |
| `get_type` | | (library, path; optional version='latest_committed', includeXml=false) Type metadata + version list. includeXml=true inlines XML body (cap ~30KB). |
| `get_tree` | | (library; optional path (default root), depth=0 unlimited (1 = immediate children), nested=true, includeItems=false, typeFilter:all\|types\|master_copies, limit) Recursive subtree view - args, defaults and depth rule now IDENTICAL to folders get_tree (v3.0.0). nested=false = flat path list (the machine contract). Cap 1000 items, loud NOTICE on truncation. Type lines carry the uniform envelope [ve... |
| `instantiate_library_type` | | (deviceName, path; optional library='project', version='latest_committed') Instantiate type version into device blocks. Only Committed versions. Side effect: seeds project.ProjectLibrary. |
| `instantiate_master_copy` | | (deviceName, path; optional library='project') Materialize master copy into device blocks. |
| `list_libraries` | | All libraries (project + loaded globals). Returns names for 'library' arg. Reserved name 'project' = project library. |
| `open_global_library` | | (optional path; optional openMode=ReadOnly\|ReadWrite) Load .al19 file. Without path, lists available libraries from configured libraries root. |
| `promote_to_global` | | (targetLibraryName; optional sourceLibrary='project', path, forceUpdateMode, structureConflictMode, deleteUnusedVersions) Copy types to writable global library. |
| `publish_block_as_master_copy` | | (deviceName, blockName; optional library='project', folderPath='', onCollision=autoRename\|replace\|fail) Publish FB/FC/OB/GlobalDB as master copy. Works on inconsistent blocks. |
| `publish_plc_type_as_master_copy` | | (deviceName, udtName; optional library, folderPath, onCollision) Same as above for UDTs. |
| `reload_global_library` | | (libraryName; optional discardChanges=false) Re-read a global library from disk after it was changed outside this session. Openness has no refresh, so this is a supervised close+open: it REFUSES when the library has unsaved changes (IsModified) unless discardChanges=true. Every path or handle from before the reload is stale. |
| `rename_library_folder` | | (folderPath, newName; optional library='project', typeFilter=master_copies\|types) Rename a user folder in either section. The section's system root is not renameable. (#231 H15) |
| `rename_master_copy` | | (path, newName; optional library='project') Rename a master copy. The WRAPPED object keeps its own name — ContentName is read-only — and the result says so. (#231 H13) |
| `rename_type` | | (path, newName; optional library='project') Rename a library type. Versions and already-instantiated blocks are untouched. (#231 H15) |
| `save_global_library` | | (libraryName) Persist open global library to .al19. |
| `update_check` | | (optional library='project', path, mode=ReportOutOfDateOnly) Preview what update_project would change. Read-only. |
| `update_project` | | (optional library='project', path, deleteUnusedVersions=false) DESTRUCTIVE: apply library-type updates to all matching blocks. Run update_check first. |
| **`live_data`** | **11** | **Live PLC values + diagnostics** |
| `connect` | | (host; optional password) Attach to a PLC over an encrypted connection (TCP port 102). host = PLC IP. password only if the CPU access level requires it (never logged/echoed). If password is omitted and one was stored via set_credential for this host, it is used automatically. |
| `delete_credential` | | (host; optional passwordClass, scope) Remove stored credential(s) for a host. scope='project' removes the open project's credential; scope='global' removes the one shared by any project. The response states which tier was removed. |
| `disconnect` | | Release the live-data session. |
| `get_status` | | Live-data readiness, connection state, PLC identity. Safe anytime. |
| `list_credentials` | | List stored credentials (host, SCOPE, class, label, timestamps). NEVER shows the secret. Each row states scope=project or scope=global using the same vocabulary the scope argument takes, so a row read here can be passed straight back to delete_credential; a project row also names its project path and is marked [OPEN in TIA] when it is the one scope=project would act on. |
| `list_readable` | | (optional root, limit) What the PLC actually exposes for reading, by root. No argument = one line per root with leaf counts; root=MArea (or a DB name) lists that root's leaves. Use this when a tag comes back unresolved - it separates 'not declared' from 'whole area empty'. |
| `read_db` | | (dbName; optional members[]) Live values of a data block (optimized or standard), symbolic, with quality codes. members[] limits to specific members. |
| `read_diagnostics` | | (optional kind=all\|identity\|protection\|alarms\|buffer, maxEntries) CPU order number + firmware (online - Openness CANNOT read this), protection level, active + configured alarms, and the CPU diagnostic buffer (kind=buffer or all): the same event log TIA Portal shows under Online and Diagnostics, newest first, timestamped from the CPU clock in UTC. Event text is resolved locally from a catalog, s... |
| `read_tag_table` | | (deviceName, tagTableName; optional tags[]) Live values for a PLC tag table. Tags may be named symbolically or by absolute address (%M1.0, %MB1, %MW20, %MD4, and the %I/%Q equivalents). Blocks if the named device's order number differs from the connected CPU's. |
| `read_watch_table` | | EITHER (symbols[]) for fully-qualified symbols, OR (deviceName, watchTableName) to resolve a project watch table and read its entries live. Passing both is an error. |
| `set_credential` | | (host, password; optional passwordClass, label, scope) Store a CPU password ENCRYPTED at rest (machine-bound), so connect can use it without passing the password each time. The secret is never echoed or logged. scope='project' binds it to the open project; scope='global' applies to any project. connect prefers the project credential and falls back to the global one. |
| **`open_manager`** | **-** | **Open Manager window** |
| **`session`** | **16** | **Session management** |
| `archive` | | (optional outputDirectory; optional archiveName, timestamp, archivationMode, saveChanges) Create .zapXX archive. outputDirectory defaults to configured archives root — do NOT pass outputDirectory unless user explicitly specifies a different path. If archives root is not configured, direct user to open_manager → Paths tab. timestamp=true default. archivationMode: None\|Compressed\|DiscardRestorabl... |
| `close_project` | | (optional saveChanges) Close project. saveChanges: prompt\|save\|discard\|auto. |
| `configure` | | (optional projectsRoot, archivesRoot, exportsRoot, librariesRoot, httpEnabled) Set default folder paths for create/open/archive/exports/libraries. Validates directory exists (exportsRoot auto-creates if missing). Use open_manager GUI as alternative. ALSO (#168): preferredTiaBinding=<version> is the TIA Portal SELECTOR - on a PC with several TIA Portals installed, pick which one TiaCommander bin... |
| `connect` | | (optional withUI=true) Attach to running TIA Portal, auto-loads first project. Releases any stale handle first. |
| `create` | | (name; optional parentDirectory, withUI=true) Create new project. Self-contained: auto-launches TIA Portal or attaches to a running instance, cleans up stale handles. ASCII names only (M12). parentDirectory defaults to configured projects root — do NOT pass parentDirectory unless user explicitly specifies a different path. If projects root is not configured, direct user to open_manager → Paths ... |
| `disconnect` | | (optional saveChanges, closeTia) Release Openness handle. closeTia=true also terminates TIA process. |
| `get_project` | | Name, path, version, device count of open project. |
| `get_state` | | Proactive state check. Returns state level (0-4), TIA/project/device status, license info, and restart flag. Call at session start. Works at any state. |
| `info` | | Server version, tool count, workflow hint. |
| `is_dirty` | | Returns true/false for unsaved changes. |
| `launch` | | (optional withUI=true) Start new TIA Portal (no project). Releases any stale handle first. Prefer create/open which auto-launch. |
| `list_archives` | | (optional archivesRoot) List all .zap* archive files from configured or explicit archives root. Shows filename, size, date, TIA version. |
| `list_devices` | | All devices in project. Provides deviceName for other tools. |
| `open` | | (optional projectPath; optional withUI=true) Open project, auto-launch TIA if needed. Idempotent. Without projectPath, lists available projects from configured projects root. |
| `save` | | Save project. OFFLINE REQUIRED: refuses with OnlineModeRestriction while any device is online — run diagnostics go_offline first. |
| `save_as` | | (newName; optional newParentDirectory) Save copy at new location. newParentDirectory defaults to configured projects root if set. |
| **`tag`** | **16** | **PLC tag management** |
| `add_tag` | | (deviceName, tagTableName, tagName, dataType; optional logicalAddress, comment) Add tag. dataType: Bool, Int, Real, etc. logicalAddress: %%M0.0, %%MW100. |
| `create_table` | | (deviceName, tagTableName; optional targetFolder, createParents=false) New empty table. targetFolder ('Motors/Drives' syntax) creates it directly inside that folder in the PLC tags tree; missing folders are an ERROR unless createParents=true. Name collision is checked recursively across all folders. |
| `delete_table` | | (deviceName, tagTableName) Delete table and all tags. |
| `delete_tag` | | (deviceName, tagTableName, tagName; optional tagNames, confirm) Delete single tag. REFUSES when the tag carries a comment or non-default access flags, because add_tag cannot restore them — pass confirm='I understand this destroys the comment and access flags' to override, or use action=move to relocate it losslessly. Note delete+add is NOT a rename: it creates a NEW object and every reference t... |
| `export_tag_table_data` | | (deviceName, tagTableName, format:csv\|xlsx\|xml; optional outputPath, returnInline=false) Export tag table to CSV or XLSX for documentation/analysis, or to raw TIA XML (format=xml) for round-trip via import_table. Columns: Name, DataType, Address, Comment, ExternalAccessible, ExternalVisible, ExternalWritable. Defaults to exports_root\tag\ if no outputPath, and the auto-generated name is de-dupl... |
| `find_next_free` | | (deviceName; optional area:M\|I\|Q, startByte:int, dataType:Bool\|Byte\|Word\|DWord\|Int\|Real\|etc., mode:declared\|used) Find next free address. mode=declared (default, safest): skips all declared tag addresses. mode=used: skips only addresses referenced in code. Alignment: Bool=any bit, Byte=byte, Word=even byte, DWord=4-byte. |
| `get_assignment_list` | | (deviceName; optional area:M\|I\|Q\|all, mode:declared\|used\|conflicts) Address occupancy for M/I/Q areas + HW I/O. mode=declared (default): all tag addresses. mode=used: only addresses referenced in block code (mirrors TIA Assignment List). mode=conflicts: addresses used in 2+ blocks with Read/Write detail — detects double assignments. |
| `get_table_details` | | (deviceName, tagTableName) All tags with types, addresses and comments. |
| `import_table` | | (deviceName, filePath OR xmlContent OR exportId; optional overwrite=false, targetFolder, createParents=false) OFFLINE REQUIRED. Import a tag table from raw TIA XML — the document export_tag_table_data format=xml produces. overwrite=false CREATES and refuses if that table name already exists. overwrite=true replaces the existing table; it is a whole-table import, not a field-level merge, so tags... |
| `list_tables` | | (deviceName) All tag tables, one line each with qualified 'Folder/Sub/Name' path and the uniform envelope [type=PlcTagTable, tags=N]. Totals reconcile with folders get_tree (container=tag_tables). |
| `move` | | (deviceName, tagTableName, tagName, targetTable) Move ONE tag to another table, preserving its comment AND all three access flags (ExternalAccessible/Visible/Writable). Use this instead of delete_tag + add_tag: add_tag cannot carry the access flags, so the hand-rolled route silently resets them. Verified by read-back; fails loudly if any property did not survive. |
| `move_table` | | (deviceName, tagTableName, targetFolder; optional createParents=false) OFFLINE REQUIRED. Move a tag table between folders ('' = container root). Emulated as export -> delete -> import into the target folder (spike-proven full fidelity); restore-on-failure back to the original location. NOTE: tag tables cannot be COPIED - PLC tag names are global across all tables. |
| `rename` | | (deviceName, tagTableName, tagName, newName) REFUSES BY DESIGN, always. Openness V19 exposes no tag rename: PlcTag.Name is getter-only and SetAttribute('Name') is refused with AccessMode: Read. Not emulated via export/reimport either — tag names are PLC-GLOBAL and Openness cascades nothing, so a rebuilt tag leaves every LAD/FBD/STL/SCL operand naming the old symbol, and SCL has no programmatic ... |
| `search` | | (deviceName, tagName) Substring match across all tables. |
| `set_access` | | (deviceName, tagTableName, tagName, accessible, visible, writable) CRITICAL: args are accessible/visible/writable, NOT externalAccessible etc. |
| `update_comment` | | (deviceName, tagTableName, tagName, newComment) CRITICAL: arg is 'newComment', NOT 'comment'. |
| **`technology_objects`** | **15** | **** |
| `capabilities` | | (optional family) The documented family/version/firmware matrix. NEEDS NO TIA CONNECTION. |
| `compile` | | (deviceName, name; optional scope=group) Runs immediately; no dry run. Reports every object version before and after. |
| `connect_hardware` | | (deviceName, name, interface, target; optional confirm) Rewires a channel. Sensor indices are 1-based. |
| `create` | | (deviceName, name, family, version; optional path, confirm) family and version are FIXED at creation and cannot be changed afterwards. |
| `create_from_master_copy` | | (deviceName, masterCopy; optional path, confirm) The master copy must be authored in the TIA UI; no Openness call can mint one. |
| `delete` | | (deviceName, name; optional confirm) NOT reversible: a re-created object starts from defaults. |
| `export` | | import — (deviceName, name \| file; optional confirm) SimaticML. Version-gated per family; a refusal names the required version and its manual section. |
| `find_parameter` | | (deviceName, name, parameter) One parameter: value, type, access. The FIRST read of an object's parameters is slow (~5.5-7.5 s measured - the cost is inside Openness); subsequent reads take ~150 ms, and the link goes cold again after idle. |
| `get_hardware_connection` | | (deviceName, name) Read-only wiring report. A provider that does not apply to the family is reported as such, not as an error. |
| `get_parameters` | | (deviceName, name; optional prefix, summary, limit) The commissioning data, typed. prefix filters one area; summary=true gives areas and counts only. Each row states its access; a bare/underscore pair folds into one row naming which half accepts a write. |
| `import` | | |
| `list` | | (deviceName; optional limit) All objects: Name [type=<family>, version=<Vx.y>, parent=<owner>]. Sub-level objects (output cams, cam tracks, measuring inputs) hang off a parent axis and are included. |
| `rename` | | (deviceName, name, newName; optional confirm) Program blocks reference the object BY NAME and are NOT updated. |
| `set_parameter` | | (deviceName, name, parameter, value, expectedCurrentValue) WRITES one parameter. expectedCurrentValue is REQUIRED and must match the present value or the write is refused. Read-only parameters are refused up front. Echoes old -> new with a copy-pasteable undo. |
| `show_in_editor` | | (deviceName, name) Opens it in the TIA UI. |
| **`udt`** | **11** | **User-defined type management** |
| `add_member` | | (deviceName, udtName, memberName, dataType; optional comment, initialValue) Add member via XML round-trip. |
| `create` | | (deviceName, udtName) New empty UDT. It is created with a placeholder member `_placeholder` (Bool) because TIA rejects an empty STRUCT - remove it with delete_member, or pass members[] (same shape as add_member bulk mode) and no placeholder is created. Optional targetFolder ('Motors/Drives' syntax) + createParents create it directly in that folder. (uses SCL ExternalSources workaround internall... |
| `delete` | | (deviceName, udtName) Delete UDT. Rejects if still referenced. |
| `delete_member` | | (deviceName, udtName, memberName) Remove member via XML round-trip. |
| `export_xml` | | (deviceName, udtName; optional outputPath, returnInline, outputDirectory) Export UDT to XML. With outputPath it goes to disk; omit it and returnInline applies. |
| `get_structure` | | (deviceName, udtName) Full member list with types, comments, access flags via XML. |
| `import_xml` | | (deviceName, filePath OR xmlContent; optional overwrite) Import UDT from XML. filePath reads from disk; xmlContent accepts inline XML string (no file tool needed). Reliable for round-trips; may fail on synthesized XML (use create+add_member instead). OVERWRITE IS A WHOLE-OBJECT REPLACE, NOT A MERGE: with overwrite=true, any element ABSENT from your document is RESET to its default rather than p... |
| `list` | | (deviceName) All UDTs, one line each with qualified 'Folder/Sub/Name' path, the uniform envelope [type=PlcStruct, num=N] and the modified date. |
| &nb