Setting Gauge Process Value Indicator Color in WinCC Unified

Overview

Dynamic color changes on a gauge are one of the first pieces of screen logic every WinCC Unified developer writes. The classic WinCC line (TIA Portal V13–V15.1, WinCC Comfort/Advanced/Professional) used VBScript or C-Script for screen scripting. With TIA Portal V16, Siemens introduced WinCC Unified and switched the runtime to JavaScript — the only scripting language available on Unified screens. That single change reshapes how the gauge ProcessValueIndicatorBackColor property is bound, animated, and overwritten at runtime.

This reference walks through the entire workflow: the runtime architecture, the property model, the trigger-binding model, a clean field-ready script, the exact HMIRuntime.Math.RGB signature, the simulation-mode behavior that catches most first-time users, and the multi-band and hysteresis patterns used in production. The goal is a self-contained document an automation engineer can apply without first reading the Siemens TIA Portal Help cover-to-cover. The canonical reference for the JavaScript API is the TIA Portal Help under WinCC Unified > Scripting > JavaScript, available through the Siemens Industry Online Support portal.

Prerequisites and Runtime Versions

Before adding a single line of JavaScript, confirm the project is on a runtime that exposes the modern HMIRuntime surface. The TIA Portal version determines what is available.

Additional prerequisites for the workflow described here:

• Unified Runtime or Unified Comfort Panel. Classic Comfort Panels (TP700 Comfort, TP1500 Comfort, KTP series) keep the VBScript runtime and do not expose the JavaScript HMIRuntime object. Identify your device under Project tree > Devices > [HMI] > Device configuration; the runtime type is shown in the device properties.
• License. WinCC Unified PC Runtime requires a valid RT license. Unified Comfort Panels ship the runtime with the firmware. Trial licenses work for development.
• An HMI tag of type Real, Int, or DInt bound to the gauge's ProcessValue. Internal tags are valid for proof-of-concept work; PLC tags are required for live commissioning.
• Basic JavaScript literacy. let / const, conditional logic, function syntax, and the export keyword. The TIA Portal Help ships a JavaScript primer under WinCC Unified > Scripting > JavaScript basics.

JavaScript Runtime and Gauge Object Model

WinCC Unified runs a sandboxed JavaScript engine inside the HMI runtime. Every screen has its own script context. The runtime exposes a global HMIRuntime object that wraps the tag system, the trace, the math helpers, and the logging API. Screen objects — including the Gauge — are reachable through the item parameter of a trigger function.

The Gauge is a composite control with several visual layers: the dial face, the scale, the value text, the indicator needle (or bar), and the indicator background. The ProcessValueIndicatorBackColor property controls the fill of the indicator background. The full property set that the script can read or write is enumerated in the TIA Portal Help under WinCC Unified > Controls > Gauge; the most commonly used ones are listed below.

The COLORREF layout is the standard WinCC 32-bit color encoding: 0x00BBGGRR in hexadecimal, or B * 65536 + G * 256 + R in decimal. Most engineers will never hand-encode this; the helpers in HMIRuntime.Math produce the right value from an (R, G, B) triple.

Trigger Function Model and Binding Workflow

WinCC Unified does not support a "click handler" model on a property. There is no event on the gauge to subscribe to. Instead, the runtime owns a polling loop: a script function is called whenever its configured trigger fires. The trigger can be a tag change, a cyclic interval, a screen-open event, or a combination. The script writes the property; the runtime repaints.

The full binding workflow:

1. The function is declared in a .js file under Project tree > Scripts > Script folder. The file is compiled into the runtime image when the project is downloaded.
2. The function uses the export keyword. Exported functions appear in property trigger dropdowns; non-exported ones are not visible.
3. On the screen, the engineer selects the Gauge and opens the Properties window.
4. For ProcessValueIndicatorBackColor, the engineer clicks the property arrow and chooses Script (not Constant, Tag, or Dynamic dialog).
5. The trigger dialog asks for the function name and the trigger source. The trigger source can be a tag change, a fixed cyclic interval (e.g., 500 ms), or both.
6. On every trigger fire, the runtime calls the function with the screen item as item. The function reads tags, decides a color, and assigns it to item.ProcessValueIndicatorBackColor.

The function name does not need to follow any specific convention. A suffix like _Trigger is a common practice that makes the function easy to identify in dropdowns, but it is not enforced by the runtime.

Step-by-Step Configuration

The complete sequence from an empty project to a working color-changing gauge, in twelve explicit steps.

1. Create or open the TIA Portal project and add a Unified PC station or Unified Comfort Panel under Devices > Add new device.
2. Add an HMI tag of type Real under HMI tags > Default tag table. Name it ProcessValue. Set the start value to 5.0 for testing.
3. Add the Gauge to the screen. Open the screen under Screens, drag the Gauge from the toolbox onto the canvas.
4. Bind the gauge to the tag. In the Properties window of the gauge, find ProcessValue and click the property arrow. Select HMI tag and pick ProcessValue.
5. Create a script file. In the project tree, right-click Scripts > Script folder, choose Add new > JavaScript file. Name it GaugeColor.js. The file appears under \Script\.
6. Author the function. Open the file and write the trigger function. Use the working code sample in the next section as a starting point.
7. Compile the project. Right-click the HMI device and choose Compile > Software (rebuild all). Any JavaScript syntax error is reported in the Info window.
8. Bind the script to the property. Click the Gauge, find ProcessValueIndicatorBackColor in the Properties window, click the property arrow, and select Script.
9. Select the function. In the trigger dialog, the dropdown lists every exported function in the project. Pick Gauge_ProcessValueIndicatorBackColor_Trigger.
10. Configure the trigger source. Under the trigger tab, set the source to ProcessValue with "On change". Optionally add a 500 ms cyclic trigger for development-time testing.
11. Download the project to the runtime. In Simulation, click Start simulation. On a panel, drag the project from TIA Portal to the panel via the transfer dialog.
12. Verify on screen. Drive the ProcessValue tag (from PLCSIM, a faceplate, or a test script) and confirm the indicator color changes at the configured threshold.

Working Code and HMIRuntime.Math.RGB Reference

The minimum viable script reads the HMI tag, evaluates the threshold, and writes the COLORREF back to the gauge property. The companion reference table documents every color helper in HMIRuntime.Math and the byte layout the runtime actually uses.

// File: GaugeColor.js
// Property: Gauge.ProcessValueIndicatorBackColor
// Trigger : OnChange of HMI tag "ProcessValue"

export function Gauge_ProcessValueIndicatorBackColor_Trigger(item) {
    // Read the live process value.
    let value = Tags("ProcessValue").Read();

    // Threshold logic — adjust limits and colors for the actual process.
    if (value > 9.8) {
        item.ProcessValueIndicatorBackColor = HMIRuntime.Math.RGB(255, 0, 0);   // red
    } else if (value < 2.0) {
        item.ProcessValueIndicatorBackColor = HMIRuntime.Math.RGB(0, 0, 255);   // blue
    } else {
        item.ProcessValueIndicatorBackColor = HMIRuntime.Math.RGB(0, 200, 0);   // green
    }

    return value;  // informational; the runtime does not use this.
}

Three subtle points about the code above:

• Tags("ProcessValue").Read() — The string argument is the HMI tag name and is case-sensitive. The function returns a Variant; arithmetic comparisons coerce it to Number automatically.
• item.ProcessValueIndicatorBackColor = ... — Writing to a property on item applies the value to the screen object. The runtime repaints the gauge on the next frame; no manual refresh is needed.
• The return value — The runtime ignores the function's return for property triggers. The "value" is propagated only for tag-quality diagnostics. Returning the read value is conventional and aids in HMIRuntime.Trace diagnostics.

Reference table for the color helpers in HMIRuntime.Math:

The COLORREF encoding in detail:

The two encodings differ. Hand-composing a hex value such as 0x00FF0000 will set the value to blue in the WinCC 0x00BBGGRR layout, not red. Always use the HMIRuntime.Math helpers.

Common Errors and Field-Proven Fixes

The following issues are the ones reported most often in field projects. Each row maps a symptom to a likely cause and a tested fix.

Simulation vs. RT Runtime Behavior

A frequent first-time observation: the gauge color script runs correctly on a real Unified Comfort Panel and on Unified PC Runtime, but does nothing in the TIA Portal "Start Simulation" view. The cause is the trigger source.

The simulation runtime honors tag-change triggers only when the tag value actually changes through the simulated connection. If the gauge is bound to a PLC tag and no PLCSIM is attached, the tag value stays at the configured start value forever, and the trigger function is never called. The cyclic trigger is the workaround: a 250–1000 ms interval forces re-evaluation, regardless of whether the value changed.

Field-tested workflow:

1. Development on a PC. Configure a cyclic trigger (500 ms) in addition to the tag-change trigger. Use the Simulation to iterate quickly on threshold values and color choices.
2. Pre-commissioning. Remove the cyclic trigger. Test on the actual panel or a Unified PC Runtime with a PLCSIM connection driving the tag. The tag-change trigger alone is enough.
3. Production. Tag-change trigger only. The function runs only on real value changes, minimizing runtime overhead.

Three more simulation-specific caveats worth flagging:

• Tag multiplexing (the HMI tag's source PLC address changes at runtime) can mask the trigger if the multiplexing is set up incorrectly. The tag-change trigger fires only when the current source's value changes, not when the source itself switches.
• Some projects use a "simulation" mode where an internal tag overrides the PLC tag. In that case, the trigger must be bound to the internal tag, not the PLC tag, to fire during simulation testing.
• The TIA Portal Start simulation view runs the Unified runtime in a Windows process; behavior is closer to PC Runtime than to a Comfort Panel. Issues that appear only on a Unified Comfort Panel (firmware-dependent tag limits, panel-specific performance) will not surface in Simulation and must be verified on the real device.

Advanced Patterns

Multi-band thresholds

For processes with more than two states (normal, warning, high alarm, low alarm), a table-driven approach keeps the script compact and the colors easy to maintain.

const BANDS = [
    { limit: -Infinity, color: HMIRuntime.Math.RGB(0, 0, 255) },     // < 2.0
    { limit:  2.0,      color: HMIRuntime.Math.RGB(0, 200, 0) },    // 2.0..9.8
    { limit:  9.8,      color: HMIRuntime.Math.RGB(255, 200, 0) },  // 9.8..11.0
    { limit: 11.0,      color: HMIRuntime.Math.RGB(255, 0, 0) }     // > 11.0
];

export function Gauge_ProcessValueIndicatorBackColor_Trigger(item) {
    const v = Tags("ProcessValue").Read();
    let chosen = BANDS[0].color;
    for (const band of BANDS) {
        if (v >= band.limit) chosen = band.color;
    }
    item.ProcessValueIndicatorBackColor = chosen;
    return v;
}

Add or remove entries from BANDS to extend the visualization without rewriting the conditional logic. The -Infinity entry is the floor: it guarantees a defined color for any value, even one below the lowest configured threshold.

Hysteresis to suppress flicker

When the process value hovers near a threshold (typical for temperature, pressure, level), the indicator can strobe between two colors. A stateful fix using an HMI tag to remember the last color:

export function Gauge_ProcessValueIndicatorBackColor_Trigger(item) {
    const v = Tags("ProcessValue").Read();
    const lastState = Tags("GaugeColorState").Read(); // 0 = normal, 1 = high
    let nextState = lastState;

    if (lastState === 0 && v > 9.85)      nextState = 1;
    else if (lastState === 1 && v < 9.75) nextState = 0;

    Tags("GaugeColorState").Write(nextState);
    item.ProcessValueIndicatorBackColor = (nextState === 1)
        ? HMIRuntime.Math.RGB(255, 0, 0)
        : HMIRuntime.Math.RGB(0, 200, 0);
    return v;
}

The two thresholds (9.85 to enter, 9.75 to leave) define a 0.10-unit dead band. The exact width depends on the noise floor of the process signal — typically 2× the RMS noise of the analog input. The GaugeColorState tag should be initialized to 0 in the tag table to avoid undefined behavior on first run.

Blinking alarm

For a high-priority alarm, the indicator can be toggled between two colors at 500 ms intervals using a second, dedicated cyclic script that reads an AlarmActive tag and writes the color accordingly. Keep the blink generator in a separate function so the threshold logic above is not entangled with the cycle logic. The threshold function decides whether to alarm; the blink function decides how the alarm is rendered.

// Cyclic 500 ms trigger, no tag change source.
export function Gauge_AlarmBlink_Trigger(item) {
    const active = Tags("AlarmActive").Read();
    if (!active) return false;

    // Toggle every 500 ms; the trigger is the cycle itself.
    const phase = (Date.now() / 500) % 2 < 1 ? 0 : 1;
    item.ProcessValueIndicatorBackColor = (phase === 1)
        ? HMIRuntime.Math.RGB(255, 0, 0)
        : HMIRuntime.Math.RGB(0, 0, 0);
    return true;
}

This pattern keeps the threshold logic pure (event-driven) and the visual blink logic pure (time-driven). Splitting the responsibilities makes both easier to test and easier to disable independently.

Reading the current color back

For debugging or for coordinating multiple gauges, the current color can be read back through HMIRuntime.Math.GetRGBValue:

const current = item.ProcessValueIndicatorBackColor;
const rgb = HMIRuntime.Math.GetRGBValue(current);
HMIRuntime.Trace("Current color: R=" + rgb.R + " G=" + rgb.G + " B=" + rgb.B);

Tag quality handling

When the PLC connection is lost, the HMI tag's quality code becomes Bad and the value freezes at the last good read. A production-grade script should branch on quality:

export function Gauge_ProcessValueIndicatorBackColor_Trigger(item) {
    const tag = Tags("ProcessValue");
    const quality = tag.ReadQuality();

    if (quality !== 0 /* Good */) {
        item.ProcessValueIndicatorBackColor = HMIRuntime.Math.RGB(128, 128, 128); // gray = no data
        return false;
    }

    const v = tag.Read();
    // ... normal threshold logic ...
    return true;
}

Quality code 0 is "Good" per the OPC UA specification. Codes 1 (Bad), 2 (Uncertain), and 3 (Not Connected) all warrant a fallback color so the operator can distinguish a real reading from a connection-loss condition.

Faceplate Reuse, Performance, and Diagnostics

Faceplate reuse

The Gauge is most often embedded inside a faceplate that wraps a sensor or a valve. The same script works inside a faceplate instance — the item parameter resolves to the faceplate's internal Gauge. Trigger the script on a faceplate-level tag, not a screen-level tag, so the script travels with the faceplate instance. This pattern lets one script serve dozens of gauge instances on a single screen. The faceplate interface (left-side interface tags) should expose the process value tag to the script; the script itself is stored in the faceplate's Scripts folder, not the screen's.

Performance

The gauge color update is one of the cheapest animations on a Unified panel. Even at a 100 ms cyclic trigger, the function runs in well under 1 ms on a Unified Comfort Panel. The cost drivers to watch are:

• Number of tag reads per call. Tags("...").Read() is a synchronous API call into the HMI tag system. A few reads per trigger fire is fine; dozens of reads on a 100 ms cycle will show up in the runtime trace.
• String concatenation in HMIRuntime.Trace. Tracing at the start of every call (every 100 ms = 10 traces per second) floods the log. Trace only on state changes.
• Property write frequency. Writing the same color value back to item on every cycle is harmless; the runtime dedupes identical values, but the script overhead remains. Use a tag-change trigger where possible.
• Object literal construction. Allocating the BANDS array on every call is wasteful in the multi-band pattern. Hoist it to module scope (as shown above) so the array is constructed once when the script is loaded.

Diagnostics

Use HMIRuntime.Trace at the boundary of the function to confirm execution during commissioning:

export function Gauge_ProcessValueIndicatorBackColor_Trigger(item) {
    const v = Tags("ProcessValue").Read();
    HMIRuntime.Trace("Gauge trigger fired, v=" + v);
    // ...color logic...
    return v;
}

The trace output is visible in the runtime's diagnostic view (PC Runtime: Tools > Trace Viewer; Comfort Panel: Control Panel > Trace). Remove the trace line after sign-off to keep the log clean.

Cross-reference to process-indicator hardware

The "process value indicator" concept is not limited to HMI software. Hardware process indicators — standalone panel-mount displays that show a 4–20 mA signal on a five-digit 7-segment readout — use the same color-coded feedback pattern in physical control rooms. Phoenix Contact's process indicators product line is a representative example: the device exposes a backlit display whose color shifts with the input range. The JavaScript-driven gauge color in WinCC Unified is the software-side equivalent of that hardware pattern — same operator-facing concept, different rendering medium.

Verification Checklist

Walk through this list on every new gauge color script before sign-off.

1. The function is exported. The TIA Portal Info window does not flag a "function not exported" warning during compile.
2. The property trigger dialog shows the correct function name and the correct trigger source tag.
3. The runtime trace shows the function name at least once per expected tag change.
4. The indicator color is correct above the high threshold, below the low threshold, and in the normal band.
5. The indicator returns to the normal color when the value drops back below the threshold (with hysteresis, if configured).
6. Navigating away from the screen and back does not leave the indicator in a stale color (a cyclic trigger on screen entry handles this if needed).
7. Disconnecting the PLC (or stopping PLCSIM) does not crash the script. The tag quality goes to Bad; the script should leave the color at a defined default.
8. No TypeError or ReferenceError appears in the runtime log at steady state.
9. The script execution time, traced via performance.now() at the start and end of the function, is below 5 ms per call on the target panel.
10. The script is removed from any test override (extra cyclic trigger, debug trace) before the production image is built.

Frequently Asked Questions