--- name: tia-python description: Reference for Siemens TIA Scripting Python V1.4.3. Load only when the user explicitly chooses Python TIA Scripting or the TIA roadmap routes to it. license: MIT --- # TIA Scripting Python V1.4.3 Library: `siemens_tia_scripting` (v1.4.3) Use this skill for the Siemens-supplied Python wrapper around TIA Portal Openness. It is a reference-routed skill: do not select Python merely because a task mentions TIA Portal. If the implementation route is not already explicit, start with `tia-openness-roadmap`. ## Evidence and qualification boundary This package is aligned to the supplied Siemens V1.4.3 artifacts: - English manual `109742322_TIA_Scripting_Python_DOC_V143_en.pdf`, entry ID 109742322, dated 06/2026. - The `siemens_tia_scripting.pyi` stub bundled identically in the CPython 3.12, 3.13, and 3.14 wheels. - Siemens package metadata, changelog, and example workflows distributed with V1.4.3. The manual and stub are the authority for public names and signatures. The changelog is the authority for version-to-version behavior notes. Static package inspection does not prove import success, installed products, licensing, live portal behavior, or project mutation on a particular engineering station. ### Supported environment - Python 3.12.x, 3.13.x, or 3.14.x only, using the matching Windows x64 wheel. - The V1.4.3 manual states TIA Portal V15.1 or newer and TIA Portal Openness V15.1 or newer. - Siemens `manifest.json` lists V18-V21, while the delivered package contains adapter assemblies from V15.1 through V21.1. Treat this as mixed Siemens compatibility metadata: verify the exact installed Portal and update before promising runtime support. - The Windows user must belong to the `Siemens TIA Openness` group. The first connection can display the Siemens Openness security prompt. ## Installation Do not install an unrelated package from PyPI. Use a wheel from the Siemens download or use the extracted-file import method. ### Siemens wheel Choose the wheel whose CPython tag matches the interpreter: ```powershell py -3.12 -m pip install .\install\siemens_tia_scripting-1.4.3-cp312-cp312-win_amd64.whl py -3.13 -m pip install .\install\siemens_tia_scripting-1.4.3-cp313-cp313-win_amd64.whl py -3.14 -m pip install .\install\siemens_tia_scripting-1.4.3-cp314-cp314-win_amd64.whl ``` Install only the wheel matching the interpreter. Siemens documents IntelliSense support through this package-install path with Pylance; other language servers are not qualified in the V1.4.3 manual. ### Extracted-file import Set `TIA_SCRIPTING` to the extracted directory that contains `siemens_tia_scripting.pyd` and its Siemens adapter DLLs. Use the environment path only as a fallback when the wheel is not installed: ```python import importlib import os import sys from pathlib import Path try: ts = importlib.import_module("siemens_tia_scripting") except ImportError as first_error: scripting_dir = os.environ.get("TIA_SCRIPTING") if not scripting_dir: raise RuntimeError( "Install the matching Siemens wheel or set TIA_SCRIPTING." ) from first_error resolved_dir = Path(scripting_dir).expanduser().resolve() if not (resolved_dir / "siemens_tia_scripting.pyd").is_file(): raise RuntimeError( "TIA_SCRIPTING must contain siemens_tia_scripting.pyd." ) from first_error sys.path.insert(0, str(resolved_dir)) ts = importlib.import_module("siemens_tia_scripting") ``` Do not copy the shipped examples' lifecycle and error handling verbatim. They are useful API-shape examples, but some V1.4.3 examples contain stale Python 3.12-only comments and do not reliably close or detach portal instances. ## Public object model ```text siemens_tia_scripting |-- Enums and 10 global functions |-- ProductBundle -> Product `-- Portal |-- Project | |-- Device -> Module | |-- Plc | | |-- DownloadConfig | | |-- ExecutionResult | | |-- ProgramBlock / SystemBlock / UserDataType | | |-- PlcTagTable -> PlcTag / UserConstant / SystemConstant | | |-- ExternalSource / ForceTable / WatchTable | | |-- TechnologyObject / SafetyAdministration | | `-- SoftwareUnit -> NamedValueType and PLC data objects | |-- Hmi | | |-- HmiTagTable / HmiTag / HmiScreen / HmiScript | | `-- HmiAlarm / HmiAlarmClass / HmiConnection / HmiCycle | | / HmiGraphicList / HmiTextList | |-- ProjectLibrary -> MasterCopy / LibraryType -> LibraryTypeVersion | `-- ApplicationTest / RuleSet / SystemTest |-- ProjectServer `-- GlobalLibraryInfo / GlobalLibrary `-- LibraryType -> LibraryTypeVersion ``` The V1.4.3 stub contains 10 global functions and 45 public classes. Load the domain reference files below instead of expanding this entrypoint with every method. ## Cross-cutting contracts ### Properties The V1.4.3 manual and stub annotate `get_property(name: str) -> str` and say non-string values are converted to strings where possible. The V1.3.0 changelog instead says property values are returned as their original boolean or numeric type. Because the supplied authorities conflict, generated code must not assume one representation: ```python value = obj.get_property(name="CreationDate") if isinstance(value, bool): normalized = value elif isinstance(value, str): normalized = value.strip() else: normalized = value ``` `set_property(name: str, value: str) -> int` still requires a string value. Pass booleans, numbers, and enums as their documented string representation. ### Export and import The common V1.4.3 export signature is: ```python obj.export( target_directory_path=r"C:\Engineering\export", export_options=ts.Enums.GeneralExportOptions.WithDefaults, export_format=ts.Enums.GeneralExportFormats.SimaticML, keep_folder_structure=True, ) ``` Most V1.4.3 import methods accept `import_options: Optional[Enums.GeneralImportOptions]`. PLC/HMI bulk imports use an import root directory; explicitly named project-text, CFC, CAx, global-screen, screen-overview, configuration, and password-policy operations use file paths. Check the domain reference before choosing a path shape. ### Compile and execution results - `Device.compile()`, `Module.compile()`, PLC compile methods, block/UDT/ technology-object compile methods, and `SoftwareUnit.compile()` return `ExecutionResult`. - `ExecutionResult` exposes `get_result_state()`, `get_all_messages()`, `get_warnings()`, `get_errors()`, `get_information()`, and `print_result()`. - `Hmi.compile_hardware()` and `Hmi.compile_software()` remain the exception: they return `True` when errors exist and `False` when no errors exist. - The V1.3.0 changelog calls its breaking result change an "ExecutionReport" object, but the delivered V1.4.3 manual and stub expose the callable class as `ExecutionResult`. Use `ExecutionResult` in code. Do not discard result objects or rely only on console logging: ```python result = plc.compile_software() errors = result.get_errors() if errors: raise RuntimeError("PLC compile failed: " + " | ".join(errors)) ``` ## Exact V1.4.3 enums ```text PortalMode: WithGraphicalUserInterface=0, WithoutGraphicalUserInterface=1, AnyUserInterface=2 UmacUserMode: Project=0, Global=1 GeneralExportFormats: SimaticML=0, ExternalSource=1, SimaticSD=2 GeneralExportOptions: WithDefaults=0, Nan=1, WithReadOnly=2 LibraryCleanUpMode: PreserveDefaultVersionOfUnusedTypes=0, DeleteUnusedTypes=1 LibraryExportOptions: Nan=0, WithLibraryVersionInfoFile=1, OnlyLibraryVersionInfoFile=2 LibraryHarmonizeOptions: HarmonizePathsAndNames=0, HarmonizePaths=1, HarmonizeNames=2 LibraryDependenciesMode: DoNotAutomaticallyCreateOrReleaseDependencies=0, AutomaticallyCreateOrReleaseDependenciesIfRequired=1 GeneralDownloadOptions: Hardware=0, Software=1, HardwareAndSoftware=2, SoftwareOnlyChanges=3, HardwareAndSoftwareOnlyChanges=4 TestSuiteTestCaseImportOptions: Nan=0, IgnoreInvalidObject=1 TestSuiteRuleSetImportOptions: Nan=0, IgnorePropertyErrors=1, IgnoreMissingAttributes=2, SkipInvalidObjects=3, IgnoreErrorsAndAttributes=4 GeneralImportOptions: Nan=0, Override=1, SkipInactiveCultures=2, ActivateInactiveCultures=3 ConsoleLogLevel: All=0, Info=1, Warning=2, Error=3 ``` ## Logging Configure file/console logging before opening or attaching TIA Portal, and set the console level separately when required: ```python ts.set_logging(path=r"C:\Engineering\logs\tia-scripting.log", console=True) ts.set_log_level(log_level=ts.Enums.ConsoleLogLevel.Info) ``` ## Reference routing Load every reference needed by a cross-domain workflow before generating code. | Reference | Load for | | --- | --- | | `skills/tia-python/references/global_portal.md` | Global functions, portal lifecycle, credentials, products, devices, and modules | | `skills/tia-python/references/plc.md` | PLC online/download, compilation, imports/exports, CFC, Safety, software units, and PLC data objects | | `skills/tia-python/references/hmi.md` | Generic wrapper HMI discovery, compile, import/export, and HMI object classes | | `skills/tia-python/references/library.md` | Global/project libraries, master copies, types, and versions | | `skills/tia-python/references/project.md` | Project lifecycle, transactions, project texts, CAx, project servers, and Test Suite | ## Destructive-operation safety and authority rules These rules are mandatory for generated TIA Scripting Python: 1. Treat project/library creation, import, property writes, master-copy instantiation, protection changes, `delete()` and other deletion calls, save, archive, compile-triggered generation, and hardware upgrade as mutations. Require explicit mutation authorization and exact selectors. 2. Require explicit live-operation authorization before `go_online()`, `go_offline()`, `download()`, online comparison, online fingerprints, or any operation that communicates with a PLC. Confirm the exact target using `pc_interface_type`, `pc_interface_name`, and `target_interface`; never infer a target from the first device or first accessible interface. 3. Inspect every `ExecutionResult` and stop on errors. For HMI compile calls, remember that `True` means errors exist. 4. After generated block, tag, hardware, or HMI changes, run or request a compile check with the matching wrapper compile method. Do not present the project change as deployable until that check passes. 5. Do not save, archive, commit a server session, close a portal, delete, or overwrite existing content unless that exact action was authorized. 6. Use `project.start_transaction()` / `project.end_transaction()` only around already authorized mutations supported by the transaction, and roll back on every exception path: ```python transaction_open = False try: project.start_transaction( undo_text="Authorized TIA change", dialog_text="Applying reviewed Python changes", ) transaction_open = True # Perform only the already authorized mutation here. project.end_transaction(rollback=False) transaction_open = False except Exception: if transaction_open: project.end_transaction(rollback=True) raise ``` 7. A transaction does not make an unsupported operation safe. If the wrapper or target object cannot provide the required exclusive-access, rollback, exact selection, or result evidence, route the task to C# Openness through a guarded workflow. 8. Do not hardcode, print, or commit UMAC, Safety, know-how, module-access, or PLC master-secret credentials. Read them from the user's approved secret mechanism and pass them only to the exact authorized call. 9. When this script attached to a user-owned portal, use `portal.detach()` in cleanup. Call `portal.close_portal()` only for an instance the script owns and only after the project disposition has been explicitly decided. ## General coding guidance - Prefer keyword arguments; V1.4.0 added positional and keyword handling, but keyword calls preserve intent across similar string parameters. - Check optional returns before dereferencing them. V1.4.3 specifically fixes a null-reference defect involving optional parameters, but callers still need to handle absent TIA objects and values. - Preserve Unicode paths, names, and text. V1.4.0 added non-ASCII handling. - Scope retrieval with `folder_path` when the exact group is known. - Never use collection position such as `plcs[0]` as an engineering selector. - Keep PLC, HMI, project, library, and live-operation functions separate so each authority boundary can be reviewed independently.