WinCC Unified PropertyFlashing: Script-Based Dynamization Guide

Overview: Flashing Dynamization in SIMATIC WinCC Unified

WinCC Unified (TIA Portal) exposes a runtime dynamization model in which graphical object properties can be bound to tags, expressions, scripts, or — for a limited set of properties — to a built-in flashing mechanism. The flashing mechanism is configured in the Engineering software and is normally driven by a fixed Condition property that only offers three states:

• Always — flash unconditionally
• Never — never flash
• RangeViolation — flash only when a connected tag falls outside a configured limit range

For most HMI projects this is insufficient. Engineers routinely need conditional flashing driven by a script variable, an internal state machine, or a faceplate interface tag. Until TIA Portal V16 the only workaround was to toggle two static colors via a tag-driven property dynamization, which is fragile and breaks the moment the screen contains transparent icons or layered graphics.

From TIA Portal V17 onward, the runtime exposes the PropertyFlashing system function on every screen object that inherits from the HMIScreenObjectBaseInterface. This makes it possible to start, stop, and parameterize flashing directly from a Unified JavaScript, without leaving the runtime and without depending on the three static Condition modes.

The PropertyFlashing System Function (API Reference)

PropertyFlashing is a method of the screen object base interface. It accepts a single configuration object that describes which property to flash and how the flash is to be rendered. Field-tested call shape:

// Signature (typified)
Screen.Items().Item('MyRectangle').PropertyFlashing(
    PropertyName    : 'BackColor',
    FlashingColor   : 0xFFFF0000,        // ARGB, red, fully opaque
    FlashDuration   : 500,               // [ms] one full on/off cycle
    FlashEnable     : true               // bool, set false to stop
);

Parameter matrix — values are taken from the SIMATIC HMI WinCC Unified Engineering help that ships with TIA Portal V17 / V18 / V19 / V20 and from the TIA Portal V20 online help:

Prerequisites and Supported Versions

• TIA Portal V17 Update 4 or higher (V18, V19, V19.1, V20 confirmed working).
• WinCC Unified Runtime matching the engineering version. Mixed engineering (e.g. V19 project loaded on a V18 RT) may not register PropertyFlashing.
• Target object must be a screen object that implements HMIScreenObjectBaseInterface. This is the case for rectangles, ellipses, lines, polylines, text fields, buttons, IO fields, symbols, and — in faceplates — for the faceplate root and for every faceplate-internal control of the above types.
• Script must be a screen-level or faceplate-level Unified script. Global library scripts do not have direct access to Screen.Items().

Step-by-Step: Minimal Working Example

This example flashes the BackColor of a rectangle named Rect_Status for as long as the tag HMI_Tag::iValue equals 10. Any other value stops the flash and sets a static color.

1. Open the screen in TIA Portal and create a rectangle. Name it Rect_Status.
2. In the Scripts area of the screen, create a new JavaScript named Flash_OnValue.
3. Paste the following code:

// Flash_OnValue.js — Unified JavaScript, TIA Portal V19.1
// Trigger: tag cycle on HMI_Tag::iValue (250 ms recommended)
(function() {
    let item = Screen.Items().Item('Rect_Status');
    let value = Tags('HMI_Tag::iValue').Read();

    if (value === 10) {
        // Start / refresh flash
        item.PropertyFlashing({
            PropertyName  : 'BackColor',
            FlashingColor : 0xFFFF0000,   // red
            FlashDuration : 500,          // 0.5 s pulse
            FlashEnable   : true
        });
        // IMPORTANT: do NOT return a value here.
        // A returned value would re-write BackColor on every
        // trigger and overwrite the flashing.
    } else {
        // Stop flashing and pin a static color
        item.PropertyFlashing({
            PropertyName  : 'BackColor',
            FlashingColor : 0xFF808080,   // grey, ignored when stopped
            FlashDuration : 500,
            FlashEnable   : false
        });
        item.BackColor = 0xFF808080;
    }
})();

4. Open Scripts > Triggers and add a tag trigger. Set Trigger tag to HMI_Tag::iValue and Cycle to 250 ms. Per the V20 scripting reference the script may be triggered by either a fixed cycle or a tag change; for state-driven flashing a tag cycle is the most reliable option because the screen needs the flash to start and to stop on its own.
5. Compile and download to the Unified Panel or PC Runtime.

Triggers: Cycle, Tag Change, and Event

Unified scripts may be invoked in three ways. The choice drives the behavior of PropertyFlashing:

Conditional Flashing with Multiple States

The original problem statement is: change the color of some objects in a faceplate according to a variable, and start flashing when the value is 10. A common expansion is a 3-state indicator (OK / Warning / Alarm) where the alarm state also has to flash. The pattern below generalizes to any number of states:

// Flash_3State.js — Unified JavaScript, V19.1
(function() {
    let rect = Screen.Items().Item('Rect_Status');
    let v    = Tags('HMI_Tag::iState').Read();   // 0, 1, 2

    // 1) Always stop any previous flash first so that the
    //    transition between flashing states is clean.
    rect.PropertyFlashing({
        PropertyName  : 'BackColor',
        FlashingColor : 0,
        FlashDuration : 500,
        FlashEnable   : false
    });

    switch (v) {
        case 0:  // OK, solid green
            rect.BackColor = 0xFF2E7D32;
            break;

        case 1:  // Warning, solid amber, no flash
            rect.BackColor = 0xFFFFA000;
            break;

        case 2:  // Alarm, flashing red
            rect.PropertyFlashing({
                PropertyName  : 'BackColor',
                FlashingColor : 0xFFE53935,   // red
                FlashDuration : 500,
                FlashEnable   : true
            });
            break;
    }
})();

PropertyFlashing in Faceplates

Faceplate-internal objects are reachable the same way once a script is bound inside the faceplate itself. For flashing different properties of the same faceplate instance in response to a faceplate tag, use the this context inside the faceplate script:

// Inside a faceplate script (Faceplate_Type_1)
(function() {
    let faceplateItem = this;   // root of the faceplate instance
    let v = faceplateItem.Tag('FP_AlarmActive').Read();

    let border = faceplateItem.Items().Item('Border_Status');

    border.PropertyFlashing({
        PropertyName  : 'BorderColor',
        FlashingColor : 0xFFFF0000,
        FlashDuration : 500,
        FlashEnable   : (v === 1)
    });
})();

Tag access via the Tag() method is required inside a faceplate to read interface tags; Tags('PLC::FP_AlarmActive') will not resolve to the per-instance value.

Field-Proven Pitfalls and Caveats

The following items are repeatedly observed on commissioning sites and are explicitly called out in the Siemens engineering community threads that accompany the official help:

Alternative: Flashing via a User-Defined Function (V20+)

For simple one-event flashing (e.g. flash a button on press) the V20 online help documents an event-based alternative that does not require a trigger cycle:

1. Select the source object (e.g. a button).
2. In the Inspector, open Events > Press.
3. Assign a user-defined function (UDF) that calls PropertyFlashing on the target object with FlashEnable=true for a bounded duration.
4. Assign a second UDF to the matching Release event with FlashEnable=false.

This is preferred for HMI elements that flash only as feedback for a user action. It is not a substitute for the cycle-driven approach when the flashing is driven by process state.

Comparison: Available Flashing Methods in WinCC Unified

Verification and Commissioning Checklist

1. Build & download the project to the Unified RT. Open the screen containing the rectangle.
2. Force the tag HMI_Tag::iValue to 10 from the PLCSim or the HMI tag simulator. The rectangle should pulse at 0.5 s.
3. Force the tag to any value other than 10. The pulse should stop within one trigger cycle (≤ 500 ms) and the rectangle should display the static grey.
4. Check the RT trace (WinCC Unified RT > Diagnostics > Trace) for any "PropertyFlashing is not a function" or "Object reference not set" entries. Either indicates a missing object name or a mis-versioned runtime.
5. Cycle stress test — drive the tag through 0 → 10 → 0 ten times. Verify the rectangle does not get stuck in a flashing state. A stuck flash is almost always a script that returned a value, see pitfall #1.
6. Color audit — confirm that the flashing color has a minimum 4.5:1 contrast ratio against the static color. The Siemens HMI style guide recommends at least 3:1, but operator panels viewed from a distance benefit from the higher ratio.
7. Performance check — open RT Performance on a PC Runtime. The Unified RT should not exceed ~30% CPU when 50 indicators are flashing simultaneously. If it does, reduce the trigger cycle from 250 ms to 500 ms or move the indicator logic to PLC tags.