Getting Started

This guide walks you through running your first Python script inside a WinCC OA project. The script is registered as a WinCC OA manager and is started, stopped and monitored by the process monitor (PMON) — just like a CTRL or ECMAScript manager.

If you instead want to develop and test Python code on a workstation, with IDE support and unit tests but without a running project, see Development Environment.

Prerequisites

  • A WinCC OA installation with the Python runtime component (PythonEnv) selected during setup
  • CPython, in the version released for your operating system — WinCC OA does not ship a Python runtime
  • The python executable reachable through the system PATH
  • A WinCC OA project with Event and Data managers running

See Installation for the released versions and the installation steps for each operating system.

Your First Script

Python scripts are located in the python/ directory of your project. Create the file <project>/python/hello_world.py:

"""Read and write a datapoint value."""

import logging

from etm.wccoa.manager import Manager

logger = logging.getLogger(__name__)

with Manager() as manager:
    value = manager.dp_get("ExampleDP_Arg1.")
    logger.info("Current value: %s", value)

    manager.dp_set_wait("ExampleDP_Arg1.", 42.0)
    logger.info("Value set to 42.0")

General things worth noting:

  • Manager() returns the single manager instance of the process (a singleton). Creating it again from another module yields the same object.
  • The with block starts the manager, connects to the Event manager, and shuts down cleanly when the block ends — also in case of exceptions.
  • Use the standard logging module. Log records are forwarded to the WinCC OA log system and end up in the project’s log file. Output written with print() is not turned into log records — it ends up unformatted in <project>/log/python<num>.log.

The datapoint ExampleDP_Arg1 is part of the WinCC OA demo data. Replace it with a datapoint from your own project if it does not exist.

Adding the Manager to the Project

Register the script as a manager in the WinCC OA Console.

  1. Open the Console and select your project.

  2. Click Append new manager below the manager list.

  3. Select python … Python Manager from the manager list.

  4. Choose a start mode. Use manual while you are still testing the script.

  5. Enter the script name and the manager number in the options field:

    hello_world.py -num 50

  6. Apply the changes and start the manager.

The manager number must be unique among all scripting-managers (CTRL, NodeJS, Python) of the project.

Options Field

The options field is split at the script name:

Position Content Example
Before the .py file Python interpreter options -X dev
The .py file Script name, resolved in the python/ directories of the project, its subprojects and the installation hello_world.py
After the .py file Manager and script options -num 50

WinCC OA PMON adds -PROJ and -pmonIndex itself and sets the environment variables the script needs to find the Python packages and the native extension. Do not add them manually.

The Console/PMON writes these settings to the project’s config/progs file.

Checking the Result

Everything the script logs through the logging module at level INFO or higher is written to the WinCC OA log file <project>/log/PVSS_II.log, together with the output of all other managers. Records at level DEBUG go to the manager-specific log file <project>/log/python<num>.log instead.

The LogViewer displays the content of the log files, so it is the most convenient way to follow the script.

If the manager stops immediately, the log file is the first place to look. See Troubleshooting for the most common errors and how to resolve them.

Next Steps

The example scripts under api.python/examples/ of your WinCC OA installation show the core use cases as complete, runnable scripts: reading and writing values, event handling, CTRL interoperation and queries.