PLCWare - TIA Portal (tia)

Diagnoses connectivity to the TIA Openness `serve` API and whether the server is ACTIVATED. Tests GET /health (reachability) and GET /readiness (license activation). Ideal for the MCP-on-Mac-pointing-at-a-`serve`-on-a-Windows-VM scenario. Read-only. Returns { base, reachable, activated, latencyMs, hint }.

无需输入参数。

Readiness diagnostic for the TIA Openness V21 environment ON THE SERVE HOST (x64 process, Windows 'Siemens TIA Openness' group, PublicAPI, selected host/API registry key, and TIA instances). Call BEFORE connecting. Maps to GET /readiness. Read-only (class R). Returns { ready, checks:[{ name, status, detail, remediation }], version }; version reports the selected host/API and installed host inventory without claiming legacy runtime support.

无需输入参数。

THE OPERATING GUIDE for driving the tia_* tools — read the relevant topic BEFORE authoring, changing hardware or preparing a deploy. Returns bundled markdown: gates vs guards (G1..G7 are human-only), the build pipeline (validate→plan→scaffold→verify→handoff), runtime-validated gotchas, GUI-gate handoffs, the bare-CPU protection recipe, and the project-spec format. The pipeline/recipes topics distinguish host/API/firmware, observed API minVersion evidence and unverified legacy SimaticML imports; App 1.8.0 ships the V21 baseline only. Default topic 'toc' lists the chapters; 'full' returns everything. Pure/offline (class R): does NOT call the serve — works with the serve down.

Waits (up to waitSeconds, default 20, max 25) for a background job started by a long tool that answered status:"running" (tia_connect, tia_start, tia_show_ui, tia_project_create/save/saveas/close/archive, tia_compile, tia_source_put, tia_device_create, tia_import_xml, tia_types_import, tia_download, tia_upload, tia_export_xml, tia_export_block, tia_block_compare, tia_crossrefs, tia_io_map, tia_spec_apply, tia_cax_export/import, tia_hmi_screen_export, tia_hmi_screens_import, tia_hmi_validate, tia_global_library_create/open/save, tia_library_mastercopy_create, tia_device_from_mastercopy, tia_vci_status, tia_vci_export, tia_vci_import) and returns its FINAL result with job:{id,tool,state,durationMs} — including a gate handoff if the operation ended in one. While a job runs, every other serve-bound tool answers kind:"busy" (with details.jobId): call this instead of polling tia_status, and never repeat the original call. A lifecycle job that is still running may be starting or waiting for a trust dialog; running alone is not G1 evidence. Follow its conditional nextSteps, and ask a human to confirm G1 only if the dialog is visible on the serve host. Does not call serve. Class R.

Lists TIA Portal sessions exposed by Openness and native Siemens.Automation.Portal.exe processes on the serve host. Native-only rows include the PID with mode and project path set to null. Maps to GET /instances. Read-only (class R).

无需输入参数。

Current status of serve's connection to TIA Portal (attached instance, active project). `boundProjectPath` is the project this session is bound to (null when unbound); `bindingDrift` is null, or `{ actual, reason }` when the project open in the bound TIA is no longer that one (reason: project_closed | other_project | project_object_stale): ask the human which project is intended, then tia_connect to rebind. The additive `version` field reports selected host/API majors, PublicAPI path and installed host/API inventory; legacy detection is not runtime support. Maps to GET /tia. Read-only (class R).

无需输入参数。

Lists TIA project files (.ap*) in a folder on the serve host. Maps to GET /tia/projects?folder=<folder>. Read-only (class R).

Information about the currently connected project (name, path, author, `modified` = it has unsaved changes, `boundProjectPath`). Requires a connected project; answers 409 `binding_conflict` when the project open in the bound TIA is no longer the bound one (tia_status shows `bindingDrift`). Maps to GET /project. Read-only (class R).

无需输入参数。

Lists the languages (cultures) configured in the active project. Requires a connected project. Maps to GET /project/languages. Read-only (class R).

无需输入参数。

Lists the PLCs (PlcSoftware) of the active project as {name, device}: name is the PLC software name for plc arguments, device is its owning station name for device arguments. Requires a connected project. Maps to GET /plcs. Read-only (class R).

无需输入参数。

Lists the project's devices and their items. Requires a connected project. typeIdentifier prefers the station value, then the first readable DeviceItem.TypeIdentifier (including HMI panels). typeIdentifierSource is device, deviceItem or unavailable; if none can be read, typeIdentifier is null and typeIdentifierUnavailableReason explains the missing metadata. Maps to GET /devices. Read-only (class R).

无需输入参数。

Hardware tree of a device (racks/slots/modules). Requires a connected project. For a large device read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null. A page is {device, typeIdentifier, items, total, nextCursor}; total is the number of tree nodes of the whole device. A page is a forest: an item whose parent is on another page is listed at the top level of items with parentPath (the names of its ancestors, outermost first). Without limit and cursor the whole tree is returned. Each item's addresses [{start, length, ioType}] are the raw Openness values: start is a byte number and length is in BITS (an S7-1200 DI 14/DQ 10 input range of 2 bytes reads 16), not the byte length that tia_io_map answers. Maps to GET /devices/{device}/tree?limit=&cursor= (both optional). Read-only (class R).

Lists the communication connections (S7 etc.) of a device. Requires a connected project. Maps to GET /devices/{device}/connections. Read-only (class R).

Lists the blocks of a PLC (name, type, language, number, isConsistent, isKnowHowProtected). Requires a connected project. For a large project read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null. A page is {blocks, total, nextCursor}; total is the number of blocks of the whole PLC. Without limit and cursor the whole list is returned. Maps to GET /plcs/{plc}/blocks?limit=&cursor= (both optional). Read-only (class R).

Lists the user data types (UDTs) of a PLC. Requires a connected project. Maps to GET /plcs/{plc}/types. Read-only (class R).

Lists the tag tables and their tags for a PLC. Requires a connected project. For a large project read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null. A page is {tagTables, total, nextCursor}; total counts the tags of all tables (an empty table counts as one) and a table split across pages appears on both with the tags that fall on each. Without limit and cursor the whole list is returned. Maps to GET /plcs/{plc}/tags?limit=&cursor= (both optional). Read-only (class R).

Lists the watch tables of a PLC. Requires a connected project. Maps to GET /plcs/{plc}/watchtables. Read-only (class R).

Searches the hardware catalog (article number, type identifier, version). Requires TIA connected. By default the (long) 'description' is OMITTED — on broad filters it blows up the payload (description × firmware variants); pass verbose:true WITH a specific filter to include it. Maps to GET /catalog?filter=&typeIdentifier=&verbose=. Read-only (R).

Diagnostic for an S7 connection between two devices: available interfaces, nodes, and creationinfos. Requires a connected project. Maps to GET /connections/diagnose?localDevice=&partnerDevice= (both required). Read-only (class R).

Lists the active project's subnets. Requires a connected project. Maps to GET /subnets. Read-only (class R).

无需输入参数。

Reads ONE subnet: name, typeIdentifier, netType, every readable attribute, `updatable` (the attribute names tia_subnet_update can change on it, plus Name when it is writable), the connected `nodes` [{device, interface, node, address, subnetMask}] and the `ioSystems` [{name, number, controller, devices}] on it. Read it before tia_subnet_update or tia_subnet_delete: the nodes and IO systems listed (all pages of a paged read) are what a delete would disconnect or remove. An unknown subnet is 404 not_found. Requires a connected project. `inventoryGaps` [{kind, subject, reason}] lists every read that failed while the serve scanned the project (empty when all succeeded); a non-empty list means the nodes and IO systems above may be incomplete. A gap of kind `io_system_subnet` also carries `ioSystem` {number, controller}, the identity the serve decides on (`subject` is only the name). A `subnet_attribute` gap with the subject `<subnet> attribute list` means the attribute LIST could not be read: `updatable: []` is then a gap, not a statement that nothing is writable. A `subnet_attribute` gap with the subject `<subnet>.<attribute>` is one attribute that could not be read (it is absent from `attributes`) and says nothing about `updatable`. Pass limit (1..1000) and each nextCursor as cursor to page: one unit is a node, then one IO-device assignment (an empty IO system is one unit). A system split across pages repeats its header with only that page's devices. total counts these units; inventoryGaps describes the whole scan. If inventoryGaps itself is omitted, a smaller limit cannot shrink it: raise TIA_MCP_MAX_VALUE_CHARS/TIA_MCP_MAX_RESPONSE_CHARS or read the serve directly. Restart without cursor on cursor_stale. Maps to GET /subnets/{subnet}. Read-only (class R).

Reads the network configuration of ONE device, per network interface: `item` (the interface item name, the `interface` value the network write tools take), operatingMode, subnet, node {name, address, subnetMask}, pn {deviceName, autoGeneration, setDirectly, convertedName} (null when the PROFINET attributes are not readable, as on an interface that is not PROFINET), ioController {ioSystem} and ioConnector {ioSystem}. Read it before tia_pn_name_set, tia_io_system_connect or tia_io_system_disconnect. An unknown device is 404 not_found with details.validDevices; a PLC software name also identifies its owning station in details.device and details.hint. `inventoryGaps` [{kind, subject, reason}] lists every read that failed while scanning (empty when all succeeded); a gap of kind `io_system_subnet` also carries `ioSystem` {number, controller}, the identity the serve decides on (`subject` is only the name). Requires a connected project. Maps to GET /devices/{device}/network. Read-only (class R).

Lists every IO system of the project: {name, number, subnet, controller {device, interface} or null, devices [{device, interface}]}, plus `inventoryGaps` [{kind, subject, reason}] (reads that failed during the scan; empty when all succeeded, otherwise the list may be incomplete; a gap of kind `io_system_subnet` also carries `ioSystem` {number, controller}, the identity the serve decides on, while `subject` is only the name). Pass limit (1..1000) and each nextCursor as cursor to page IO-device assignments; an empty system is one unit. A split system repeats its header with only that page's devices, and total counts assignments plus empty systems. inventoryGaps describes the whole scan. If inventoryGaps itself is omitted, a smaller limit cannot shrink it: raise TIA_MCP_MAX_VALUE_CHARS/TIA_MCP_MAX_RESPONSE_CHARS or read the serve directly. Restart without cursor on cursor_stale. Requires a connected project. Maps to GET /iosystems. Read-only (class R).

Handles of the roots of the generic object model (project, devices, subnets). Requires a connected project. Maps to GET /obj/roots. Read-only (class R).

无需输入参数。

Details of an object by handle (type, name, attributes, compositions). Requires a connected project. Maps to GET /obj/{handle}. Read-only (class R).

Handles of an object's children in a composition. Requires a connected project. Maps to GET /obj/{handle}/items/{composition}. Read-only (class R).

Available compositions and invocations of an object. Requires a connected project. Maps to GET /obj/{handle}/info. Read-only (class R).

Creatable types in a composition and their parameters (mandatory/supported types). Requires a connected project. Maps to GET /obj/{handle}/creationinfos/{composition}. Read-only (class R).

Lists the services (GetService<T>) available on an object. Requires a connected project. Maps to GET /obj/{handle}/services. Read-only (class R).

Lists the connection modes and PG/PC interfaces TIA Portal sees for this PLC's CPU — name, number, target interfaces — plus each adapter's status in the serve host's OS (Up/Down/… or not_found_in_os: a DISABLED adapter is invisible). NO network scan (unlike tia_accessible_devices, GATE G7). Use it to pick connectionMode/pcInterfaceName/targetInterfaceName for tia_download. Requires app ≥ v1.6.0. Maps to GET /plcs/{plc}/pginterfaces. Read-only (class R).

Cross-references of ONE object or of a whole PLC: for every source object, the objects that use it or that it uses, each with its locations (block, network, address, access such as Read, Write or Call). Use it to see who calls, reads or writes a tag, block, type or constant before changing it, and to find objects nothing refers to. target names ONE object (block, type, tag, constant or tag table; with kind=blockgroup a user group name or a path such as Motors/Conveyor); without target the whole PLC is read. kind is plc, block, type, tag, constant, tagtable or blockgroup. Without kind the name is auto-detected across block, type, tag, constant and tag table (blocks and types in every user group): one match is used, several are 409 ambiguous_target (details lists the kinds: repeat with kind=), none is 404 not_found; kind=blockgroup is never auto-detected. filter: AllObjects (default), ObjectsWithReferences, ObjectsWithoutReferences or UnusedObjects. UnusedObjects are CANDIDATES, not proof: OBs, objects reached only from outside the PLC (HMI, OPC UA, Modbus, other CPUs, external applications) and library entry points show as unreferenced, so recommend and let the human decide, never delete from this result. On a big project scope the read with target and kind: the whole-PLC read of a large project can take minutes. A target that does not offer cross-references, or a container read with no queryable owner, is 409 crossrefs_unavailable (it depends on the TIA/CPU version). Paging: limit (1..1000) and cursor page the sources. A page adds total and nextCursor: pass it back as cursor until nextCursor is null; cursor_stale: restart without cursor; invalid_cursor: pass it unchanged. App 1.8+ caches whole-PLC walks until serve mutation, project close/switch or cursor expiry; older serves re-read every page. summary and coverage describe the WHOLE result: check coverage on every page. coverage is {complete, owners, queried, unavailable, unavailableOwners, unavailableOwnersTrunca

I/O channel map of ONE PLC, the base of a FAT/SAT I/O list: for every I/O device item reachable from the PLC (its own modules and onboard I/O, and the devices on its PROFINET IO systems) the address ranges with logical notation, the channels with logical addresses, the PLC tags that sit on them, and the I/O tags that sit on nothing. entries is one ordered list; kind is range (device, path, ioType, length, from, to, channels, status), channel (device, path, channel, address, bits, addressBasis, status, flags, tags) or tag (an I/O tag on no channel or range: table, name, address, status, reason). status: matched (one tag, exactly on the channel; on a range without channels, the tags inside it), unmatched (nothing on it), conflict (flags multipleTags, spansChannels, partial), unresolved (no address: unresolved says why), channels (a range whose channels are listed as their own entries) and unparsed (an I/O address that is not valid). Each tag carries match: exact, spans, partial or inRange. Channel addresses are DERIVED from the address range of the item and the channel number, never read from TIA (addressBasis derived): verify them against the hardware configuration. A range's length is in BYTES (Openness reports bits; the map converts, rounding up); tia_device_tree's raw addresses[].length stays in BITS. summary and coverage describe the WHOLE result: check coverage on every page. coverage.complete false, any unresolved or unparsed entry, any coverage.unreadable entry, an omission marker or an unfinished page walk means the map, and any FAT/SAT list built from it, is NOT complete: report the gap, never guess an address. coverage.limits is always present and does not change complete: PROFIBUS DP master systems and devices outside the PLC's PROFINET IO systems are not read, so an unmatched tag may belong there. Paging: limit (1..1000) and cursor page the entries; a page adds total and nextCursor: pass it back as cursor until nextCursor is null; cursor_stale: restart wi

Starts TIA Portal (or attaches to an idle instance) WITHOUT opening a project. Class M-off (offline mutation). `headless` only applies when CREATING a new instance (when attaching, it inherits the existing mode). Step 1 of the proactive trust-GATE flow: tia_start → tia_show_ui → tia_connect. Maps to POST /tia/start. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Relaunches the HEADLESS instance we started as VISIBLE, reopening the same project, to RENDER the 1st-connection trust dialog on screen (the concrete handoff of GATE G1) — so a human can confirm it. Only works if serve owns the portal (not on an attached instance). Maps to POST /tia/show-ui. Use BEFORE tia_connect when you started headless. Long operation: may answer status:"running" + jobId — then call tia_job_status.

无需输入参数。

Opens/attaches a TIA project (.ap*) on the serve host. Class M-off. Idempotent for the ALREADY-OPEN project (response `alreadyOpen:true`, no-op) and reuses a running TIA instance for a DIFFERENT project (`reusedPortal:true`). In an instance serve started, the open project and any foreign project are closed to make room (or the instance is restarted): if one has unsaved changes the call is REFUSED with 409 `unsaved_changes` and nothing is changed, unless it carries `saveUnsavedChanges:true` (saves each modified project first; recommended) or `discardUnsavedChanges:true` (closes WITHOUT saving: DATA LOSS, only on an explicit human decision, never to get past the refusal; the client asks the human to confirm first). `closedForeign` lists the foreign projects that were closed, `savedProjects`/`discardedProjects` the ones saved or discarded; an instance you had open yourself is never closed (serve only detaches). The response carries `boundProjectPath` (the project this session is bound to) and `modified` (unsaved changes); a later operation answers 409 `binding_conflict` if the project open in the bound TIA changed meanwhile (call tia_connect again to rebind). `withUserInterface` only applies when a NEW instance is started (ignored when reusing one — see tia_show_ui to change an existing instance's visibility). WARNING: the 1st connection per `serve` process can BLOCK on the trust GATE (G1) — if the dialog hasn't been confirmed, this tool does NOT retry-storm: it returns a `requires_human_action` envelope (gate trust_dialog, with resumeToken) asking a human to confirm the dialog on the host. Proactive flow: tia_start → tia_show_ui → (human confirms) → tia_connect. UMAC (umacUser/umacPassword) is GATE G6: provide it ONLY if a human gave the credentials — NEVER make them up. Maps to POST /connect. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Disconnects from TIA. This is the explicit teardown for the TIA instance the serve itself created (an instance we merely ATTACHED to is only detached, never killed) — but not the only path that can end an owned instance: tia_show_ui (relaunch visible), tia_project_create, and a tia_connect needing a fresh connect also end/replace it. Ending an instance serve started would lose the unsaved changes of its projects, so if one has any the call is REFUSED with 409 `unsaved_changes` (nothing is changed) unless it carries `saveUnsavedChanges:true` (saves each modified project, then disconnects; recommended) or `discardUnsavedChanges:true` (DATA LOSS: only on an explicit human decision, never to get past the refusal; the client asks the human to confirm first); `savedProjects`/`discardedProjects` report what was saved or discarded. For a serve-started portal the answer waits up to 10 seconds after disposal for its exact native process to exit, even headless. If it survives or exit cannot be verified, `500 tia_release_incomplete` reports `details.leftoverProcesses` entries `{pid,startedUtc,mode}` with `waitMs:10000` and `sessionDropped:true`; it is logged and stays visible in tia_instances. Inspect the host before reconnecting; no unrelated process is killed. The same 10-second native-exit wait applies to owned-portal replacement and settled shutdown. Shutdown during an unsettled connect instead has a 15-second answer window including queue wait and teardown; if unfinished, the exiting host logs verified owned survivor identities or explicitly unknown identity. It has no HTTP shutdown answer: a human must inspect the host and close only remaining serve-started TIA processes, leaving attached portals untouched. WARNING (Gd3): on an ATTACHED instance, /disconnect does NOT close the project (nothing to save or discard) — to RELEASE the project lock while KEEPING the TIA process alive (so the next tia_connect reuses it) use tia_project_close instead. Maps to POST /disconnect.

Creates a new TIA project. Guard Gd4: the target directory must be EMPTY — if it isn't, serve returns 409 conflict (this tool passes the error through; rediscover/choose another directory). A project already open in this session is closed to make room: if it has unsaved changes the call is REFUSED with 409 `unsaved_changes` (nothing is changed) unless it carries `saveUnsavedChanges:true` (saves it first; recommended) or `discardUnsavedChanges:true` (DATA LOSS: only on an explicit human decision, never to get past the refusal; the client asks the human to confirm first). The response carries `boundProjectPath` and `modified` for the new project, and `savedProjects`/`discardedProjects`. If a fresh create is refused with `tia_process_untracked` or `tia_process_inventory_unavailable`, `details.sessionDropped:true` means the previous session was already released (attached TIA detached or dead owned portal abandoned); its object handles are invalid. Re-read tia_status before continuing. `false` means no previous portal existed. Reusing an owned live portal does not start another portal and cannot produce these start refusals. Maps to POST /project/create. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Saves the open project. Maps to POST /project/save. Long operation: may answer status:"running" + jobId — then call tia_job_status.

无需输入参数。

Saves the open project to another directory. Maps to POST /project/saveas. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Closes the open project and RELEASES the lock (Gd3: use this, not tia_disconnect, to release the project). KEEPS the TIA process alive (response `portalKept`/`pid`) — the next tia_connect reuses it instead of paying the 40-80s cold start. A project with unsaved changes is never closed silently: the call is REFUSED with 409 `unsaved_changes` (nothing is changed) unless it carries `saveUnsavedChanges:true` (saves it, then closes; recommended, or call tia_project_save first) or `discardUnsavedChanges:true` (closes WITHOUT saving: DATA LOSS, only on an explicit human decision, never to get past the refusal; the client asks the human to confirm first). The response lists `savedProjects`/`discardedProjects`. Maps to POST /project/close. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Archives the open project (.zap*). Maps to POST /project/archive. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Creates a device (CPU/HMI/IO) by typeIdentifier. Optional group is an existing device user-group path (Area/Line, case-insensitive); omitted means project level. For group, GET /status must advertise supportsDeviceGroupCreation:true (app 1.8.1+); older serves are refused before creation. Uses typed CreateWithItem, never the unsafe generic CreateDevices call. The successful receipt identifies the canonical group; missing or different placement is an error naming the created station when available: inspect before retrying, never retry automatically. A dryRun preview does not check serve support. The answer uses the station type identifier, falling back to the first readable DeviceItem.TypeIdentifier, including HMI panels. typeIdentifierSource is device, deviceItem or unavailable; unavailable metadata has typeIdentifier:null and an explicit typeIdentifierUnavailableReason. For a single-item device such as a Classic panel, set its name as deviceItemName and omit deviceName; deviceName is the station name and may be read-only. On 400 device_name_read_only, re-read GET /devices before retrying with only deviceItemName. Guard Gd5: '/V<fw>' (slash), never ':V' — resolve via tia_catalog. Maps to POST /devices. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Changes the CPU's FIRMWARE version IN-PLACE (wraps DeviceItem.ChangeType), PRESERVING the program — an alternative to delete+recreate (enables 'auto-FW-match'). Guard Gd5: the typeIdentifier follows 'OrderNumber:<MLFB>/V<fw>' with '/V' (slash), never ':V' — resolve via tia_catalog. Rule: the PROJECT's firmware version must be ≤ the physical DEVICE's (project FW ≤ device FW). dryRun (Gd11) returns the plan without mutating. Maps to POST /plcs/{plc}/device/changeversion. Class M-off. API minVersion evidence: V18 (V17 lacks ChangeType; V18–V20 metadata binds, not legacy runtime acceptance).

Plugs a module into an existing device by typeIdentifier (Gd5: '/V', never ':V'; resolve via tia_catalog). Maps to POST /devices/{device}/plug. M-off.

Removes a device item (module). Maps to DELETE /devices/{device}/items/{item}. M-off.

Creates a device group. Maps to POST /devicegroups. M-off.

Creates a subnet by typeIdentifier (Gd5: '/V', never ':V'). Refused with 409 subnet_name_in_use (details.existing) when the name matches another subnet, ignoring case. The result carries a `postcheck` (the serve re-reads the project after the write); a mismatch is 409 postcheck_failed (details.mismatches): re-read with tia_subnets before retrying. Maps to POST /subnets. M-off.

Connects a device's interface to a subnet (with IP; optionally creates an IO-system). CPU and IO-devices MUST be on the SAME subnet. The result carries a `postcheck` (the serve re-reads the connection after the write); a mismatch is 409 postcheck_failed (details.mismatches): re-read with tia_device_network before retrying. Before connecting or writing an IP, the serve checks Address metadata and its current value: 409 node_attribute_list_unavailable or node_attribute_unreadable means nothing changed. dryRun uses POST /network/connect/plan and runs the same address guards without changing the project; an older serve refuses that route safely. Maps to POST /network/connect. M-off.

Sets address attributes (IP/mask/etc.) of a device's interface. The result carries a `postcheck` (the serve re-reads the attributes after the write); a mismatch is 409 postcheck_failed (details.mismatches; details.rollback says whether the previous values were restored; details.restoreFailures lists every field that is NOT back at its previous value, re-read after the rollback): re-read with tia_device_network before retrying. Refused before anything is written, nothing changed: 409 node_attribute_list_unavailable (details.attributes, details.reason: the attribute list of the node could not be read, so it cannot be verified that the attributes can be written) and 409 node_attribute_unreadable (details.attributes: the current value could not be read, so a failed write could not be rolled back). Maps to POST /network/address. M-off.

Disconnects a device's interface from the subnet. The result carries a `postcheck` (the serve re-reads the interface after the write); a mismatch is 409 postcheck_failed (details.mismatches): re-read with tia_device_network before retrying. Maps to POST /network/disconnect. M-off.

Updates ONE subnet: rename it (`name`) and/or set attributes from the serve's allow-list for its net type (Ethernet: DefaultSubnet; Mpi: HighestAddress, TransmissionSpeed; Profibus: HighestAddress, TransmissionSpeed, BusProfile; tia_subnet_get lists `updatable` for the subnet; SubnetId is never updatable). Only the fields that differ from the current value are written (none passed: 400 missing_param; all unchanged: 200 with changes:[]). A rename takes at most 24 characters: a longer name is 400 invalid_subnet_name (details.name, length, maxLength), a dryRun included, after the subnet is found and before its attribute list is read or anything is written, although tia_subnet_create accepts longer names; a name equal to the subnet's current name is not a rename and is not refused, and the serve counts UTF-16 code units as sent, spaces included. Refused, nothing changed: 409 subnet_name_in_use (details.existing) when another subnet has the name, ignoring case; 400 unsupported_subnet_attribute (details.unsupported, details.allowed); 409 subnet_not_writable (details.attributes); 409 subnet_attribute_unreadable (details.attributes: the current value could not be read, so a failed write could not be rolled back); 409 subnet_attribute_list_unavailable (details.attributes, details.reason: the attribute list of the subnet could not be read, so it cannot be verified that they can be written); 400 bad_request for a blank name; 404 not_found for an unknown subnet. The result carries `changes` [{field,from,to}] and a `postcheck` (the serve re-reads the subnet after the write); a mismatch is 409 postcheck_failed (details.mismatches; details.rollback says whether the previous values were restored, verified by a fresh read; details.restoreFailures lists every field that is NOT back at its previous value): re-read with tia_subnet_get before anything else. dryRun (Gd11) is answered by the serve (needs an open project): it runs the same guards and returns the plan WITHOUT changing anyth

Deletes a subnet. A subnet that still has nodes or IO systems is refused with 409 subnet_not_empty (details.nodes and details.ioSystems list everything that would be disconnected or removed) unless disconnectNodes:true, which disconnects every node from it and removes the IO systems on it first; an unknown subnet is 404 not_found. Read it with tia_subnet_get first. The result carries `disconnected`, `removedIoSystems` and a `postcheck` (the serve re-reads: the subnet is gone and no node is connected to it); a mismatch is 409 postcheck_failed: re-read with tia_subnets and tia_device_network before anything else. dryRun (Gd11) is answered by the serve (needs an open project): it returns the plan {nodes, ioSystems, willDisconnect, willRemoveIoSystems} WITHOUT deleting, and a dryRun of a non-empty subnet without disconnectNodes:true is the same 409 subnet_not_empty refusal as the real call. 409 subnet_inventory_mismatch means Openness counts other nodes on the subnet than the project devices show: nothing was deleted, do not retry blindly. 409 subnet_inventory_incomplete means the serve could not list the IO systems of the subnet (details.gaps): nothing was deleted, and a dryRun refuses the same way; read tia_subnet_get (inventoryGaps) and do not retry blindly. 409 subnet_delete_incomplete means a step failed midway and the project is partially changed (details list what was removed): re-read with tia_subnet_get. Maps to DELETE /subnets/{subnet}?disconnectNodes=true. M-off.

Sets the PROFINET device name of ONE interface and/or its automatic name generation. `interface` is the interface item name from tia_device_network. Pass `name` (an explicit name turns auto-generation off, so the plan lists both changes) and/or `autoGeneration`; neither: 400 missing_param; `name` together with autoGeneration:true: 400 conflicting_params. The name must be DNS-style: labels of a-z, 0-9 and '-' separated by '.', each label 1-63 octets and 240 octets in all, no label starting or ending with '-', the first label not `port-xyz` or `port-xyz-abcde`, the whole not shaped like an IPv4 address, and an upper-case letter is refused, never lowered: 400 invalid_pn_device_name (details.violations [{code,message}], details.rule). Also refused, nothing changed: 409 pn_name_in_use (another node on the same subnet has the name as its visible name or as its effective converted name, details.usedBy.matchedOn), 409 pn_names_unverifiable (the names of other nodes on the subnet could not all be read, details.unreadable), 409 node_attribute_list_unavailable (details.attributes, details.reason: the attribute list of the node could not be read, so it cannot be verified that the names can be written), 409 node_attribute_unreadable (details.attributes: the current value of the PROFINET device name or of its auto-generation could not be read, so a failed write could not be rolled back; nothing changed), 409 pn_name_unsupported (not a PROFINET interface, or an attribute the request writes is not writable; details.attributes), 400 bad_request for a blank name, 404 not_found for an unknown device or interface (details lists the interface names). Only the values that differ are written; the result carries `changes` and a `postcheck` (the serve re-reads the node after the write); a mismatch is 409 postcheck_failed (details.mismatches; details.rollback says whether the previous name and auto-generation were restored, verified by a fresh read; details.restoreFailures lists every field

Creates the IO system of a PROFINET controller interface; connect the IO devices to it afterwards with tia_io_system_connect. `controllerInterface` is the interface item name from tia_device_network (default: the primary network interface). `name` and `number` are optional (left out, TIA chooses); a number outside 100-115 is 400 invalid_io_system_number and one another IO system already has is 409 io_system_number_in_use (details.usedBy); when a number is passed and the IO systems of a subnet could not be listed it is 409 subnet_inventory_incomplete (details.gaps). Also refused, nothing changed: 409 not_io_controller, 409 interface_not_connected (connect the interface to a subnet with tia_network_connect first), 409 io_system_exists (details.ioSystem: the controller already has one, use tia_io_system_update), 404 not_found. The result carries `ioSystem` {name, number, subnet} and a `postcheck` (the serve re-reads the IO system after the write); a mismatch is 409 postcheck_failed (details.mismatches): re-read with tia_io_systems before retrying. 409 io_system_create_incomplete (details.error, details.cleanupError, details.ioSystemRemains): setting the number failed and removing the new IO system did not verify, so the project may be partially changed and an IO system may be left on the controller: re-read with tia_io_systems before retrying. dryRun (Gd11) is answered by the serve (needs an open project): it runs the same guards and returns the plan WITHOUT creating anything. Maps to POST /iosystems. M-off.

Renames the IO system of a controller interface and/or changes its number (neither passed: 400 missing_param). `controllerInterface` is the interface item name from tia_device_network (default: the primary network interface). A number outside 100-115 is 400 invalid_io_system_number and one another IO system already has is 409 io_system_number_in_use (details.usedBy), or 409 subnet_inventory_incomplete (details.gaps) when the IO systems of a subnet could not be listed to check it. Also refused, nothing changed: 409 no_io_system (the controller has no IO system: create it with tia_io_system_create), 409 not_io_controller, 404 not_found. Only the values that differ are written; the result carries `ioSystem`, `changes` and a `postcheck` (the serve re-reads the IO system after the write); a mismatch is 409 postcheck_failed (details.mismatches; details.rollback says whether the previous name and number were restored, verified by a fresh read; details.restoreFailures lists every field NOT back at its previous value): re-read with tia_io_systems. dryRun (Gd11) is answered by the serve (needs an open project): it runs the same guards and returns the plan WITHOUT changing anything. Maps to POST /iosystems/update. M-off.

Assigns the interface of an IO device to the IO system of a controller interface. `interface` and `controllerInterface` are interface item names from tia_device_network (default: the primary network interface). The controller must already have an IO system (409 no_io_system: create it with tia_io_system_create) and the device interface must be on the SAME subnet as that IO system (409 cross_subnet_assignment, details.deviceSubnet and details.ioSystemSubnet: connect the device to that subnet with tia_network_connect first; 409 subnet_inventory_incomplete, details.gaps: the subnet of an IO system could not be read, so the check cannot be made). Also refused, nothing changed: 409 not_io_device, 409 already_assigned (the interface is on a DIFFERENT IO system: tia_io_system_disconnect first), 404 not_found; assigning it to the IO system it is already on is a no-op with changes:[]. The result carries `ioSystem`, `changes` and a `postcheck` (the serve re-reads the assignment after the write); a mismatch is 409 postcheck_failed (details.mismatches): re-read with tia_device_network. dryRun (Gd11) is answered by the serve (needs an open project): it runs the same guards and returns the plan WITHOUT changing anything. Maps to POST /iosystems/connect. M-off.

Removes the interface of an IO device from its IO system (to leave the subnet use tia_network_disconnect). `interface` is the interface item name from tia_device_network (default: the primary network interface). Refused, nothing changed: 409 not_io_device, 404 not_found. The result carries `ioSystem:null`, `changes` and a `postcheck` (the serve re-reads the assignment after the write); a mismatch is 409 postcheck_failed (details.mismatches): re-read with tia_device_network. dryRun (Gd11) is answered by the serve (needs an open project): it runs the same guards and returns the plan WITHOUT changing anything. Maps to POST /iosystems/disconnect. M-off.

Creates a tag table on a PLC. Maps to POST /plcs/{plc}/tagtables. M-off.

Deletes a tag table with every tag and constant in it (a user table group is searched; exact name first, then ignoring case). The DEFAULT tag table is refused with 409 default_tag_table (details.table, isDefault:true); an unknown table is 404 not_found. dryRun (Gd11) is answered by the serve (needs an open project): it runs the same guards and lists the tags and constants that would go, WITHOUT deleting. Maps to DELETE /plcs/{plc}/tagtables/{table}. M-off.

App 1.8+ serve returns 400 bad_request (details.field, rule) for quote-bearing names or malformed/type-mismatched/out-of-range absolute addresses. Creates a tag in a table. Refused with 409 name_collision (details.collidesWith = the colliding tag, constant or block) when the name matches, ignoring case, any tag, constant or block of the PLC. The result carries `overlaps`: the OTHER tags whose logical address overlaps this one (informational, never a refusal). Maps to POST /plcs/{plc}/tags. M-off.

Deletes a tag from a table. Maps to DELETE /plcs/{plc}/tagtables/{table}/tags/{tag}. M-off.

App 1.8+ serve returns 400 bad_request (details.field, rule) for quote-bearing names or malformed/type-mismatched/out-of-range absolute addresses, including previews. Updates ONE tag: rename, data type, logical address and the external accessible/visible/writable flags. Only the fields you pass change, and only those that differ from the current value are written (none passed: 400 missing_param; all unchanged: 200 with changes:[]). A rename is refused with 409 name_collision (details.collidesWith = the colliding tag, constant or block) when the new name matches, ignoring case, another tag, constant or block of the PLC; an unknown table or tag is 404 not_found. The result carries `changes` [{field,from,to}] and `overlaps`: the OTHER tags whose address overlaps the final one (informational, never a refusal). dryRun (Gd11) is answered by the serve (needs an open project): it runs the same guards and returns that plan WITHOUT changing anything. Maps to POST /plcs/{plc}/tagtables/{table}/tags/{tag}. M-off.

App 1.8+ serve returns 400 bad_request (details.field, rule) for quote-bearing names or invalid decimal integer literals; typed/radix literals pass through. Creates a user constant in a tag table. Refused with 409 name_collision (details.collidesWith = the colliding tag, constant or block) when the name matches, ignoring case, any tag, constant or block of the PLC. Maps to POST /plcs/{plc}/constants. M-off.

App 1.8+ serve returns 400 bad_request (details.field, rule) for quote-bearing names or invalid decimal integer literals, including previews; typed/radix literals pass through. Updates ONE user constant: rename, data type and value. Only the fields you pass change, and only those that differ from the current value are written (none passed: 400 missing_param; all unchanged: 200 with changes:[]). A rename is refused with 409 name_collision (details.collidesWith = the colliding tag, constant or block) when the new name matches, ignoring case, another tag, constant or block of the PLC; an unknown table or constant is 404 not_found. dryRun (Gd11) is answered by the serve (needs an open project): it runs the same guards and returns the plan {changes:[{field,from,to}]} WITHOUT changing anything. Maps to POST /plcs/{plc}/tagtables/{table}/constants/{constant}. M-off.

Deletes a user constant from a tag table; an unknown table or constant is 404 not_found. dryRun (Gd11) is answered by the serve (needs an open project): it resolves the constant and returns the plan {dataType, value} WITHOUT deleting. Maps to DELETE /plcs/{plc}/tagtables/{table}/constants/{constant}. M-off.

Creates an EMPTY Function Block (empty interface, no logic) by importing a minimal SimaticML skeleton. Supported languages: SCL (the default when `language` is omitted), LAD, FBD, STL or ProDiag, in any case; any other value is refused with 400 bad_request listing them, and a CPU family can still refuse one it does not support. Gd6: for LOGIC use a textual language (SCL) via tia_source_put, or graphical (LAD/FBD) via tia_import_xml. Refused with 409 name_collision (details.collidesWith = the colliding tag, constant or block) when the name matches, ignoring case, any tag, constant or block of the PLC. Maps to POST /plcs/{plc}/fbs. M-off.

Creates an instance DB of an FB. Refused with 409 name_collision (details.collidesWith = the colliding tag, constant or block) when the name matches, ignoring case, any tag, constant or block of the PLC. Maps to POST /plcs/{plc}/instancedbs. M-off.

Creates an organization block (OB) of an event class (eventClass is one of the 15 listed). Gd6: put the LOGIC in afterwards via tia_source_put (SCL/STL) or tia_import_xml (LAD/FBD). `number` optional: omitted → the class's base number when free, else the lowest free one in 123..32767 (non-singleton classes only). An explicit number must be one Siemens permits for the class: ProgramCycle 1 or 123+, Startup 100 or 123+, TimeOfDay 10-17 or 123+, TimeDelayInterrupt 20-23 or 123+, CyclicInterrupt 30-38 or 123+, HardwareInterrupt 40-47 or 123+. Singleton classes (Status, Update, Profile, TimeErrorInterrupt, DiagnosticErrorInterrupt, PullOrPlugOfModules, RackOrStationFailure, ProgrammingError, IOAccessError) hold ONE OB, with the base number: a second one is refused with 409 ob_singleton_exists (details.existing = the OB that holds it). Other refusals: 400 invalid_event_class (details.validClasses), 400 invalid_ob_number (not an integer, outside 1..32767, or not permitted for the class: details.allowed lists the permitted ranges), 409 ob_number_in_use (details.usedBy), 409 ob_number_exhausted, 409 name_collision (details.collidesWith). dryRun (Gd11) is answered by the serve (needs an open project): it runs the same guards and returns the plan {number, eventClass, language, group, createsGroup} WITHOUT creating anything. Maps to POST /plcs/{plc}/obs. M-off.

Deletes a block. Maps to DELETE /plcs/{plc}/blocks/{block}. M-off.

Sets an attribute of a block (e.g., optimized access). Maps to POST /plcs/{plc}/blocks/{block}/attributes. M-off.

Creates a block group. Maps to POST /plcs/{plc}/blockgroups. M-off.

Deletes a block group. `group` is a user group name or a '/'-separated path from the program-blocks root (e.g. Motors/Conveyor; sent as ONE encoded path segment); each level matches the exact name first, then ignoring case. A group that holds any block or subgroup (recursively) is refused with 409 group_not_empty (details.blocks and details.groups list everything that would go) unless recursive:true, which deletes them all; an unknown group is 404 not_found. dryRun (Gd11) is answered by the serve (needs an open project): it returns the same blocks/groups list as the plan WITHOUT deleting. Maps to DELETE /plcs/{plc}/blockgroups/{group}?recursive=true. M-off.

Creates a type group (UDTs). Maps to POST /plcs/{plc}/typegroups. M-off.

Deletes a type (UDT). Maps to DELETE /plcs/{plc}/types/{type}. M-off.

Writes a block from textual SCL source and (optionally) compiles it. Gd6: use THIS for TEXTUAL language (SCL/STL); for graphical (LAD/FBD/GRAPH) use tia_import_xml. With compile:true, the raw compile DTO is nested under 'compile' (same as tia_compile's response), and 'located[]' plus a nextHint are merged at the TOP LEVEL of the result — same place tia_compile puts them — when the compile regenerated blocks, e.g. an instance DB after an FB interface change. `generatedOrUpdated` lists every block the source created or regenerated (app ≥ v1.6.0; older serves list only new ones) — TIA regenerates a block even when the text is identical, so it then needs a compile — and `sourceChanges` gives the per-block change and parts. Stale-write guard: pass the `contentHash` you read (tia_export_block, tia_export_type or tia_type_source) as `expectedContentHash` and the serve checks it BEFORE writing — a mismatch is 409 state_changed and NOTHING is written; a match adds `contentGuard` to the result. `contentHash`, `normalizedSha256` and `sha256` are different hash contracts over different normalizations: never substitute one for another, and pass only the `contentHash` of a fresh read as `expectedContentHash`. `normalizedSha256` now uses wiring-safe UId canonicalization: stored values may change; recompute comparison baselines. It guards exactly ONE object: the code must declare exactly one block or type (else 400 bad_request), and a hash for an object that does not exist (any more) is refused as state_changed — omit it to create. The guard never compiles: an existing block that is not consistent is refused with 409 inconsistent (compile, re-read with tia_export_block, retry), and an existing object whose current export is not well-formed XML cannot be hashed and is refused with 409 unverifiable (NOTHING is written; repair it, or omit expectedContentHash to write without the guard). Needs an app with the guard: an older serve ignores the field and the result says the write was NOT

Imports a block in SimaticML XML (the only path for LAD/FBD/GRAPH — Gd6). PREFER `xml` inline (tested up to ~300 KB: 280 KB imported in 1–5 s); use `path` ONLY for a file that is already on the serve host — never copy files to the host to import them. Gd7: author from a real export for the selected target version; no cross-version import matrix is established. V21 import behavior is unchanged (no new version preflight refusal). See tia_guide recipes, 'TIA version evidence and SimaticML'. Import UDTs FIRST (tia_types_import). Returns, per block, type/number/created/interfaceChanged/affectedInstanceDbs, and — when `xml` was sent inline — a transport check (sha256 sent vs received). Requires app ≥ v1.6.0 for the receipt; with an older serve transport.match is null and there are no per-block fields. An FB whose interface changed makes the next compile regenerate its instance DBs. Stale-write guard: pass the block's `contentHash` from tia_export_block as `expectedContentHash` and the serve checks it against the block's current export BEFORE importing — a mismatch is 409 state_changed and NOTHING is imported; a match adds `contentGuard` to the result. `contentHash`, `normalizedSha256` and `sha256` are different hash contracts over different normalizations: never substitute one for another, and pass only the `contentHash` of a fresh read as `expectedContentHash`. `normalizedSha256` now uses wiring-safe UId canonicalization: stored values may change; recompute comparison baselines. It guards exactly ONE block: the XML (or the file at `path`) must contain exactly one block (else 400 bad_request), and a hash for a block that does not exist (any more) is refused as state_changed — omit it to create. The guard never compiles: a block that is not consistent is refused with 409 inconsistent (compile, re-read with tia_export_block, retry), and one whose current export is not well-formed XML cannot be hashed and is refused with 409 unverifiable (NOTHING is imported; repair it, or o

Imports a UDT in SimaticML XML. Use a real export for the selected target; cross-version import compatibility is unverified, and V21 import behavior is unchanged (no new version preflight refusal). See tia_guide recipes, 'TIA version evidence and SimaticML'. Import UDTs BEFORE the blocks that use them (Gd6). Stale-write guard: pass the type's `contentHash` from tia_export_type (or tia_type_source) as `expectedContentHash` and the serve checks it against the type's current export BEFORE importing — a mismatch is 409 state_changed and NOTHING is imported; a match adds `contentGuard` to the result. `contentHash`, `normalizedSha256` and `sha256` are different hash contracts over different normalizations: never substitute one for another, and pass only the `contentHash` of a fresh read as `expectedContentHash`. `normalizedSha256` now uses wiring-safe UId canonicalization: stored values may change; recompute comparison baselines. It guards exactly ONE type: the XML (or the file at `path`) must contain exactly one type (else 400 bad_request), and a hash for a type that does not exist (any more) is refused as state_changed — omit it to create; an existing type whose current export is not well-formed XML cannot be hashed and is refused with 409 unverifiable (NOTHING is imported; repair it, or omit expectedContentHash to write without the guard). Returns changeImpact/compileImpact (flags/members), memberCapture and readGaps (unknown); trackChanges:false skips observation. See tia_guide gotchas. Needs an app with the guard: an older serve ignores the field and the result says the import was NOT guarded. dryRun never verifies it. Maps to POST /plcs/{plc}/types/import. M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Exports the PLC's blocks and types to SimaticML XML files in a directory (project-as-code). Maps to POST /plcs/{plc}/export. M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Creates a watch table. Maps to POST /plcs/{plc}/watchtables. M-off.

Deletes a watch table. Maps to DELETE /plcs/{plc}/watchtables/{wt}. M-off.

Acquires a service from an object by handle (generic GetService<T>) and returns a service HANDLE, to then invoke methods via tia_obj_invoke. E.g.: PlcMasterSecretConfigurator.Protect — unlocks a bare CPU (offline confidential-data password; generates the certificate). The acquisition itself does NOT mutate the project. Maps to POST /obj/{handle}/service {type}. M-off.

Sets attributes of any model object by handle. Maps to POST /obj/{handle}/attributes. M-off. Use the handles from the read-only obj tools (M1).

Invokes a method of a model object by handle (args coerced to the parameter types; {"$handle":N} passes another object). Maps to POST /obj/{handle}/invoke. M-off. Powerful — combine with tia_obj_info to see the signature.

Creates an object in a composition of a parent object by handle. Maps to POST /obj/{handle}/create. M-off. See the creatable types in tia_obj_creationinfos. DeviceUserGroup.Devices creation is refused with 409 unsafe_object_creation before V21 CreateDevices can terminate TIA; use tia_device_create with group instead (app 1.8.1+).

Exports ONE block as SimaticML XML and returns it INLINE with sha256, normalizedSha256 and bytes — no file on the serve host. `contentHash` is the stale-write guard hash: the SHA-256 of this block's export with the DEFAULT options after removing volatile noise (Created, InstalledProducts, formatting tokens, line endings, layout whitespace between tags; whitespace INSIDE text, comments and string values is part of the hash) and renumbering the UIds canonically, so a renumbering by TIA never changes it while a rewiring does; the serve computes it, so it stays the default-options hash even when you ask for other options, and it exists only for a well-formed XML export: otherwise the XML is still returned, `contentHash` is absent and `contentHashError` says why. `normalizedSha256` uses the tia_block_compare normalization (canonical UIds preserve wiring); `sha256` hashes the raw text. `contentHash`, `normalizedSha256` and `sha256` are different hash contracts over different normalizations: never substitute one for another, and pass only the `contentHash` of a fresh read as `expectedContentHash`. `normalizedSha256` now uses wiring-safe UId canonicalization: stored values may change; recompute comparison baselines. Pass the `contentHash` as `expectedContentHash` to tia_import_xml or tia_source_put and the write is refused with 409 state_changed if the block changed in the project after this read (the guarded write itself never compiles: a block that is not consistent is refused with 409 inconsistent — compile, re-read with this tool, retry; one whose current export is not well-formed XML is refused with 409 unverifiable); an older serve returns no contentHash. Read-mostly — it does not change code/data, but the export may compile an inconsistent block first if needed (export requires consistency), which can regenerate its instance DB; treated as read for agent tool policy. Maps to GET /plcs/{plc}/blocks/{block}/xml. V21 is the fixture baseline; preserve the target's Engine

Exports the block from the project and compares it with the SimaticML you pass (e.g. the file committed in git). Like tia_export_block, this may compile an inconsistent block first (export requires consistency), which can regenerate its instance DB; read-mostly, treated as read for agent tool policy. Normalized: ignores BOM, line endings, indentation, blank lines, <Created>, <InstalledProducts> and — unless ignoreFormatting:false — <NewLine/>/<Blank/> formatting tokens (see the result's `ignored` field for the exact list). UIds are renumbered by first appearance across definitions and references: rewiring differs, pure renumbering matches; UId-like text in comments and values is preserved. Returns verdict equal|different and the first differing line. `normalizedSha256` now uses wiring-safe UId canonicalization: stored values may change; recompute comparison baselines. This is the proof that the project contains what was versioned. Maps to GET /plcs/{plc}/blocks/{block}/xml. Engineering version and schema namespaces remain significant; equality is not cross-version import acceptance. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Class R, pure/offline: never calls serve. Pass XML text, not a file path: use the inline xml field of tia_export_block {plc, block}. Renders ONE SimaticML block as readable pseudo-SCL: LAD/FBD contacts, coils, logic boxes, comparators, MOVE/arithmetic, timers, counters, edges and block calls become SCL-like statements; SCL networks are rebuilt from their tokens; STL/GRAPH networks are marked not rendered. A value read by several statements or assigned to several targets is evaluated once: held in an RLO_<UId> temporary (UId of the part producing it) or read back from the first coil that wrote it. A MOVE/arithmetic output read by another part is inlined only when the box is always enabled; otherwise IF <EN> THEN TMP_<UId> := <value>; END_IF; and the reader uses TMP_<UId>, which keeps its previous (stale) value when EN is false. The output or return value of ONE call is TMP_<UId>_<pin> when it has several targets or, for an FC (no instance), when another part reads it or it is negated: bound in the call (pin => TMP_<UId>_<pin>, or TMP_<UId>_<pin> := call(args); for the return value), and targets and readers copy from it; two calls never share one. A call with an instance and one target is direct or read as #inst.pin. An edge (P_TRIG/N_TRIG) runs every scan: used inside an IF <EN> body it is evaluated before the IF (RLO_<UId> := P_TRIG(...);), not conditional on that EN. A negated output pin shows as NOT (a negated instance or call output: a following line target := NOT #t.Q; under the same EN). TYPE#(x) is x read as TYPE: an absolute address of a non-natural type for its size shows its own type (INT#(%MW0)); a comparator, arithmetic box or Inc/Dec casts with the instruction type every operand but a constant, a boolean or one of that type, values forwarded by MOVE, a box or a call too (INT#(RLO_40), INT#(TMP_41)); constants and written places are never cast. What it cannot translate stays visible as (* unsupported: ... *) and is listed in unsupported, as are a duplicat

Exports ONE user data type (UDT) as SimaticML XML and returns it INLINE with sha256, normalizedSha256 and bytes — hashed exactly like tia_export_block, no file on the serve host. `contentHash` is the stale-write guard hash, defined as in tia_export_block (SHA-256 of the default-options export with volatile noise removed and UIds renumbered canonically; it exists only for a well-formed XML export: otherwise the XML is still returned, `contentHash` is absent and `contentHashError` says why). `contentHash`, `normalizedSha256` and `sha256` are different hash contracts over different normalizations: never substitute one for another, and pass only the `contentHash` of a fresh read as `expectedContentHash`. `normalizedSha256` now uses wiring-safe UId canonicalization: stored values may change; recompute comparison baselines. Pass the `contentHash` as `expectedContentHash` to tia_types_import and the write is refused with 409 state_changed if the type changed in the project after this read (an existing type whose current export is not well-formed XML is refused with 409 unverifiable); an older serve returns no contentHash. It never compiles: a type that is not consistent is refused with 409 inconsistent (compile the PLC first with tia_compile) and an unknown type with 404 not_found (exact name first, then ignoring case). Maps to GET /plcs/{plc}/types/{type}/xml. Class R. V21 is the fixture baseline; use target-local exports, never rewrite version markers to down-convert a UDT. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Reads the SCL source of ONE user data type (UDT) and returns it INLINE with the sha256 of the code (UTF-8) and bytes. It never compiles: a type that is not consistent is refused with 409 inconsistent (compile the PLC first with tia_compile) and an unknown type with 404 not_found. `contentHash` is the stale-write guard hash of the SimaticML export (default options) of the SAME type, not of this SCL text, so what you read as SCL can be guarded like with like: pass it as `expectedContentHash` to tia_source_put (a TYPE source) or tia_types_import. The `sha256` it returns is the hash of the SCL code, and the XML reads' `normalizedSha256` is the tia_block_compare normalization (canonical UIds preserve wiring). `contentHash`, `normalizedSha256` and `sha256` are different hash contracts over different normalizations: never substitute one for another, and pass only the `contentHash` of a fresh read as `expectedContentHash`. `normalizedSha256` now uses wiring-safe UId canonicalization: stored values may change; recompute comparison baselines. It exists only for a well-formed XML export of the type: when the serve could not compute it `contentHash` is absent and `contentHashError` says why (the code is still returned); an older serve returns neither. Maps to GET /plcs/{plc}/types/{type}/source. Class R. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Lists the master copies in the open project's library (names, from every folder). Maps to GET /library/mastercopies. Read-only (class R).

无需输入参数。

Creates a master copy of a DEVICE (station) in the open project's library and returns its name. Only a device is accepted as the source — a PLC block cannot become a master copy through this route. Maps to POST /library/mastercopies {device}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Requires app ≥ v1.8.0. Creates a new station from a device master copy in the open project's library (name from tia_library_mastercopies), returning {device: actualName}; TIA may rename the copy and its PLC. Known block-only content is refused with 409 mastercopy_not_device; unknown content goes to Openness. Clones an owner-prepared configuration, including PUT/GET, purchased-license selection and OPC UA interface mappings on the validated 1214C V4.4; it is not a setter for an existing CPU and does not grant license entitlement. Certificates are not copied: inspect the new OPC UA item, regenerate its server certificate if needed and compile before any human-gated download. Maps to POST /devices/frommastercopy {masterCopy}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Lists the types in the open project's library with their versions as {name, ns, guid, status, versions:[{version, state, isDefault, author, modified, guid}]}. Maps to GET /library/types. Read-only (class R).

无需输入参数。

Creates a PLC block from a master copy of the open project's library (name from tia_library_mastercopies) and returns the new block's name. The master copy must hold PLC blocks: one that holds hardware and no block — e.g. a device master copy, the only kind tia_library_mastercopy_create makes — is refused with 409 kind:"mastercopy_not_blocks" by serves after app 1.6.3 (up to 1.6.3: 500 "Copying from the library failed"); other non-block content (a UDT or tag-table copy) still fails inside Openness. Maps to POST /plcs/{plc}/blocks/frommastercopy {masterCopy}. Class M-off.

Lists the names of the global libraries open in the TIA Portal session (system libraries included). Maps to GET /globallibraries. Read-only (class R).

无需输入参数。

Creates a new global library on disk (directory on the serve host) and opens it in the TIA Portal session; returns its name. Maps to POST /globallibraries {directory, name}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Opens a global library file (.alNN on the serve host, e.g. MyLib.al21 — the file inside the library folder) in the TIA Portal session and returns its name; readWrite defaults to true (pass false to open it read-only). Serves after app 1.6.3 refuse an unusable path before TIA, nothing opened: a missing file is 404 kind:"not_found"; a folder, a file that is not .alNN or a malformed path (e.g. with quotes) is 400 kind:"bad_request" (up to 1.6.3: 500 internal). Maps to POST /globallibraries/open {path, readWrite}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Saves an open user global library by name (from tia_global_libraries; exact name first, then ignoring case) and returns its name as {saved}. Serves after app 1.6.3 refuse a name that picks no single open USER library, nothing saved: an unknown name is 404 kind:"not_found"; a system or corporate library (read-only), or a name several user libraries match only ignoring case, is 409 kind:"conflict"; details.userLibraries / systemLibraries / corporateLibraries list the open libraries (up to 1.6.3: 200 {saved:<name>} even when nothing was saved — confirm the name with tia_global_libraries first). A user library opened read-only (tia_global_library_open with readWrite:false) cannot be saved: 409 kind:"conflict" with details.readOnly:true after app 1.6.3 (up to 1.6.3: 500 internal) — close it and open it again with readWrite:true to change and save it. Maps to POST /globallibraries/save {name}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Closes an open user global library by name (from tia_global_libraries; exact name first, then ignoring case; unsaved changes are not saved — call tia_global_library_save first) and returns its name as {closed}. Serves after app 1.6.3 refuse a name that picks no single open USER library, nothing closed: an unknown or already-closed name is 404 kind:"not_found"; a system or corporate library (read-only), or a name several user libraries match only ignoring case, is 409 kind:"conflict"; details.userLibraries / systemLibraries / corporateLibraries list the open libraries (up to 1.6.3: 200 {closed:<name>} even when nothing was closed — confirm the name with tia_global_libraries first). A library open read-only can be closed. Maps to POST /globallibraries/close {name}. Class M-off.

Lists the HMIs in the open project as {kind, name}: kind "classic" (WinCC Classic HmiTarget) or "unified" (WinCC Unified). Maps to GET /hmi. Read-only (class R).

无需输入参数。

Lists the screen names of an HMI (Classic: every screen folder, recursively; Unified: flat). Maps to GET /hmi/{hmi}/screens. Read-only (class R).

Exports one screen of a CLASSIC WinCC HMI to an XML file on the serve host. WinCC Unified screens have no file export in the V21 API (the serve refuses them). Writes the file only — the project is not changed. Maps to POST /hmi/{hmi}/screens/{screen}/export {path}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Imports the screens of an XML file on the serve host into the root screen folder of a CLASSIC WinCC HMI; a screen with the same name is OVERWRITTEN. WinCC Unified is refused (no file import in the V21 API). Returns the imported screen names. Maps to POST /hmi/{hmi}/screens/import {path}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Exports the hardware configuration as CAx / AutomationML (.aml) to a file on the serve host: one device when `device` is given, otherwise the whole project. Writes the file only — the project is not changed. Returns the transfer state, errors, warnings and messages (capped; messagesTruncated); a transfer whose state is Error or that counts any error is an error (500 cax_transfer_failed, those fields in details), and `unreadable` flags an outcome that could not be fully read. Serves up to app 1.6.3 return only an opaque `result` string even when the transfer failed — check the outcome with tia_devices. Maps to POST /cax/export {device?, file}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Imports a CAx / AutomationML (.aml) file on the serve host into the open project's hardware configuration. `option` decides what happens to a device that already exists: RetainTiaDevice (default — keep the project's device), OverwriteTiaDevice (replace it) or MoveToParkingLot. Archive the project first (tia_project_archive) before an overwrite: a failed import may have applied part of the file. Returns the transfer state, errors, warnings and messages (capped; messagesTruncated); a transfer whose state is Error or that counts any error is an error (500 cax_transfer_failed, those fields in details), and `unreadable` flags an outcome that could not be fully read. Serves up to app 1.6.3 return only an opaque `result` string even when the transfer failed — check the outcome with tia_devices. Maps to POST /cax/import {file, option}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Lists the Project Server connections configured in TIA Portal on the serve host as {servers:[{name, host, port}], total}; an empty list is valid (none configured). Reads the local configuration only. Use `name` as `server` in tia_project_server_groups, tia_server_projects and tia_server_project_sessions. Needs a running TIA Portal on the serve host (tia_start) but no open project. Maps to GET /multiuser/servers. Read-only (class R).

无需输入参数。

Lists the project groups of one Project Server as {server, groups:[{name}], total}; `server` is the connection name from tia_project_servers (exact name first, then ignoring case) and comes back resolved. Contacts the Project Server with the Windows user of the serve. An unknown name is 404 not_found (details.available lists the names that work), a name that matches several is 409 ambiguous_name (details.matches), and a Project Server that is unreachable or refuses the Windows user of the serve is 502 project_server_error (details.server, operation, type, message). Needs a running TIA Portal on the serve host (tia_start) but no open project. Maps to GET /multiuser/servers/{server}/groups. Read-only (class R).

Lists the projects of a Project Server with their lock state: every project of the server, or only those of `group` (matched like `server`). A page is {server, group, projects:[{projectName, serverAlias, lockState:{isLocked, owner, error}}], total, nextCursor}; the lock state is read for the projects of the returned page only, a failed lock read gives isLocked:null with the reason in error instead of failing the call, and owner is null when the project is not locked. For a large server read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null; total is the number of projects of the whole list. Without limit and cursor the whole list is returned. An unknown name is 404 not_found (details.available lists the names that work), a name that matches several is 409 ambiguous_name (details.matches), and a Project Server that is unreachable or refuses the Windows user of the serve is 502 project_server_error (details.server, operation, type, message). Needs a running TIA Portal on the serve host (tia_start) but no open project. Maps to GET /multiuser/servers/{server}/projects?group=&limit=&cursor= (the last three optional). Read-only (class R).

Lists the local sessions that exist for one server project on the serve host, created by the Windows user of the serve, as {server, project, sessions:[{sessionId, projectFile}], total}; projectFile is the session file (.alsNN) or null. Pass projectFile to tia_local_session_open. `project` is the project name from tia_server_projects (exact name first, then ignoring case). An unknown name is 404 not_found (details.available lists the names that work), a name that matches several is 409 ambiguous_name (details.matches), and a Project Server that is unreachable or refuses the Windows user of the serve is 502 project_server_error (details.server, operation, type, message). Needs a running TIA Portal on the serve host (tia_start) but no open project. Maps to GET /multiuser/servers/{server}/projects/{project}/sessions. Read-only (class R).

Lists the local multiuser sessions open in the TIA Portal of the serve as {sessions:[{index, name, path, handle, isModified, isUpToDate, upToDateError, attributes}], total}; an empty list is valid (single-user project or no session open). `handle` is the object handle of the session's project: read and edit it with tia_obj_get, tia_obj_items and the other tia_obj_* tools. isUpToDate asks the Project Server and is null with upToDateError when that call failed. Use name or path as `session` in the other session tools. Needs a running TIA Portal on the serve host (tia_start) but no open project. Maps to GET /multiuser/localsessions. Read-only (class R).

无需输入参数。

Lists the objects marked for check-in in a local session as {session:{index, name, path}, conflictedOnly, markings:[{handle, type, name, markState, isUpToDate, isMarkedByMe, isMarkedByOthers}], total, nextCursor}, read in real time from the Project Server. Marking selects objects of YOUR local session for check-in; other users only see them as marked in another local session. conflicted:true lists only the conflicted markings (an object also marked in another local session, or out of date), which must be resolved before check-in. Every object has a `handle` for the tia_obj_* tools. For a large session read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null. Without limit and cursor the whole list is returned. A page is refused with 409 paging_unavailable (details.incomplete, details.total) when the ancestry of some marked objects cannot be read: call again without limit and cursor, or retry. `session` is the name or the full path of an open local session (as listed by tia_local_sessions; the project path first, then the project name ignoring case) and may be left out when exactly one session is open: none open is 409 no_local_session, several open without `session` (or a selector that matches several) is 409 ambiguous_session (details.sessions lists index, name and path), an unknown one is 404 not_found. Needs a running TIA Portal on the serve host (tia_start) but no open project. Maps to GET /multiuser/localsessions/markings?session=&conflicted=&limit=&cursor= (all optional). Read-only (class R).

Reads the mark state of objects of a local session as {session:{index, name, path}, objects:[{handle, type, name, isMarkable, markState, isUpToDate, isMarkedByMe, isMarkedByOthers}]}. markState is the flags text (for example "IsUptoDate, IsMarkedByMe") and the three booleans are its flags; an object with isMarkable:false cannot be marked. Object handles (positive integers) come from the `handle` fields of tia_local_sessions and tia_markings or from the tia_obj_* tools on the session's project; they die with the session. Missing handles is 400 missing_param, malformed or more than 200 is 400 bad_request, an unresolvable handle is 404 not_found. `session` is the name or the full path of an open local session (as listed by tia_local_sessions; the project path first, then the project name ignoring case) and may be left out when exactly one session is open: none open is 409 no_local_session, several open without `session` (or a selector that matches several) is 409 ambiguous_session (details.sessions lists index, name and path), an unknown one is 404 not_found. Needs a running TIA Portal on the serve host (tia_start) but no open project. Maps to GET /multiuser/localsessions/markstate?session=&handles=1,2,3. Read-only (class R).

Opens a local multiuser session (a .alsNN file on the serve host, for example the projectFile of tia_server_project_sessions) in the TIA Portal of the serve. The portal MUST hold NO open project and no other session: start it without a project (tia_start, not tia_connect). Do NOT call tia_connect first: it opens a project, and an open project is refused with 409 project_open (details.openProjects). No portal running is 409 not_connected: start one with tia_start, never with tia_connect. A different session already open is 409 session_open (details.openSessions); nothing is ever closed to make room. The same session already open is an idempotent success (alreadyOpen:true). A missing file is 404 not_found; a folder, a file that is not .alsNN or a malformed path is 400 bad_request; nothing was opened. Opening the session of a UMAC-protected project may wait on a Siemens logon dialog on the serve host that a human must answer (GATE G6: never invent credentials): a long wait answers status running, and a call that times out while the serve is alive returns a requires_human_action handoff. Returns {opened, alreadyOpen, session} with the session as in tia_local_sessions; its `handle` reaches the session's objects through tia_obj_*. dryRun (Gd11) is answered by the serve: it runs the same checks and returns the plan or the same refusal WITHOUT changing anything. Nothing is ever checked in to the Project Server: check-in (CloseAndCommit) is not offered by any tool. Maps to POST /multiuser/localsessions/open {path}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Saves the changes of a local session in the session itself with LocalSession.Save(); it never checks in to the Project Server. Only a multiuser or an exclusive session can be saved: a server-project session is refused with 409 save_not_supported and nothing is changed. Returns {saved:true, session:{index, name, path, ...}}. `session` is the name or the full path of an open local session (as listed by tia_local_sessions; the project path first, then the project name ignoring case) and may be left out when exactly one session is open: none open is 409 no_local_session, several open without `session` (or a selector that matches several) is 409 ambiguous_session (details.sessions lists index, name and path), an unknown one is 404 not_found. dryRun (Gd11) is answered by the serve and reports the session and its isModified WITHOUT saving. Nothing is ever checked in to the Project Server: check-in (CloseAndCommit) is not offered by any tool. Maps to POST /multiuser/localsessions/save {session?}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Closes a local session; it NEVER checks in to the Project Server. Closing discards every pending change of the session, so a session with unsaved changes (or whose modified state cannot be read) is refused with 409 unsaved_changes (details.session, details.path) until the call chooses: save:true saves it first (multiuser or exclusive sessions only; otherwise 409 save_not_supported and nothing is closed) or discard:true drops the changes; both together are 400 bad_request. Every object handle of the session dies with it. Returns {closed:true, action, session} with action close, save_then_close or discard_then_close. `session` is the name or the full path of an open local session (as listed by tia_local_sessions; the project path first, then the project name ignoring case) and may be left out when exactly one session is open: none open is 409 no_local_session, several open without `session` (or a selector that matches several) is 409 ambiguous_session (details.sessions lists index, name and path), an unknown one is 404 not_found. dryRun (Gd11) is answered by the serve and reports the action or the same refusal WITHOUT closing. Nothing is ever checked in to the Project Server: check-in (CloseAndCommit) is not offered by any tool. Maps to POST /multiuser/localsessions/close {session?, save?, discard?}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Marks objects of a local session for check-in. Marking selects objects of YOUR session: it does not lock them for others, who only see them as marked in another local session, and an object another session also marked is a conflict to resolve before check-in. Object handles (positive integers) come from the `handle` fields of tia_local_sessions and tia_markings or from the tia_obj_* tools on the session's project; they die with the session. 1 to 200 distinct handles. Refused, nothing changed: an object that is not markable is 409 not_markable (details.objects); an object another session marked and this one has not is 409 marked_by_others unless allowConflict:true, which marks it anyway and lists it in `conflicts` (only when the human wants the conflict). An object this session already marked is skipped (already_marked); with nothing to apply the answer is 200 with applied:[]. Returns {action, session, applied, skipped, conflicts, states}. Undo with tia_objects_unmark. `session` is the name or the full path of an open local session (as listed by tia_local_sessions; the project path first, then the project name ignoring case) and may be left out when exactly one session is open: none open is 409 no_local_session, several open without `session` (or a selector that matches several) is 409 ambiguous_session (details.sessions lists index, name and path), an unknown one is 404 not_found. dryRun (Gd11) is answered by the serve (toApply, skipped, conflicts or the same refusal) WITHOUT marking. Nothing is ever checked in to the Project Server: check-in (CloseAndCommit) is not offered by any tool. Maps to POST /multiuser/localsessions/markings/mark {session?, handles, allowConflict?}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Removes the mark for check-in that THIS session put on objects (handles as in tia_objects_mark, for example from tia_markings or the tia_obj_* tools); the mark of other sessions is never touched, so it is never refused because of other users. An object this session did not mark is skipped (not_marked); with nothing to apply the answer is 200 with applied:[]. Returns {action, session, applied, skipped, states}. Refusals: no_local_session, ambiguous_session, 404 not_found for an unresolvable handle. `session` is the name or the full path of an open local session (as listed by tia_local_sessions; the project path first, then the project name ignoring case) and may be left out when exactly one session is open: none open is 409 no_local_session, several open without `session` (or a selector that matches several) is 409 ambiguous_session (details.sessions lists index, name and path), an unknown one is 404 not_found. dryRun (Gd11) is answered by the serve (toApply, skipped or the same refusal) WITHOUT unmarking. Nothing is ever checked in to the Project Server: check-in (CloseAndCommit) is not offered by any tool. Maps to POST /multiuser/localsessions/markings/unmark {session?, handles}. Class M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Lists the tag tables of a WinCC Unified HMI as {hmi, tagTables:[{name, group, tagCount}], total, nextCursor, inventoryGaps}; group is the "/"-joined path of the tag table group (null at the root) and tagCount the number of tags in the table. Use it before creating or deleting a tag table and to find the table a tag lives in (tia_hmi_tags takes it as `table`). For a large HMI read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null; total is the number of tag tables of the whole list. Without limit and cursor the whole list is returned with nextCursor null. A cursor of a list that changed is 409 cursor_stale (restart without cursor), one that is not a nextCursor is 400 invalid_cursor. `inventoryGaps` [{kind, subject, reason}] lists every value or object the serve could not read while building the answer (empty when all reads succeeded): the unreadable value is null and one gap names it, so a null next to a gap means unreadable, while a value the object does not offer is null without a gap. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to GET /hmi/{hmi}/tagtables?limit=&cursor= (both optional). Read-only (class R).

Lists the tags of a WinCC Unified HMI as {hmi, table, tags:[{name, table, tagType, dataType, connection, plcName, plcTag, address, accessMode, acquisitionMode, acquisitionCycle}], total, nextCursor, inventoryGaps}, every value text or null. Use it to see what exists before creating, updating or deleting a tag or an alarm. An internal tag has connection, plcName, plcTag, address, accessMode, acquisitionMode and acquisitionCycle all null (TIA reads its connection back as a placeholder such as <Internal tag>, which the serve answers as null); an external tag names its connection and the PLC tag or address it reads. `table` limits the list to one tag table (an unknown table is 404 not_found) and is echoed back, null when not given. For a large HMI read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null; total is the number of tags of the whole list. Without limit and cursor the whole list is returned with nextCursor null. A cursor of a list that changed is 409 cursor_stale (restart without cursor), one that is not a nextCursor is 400 invalid_cursor. `inventoryGaps` [{kind, subject, reason}] lists every value or object the serve could not read while building the answer (empty when all reads succeeded): the unreadable value is null and one gap names it, so a null next to a gap means unreadable, while a value the object does not offer is null without a gap. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to GET /hmi/{hmi}/tags?table=&limit=&cursor= (all optional). Read-only (class R).

Lists the connections of a WinCC Unified HMI as {hmi, connections:[{name, communicationDriver, station, partner, node, initialAddress, disabledAtStartup, comment, plc}], total, nextCursor, inventoryGaps}; `plc` is the name of the one PLC the partner resolves to, or null when none or several match. Use it before creating an external tag: the connection must exist and plc says whether plcName can be left out. For a large HMI read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null; total is the number of connections of the whole list. Without limit and cursor the whole list is returned with nextCursor null. A cursor of a list that changed is 409 cursor_stale (restart without cursor), one that is not a nextCursor is 400 invalid_cursor. `inventoryGaps` [{kind, subject, reason}] lists every value or object the serve could not read while building the answer (empty when all reads succeeded): the unreadable value is null and one gap names it, so a null next to a gap means unreadable, while a value the object does not offer is null without a gap. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to GET /hmi/{hmi}/connections?limit=&cursor= (both optional). Read-only (class R).

Lists the alarms of a WinCC Unified HMI as {hmi, kind, alarms:[{kind, name, alarmClass, priority, triggerTag, triggerBit, triggerBitAddress, triggerMode, condition, conditionValue, triggerAddress, eventText}], total, nextCursor, inventoryGaps}. Discrete alarms come first, then analog ones; a discrete alarm fills triggerBit, triggerBitAddress and triggerMode, an analog one fills condition, conditionValue and triggerAddress, and the fields of the other kind are null. eventText is {culture name: plain text or null} for every active project language: TIA stores the text as rich text and the serve answers a body that holds one paragraph of text only as that plain text (an item without text is an empty string, a language without an item null); any other markup comes back unchanged as raw rich text, which cannot be written back. conditionValue is a JSON number, except a whole value held by an integer-backed trigger tag (LInt, ULInt, LWord, ...) whose magnitude is greater than 2^53: that is a decimal string, up to 18446744073709551615 (TIA stores the value as a double, so only an alarm that already existed could hold one: unverified that TIA reports it). A Real or LReal value is always a number, even when whole and large (1e20), so it can be passed back as input. `kind` limits the list to discrete or analog alarms and is echoed back. Use it before creating, updating or deleting an alarm. For a large HMI read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null; total is the number of alarms of the whole list. Without limit and cursor the whole list is returned with nextCursor null. A cursor of a list that changed is 409 cursor_stale (restart without cursor), one that is not a nextCursor is 400 invalid_cursor. `inventoryGaps` [{kind, subject, reason}] lists every value or object the serve could not read while building the answer (empty when all reads succeeded): the unreadable value is null and one gap names it, so a null

Lists the alarm classes of a WinCC Unified HMI as {hmi, alarmClasses:[{name, id, priority, stateMachine, log, isSystem, commonAlarmClass}], total, nextCursor, inventoryGaps}; commonAlarmClass is null when TIA reports a placeholder such as <No alarm class> instead of a class. Use it before creating or updating an alarm: its alarmClass must be one of these names. For a large HMI read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null; total is the number of alarm classes of the whole list. Without limit and cursor the whole list is returned with nextCursor null. A cursor of a list that changed is 409 cursor_stale (restart without cursor), one that is not a nextCursor is 400 invalid_cursor. `inventoryGaps` [{kind, subject, reason}] lists every value or object the serve could not read while building the answer (empty when all reads succeeded): the unreadable value is null and one gap names it, so a null next to a gap means unreadable, while a value the object does not offer is null without a gap. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to GET /hmi/{hmi}/alarmclasses?limit=&cursor= (both optional). Read-only (class R).

Lists the items of ONE screen of a WinCC Unified HMI as {hmi, screen, screenNumber, width, height, items:[{name, type, visible, enabled, left, top, width, height}], total, nextCursor, inventoryGaps}; type is the item class (HmiButton, HmiIOField, ...) and the layout values are null for a type that does not offer them. Items are flat: the V21 API exposes no nested items. Use it to inspect a screen (screen names come from tia_hmi_screens); an unknown screen is 404 not_found. For a large HMI read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null; total is the number of items of the whole list. Without limit and cursor the whole list is returned with nextCursor null. A cursor of a list that changed is 409 cursor_stale (restart without cursor), one that is not a nextCursor is 400 invalid_cursor. `inventoryGaps` [{kind, subject, reason}] lists every value or object the serve could not read while building the answer (empty when all reads succeeded): the unreadable value is null and one gap names it, so a null next to a gap means unreadable, while a value the object does not offer is null without a gap. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to GET /hmi/{hmi}/screens/{screen}/items?limit=&cursor= (both optional). Read-only (class R).

Runs the validation of every tag, alarm, connection and screen (with its items) of a WinCC Unified HMI, as far as the scope selects, and lists what it reports as {hmi, scope, checked:{tags, alarms, connections, screens, screenItems}, errors, warnings, findings:[{objectKind, object, property, errors, warnings}], total, nextCursor, inventoryGaps}. This is NOT a compile: the V21 API has none for Unified, so no result says the HMI compiles, and `checked` counts the objects that were validated (0 for a scope not selected). Use it after tag or alarm writes, which do not scan screens, scripts or logging for references. errors and warnings count the WHOLE result, not the page; a finding is one object property with at least one error or warning, and a validation that threw is a finding with property null plus an inventoryGaps entry. `scope` is all (default), tags, alarms, connections or screens. A big HMI can take minutes: narrow with scope. For a large HMI read it in pages: pass limit (1-1000), then pass the nextCursor of each page as cursor until nextCursor is null; total is the number of findings of the whole list. Without limit and cursor the whole list is returned with nextCursor null. A cursor of a list that changed is 409 cursor_stale (restart without cursor), one that is not a nextCursor is 400 invalid_cursor. `inventoryGaps` [{kind, subject, reason}] lists every value or object the serve could not read while building the answer (empty when all reads succeeded): the unreadable value is null and one gap names it, so a null next to a gap means unreadable, while a value the object does not offer is null without a gap. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to GET /hmi/{hmi}/validate?scope=&limit=&cursor= (all optional). Read-only (class R). Long operation: may a

Creates a tag table in a WinCC Unified HMI. Refused, nothing changed: 400 invalid_name (details.kind, name, rule) for a blank, over-long or malformed name, 409 name_collision (details.existing) for a used name. The result is {hmi, tagTable, created:true, postcheck}. dryRun (Gd11) is answered by the serve: it runs every guard the real write runs and answers {dryRun:true, status:"plan_ok", hmi, ...} with no `postcheck`, changing nothing. A real write answers the re-read values and a `postcheck` {verified:true, requested, actual}; a mismatch is 409 postcheck_failed (details.mismatches, details.rollback: restored, not_restored or not_attempted): re-read before anything else. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to POST /hmi/{hmi}/tagtables {name}. M-off.

Deletes a tag table of a WinCC Unified HMI. Refused, nothing changed: 404 not_found, 409 default_tag_table for the default table, 409 tag_table_not_empty (details.tags) while it holds tags unless recursive:true, which deletes its tags with it, and 409 tag_in_use (details.references) when an alarm references any of those tags. Screens, scripts and logging that use the tags are NOT scanned: run tia_hmi_validate afterwards. A recursive delete that stops part-way is 409 tag_table_delete_incomplete: the project IS partially changed (the tags already removed stay removed), so re-read with tia_hmi_tags before repeating it. A dryRun lists the tags and the group path; a real delete answers {hmi, tagTable, deleted:true, removedTags, postcheck:{exists:false, tagsRemaining:0}}. dryRun (Gd11) is answered by the serve: it runs every guard the real write runs and answers {dryRun:true, status:"plan_ok", hmi, ...} with no `postcheck`, changing nothing. A real write answers the re-read values and a `postcheck` {verified:true, requested, actual}; a mismatch is 409 postcheck_failed (details.mismatches, details.rollback: restored, not_restored or not_attempted): re-read before anything else. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to DELETE /hmi/{hmi}/tagtables/{table}?recursive=true. M-off.

Creates a tag in a WinCC Unified HMI, in `table` or the default tag table. A tag WITHOUT `connection` is internal: dataType is required and plcName, plcTag, address, accessMode, acquisitionMode and acquisitionCycle are refused (400 bad_request). A tag WITH `connection` is external: the connection must exist (409 reference_not_found; tia_hmi_connections lists them), exactly one of plcTag or address is given, and dataType is optional. The PLC of a plcTag is plcName, else the one PLC the connection's partner resolves to (none or several: 409 plc_unresolved). A plcTag is a PLC tag or a data block member path (struct and UDT members, array elements with literal in-bounds indices): one that matches no tag or block is 409 reference_not_found, one that cannot be established is 409 plc_reference_unresolved (details.segment, reason), possibly a false refusal when the DB or a UDT is inconsistent: compile the PLC first. A PLC tag name with a dot is sent as ONE quoted token ("A.B"): two or more segments are always a data block member path, never matched against tags. A dangling reference is never written. A dryRun cannot check whether the attributes of the not-yet-existing object are writable: a real create refused for that reason (409 hmi_attribute_not_writable or hmi_attribute_list_unavailable) removes the object it made and verifies it gone. Refused, nothing changed: 400 invalid_name (details.kind, name, rule) for a blank, over-long or malformed name, 409 name_collision (details.existing) for a used name, 400 invalid_data_type, 400 bad_request for fields that do not fit the rule above, 409 hmi_attribute_list_unavailable, hmi_attribute_unreadable or hmi_attribute_not_writable when the serve cannot read or may not write what it needs. dryRun (Gd11) is answered by the serve: it runs every guard the real write runs and answers {dryRun:true, status:"plan_ok", hmi, ...} with no `postcheck`, changing nothing. A real write answers the re-read values and a `postcheck` {verified:true,

Updates ONE tag of a WinCC Unified HMI: only the fields passed change (none passed: 400 missing_param). The rules of a create apply to what it changes and to what those changes interact with; the references it carries unchanged are not re-audited: tia_hmi_validate finds dangling ones. Moving a tag to another tag table is not supported. A tag WITHOUT `connection` is internal: dataType is required and plcName, plcTag, address, accessMode, acquisitionMode and acquisitionCycle are refused (400 bad_request). A tag WITH `connection` is external: the connection must exist (409 reference_not_found; tia_hmi_connections lists them), exactly one of plcTag or address is given, and dataType is optional. The PLC of a plcTag is plcName, else the one PLC the connection's partner resolves to (none or several: 409 plc_unresolved). A plcTag is a PLC tag or a data block member path (struct and UDT members, array elements with literal in-bounds indices): one that matches no tag or block is 409 reference_not_found, one that cannot be established is 409 plc_reference_unresolved (details.segment, reason), possibly a false refusal when the DB or a UDT is inconsistent: compile the PLC first. A PLC tag name with a dot is sent as ONE quoted token ("A.B"): two or more segments are always a data block member path, never matched against tags. A dangling reference is never written. Refused, nothing changed: 400 invalid_name (details.kind, name, rule) for a blank, over-long or malformed name, 409 name_collision (details.existing) for a used name, 400 invalid_data_type, 400 bad_request, 404 not_found, 409 hmi_attribute_list_unavailable, hmi_attribute_unreadable or hmi_attribute_not_writable when the serve cannot read or may not write what it needs. A failed write restores the previous values. dryRun (Gd11) is answered by the serve: it runs every guard the real write runs and answers {dryRun:true, status:"plan_ok", hmi, ...} with no `postcheck`, changing nothing. A real write answers the re-read valu

Deletes a tag of a WinCC Unified HMI. Refused, nothing changed: 404 not_found and 409 tag_in_use (details.references) when an alarm references the tag. Screens, scripts and logging that use the tag are NOT scanned: run tia_hmi_validate afterwards. dryRun (Gd11) is answered by the serve: it runs every guard the real write runs and answers {dryRun:true, status:"plan_ok", hmi, ...} with no `postcheck`, changing nothing. A real write answers the re-read values and a `postcheck` {verified:true, requested, actual}; a mismatch is 409 postcheck_failed (details.mismatches, details.rollback: restored, not_restored or not_attempted): re-read before anything else. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to DELETE /hmi/{hmi}/tags/{tag}. M-off.

Creates a discrete or analog alarm in a WinCC Unified HMI. Needs name, alarmClass and triggerTag, plus triggerBit (discrete) or condition and conditionValue (analog). alarmClass and triggerTag must exist, else 409 reference_not_found. A discrete alarm raises on a bit of the trigger tag: triggerBit (required on create) and triggerMode; a tag that is not bit-addressable is 409 tag_type_mismatch, a bit past the width 409 trigger_bit_out_of_range (details.tag, dataType, bit, max). An analog alarm compares a numeric trigger tag with ONE conditionValue (there is no second limit) under a condition; the value must fit the tag's data type, else 409 tag_type_mismatch or condition_value_out_of_range (also above 2^53 on LInt, ULInt, LWord: TIA stores a double). Whole numbers of 2^53 or more must be strings, and the serve refuses a whole number written as a decimal JSON number such as 5.0 (400 bad_request). A property of the other kind is 400 bad_request, as is an eventText culture that is not an active project language. A dryRun cannot check whether the attributes of the not-yet-existing object are writable: a real create refused for that reason (409 hmi_attribute_not_writable or hmi_attribute_list_unavailable) removes the object it made and verifies it gone. Refused, nothing changed: 400 invalid_name (details.kind, name, rule) for a blank, over-long or malformed name, 409 name_collision (details.existing) for a used name, 409 hmi_attribute_unreadable, and 409 hmi_attribute_list_unavailable or hmi_attribute_not_writable only for the Text of the event text item of an eventText culture (an alarm's own attribute list is never read). dryRun (Gd11) is answered by the serve: it runs every guard the real write runs and answers {dryRun:true, status:"plan_ok", hmi, ...} with no `postcheck`, changing nothing. A real write answers the re-read values and a `postcheck` {verified:true, requested, actual}; a mismatch is 409 postcheck_failed (details.mismatches, details.rollback: restored, not

Updates ONE alarm of a WinCC Unified HMI: only the fields passed change (none passed: 400 missing_param). The rules of a create apply to what it changes and to what those changes interact with; the references it carries unchanged are not re-audited: tia_hmi_validate finds dangling ones. alarmClass and triggerTag must exist, else 409 reference_not_found. A discrete alarm raises on a bit of the trigger tag: triggerBit (required on create) and triggerMode; a tag that is not bit-addressable is 409 tag_type_mismatch, a bit past the width 409 trigger_bit_out_of_range (details.tag, dataType, bit, max). An analog alarm compares a numeric trigger tag with ONE conditionValue (there is no second limit) under a condition; the value must fit the tag's data type, else 409 tag_type_mismatch or condition_value_out_of_range (also above 2^53 on LInt, ULInt, LWord: TIA stores a double). Whole numbers of 2^53 or more must be strings, and the serve refuses a whole number written as a decimal JSON number such as 5.0 (400 bad_request). A property of the other kind is 400 bad_request, as is an eventText culture that is not an active project language. Refused, nothing changed: 400 invalid_name (details.kind, name, rule) for a blank, over-long or malformed name, 409 name_collision (details.existing) for a used name, 404 not_found, 409 hmi_attribute_unreadable, and 409 hmi_attribute_list_unavailable or hmi_attribute_not_writable only for the Text of the event text item of an eventText culture (an alarm's own attribute list is never read). An update is refused before anything is written, its dryRun included. A failed write restores the previous values. dryRun (Gd11) is answered by the serve: it runs every guard the real write runs and answers {dryRun:true, status:"plan_ok", hmi, ...} with no `postcheck`, changing nothing. A real write answers the re-read values and a `postcheck` {verified:true, requested, actual}; a mismatch is 409 postcheck_failed (details.mismatches, details.rollback: restor

Deletes a discrete or analog alarm of a WinCC Unified HMI; an unknown alarm is 404 not_found, nothing changed. dryRun (Gd11) is answered by the serve: it runs every guard the real write runs and answers {dryRun:true, status:"plan_ok", hmi, ...} with no `postcheck`, changing nothing. A real write answers the re-read values and a `postcheck` {verified:true, requested, actual}; a mismatch is 409 postcheck_failed (details.mismatches, details.rollback: restored, not_restored or not_attempted): re-read before anything else. Needs an open project and a WinCC Unified HMI (hmi = its name from tia_hmis, matched ignoring case): a classic WinCC HMI is refused with 409 hmi_not_unified, an unknown HMI is 404 not_found and two HMIs with the same name are 409 ambiguous_name. Maps to DELETE /hmi/{hmi}/alarms/{kind}/{alarm}. M-off.

Lists the Version Control Interface (VCI) workspaces of the open project, sorted by name: {name, group, rootPath, mappedObjects}. group is "" for the system group and a path such as G1/G2 for a workspace of a user group (nested groups are included). A workspace is a folder on the serve host that mirrors project objects as files, so that an external tool can version them. rootPath is null when the workspace has no root folder configured (tia_vci_status then answers 409 workspace_unconfigured); mappedObjects counts every mapped object of any kind. Only leaf objects (PLC blocks, PLC data types and tag tables) go through this tool set. A name shared by workspaces of several groups makes tia_vci_status, tia_vci_export and tia_vci_import answer 409 workspace_ambiguous, and an inventory that cannot be read completely is 409 vci_inventory_incomplete (nothing changed). Requires a connected project (409 not_connected); a TIA without VCI is 409 vci_unavailable. Maps to GET /vci/workspaces. Read-only (class R).

无需输入参数。

Compares every object mapped in a VCI workspace with its file and returns, per object, its state: equal, projectChanged, workspaceChanged, conflict (both changed), workspaceFileMissing, unknown, unequal, statusFailed or unsupported. Use it to verify what tia_vci_export wrote and to see what tia_vci_import would overwrite. Only leaf objects (PLC blocks, PLC data types and tag tables) are compared: any other mapped object is listed as unsupported and is never passed to VCI. unsupported, statusFailed and unknown rows, and coverage.complete:false, mean NOT verified: claim nothing about those objects. A mapping follows the project object it was made for: an edit that keeps the object (a block attribute, tia_block_set_attribute) makes the row projectChanged, but regenerating a block from SCL (tia_source_put) replaces the object and V21 drops its mapping, so the row disappears and tia_vci_import answers 409 not_mapped. Paging: limit (1..1000, recommended 100) and cursor page the rows in a stable order, and the serve compares only the rows of the page, so paging bounds the time and the size of one call. A page adds total and nextCursor (null on the last page): pass nextCursor back as cursor until it is null. 409 cursor_stale (a mapping appeared, disappeared or moved): restart once from the first page; invalid_cursor: pass the cursor unchanged. summary and coverage describe the rows OF THE RESPONSE (the whole workspace only when unpaged): fold them across ALL pages before saying that the workspace is in sync. coverage is {complete, rows, inspected, unsupported, failed, unsupportedObjects, failedObjects, unsupportedObjectsTruncated, failedObjectsTruncated}. An omission marker on objects means the response budget dropped rows, and the page's nextCursor was removed with them: retry the same request (the same cursor) with a smaller limit, and follow a nextCursor only from a page without a marker. Unknown workspace: 404 not_found; no root folder: 409 workspace_unconfigured; a nam

Creates a VCI workspace (a folder on the serve host that mirrors project objects as files) or reuses it: the same name with the same root answers status reused with the EXISTING workspace's root and writes nothing to TIA. It always creates in the system group, and the serve creates the root folder when it is missing (createdDirectory). rootPath must be an absolute local drive path such as C:\TIA\_scratch\ws; a UNC, device or relative path, a . or .. segment or a reserved name is 400 invalid_workspace_path. Refusals, each with nothing changed: 409 workspace_exists (the name exists, in any group, with a DIFFERENT root: details.name, existingRoot, requestedRoot), 409 workspace_root_in_use (another workspace of any group already uses that root: details.root, workspace) and 409 vci_unavailable. A 504 worker_restarted, a timeout or a lost connection has an UNKNOWN outcome: list the workspaces before repeating. Run it with dryRun:true first (Gd11): the serve answers with the plan (action create or reuse, willCreateDirectory) or the same refusal WITHOUT creating anything. Requires a connected project; 409 vci_inventory_incomplete (the workspace inventory could not be read completely): the name and root cannot then be checked against every group, nothing changed. Maps to POST /vci/workspaces {name, rootPath, dryRun?}. Class M-off.

Writes 1 to 50 project objects {plc?, kind, name, format?} to the files of a VCI workspace. Only leaf objects are accepted: PLC blocks (OB, FB, FC, data blocks), PLC data types and tag tables; any other object (a container, a device, a PLC...) is refused with 409 vci_not_leaf before VCI is called, nothing changed. An object that is not mapped yet is exported to a new file with the format you chose (action export, under <PLC>\Blocks, Types or TagTables and its groups); an object that is already mapped is synchronized, keeps its mapping's folder, file and format (a format you pass is not validated for it) and its workspace file is OVERWRITTEN with the project content (action synchronize). Everything is checked before the first write: 404 not_found (names the object), 409 vci_not_leaf, 409 vci_unsupported_object, 409 vci_path_too_long, 409 vci_path_collision (details.collisions[].reason: batch = two objects share a target, mapped_to_other_object, file_exists, or alias_unverifiable = an existing file's 8.3 short name could not be read, so a collision with its alias cannot be excluded; details file) and 400 batch_too_large. 409 vci_mapping_outside_workspace: a mapping whose folder is not below the workspace root is refused before any write (details plc, kind, name, directory, root); but when a NEW export reports a folder outside the root, the file WAS written there (details object, directory, root, done) and that answer is not 'nothing changed'. The batch is NOT a transaction: it stops at the first failure. 409 vci_batch_incomplete (details.done, failed, notAttempted) means the objects in done WERE written and the failed one may be partly written. 'Nothing was changed.' is promised only by refusals before the first write: any other failure (a first object's own error, 504 worker_restarted, a timeout, a lost connection) has an UNKNOWN or possibly partial outcome, so re-read with tia_vci_status before repeating. No status check runs inside the export: verify the result wit

Imports objects from the files of a VCI workspace into the project: it OVERWRITES each project object with its workspace file, and there is no undo. Only leaf objects are accepted: PLC blocks (OB, FB, FC, data blocks), PLC data types and tag tables; any other object (a container, a device, a PLC...) is refused with 409 vci_not_leaf before VCI is called, nothing changed. The object must already be mapped (409 not_mapped: export it first) and its file must exist (409 workspace_file_missing); 409 vci_mapping_outside_workspace: a mapping whose folder is not below the workspace root is refused before any write (details plc, kind, name, directory, root). An object whose status is already equal is skipped (action skip). The dryRun plan shows per object statusBefore and overwritesProjectChanges (true for projectChanged and conflict). expectedContentHash guards a block (hash from tia_export_block) or a type (tia_export_type), never a tag table (the schema refuses it); the serve verifies it in a dryRun too: a stale hash is 409 state_changed, a matching one returns the contentGuard receipt. After each import the serve runs a postcheck (status, consistency, compile errors, content hash) on the object it finds again by name, because an import REPLACES the project object: re-read it by name, not through a stale handle. A failed postcheck is 409 import_unverified: the project object WAS ALREADY WRITTEN and may differ from the file: review it with tia_export_block or restore it from the workspace, and never report the import as done. The batch is NOT a transaction: it stops at the first failure. 409 vci_batch_incomplete (details.done, failed, notAttempted) means the objects in done WERE written and the failed one may be partly written. 'Nothing was changed.' is promised only by refusals before the first write: any other failure (a first object's own error, 504 worker_restarted, a timeout, a lost connection) has an UNKNOWN or possibly partial outcome, so re-read with tia_vci_status

Lists the certificates in the CPU's local certificate store as {id, subject, validUntil, hasPrivateKey}. A CPU or firmware without a local certificate manager is refused (409). Maps to GET /plcs/{plc}/certificates. Read-only (class R).

Reads the CPU's certificate template for a usage (default Tls): subject, usage, signature, validFrom, validUntil. A CPU without a local certificate manager is refused (409). Maps to GET /plcs/{plc}/certificates/template?usage=<usage>. Read-only (class R).

Imports a certificate file on the serve host into the CPU's local certificate store and returns {id, subject}. A password-protected file (PKCS#12 with its private key) needs `password`: GATE G6 — it comes from a HUMAN, never invented or guessed; the dryRun plan shows it as [redacted]. The password travels to the serve over plain HTTP — keep the serve on this host or a trusted network. Offline change: it reaches the CPU only with a later compile + download. Maps to POST /plcs/{plc}/certificates/import {path, password?}. Class M-off.

Exports one certificate of the CPU's local store (id from tia_certificates) to a file on the serve host. Writes the file only — the project is not changed. Maps to POST /plcs/{plc}/certificates/{id}/export {path}. Class M-off.

Deletes one certificate (id from tia_certificates) from the CPU's local store in the project. Offline change: the CPU keeps its certificate until a later compile + download. Maps to DELETE /plcs/{plc}/certificates/{id}. Class M-off.

Reads the CPU's password policy: `modern` {enabled} and `legacy` {enabled, minLength, minNumeric, minSpecial, requiresMixedCase} — each null when the CPU does not expose that service. Maps to GET /plcs/{plc}/passwordpolicy. Read-only (class R).

Changes the CPU's password policy in the project. GATE G6: the values are the site's security decision — take them from a HUMAN, never choose them yourself. Only the fields you pass change; pass at least one. The length and complexity fields live in the legacy policy service: on a CPU that exposes only the modern service just `enabled` applies — the result then lists the dropped fields in `ignoredFields`. A CPU with neither service is refused (409). Offline change: it reaches the CPU only with a later compile + download. Maps to POST /plcs/{plc}/passwordpolicy. Class M-off.

Sets know-how protection on a PLC block with a password (protect:true, the default) or removes it (protect:false, with the same password). GATE G6: the password comes from a HUMAN — never invented, guessed or reused; a password nobody knows locks the block for good. Never retry a rejected password with a guess: after one rejected unprotect, TIA has refused even the correct password for the rest of the session. The dryRun plan shows the password as [redacted]. The password travels to the serve over plain HTTP — keep the serve on this host or a trusted network. Maps to POST /plcs/{plc}/blocks/{block}/protect {password, protect}. Class M-off.

Compiles the PLC and returns the message tree + a verification summary (Gd8: only ERROR blocks, warnings don't) and nextHints. This is the offline VERIFIER: a clean compile is a precondition (Gd9) for download/S7. Maps to POST /plcs/{plc}/compile. M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Compiles ONE block (not the whole PLC) and returns the same message tree, Gd8 verification summary (only ERROR blocks, warnings don't), located[] and nextHints as tia_compile. A clean block compile is NOT the Gd9 precondition for download/S7: run tia_compile for the whole PLC before that. 404 not_found when the block does not exist. dryRun (Gd11) is answered by the serve (needs an open project): it resolves the block and returns the plan {block, blockType, isConsistent} WITHOUT compiling. Maps to POST /plcs/{plc}/blocks/{block}/compile. M-off. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Downloads hardware/software to the PHYSICAL CPU (STOPS and RESTARTS the CPU). GATE G3: does NOT download without human approval. dryRun:true asks serve for a VERIFIED plan (clean compile, PG/PC interface found, software fingerprint) and returns a single-use planHash that expires (TIA_PLAN_TTL_MS, default 15 min). After a human approves that plan, call with approved:true and the SAME planHash; serve re-checks the fingerprint inside the download and refuses (plan_stale) if the project changed. Pick connectionMode/pcInterfaceName/targetInterfaceName with tia_pg_interfaces (no scan). The serve also issues its own single-use approval token with the plan; this MCP keeps it and sends it with the download (a newer serve refuses any download without it — keep this MCP up to date). The download flow compiles and leaves the project modified; projectModified reports Project.IsModified. Save with tia_project_save before switching projects. Requires app ≥ v1.6.0. Maps to POST /plcs/{plc}/download/plan and POST /plcs/{plc}/download. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Station upload (GATE G4): goes ONLINE to the PHYSICAL CPU at `ip` and reads its hardware configuration and program into the OPEN project as a new station — it reads the CPU and does not write or stop it (observed on hardware: the CPU stayed in RUN). Back up into a dedicated EMPTY project, never the working project (skill tia-backup). Without confirm it asks serve for an upload plan (PG/PC interface resolved, the open project's path and devices — no network access) and returns a single-use planHash bound to that project; after a human confirms, call again with confirm:true and that planHash. A plan blocked by connection_unresolved because no connectionMode was given asks serve for one more plan per available mode (one at a time, never confirmed; up to 8 modes) and lists the PG/PC interfaces it reports in connectionCandidates (up to 32): repeat without confirm with one candidate's exact connectionMode, pcInterfaceName and pcInterfaceNumber. A read-protected CPU needs its read-access password from a HUMAN (G6 — never invented). Needs the deploy license scope (Basic → 403 scope_required) and app ≥ v1.6.0. Maps to POST /stations/upload/plan and POST /stations/upload. Long operation: may answer status:"running" + jobId — then call tia_job_status.

Creates an S7 connection between two devices. Guard G2: requires ≥2 CONSISTENT CPUs (compile clean) — a bare CPU fails. On error, the envelope's 'details' carries the diagnostic (or use tia_connections_diagnose). Maps to POST /connections. M-off.

Connects ONLINE to the physical PLC. GATE G4: pass confirm:true (after a human confirms it's safe to connect to the target machine); without it, returns a handoff. The confirm:true call must repeat the SAME connectionMode, pcInterfaceName, pcInterfaceNumber and targetInterfaceName as the approved plan: without connectionMode or pcInterfaceName it is refused (connection_fields_required) and nothing is sent. Maps to POST /plcs/{plc}/online.

Disconnects the PLC from online mode. Maps to POST /plcs/{plc}/offline.

Reads the PLC's online state (online/offline). Read-only (class R). Maps to GET /plcs/{plc}/online/state.

Scans the network via the PG/PC adapter and lists accessible devices — to see which devices answer on the network — to discover mode/adapter/interface names WITHOUT a scan, use tia_pg_interfaces. GATE G7 (net scan): pass confirm:true. Maps to POST /plcs/{plc}/online/accessibledevices.

Sets the master secret (password) of a protected CPU, before online/download. GATE G6: the password comes from a HUMAN (or a credential vault) — the AI NEVER makes it up. (Note: P3.7 questions sending the secret over HTTP in plain text; prefer local entry on the host.) Maps to POST /plcs/{plc}/online/mastersecret.

Removes/resets the CPU's master secret. Maps to DELETE /plcs/{plc}/online/mastersecret.

Validates a project-spec (docs/TIA-BEST-PRACTICES §13.2) deterministically, WITHOUT touching serve (rung 0): R-NAMES (unique names), R-TYPEID (OrderNumber:<MLFB>/V<fw>), R-SUBNET (IP∈CIDR, same subnet, 1 IO-system), R-LANGFAM (STL/GRAPH S7-1500 only), R-MODLIMIT, and G5 (safety.required && autonomous ⇒ REJECT). Returns { valid, violations:[{rule,severity,detail}], counts }.

Validates and transforms a project-spec into the ORDERED SEQUENCE of offline operations (subnets→devices→modules→network→tags→blocks→compile), WITHOUT touching serve. Gated operations (connect/download) are NOT included. Returns { steps, assumptions, plc } or the violations if invalid. PLC-scoped steps (tag tables, tags, FBs, instance DBs, compile) carry the {plc} placeholder: tia_spec_apply resolves the PlcSoftware TIA created for the device (named after the CPU device item, e.g. PLC_1 — not after the device; set the optional plcName on the device to choose it) right after the device step.

Orchestrates the OFFLINE build of a project-spec on an ALREADY OPEN project: validates → G5 (rejects safety+autonomous) → serially executes subnets/devices/modules/network/tags/blocks → compiles. STOPS at the 1st error (continueOnError to keep going). NEVER downloads (download is GATE G3, always human). dryRun:true returns the plan without applying. Requires an open project (tia_connect/tia_project_create beforehand). The PLC-scoped steps use the PlcSoftware resolved from the serve after the device step (it is recorded in applied as plc.resolve), never the device name; an unidentifiable PlcSoftware stops with kind plc_unresolved. Long operation: may answer status:"running" + jobId — then call tia_job_status.