WinCC C-Script: Change Pictures from a PLC Digital Input Tag

Overview

WinCC (TIA Portal WinCC and WinCC V7/V8) provides several ways to navigate between process screens: direct screen windows, picture windows, screen change buttons with the OpenPicture function, and global C-scripts that react to PLC tag values. When a physical pushbutton wired to a digital input on the PLC must select one of several PDL pictures, the cleanest pattern is to map the button (or a counter/selector in the PLC) to a single integer tag, then let a WinCC global action read that tag on a cyclic trigger and call OpenPicture for the matching screen.

Prerequisites

• WinCC V7.x runtime or WinCC Professional (TIA Portal) with the C-Editor option licensed (C-Script for WinCC V7 is part of the standard install; C-Scripting in WinCC Professional is available for runtime).
• A configured WinCC project with at least four PDL pictures (Picture1.PDL through Picture4.PDL).
• A PLC tag (e.g. DB1.DBW0 on an S7-1500, or MW10 on an S7-300/400) of type WORD (16-bit unsigned) that the PLC sets to 0, 1, 2, or 3 according to the desired screen.
• A physical pushbutton wired to a digital input on the PLC, with PLC logic that increments or selects the picture index.
• The tag PLCtag created in WinCC Tag Management with the same name and type used by the C-script.

Tag Configuration in WinCC

The WinCC tag must mirror the PLC tag exactly. Mismatch in data type, address, or update cycle is the most common reason a C-script reads a constant value and falls through to the else branch.

The C-Action Pattern

A WinCC C-action is a C function with a fixed signature, including the header apdefap.h which provides the prototypes for GetTagWord, SetTagWord, OpenPicture, and the rest of the WinCC C API. The two lines #include "apdefap.h" and int gscAction( void ) are inserted automatically by the editor and must not be removed.

/* WINCC:TAGNAME_SECTION_START
// next TagID : 1
#define TAG_1 "PLCtag"
// WINCC:TAGNAME_SECTION_END
*/

#include "apdefap.h"
int gscAction( void )
{
    WORD wValue = 0;

    /* Read the current value of the PLC tag into a local WORD */
    wValue = GetTagWord( TAG_1 );

    /* Map tag value to picture */
    if ( wValue == 0 )
    {
        OpenPicture( "Picture1.PDL" );   /* Return-Type: void */
    }
    else if ( wValue == 1 )
    {
        OpenPicture( "Picture2.PDL" );
    }
    else if ( wValue == 2 )
    {
        OpenPicture( "Picture3.PDL" );
    }
    else if ( wValue == 3 )
    {
        OpenPicture( "Picture4.PDL" );
    }
    else
    {
        OpenPicture( "Picture1.PDL" );
    }

    return 0;
}

The same logic with a switch statement is more compact and slightly faster for large mappings:

#include "apdefap.h"
int gscAction( void )
{
    WORD wValue = GetTagWord( "PLCtag" );

    switch ( wValue )
    {
        case 0:  OpenPicture( "Picture1.PDL" ); break;
        case 1:  OpenPicture( "Picture2.PDL" ); break;
        case 2:  OpenPicture( "Picture3.PDL" ); break;
        case 3:  OpenPicture( "Picture4.PDL" ); break;
        default: OpenPicture( "Picture1.PDL" ); break;
    }
    return 0;
}

Trigger Configuration

The C-action must be triggered cyclically so that the value of PLCtag is re-read on a regular basis. Configure the trigger in the right-hand pane of the C-Editor:

1. Open the action in Global Script → C-Editor → Actions → Global Actions.
2. Right-click and select Info / Trigger.
3. Add a trigger of type Timer → Cyclic.
4. Set Cycle to 2 s (or 500 ms for snappier response; do not go below 250 ms as it loads the WinCC scheduler).
5. Keep Event: Standard cycle checked; this is the default that fires the action on the configured cycle.

Common Errors in the Original Code

The thread documents three distinct mistakes. The fixes are listed in the order they appeared during the debugging session.

After the third correction, the script compiled, ran on the 2-second cycle, and successfully switched the runtime picture whenever the PLC wrote a new value to PLCtag.

Debugging with GSC Diagnostics and printf

The line printf("%d\r\n", wValue); in the C-action writes the variable value to the Global Script diagnostics window. To see the output in Runtime, drop a GSC Diagnostics application window into the start picture:

1. Open the start picture (e.g. Picture1.PDL) in Graphics Designer.
2. From the Smart Objects palette choose Application Window → Global Script → GSC Diagnostics.
3. Place the object on the picture and resize it.
4. Alternatively, use apDiag in the background to capture printf output without embedding a window.

This technique is essential for the commissioning phase because it lets you verify the tag value the script sees, independent of the value displayed in a WinCC IO field. If the diagnostics window shows the correct value but the picture does not change, the failure is downstream of the read (i.e. in the OpenPicture call or the picture name).

Alternative Implementations

The C-action pattern is the most flexible, but two other approaches cover common requirements.

Picture Window with Dynamic Picture Name

Insert a Picture Window smart object on a base screen. Bind its Picture Name property to a WinCC tag that holds the full picture name. Configure an event on a tag change to update the property, or use a direct tag connection:

1. Add a string tag, e.g. PictureName (TEXT 8).
2. In the PLC, write the ASCII string Picture1.PDL through Picture4.PDL to the tag area.
3. In the Graphics Designer, select the Picture Window, open the Properties dialog, and under Miscellaneous → Picture Name create a direct tag connection to PictureName.
4. Set the update cycle to 1 s.

Tag-Based Display Property on a Button

Place a transparent full-screen button over the screen. In the Display property, bind the Yes bit to a tag that the script sets after OpenPicture returns. This is what the thread author tried and rejected because the screen also had to be reachable from in-picture navigation buttons.

Trigger Cycle vs. PLC Debounce

With a 2-second trigger cycle, holding the physical button will cause a maximum of 2 seconds of latency before the screen catches up. For faster response, drop the cycle to 500 ms, but debounce the button in the PLC first; otherwise the PLC will write a sequence of increment values to the tag in tens of milliseconds and the script will skip screens.

A recommended PLC pattern uses a one-shot with a 200 ms debounce timer and a counter that wraps at 4:

// STEP 7 STL pseudo-code (S7-1500)
A    I 0.0         // physical button
FP   M 0.0         // rising edge
AN   M 0.1         // debounce
S    M 0.2         // one-shot

A    M 0.2
L    1
T    DB1.DBB0      // increment

A    M 0.2
JC   noReset
L    0
T    DB1.DBW0      // wrap to 0 after value 3
noReset: NOP 0

The PLC writes the value to DB1.DBW0, the WinCC tag PLCtag mirrors it on the configured update cycle, and the C-action re-reads it on its 2 s trigger.

Verification

1. Compile the project in Graphics Designer; verify no errors in the C-Editor output window.
2. Activate Runtime and confirm the GSC Diagnostics window shows the expected PLCtag value as the button is pressed.
3. Watch the WinCC screen: it must change to Picture1.PDL when PLCtag == 0, Picture2.PDL when PLCtag == 1, and so on.
4. Force PLCtag to 4 in the WinCC Tag Simulation table; the screen must fall back to Picture1.PDL (the else branch).
5. Stop Runtime, edit the script to add printf calls, reactivate, and check that the diagnostics window still shows the correct value (proves the script is being invoked).

Troubleshooting Matrix

Performance Notes

A C-action that runs every 2 s and performs a single GetTagWord plus an OpenPicture adds well under 0.1% CPU load on a typical WinCC server. The 2 s cycle is conservative; for most operator-screen tasks 500 ms is the practical minimum. Below that, prefer an event-driven trigger (e.g. on tag change) rather than reducing the cycle further. WinCC does not have a built-in "on tag change" trigger for external WinCC tags; the closest is to use a small cycle (500 ms) or to write a hotkey-driven script that fires on a user action.

Security and Safety Considerations

Screen switching driven by a PLC tag is a comfort feature, not a safety function. If the screen change is used to acknowledge a fault, ensure that the PLC writes the same fault ID to a non-volatile area and that the operator still has a manual acknowledgement path. A global C-action that calls OpenPicture cannot replace a SIL-rated acknowledgement.

Migration to TIA Portal / WinCC Professional

WinCC Professional in TIA Portal moves scripting to VBScript for the engineering project, but C remains available for runtime actions. The equivalent VBScript pattern is:

' HMIRuntime global action, triggered every 2 s
Sub OnLoseFocus(ByVal Item)
    Dim vValue
    vValue = HMIRuntime.Tags("PLCtag").Read
    Select Case CLng(vValue)
        Case 0  HMIRuntime.BaseScreenName = "Picture1.PDL"
        Case 1  HMIRuntime.BaseScreenName = "Picture2.PDL"
        Case 2  HMIRuntime.BaseScreenName = "Picture3.PDL"
        Case 3  HMIRuntime.BaseScreenName = "Picture4.PDL"
        Case Else HMIRuntime.BaseScreenName = "Picture1.PDL"
    End Select
End Sub

Setting HMIRuntime.BaseScreenName is preferred over the legacy OpenPicture call in TIA Portal because it works with faceplates and the new screen window navigation model.

Edge Cases and Field Tips

• If the project has a configured start picture, calling OpenPicture on the start picture has no visible effect, but the action still consumes a runtime tick. Skip the call when the current picture is already the target.
• The PDL extension is required in WinCC V7; WinCC Professional accepts the name without the extension but adding it explicitly is portable.
• If the user has multiple monitors, OpenPicture opens the picture on the default monitor; use OpenPictureInPopup or a picture window for secondary screens.
• Avoid putting the C-action in the picture itself; global actions persist across picture changes and are easier to maintain.

FAQ