Overview
Faceplates in TIA Portal WinCC let you encapsulate reusable visualization objects (pumps, valves, motors, tank widgets) so that one type definition can be instantiated dozens of times on a screen, each instance bound to its own tag set. The question that comes up repeatedly in WinCC Comfort / WinCC RT Advanced projects is whether you can drive faceplate behavior — most commonly object visibility, color, position, or label text — with VBScript (VBS) without having to declare external PLC tags just to switch a bit back and forth.
On TIA Portal V13 SP1 with WinCC Runtime Advanced, VBScript is available inside faceplate types under specific event bindings. The trick is that the VBS does not run from a button event on the instance the way most engineers first attempt; it runs from the Change value event of an interface property on the faceplate type itself. Once this is understood, both a script-free toggle and a script-driven visibility model become straightforward.
This reference walks through the two supported methods, the faceplate-internal tag model, the version-specific behavior documented by Siemens for RT Advanced, and the differences when you target RT Professional instead. It closes with a verification procedure, a troubleshooting matrix, and an FAQ targeting the most common engineer searches.
Prerequisites
- STEP 7 / TIA Portal in version V13 SP1 (Update 4 or later recommended) installed on the engineering station.
- WinCC Comfort or WinCC Advanced option installed and licensed for the engineering station.
- Runtime license for WinCC RT Advanced (or a Comfort Panel target with the equivalent image) for the runtime target.
- A compiled HMI device with a screen that contains at least one faceplate type instance.
- Read access to the official Siemens entry Notes on the behavior of faceplates in WinCC (TIA Portal) for version-pinning rules.
- For RT Professional cross-reference, the TIA Portal online help Configuring an event in the faceplate type (RT Professional).
Faceplate Architecture: Internal Tags vs. Interface Tags
A faceplate type has two distinct tag scopes and engineers frequently conflate them. Understanding the boundary is what makes the visibility trick work.
| Scope | Where declared | Visible to HMI tags table? | Typical purpose |
|---|---|---|---|
| Faceplate internal tag | Inside the faceplate type only, under "Interface" → "Tags" (internal area) | No — hidden from the surrounding screen | Local state for animations, counters, latching logic inside the faceplate |
| Faceplate interface property (tag) | Under "Interface" → "Properties" or "Tags" (external / interface area) | Yes — bound to a tag, DB element, or constant per instance | Passing instance-specific values in and out of the faceplate |
| HMI tag | HMI tags table of the device | Yes — global to the device | Shared between screens, archives, scripts, PLC |
The key property: a faceplate internal tag does not require any HMI tag declaration. It exists only inside the faceplate type, persists for the lifetime of the instance, and can drive animations on that faceplate's own objects. The first method below relies entirely on this scope, which is why it works without polluting the HMI tag namespace.
Method 1 — Toggle Visibility With a Faceplate Internal Tag (No VBS Required)
This is the recommended first approach because it requires no scripting at all, compiles faster, and survives any later TIA Portal upgrade. Use it for any binary state (show / hide, two-color swap, two-state button).
- Open the faceplate type in the WinCC editor (double-click the type under "Faceplates" in the project tree).
- In the faceplate interface, add a new internal tag named e.g.
visibilityof data type Bool. Set its initial value toTRUEorFALSEper your default. - Select the object whose visibility should toggle (a circle, a label, a rectangle — any I/O field graphic object).
- In the Inspector window, switch to Animations → Display.
- Click the small lightning/lightbulb icon next to the "Visibility" property to attach a dynamic value. In the dialog, choose Tag, then drill into the faceplate interface and select
visibility. - Configure the value range:
0 → Hidden,1 → Visible. The faceplate's own object is now driven by the internal tag. - Drop a button onto the faceplate. In the Inspector, go to Events → Click and add a Set tag action:
visibility = NOT visibility. The button now inverts the tag, which inverts the visibility of the bound object. - Compile the faceplate type. Place an instance on a screen. The internal tag is scoped to this instance — each instance has its own copy of
visibility, so toggling one widget never affects another.
0 = Hidden, 1 = Visible, 2 = Visible + blinking, etc. The same NOT trick generalizes to visibility = (visibility + 1) MOD 3 inside a small VBS action or as a C-action in Set value mode.
Method 2 — Trigger VBScript From an Interface Property Change Event
When the logic inside the faceplate is more than a single inversion — e.g. you want to enumerate child objects, write to logs, manipulate multiple graphic properties in one transaction — you need a script. On RT Advanced the supported binding is the Change value event of an interface property.
- Open the faceplate type editor.
- Under Interface, switch to the "Properties" or "Tags" category and add an interface tag named e.g.
visibilityInputof type Bool. This is an interface tag, not an internal one — it will be wired to a real tag or constant when the faceplate is instanced. - Select the newly declared
visibilityInputproperty in the interface list. - In the Inspector window, switch to Events → Change value. The available action list here is the critical detail: in TIA V13 SP1 RT Advanced, this event supports VBScript actions, system functions, and user-defined functions. Earlier versions may show a reduced list — see the version matrix below.
- Add a new action, select VBScript, and give it a name such as
OnVisibilityInput_Change. - Inside the VBScript editor, write the script. A working example:
' OnVisibilityInput_Change on faceplate type
' Triggered each time the linked tag toggles
Dim bNewValue
bNewValue = HMIruntime.Tags("visibilityInput").Read
If bNewValue = True Then
' Show / hide example: write the internal visibility tag
HMIruntime.Tags("visibility").Write True
' Optional: also drive a label color
Dim oItem
Set oItem = HMIruntime.Screens("Screen_1").ScreenItems("StatusLabel")
oItem.BackColor = RGB(0, 200, 0)
Else
HMIruntime.Tags("visibility").Write False
Set oItem = HMIruntime.Screens("Screen_1").ScreenItems("StatusLabel")
oItem.BackColor = RGB(200, 0, 0)
End If
- Compile the faceplate type.
- Place an instance on a screen. In the instance configuration, bind
visibilityInputto the desired runtime tag (a PLC bit, an HMI tag, or a fixed constant). - Compile the HMI device. Start the RT Advanced runtime. Every transition on the bound tag fires the VBS once.
HMIruntime.Screens(...) you must use the screen name where the instance sits, not the faceplate type editor's screen. Hardcoding the screen name is brittle; for RT Advanced the pragmatic alternative is to drive everything via the faceplate's own internal tags and animations (Method 1 hybrid) so that VBS only writes the internal tag and the animation engine takes care of the visual change.
VBScript API and Runtime Object Model (RT Advanced)
The WinCC RT Advanced VBS object model is a documented subset of the full WinCC V7 / Professional model. The objects you will actually use inside a faceplate:
| Object | Purpose | Typical call from faceplate VBS |
|---|---|---|
HMIruntime.Tags(name) |
Read/write any HMI tag by name | HMIruntime.Tags("Pump1.Run").Read |
HMIruntime.Screens(name).ScreenItems(item) |
Access a graphic object on a known screen | oItem.BackColor = vbGreen |
SmartTags("name") |
Shorthand access to tags configured on the HMI device | SmartTags("visibility") = True |
HMIRuntime.BaseScreenName |
Returns the screen name of the calling instance at runtime | HMIruntime.Screens(HMIRuntime.BaseScreenName).ScreenItems(...) |
| Internal faceplate tags | Accessed via the same SmartTags / HMIruntime.Tags syntax using the tag's interface name |
SmartTags("visibility") = Not SmartTags("visibility") |
Two facts that save hours of debugging:
-
Tag names are case-sensitive in
HMIruntime.Tags(...). If your interface tag isvisibilityInput, calling it asvisibilityinputsilently fails and the script aborts on the next line. -
Boolean literals in TIA VBS are
True/False(Pascal-style), nottrue/false. The runtime silently coerces in some contexts but throws in others; stick toTrue/False. -
No
Wait/Sleepis allowed inside VBS that runs synchronously from a tag change event. If you need to debounce, use an internal timer tag or shift state into a separate scheduled task.
Version-Specific Behavior in RT Advanced (V13 SP1)
The official Siemens support entry Notes on the behavior of faceplates in WinCC (TIA Portal) pins down a behavior change that engineers stumble over:
- Up to and including WinCC V13 SP1, the script-event capability inside faceplates — including VBS actions — is only available for faceplate types used on Panels and WinCC Runtime Advanced. RT Professional faceplates use a separate event configuration paradigm.
- From WinCC V13 SP1 and higher, the documented procedure for binding VBS to the Change value event of an interface property is officially supported as described in Method 2 above.
- WinCC V14 / V15 / V16 / V17 / V18 / V19 / V20 retain the same RT Advanced model; the editor dialog labels move slightly but the underlying bindings (Animations → Display, Events → Click, Events → Change value, VBS action) remain identical. The TIA V20 cloud documentation configuring an event in the faceplate type (RT Professional) covers the RT Professional path and uses a slightly different inspector structure.
Configuring Events in RT Professional (Cross-Reference)
If the project target is WinCC RT Professional (TIA V14+), the faceplate event model is configured in a different place — under the faceplate type editor, Events tab, where each interface property has its own configurable event. The TIA Portal V20 cloud documentation Configuring an event in the faceplate type (RT Professional) covers the exact inspector path. The conceptual difference:
| Aspect | RT Advanced (Panels, Comfort, WinCC RT Advanced) | RT Professional (WinCC Runtime Professional) |
|---|---|---|
| Event binding location | Select interface property → Inspector → Events → Change value | Faceplate type → Events tab → pick property → configure |
| VBScript support | Yes (V13 SP1+) | Yes (V14+) |
| C script support | No | Yes (per property event) |
| Anonymous internal tags | Yes | Yes (via container interface) |
| Cross-screen screen-items access | Possible but discouraged | Standard pattern, with qualifier |
Verification Procedure
After applying either method, run through this sequence in the RT Advanced simulator before deploying to a panel.
- Compile check: right-click the HMI device → Compile → Software (rebuild all). A missing or misspelled internal tag surfaces here as a warning.
- Static tag list: in the HMI tags table of the device, confirm that only the expected PLC tags appear — no leaked faceplate internal tags. Internal tags must remain invisible.
- Runtime simulator: start the RT Advanced simulator (RT button in the toolbar). Open the screen containing the faceplate instance.
- Method 1 test: click the toggle button on the faceplate instance. The bound object should appear / disappear. Verify that clicking the button on a different instance does not affect the first one.
-
Method 2 test: force the tag bound to
visibilityInputfrom the PLC or from the HMI tag simulator. The script should fire once per transition. Verify the script's side effects (color change, log entry, internal tag flip). - Stress test: toggle the input tag rapidly (e.g. 10 Hz for 5 seconds). The faceplate should remain responsive and the runtime should not accumulate script tasks. If you see UI lag, suspect a synchronous loop or a screen-items call to a non-existent object.
- Restart test: stop the runtime, restart, and confirm the initial state of internal tags matches what was configured. RT Advanced persists runtime tag values to volatile memory only by default; persistence requires explicit configuration.
Troubleshooting Matrix
| Symptom | Likely root cause | Remediation |
|---|---|---|
| No "VBS action" item in event list of interface property | TIA Portal version below V13 SP1 or faceplate type created on an RT Professional target | Upgrade to V13 SP1 with latest updates; verify target is RT Advanced or a Comfort Panel |
| VBS does not run when the bound tag changes | Interface property declared as "internal" instead of "external"; or bound to a constant rather than a tag | Verify the property is in the interface (not internal) area and is wired to a real tag or simulated value |
| Runtime error: "Object required: 'HMIruntime.Screens(...)...ScreenItems(...)" | Screen name or item name misspelled, or item is on a different screen than where the faceplate instance sits | Use HMIRuntime.BaseScreenName; cross-check item names against the screen's objects list |
| Visibility toggle works on one instance but breaks on all others | VBS writes to a global HMI tag instead of the faceplate's internal tag | Change SmartTags(...) reference to the faceplate-internal tag name as declared in the interface |
| Compile error: "Tag 'visibility' is not declared" | The animation is bound to a tag that has not been declared in the faceplate interface | Add the tag to the faceplate interface (internal area), then re-bind the animation |
| Script fires repeatedly even though the tag only changed once | Script writes back to the same tag it reads, causing an event loop | Read visibilityInput only; write to a different tag (internal visibility); or guard the write with a conditional |
| Initial state of internal tag is wrong after a screen change | Internal tag's initial value was not set, or was set inside a script that runs only on tag change | Set the initial value in the faceplate interface property dialog; for dynamic defaults, use the "OpenFaceplate" event |
| Button click toggles nothing | Click action was placed on a static graphic object instead of a button; or the action's expression has a syntax error | Verify the object has the "Button" property enabled; check the Set value expression for typos |
| Performance drops after adding VBS to many faceplate instances | Each instance triggers an independent script on every change | Pre-aggregate the input at the PLC or use a system function instead of a VBS for simple bit toggles |
Performance and Best Practices
- Prefer Method 1 for any purely visual, binary-state change. It compiles smaller, runs faster, and survives editor upgrades.
-
Limit cross-screen access in VBS inside faceplates. If you must reach across screens, qualify by
HMIRuntime.BaseScreenNameand cache the object reference rather than re-querying every cycle. - Avoid loops with VBS. The VBS engine on RT Advanced is single-threaded for screen-item access; a long-running loop inside a faceplate will freeze the panel UI.
- Use internal tags as a sandbox. Because internal tags are not visible to the HMI tag table, they cannot accidentally be archived, polled, or read by the wrong screen. Use them as the local memory of the faceplate.
- Keep the faceplate interface minimal. Declare only the properties the instance must expose. Each interface property adds compile time and increases the risk of binding errors.
- Version-pin your project. Always note the exact TIA Portal version (e.g. V13 SP1 Upd 9) and the WinCC option version in the project documentation. The Siemens faceplate behavior is version-sensitive, as documented in Siemens support entry 85239213.
- Test on the real panel before final acceptance. The simulator and a TP / Comfort Panel behave identically for faceplate scripts, but a faulty SD card or undersized memory card can mask itself as a script bug.
Can I add VBScript directly to a button click event inside a WinCC TIA Portal V13 SP1 faceplate?
Yes, on Panels, Comfort Panels, and WinCC Runtime Advanced targets from TIA Portal V13 SP1 onward. Select the button inside the faceplate type, open Inspector → Events → Click, and add a VBS action. For RT Professional targets, the equivalent is configured under the faceplate type's Events tab as documented in the TIA V20 online help entry "Configuring an event in the faceplate type (RT Professional)".
Why does my faceplate internal tag not appear in the HMI tags table?
By design. Faceplate internal tags are scoped to the faceplate type instance and are intentionally hidden from the surrounding HMI tag namespace. If you need a tag visible globally — for example to drive a screen-level animation — declare it as an interface property or as a regular HMI tag instead.
How do I toggle the visibility of multiple objects inside one faceplate with a single click?
Bind every target object's visibility animation to the same internal Bool tag, then drive the tag from one button's Click event with a single "Set tag" action. For more complex behavior (e.g. some objects show while others hide in the same transition), use a VBS action triggered from the interface property's Change value event and have the script write multiple internal tags or call HMIruntime.Screens(HMIRuntime.BaseScreenName).ScreenItems(...) per object.
Does Method 2 (VBScript on Change value event) work on every TIA Portal version?
Only from WinCC V13 SP1 onward for Panels, Comfort Panels, and WinCC Runtime Advanced, per the official Siemens support entry on faceplate behavior. On older versions, the Change value event of an interface property supports system functions and Set-tag actions but not VBS. For RT Professional, VBS and C-script event bindings have been supported from TIA V14 onward.
Why does the VBS inside my faceplate access the wrong screen's objects?
Because HMIruntime.Screens("Screen_1") resolves to a fixed screen name at runtime; if the faceplate instance is hosted on a different screen, the reference either fails or points at the wrong graphic object. Use HMIruntime.Screens(HMIRuntime.BaseScreenName) to obtain the screen that actually hosts the calling instance. As an alternative, drive visual properties through internal-tag-bound animations rather than direct screen-item access.