Access WinCC Faceplate Variables and Properties from C Scripts

Faceplates in WinCC Runtime (Comfort, Professional, and Unified) expose a controlled interface to the parent screen. Engineers frequently need to read or write faceplate data from a C script running on the parent picture, or from a script embedded inside the faceplate type. WinCC documents two distinct containers: faceplate variables (internal to the type, used to dynamize the faceplate itself) and faceplate properties (the public, configurable interface of an instance). C scripts in classic WinCC cannot reach faceplate instance variables directly; they can only reach properties and external tags. WinCC Unified V20 documents an additional Parent property on the Faceplate object that lets an internal script walk up to the container. This reference documents the access model, the documented workarounds, and the runtime API for both RT environments.

Faceplate Architecture Overview

A WinCC faceplate is a reusable picture that is instantiated one or more times in a parent screen. Each instance receives its own configuration values through the instance properties configured in the parent. Internally, the faceplate type uses faceplate variables to drive its own visualization. The distinction matters for scripting:

• Faceplate type — the *.fpt template stored in the project library; defines properties, variables, and the visual layout.
• Faceplate instance — a configured occurrence in a parent picture; holds concrete property values.
• Faceplate property — a typed interface value (BOOL, INT, REAL, STRING, tag reference) declared on the type, configurable per instance, accessible from outside.
• Faceplate variable — an internal tag (HMI tag) declared on the type, used only inside the type itself, used to dynamize the faceplate graphics.

The rule of separation is: properties flow in from outside and out of the faceplate; variables live inside the faceplate. The C script environment on a parent screen can only see the properties of the instance, never the internal variables of the type, unless the type chooses to expose them through a property.

Faceplate Variables vs. Faceplate Properties

The table below captures the practical differences an engineer needs to know when designing faceplate access logic.

C Script Runtime Environment in WinCC Comfort and Professional

Classic WinCC RT supports two script languages: VBScript and C-Script (a C-style language with WinCC API extensions). C-Script is compiled at download time and runs in the WinCC RT scheduler. The relevant API for faceplate access includes:

• GetTag(lpszTagName) / SetTag(lpszTagName, value) — read/write an HMI tag by name.
• GetTagBit, SetTagBit, GetTagByte, SetTagByte, GetTagWord, SetTagWord, GetTagDWord, SetTagDWord, GetTagFloat, SetTagFloat — typed tag accessors.
• GetProp(lpszPictureName, lpszObjectName, lpszPropertyName) — read any object property, including a faceplate instance property.
• SetProp(lpszPictureName, lpszObjectName, lpszPropertyName, value) — write any object property, including a faceplate instance property.
• GetLinkedProperty / SetLinkedProperty — read/write the source of a tag-linked property.

These calls operate on a fully qualified PictureName, ObjectName, and PropertyName. For a faceplate instance in the picture Main, the object name is the instance name (e.g. FaceplateInstance_1); the property name is the property as declared on the faceplate type.

Access Restrictions for Faceplate Instance Variables

A C-Script running on a parent screen cannot directly address a faceplate variable. WinCC exposes the property interface of a faceplate instance to the parent; the variable namespace is private to the faceplate type. Three consequences follow:

1. You cannot call GetTag("Faceplate_Var_1") from a parent C script to read a faceplate variable, because faceplate variables are not visible at the parent level.
2. You cannot call GetProp on a faceplate instance with the name of a faceplate variable and get a value back, because the variable is not a property.
3. If the requirement is to expose internal state, the faceplate designer must add a property to the type and bind the faceplate variable to that property internally.

Workaround: Link the Property to an IO Field Output Value

When a faceplate type does not expose a needed value as a property, a documented workaround is to add an I/O field inside the faceplate type, bind its output value to a property (so the value is read out of the faceplate), and then read that property from a parent script. The pattern is:

1. Inside the faceplate type, place an I/O field whose Output property is configured to the faceplate variable you want to expose.
2. Configure a new faceplate property, e.g. ExposedValue, on the type. Configure the I/O field to update that property in the Output Value configuration.
3. Set the I/O field to invisible if no display is desired; the property is still updated.
4. From a parent C script, call GetProp("Main", "FaceplateInstance_1", "ExposedValue") to read the previously internal value.

This pattern is supported in WinCC Comfort and WinCC Professional and works for any data type the I/O field can carry (numeric, string, with appropriate conversion).

WinCC Unified V20: Accessing Container Properties with the Parent Property

WinCC Unified Runtime changes the scripting model. Scripts are written in JavaScript or C# and execute against a unified object model. The Accessing properties of the faceplate container with a script (RT Unified) page documents that, to read or write faceplate container properties from a faceplate type, you use the Parent property of the Faceplate object inside the script. This gives the faceplate type the ability to walk up the faceplate container hierarchy to the embedding screen, and from there to its own instance properties.

The Parent property is exposed on the faceplate type's Faceplate object and returns a reference to the container (the embedding faceplate instance or screen). Once the container reference is obtained, the script can read or write properties on the container, including properties that are themselves faceplate references, allowing a nested access pattern.

Reading a Container Property in WinCC Unified (JavaScript)

The following JavaScript snippet, embedded in a faceplate type event or a scheduled script, reads a property named Level from the embedding faceplate container. The Parent reference is the documented entry point.

// Inside a faceplate type script (WinCC Unified, JavaScript)
// 'Parent' is the faceplate container that hosts this instance.
let container = this.Parent;
if (container !== null) {
    let levelValue = container.Level;
    // Use levelValue to dynamize internal state, log, or trigger UI updates.
    HMIRuntime.Trace("Container Level = " + levelValue);
}

This pattern is supported per the TIA Portal V20 documentation referenced above. The Parent reference is available on the Faceplate object inside the faceplate type, and properties on the container are accessed by name as object properties.

Writing a Container Property in WinCC Unified (JavaScript)

To push a value out from the faceplate type to the container, assign to the property on Parent. The container side will see the change as a property update, which can in turn trigger dynamization, scripts, or tag links configured on the container side.

// Inside a faceplate type script (WinCC Unified, JavaScript)
let container = this.Parent;
if (container !== null) {
    container.AcknowledgeFlag = true;
    container.StatusText = "Acknowledged at " + new Date().toISOString();
}

Note that writing to a container property is only meaningful if that property is declared on the container faceplate type. Writing to a non-existent property is silently ignored or rejected, depending on the property and the RT build.

Reading and Writing Properties from a Parent Script in WinCC Unified

A script that lives on the parent screen, not inside the faceplate type, addresses a faceplate instance through the screen's object model. The instance is referenced by its name; properties are accessed by name on the instance object.

// Parent screen script, WinCC Unified (JavaScript)
let instance = Screen.FindItem("FaceplateInstance_1");
if (instance) {
    // Read a faceplate property
    let setpoint = instance.Setpoint;

    // Write a faceplate property
    instance.Setpoint = 75.0;

    // Trigger a method exposed by the faceplate type
    if (typeof instance.Reset === "function") {
        instance.Reset();
    }
}

This script lives on the parent picture and addresses the faceplate instance directly. It cannot read internal faceplate variables; it can only read or write properties and call methods exposed by the type.

C-Script Example: Reading a Faceplate Property in WinCC Comfort/Professional

The equivalent in classic WinCC C-Script uses the GetProp API. The picture name is the parent picture, the object name is the instance name, and the property name is the faceplate property as declared on the type.

// Classic WinCC C-Script, executed on a parent picture event
// PictureName: "Main"
// ObjectName:  "FaceplateInstance_1"
// Property:    "Setpoint" (declared on the faceplate type)

double currentSetpoint;
currentSetpoint = GetPropDouble("Main", "FaceplateInstance_1", "Setpoint");
// or, in a numeric form:
// currentSetpoint = atof(GetPropChar("Main", "FaceplateInstance_1", "Setpoint"));

The result of GetProp depends on the data type of the property. Use GetPropWord for 16-bit integers, GetPropDouble for floating-point properties, and GetPropChar for string properties. The function name suffix matches the data type.

C-Script Example: Writing a Faceplate Property in WinCC Comfort/Professional

// Classic WinCC C-Script, executed on a parent picture event
// Set a BOOL property to TRUE
SetPropBool("Main", "FaceplateInstance_1", "Acknowledge", TRUE);

// Set a numeric property to a new value
SetPropDouble("Main", "FaceplateInstance_1", "Setpoint", 80.0);

// Set a string property
SetPropChar("Main", "FaceplateInstance_1", "StatusText", "Running");

These calls succeed only if Setpoint, Acknowledge, and StatusText are declared as faceplate properties on the type. Calling SetProp with a faceplate variable name returns an error and does not change the internal state.

Tag-Based Communication Pattern

For values that must be read across multiple instances or across screens, the most reliable pattern is to use a tag link on a faceplate property. The faceplate designer declares the property, sets the type to Tag, and the user configures the parent side to bind a specific HMI tag to that property. From a parent C script, the script can then read or write the HMI tag directly, completely independent of the faceplate instance.

// Parent C script reads the HMI tag that the faceplate's tag-linked
// property is bound to. The faceplate reads the same tag internally.
int currentMode = GetTagWord("Process_Mode_Select");
if (currentMode == 2) {
    SetTagWord("Process_Mode_Select", 3);
}

This pattern works in all WinCC editions, requires no API tricks, and is the recommended approach for shared, persistent state across faceplate instances.

Distinguishing Faceplate Variables from Instance Variables

A faceplate type also creates instance variables when instantiated — one set of variable instances per faceplate instance. The naming convention prefixes the instance name to the variable name. From outside the faceplate, however, those instance variables are not addressable through the documented C-Script API; they live in the faceplate type's own variable space and are only readable from scripts executing inside the type. This is by design and is the architectural reason for the access limitations described above.

Troubleshooting Matrix

Verification and Commissioning Steps

1. Declare the property on the faceplate type with the correct data type, direction (input/output/input-output), and default value.
2. Re-bind internal dynamization in the type to the new property so the faceplate actually uses the value.
3. Configure the instance in the parent picture to override the default if needed; the property is now visible in the instance configuration dialog.
4. Write the C-Script on the parent side using GetProp / SetProp (classic) or the screen object model (Unified). Compile and download.
5. Test read: trigger the parent script with a known property value, verify the script reads back the same value, and check the diagnostic trace.
6. Test write: from the parent script, write a new property value and verify the faceplate updates its display.
7. Test cross-instance: place a second instance, set its property to a different value, and confirm each parent script reads the correct per-instance value.
8. Test download cycle: stop the RT, recompile, download, and confirm the property mappings survive a full project recompile.

Field-Proven Cautions

• Property names are case-sensitive in GetProp / SetProp calls; an incorrect case returns 0 or empty.
• Calling SetProp on a read-only property at runtime is silently ignored on some RT builds; configure the property as input-output if runtime writes are required.
• The Parent reference in WinCC Unified returns null when the script is running outside a faceplate context; always guard the access with a null check before dereferencing.
• Faceplate variable changes do not propagate to other instances. If two faceplates need a shared value, use a tag link on a property bound to a shared HMI tag.
• In TIA Portal V20, the Parent access pattern is the documented mechanism for faceplate-internal scripts that need to read or write container properties; there is no equivalent documented GetProp / SetProp path in Unified as there is in classic RT.

FAQ