tia-openness-control

name

tia-openness-control

description

Build, review, and run Siemens TIA Portal Openness automations that let any AI-assisted workflow control TIA Portal projects through the official Siemens.Engineering .NET API. Supports TIA Portal V15 through V21, including automatic installed-version detection. Use when the user asks to automate BoTu/TIA Portal operations, generate C# or PowerShell wrappers for Openness, open/create/modify/compile/export/import/archive TIA projects, inspect PLC/HMI/hardware objects, or design a safe AI-to-TIA command layer.

TIA Openness Control

Mission

Use TIA Portal Openness as the execution boundary: any AI proposes structured actions, generated .NET code performs them through Siemens.Engineering, and every destructive or plant-impacting operation is explicit, logged, and reviewable.

Workflow

1. Identify the project path and exact operation. Detect the installed TIA Portal version automatically when the user does not specify one.
2. Confirm prerequisites: Windows host, TIA Portal V15 through V21 installed, user in the Siemens TIA Openness Windows group, Openness enabled, project backed up, and matching PublicAPI path. For first-time setup, instruct the user to add the Windows account to that group with administrator rights, then sign out and back in.
3. Choose execution mode: WithUserInterface for exploratory/debug work, WithoutUserInterface for repeatable batch work.
4. Generate or modify a C# .NET controller. Use scripts/new-openness-controller.ps1 to scaffold a starter controller when useful.
5. Keep AI commands declarative, such as JSON/YAML action plans, and map them through a whitelist. Do not execute arbitrary prompt text as code.
6. Run read-only or dry-run behavior first; then write only the requested target objects.
7. Capture stdout, stderr, exit code, active project path, and log file path for every run.
8. Verify results by reading the project back through Openness. Do not claim success from exit code, file timestamp, or "no exception" alone.
9. Save or archive the project and report changed objects, warnings, and compile diagnostics.

Universal AI Interface

Keep this skill usable by any AI agent or automation runner:

• Describe actions as plain JSON/YAML command documents.
• Generate ordinary PowerShell, C#, .csproj, and CLI commands.
• Avoid product-specific hidden state, proprietary prompt features, or assumptions about a single AI runtime.
• Make every generated controller runnable by a human from a terminal.
• Return machine-readable results when possible so another AI can continue from logs.

Example command document:

{
  "tiaVersion": "auto",
  "projectPath": "D:/Projects/Line1.ap20",
  "mode": "WithUserInterface",
  "dryRun": true,
  "actions": [
    { "type": "ListDevices" }
  ]
}

Version Support

Support TIA Portal V15, V15.1, V16, V17, V18, V19, V20, and V21.

When scaffolding a controller, prefer automatic detection:

powershell -ExecutionPolicy Bypass -File .\scripts\new-openness-controller.ps1 -OutputPath . -ProjectName TiaOpennessController

The script scans C:\Program Files\Siemens\Automation\Portal V*\PublicAPI\V* and selects the highest supported installed version. Use -TiaVersion V17 or -TiaVersion V15_1 only when the user explicitly wants a specific version.

Safety Rules

• Never connect to a PLC, download to a device, change online state, or alter production hardware without explicit user approval.
• Prefer offline project edits and generated source import/export.
• Before writes, create a .zap archive or duplicate project folder when TIA Portal supports the workflow.
• Pin Siemens.Engineering.dll to the detected or selected TIA Portal version; do not mix assemblies and runtime versions.
• Set Siemens Engineering assembly references to Copy Local = false, or load them from PublicAPI at runtime.
• Treat block names, device names, file paths, credentials, project libraries, and know-how protected content as user data.

First-Time Windows Group Setup

If the current Windows account is not in the Siemens TIA Openness group, tell the user to run an elevated PowerShell session and execute:

net localgroup "Siemens TIA Openness" "$env:USERNAME" /add

After adding the account, the user should sign out and sign in again, or restart Windows, before running Openness automation.

Common Tasks

• Open, create, save, close, or archive a project.
• Enumerate devices, PLC software, blocks, external sources, tag tables, HMI objects, and libraries.
• Import/export PLC blocks, tag tables, libraries, and hardware descriptions as source/XML files.
• Generate SCL/LAD/FBD source files, then import them through Openness.
• Compile software or hardware and summarize diagnostics.
• Start TIA Portal, use a visible UI session, or attach to an existing Openness process when the local version supports it.

Implementation Patterns

Read references/openness-patterns.md when generating C# code, planning an AI command schema, or troubleshooting assembly loading/version problems.

Critical assembly-loading rule: keep Main as a clean bootstrap that does not reference any Siemens.Engineering types. Register AssemblyResolve, preload Siemens.Engineering.dll, then call the real Openness logic in a separate [MethodImpl(MethodImplOptions.NoInlining)] method or class. If Main directly uses TiaPortal, TiaPortalMode, Project, or an Options property typed as TiaPortalMode, .NET Framework can throw FileNotFoundException before the resolver is registered.

When another AI or user reports FileNotFoundException at Program.Main, replace the generated controller with the current scaffold from scripts/new-openness-controller.ps1 before attempting feature work. Do not keep patching a controller whose Main directly references Siemens types.

For device creation tasks, require a read-back verification step such as ListDevices after saving and reopening the project. If the target order number, device type identifier, or catalog version is unknown for the installed TIA version, inspect/export an existing matching device or ask the user for the exact catalog item instead of guessing.

For Chinese users, read README.md when user-facing guidance is needed.

Use official Siemens documentation for exact version-specific APIs. Useful starting points:

• TIA Portal Openness V21 example program: https://docs.tia.siemens.cloud/r/en-us/v21/tia-portal-openness-api-for-automation-of-engineering-workflows/tia-portal-openness-api/general-functions/example-program
• TIA Portal Openness V20 connecting guide: https://docs.tia.siemens.cloud/r/en-us/v20/tia-portal-openness-api-for-automation-of-engineering-workflows/tia-portal-openness-api/general-functions/connecting-to-the-tia-portal

Output Expectations

When helping a user, provide:

• the exact command or C# project to run,
• detected TIA Portal version, PublicAPI path, and project path,
• the list of operations the automation will perform,
• stdout, stderr, and exit code from the last automation run,
• validation steps and expected diagnostics,
• read-back evidence for created or modified objects,
• any operation that still needs manual confirmation inside TIA Portal.