C135 PCS 7 (PCS7)
6C
6 Cielo Ciencia y Tecnología
·Publicada en C135 PCS 7 (PCS7)

Diagnosing Faceplate Button Freezing and Focus Locks in Custom WinCC Scripts

Diagnosing Faceplate Button Freezing and Focus Locks in Custom WinCC Scripts

When a customized button in a SIMATIC PCS 7 WinCC faceplate (such as an incremental setpoint button on VlvAnL) freezes after a single click and refuses further interaction until clicking another field or reopening the window, the fault is caused by unresolved Windows GUI focus capture or an unreset APL command handshake. In WinCC Graphics Designer, custom mouse-click C-scripts that write to process tags without releasing input focus or invoking the standard APL operation completion event leave the GUI thread locked. To resolve this, inspect apdiag.exe for C-script runtime faults, call SetFocus on the parent picture window, or utilize standard APL keypad templates (@PG_APL_OA_Analog101.pdl).

Table of Contents

Executive Summary

During human-machine interface (HMI) customization in SIMATIC PCS 7 V9.0, developers frequently add custom direct-action buttons to standard Advanced Process Library (APL) faceplates (e.g., adding '+0.5' or '+1.0' nudge buttons to VlvAnL or PIDConL to allow rapid setpoint trimming). A notorious defect observed during testing is that clicking the custom button successfully transmits the new value to the controller, but the button visually 'freezes' (remains depressed, disabled, or unresponsive to subsequent clicks). The operator must click another object (such as the MV display box) or close and reopen the faceplate to unfreeze the control. This behavior stems from Windows mouse-focus retention and APL faceplate script-engine handshake deadlocks.

Architecture and Fundamental Mechanics

Analyzing button freezing in WinCC faceplates involves understanding Windows message routing and APL GUI event handling:

1. Windows Message Focus Retention and GUI State

In WinCC Graphics Designer:
- When an operator clicks a Windows Button control, Windows assigns keyboard and input focus to that button (WM_SETFOCUS).
- In standard Windows behavior, a button releases focus upon receiving the mouse-up (WM_LBUTTONUP) event.
- If a custom C-action script on the mouse-click event executes blocking calls (SetTagWait), triggers an unhandled script error, or does not return focus cleanly, the Windows GUI message loop fails to clear the depressed/active state.
- Clicking an external object (like the MV text box) forces Windows to issue WM_KILLFOCUS to the button, instantly unfreezing it.

2. APL Faceplate Cyclic Script Handshake Deadlocks

Standard APL faceplates (@PG_..._Standard.pdl) run an internal background cyclic script (typically every 250 ms):
- The script evaluates whether an operator modification is currently active (OpActive = 1).
- When a custom script writes directly to an AS input tag without clearing the APL internal operation flag or without triggering the OnPropertyChanged event, the faceplate script engine assumes a dialog is still modal or in-flight, disabling further input events on that panel.

3. Diagnosis via APDiag

The WinCC diagnostic utility apdiag.exe monitors script execution in real-time. Unhandled null pointers, type mismatches (e.g., passing a float to SetTagWord), or timeout exceptions during C-script execution appear immediately in the APDiag Output Window.

Step-by-Step Implementation Procedure

To diagnose and eliminate button freezing on customized WinCC faceplates:

Step 1: Monitor Script Execution in APDiag

  1. On the OS workstation, open Windows Explorer and navigate to:
    C:\Program Files (x86)\Siemens\WinCC\uTools\ (or ...\WinCC\bin\).
  2. Launch apdiag.exe as Administrator.
  3. In the APDiag menu, select Output Window.
  4. In WinCC Runtime, open the faceplate and click the '+0.5' button.
  5. Observe the APDiag Output Window. Check for script warnings such as:
    - Execute: Error in action...
    - Tag not found...
    - Call stack trace...

Step 2: Refactor Custom Mouse-Click C-Script

  1. Open the customized faceplate PDL in WinCC Graphics Designer.
  2. Select the custom button -> Object Properties -> Event tab -> Mouse -> Mouse Click.

  3. Ensure the script uses non-blocking functions and explicitly releases focus:
    ```c
    #include "apdefap.h"
    void OnClick(char lpszPictureName, char lpszObjectName, char* lpszPropertyName)
    {
    char szTag[255];
    float fVal = 0.0;

    // Construct fully qualified tag using TagPrefix
    sprintf(szTag, "%s%s", GetTagPrefix(lpszPictureName, ""), "MV_Int");

    // Read current value and increment
    fVal = GetTagFloat(szTag);
    fVal += 0.5;

    // Write back value asynchronously
    SetTagFloat(szTag, fVal);

    // Explicitly reset focus to the picture window to unfreeze button
    SetFocus(lpszPictureName, "");
    }
    ```
    4. Save the PDL.

Step 3: Implement Standard APL Analog Keypad Alternative (Best Practice)

  1. Instead of creating ad-hoc increment buttons that bypass APL security, utilize the standard APL numeric input dialog:
    - Double-clicking the analog value natively opens @PG_APL_OA_Analog101.pdl.
    - This standard dialog includes built-in, fully validated incremental nudge buttons (+1, -1, +10, -10) that never freeze and adhere to operator authorization levels.

Verification

To confirm that the freezing issue is eliminated:

  1. Rapid Multi-Click Test:
    - Open the faceplate in WinCC Runtime.
    - Click the '+0.5' button 5 times in rapid succession.
    - Confirm that the button depresses and releases cleanly with every click, and the MV increments by +2.5 without freezing.

  2. APDiag Log Verification:
    - Confirm that APDiag Output Window remains completely silent with zero script error messages during button operation.

Limitations and Operational Precautions

Operational limitations and precautions:

  1. Bypassing Interlocks and Limits: Directly writing increments via SetTagFloat('MV_Int', ...) can bypass actuator high/low limits (MV_HiLim, MV_LoLim) unless software clamping is explicitly coded in the script or enforced in the AS block.
  2. OS Compilation Overwrites: Custom modifications made directly to system PDLs (@PG_...) will be overwritten during future PCS 7 software updates. Always save customized faceplates under project-specific names.
  3. Synchronous vs Asynchronous Calls: Never use SetTagFloatWait in faceplate UI buttons, as network latency on the terminal bus will cause visible GUI stuttering.
  4. Commercial Disclaimer: Verify all software libraries, engineering licenses, and system packages with an authorized Siemens distributor or the Siemens Industry Mall.

Engineer FAQ

Why does clicking an external object unfreeze the stuck button?

Clicking an external object forces Windows to issue a WM_KILLFOCUS event to the button, releasing the trapped mouse capture and resetting its visual state.

What diagnostic tool detects WinCC C-script errors in real time?

The Siemens utility apdiag.exe (specifically the Output Window) located in C:\Program Files (x86)\Siemens\WinCC\uTools\.

How do I explicitly release focus in a WinCC C-script?

Call SetFocus(lpszPictureName, ""); at the end of the script to shift focus back to the parent picture window.

Why is SetTag preferred over SetTagWait in faceplates?

SetTag writes asynchronously to the local cache without blocking the GUI thread, whereas SetTagWait halts the interface until the server acknowledges the write.

Does APL have built-in incremental setpoint buttons?

Yes. The standard operating dialog @PG_APL_OA_Analog101.pdl includes pre-engineered incremental and decremental buttons that handle focus and limits automatically.

Technical References

Related Articles

Related Tags

  • WinCC Scripting
  • Button Freezing
  • APDiag
  • Faceplate Customization
  • GUI Focus
20 respuestas