1. Problem Overview and Engineering Context
WinCC Flexible 2008 SP5 and earlier Siemens HMI configuration environments expose multiple paths for binding display text to process values. The most common field requirement is to translate a binary or multi-state tag (e.g., a temperature status, valve state, motor run feedback) into a human-readable string on a Text Field or I/O Field. The naive first approach is to use the Visible property combined with stacked text objects, but this wastes panel layout area and complicates localization.
The two production-grade solutions engineers should evaluate are:
- Text List (multilingual text library) – a native, declarative configuration object that maps tag values to display strings without any script overhead.
-
VBScript on the tag's
Change_Valueevent – a procedural fallback that allows conditional logic, derived strings, and runtime calculations.
Siemens documentation explicitly recommends the Text List approach because scripts execute synchronously on the HMI panel and can degrade refresh rates on panels with limited CPU resources (KTP400 Basic, TP177, OP77). Use VBScript only when the text must be composed at runtime from multiple tags or formatted dynamically.
2. Prerequisites
Before configuring text changes, verify the following:
- WinCC Flexible 2008 SP5 (or WinCC Flexible 2008 SP3 for legacy TP170A compatibility)
- Configured HMI connection to a SIMATIC S7-300/400/1200/1500 PLC (MPI, PROFIBUS, or PROFINET)
- An internal HMI tag or external PLC tag of data type
Bool,Int, orWord - A Text Field or Symbolic I/O Field placed on the screen where the text is to appear
- Read access to the project via WinCC Flexible ES (Engineering Station license)
For TIA Portal users targeting S7-1200/1500 panels, see Siemens KB 109755202 - WinCC Comfort/Advanced scripting basics for the equivalent workflow in V15 and later.
3. Recommended Method: Text List Configuration
Text Lists are the canonical Siemens solution and require zero scripting. They support up to 32000 entries per list and integrate directly with Symbolic I/O Fields for type-safe value-to-text binding.
3.1 Creating a Text List
- Open the WinCC Flexible project and navigate to Project > Text and Graphics Lists > Text Lists.
- Right-click and select Add New Text List.
- Assign a name such as
TempStatusList. - In the Selection column, choose Value/Range for discrete numeric values or Bit for bit-mapped lists.
- Populate entries:
| Value | Text (Default) | Text (English) | Text (German) |
|---|---|---|---|
| 0 | Low | Low | Niedrig |
| 1 | High | High | Hoch |
| 2 | Sensor Fault | Sensor Fault | Sensorfehler |
Each row is a static mapping. Runtime lookup is performed via a hash table indexed by the configured value, so even lists with thousands of entries evaluate in under one millisecond on a TP177.
3.2 Binding the Text List to a Symbolic I/O Field
- Place a Symbolic I/O Field on the screen.
- In the properties dialog under General > Display, set Mode to Output.
- Set the Tag to the process tag (e.g.,
DB1.DBX0.0for a temperature status bit, orMW10for an integer status code). - Under Display > Text List, select the previously created
TempStatusList. - Compile and download to the panel.
The Symbolic I/O Field will now automatically display "High" when the tag equals 1 and "Low" when the tag equals 0, with no script involvement.
4. VBScript Method: Changing Text on Tag Change Event
When the required text depends on runtime computation (e.g., concatenating a unit suffix, applying a tolerance threshold, or formatting a derived value), VBScript is the correct tool. The implementation pattern uses the tag's Change_Value event to invoke a project function that writes to the target Screen Item's Text property.
4.1 Authoring the Project Function
- In the project tree, navigate to Scripts > Project Functions.
- Add a new function named
UpdateTempText. - Paste the following code:
' UpdateTempText - writes localized status text to a target Text Field
' Parameters:
' sItemName : Name of the Text Field ScreenItem on the active screen
' iValue : Current integer value of the source tag
Function UpdateTempText(ByVal sItemName, ByVal iValue)
Dim oScreen
Dim oItem
Dim sText
Set oScreen = HmiRuntime.Screens(HmiRuntime.ActiveScreen.Name)
Set oItem = oScreen.ScreenItems(sItemName)
Select Case iValue
Case 0
sText = "Temperature: LOW (< 50 C)"
Case 1
sText = "Temperature: HIGH (>= 50 C)"
Case 2
sText = "Temperature: SENSOR FAULT"
Case Else
sText = "Temperature: UNKNOWN (" & CStr(iValue) & ")"
End Select
oItem.Text = sText
End Function
4.2 Wiring the Function to the Tag Event
- In HMI Tags, locate the tag that drives the status (e.g.,
TempStatus). - Right-click and select Properties > Events > Change_Value.
- Set the event to Call Project Function and select
UpdateTempText. - Add the tag itself as the first argument and the ScreenItem name (e.g.,
txtTempStatus) as the second argument.
Every time the PLC writes a new value to TempStatus, the runtime fires the event, calls UpdateTempText, and the text field updates within the next screen refresh cycle (typically 100–500 ms on TP277).
5. HMI Runtime Object Model Reference
The VBScript runtime exposes a hierarchical COM-like object model rooted at the global HmiRuntime object. The relevant nodes for text manipulation are:
| Object | Property / Method | Data Type | Description |
|---|---|---|---|
| HmiRuntime | ActiveScreen | Screen | Currently displayed screen object |
| HmiRuntime | Screens(Name) | Screen Collection | Indexed access to all screens by name |
| Screen | ScreenItems(Name) | ScreenItems Collection | Indexed access to all screen objects by name |
| ScreenItem | Text | String | Read/write text content (Text Field, Symbolic I/O Field) |
| ScreenItem | Visible | Boolean | Show/hide the object |
| ScreenItem | BackColor | Long | RGB background color (BGR encoding) |
| ScreenItem | Left / Top / Width / Height | Long | Position and size in pixels |
5.1 Enumerating Screen Items
To list every ScreenItem on the active screen and inspect its name, use the following diagnostic snippet:
Sub DumpScreenItems()
Dim oItem
Dim sList
sList = ""
For Each oItem In HmiRuntime.Screens(HmiRuntime.ActiveScreen.Name).ScreenItems
sList = sList & oItem.Name & " (" & TypeName(oItem) & ")" & vbCrLf
Next
HmiRuntime.Trace sList
End Sub
Output is written to the WinCC Flexible trace buffer and can be observed with the HMI Tag Simulator or the TraceViewer on the engineering station.
6. Advanced Patterns
6.1 Localized Text Using @-Prefixed Tags
WinCC Flexible supports language-switching via the @Language system tag. To produce multilingual strings from VBScript, concatenate the active language index into a resource lookup:
Function LocalizedText(ByVal iKey)
Dim iLang
iLang = HmiRuntime.Tags("@Language").Read
Select Case iLang
Case 0 : LocalizedText = GetEnglish(iKey)
Case 1 : LocalizedText = GetGerman(iKey)
Case 7 : LocalizedText = GetFrench(iKey)
Case Else : LocalizedText = GetEnglish(iKey)
End Select
End Function
For pure text list workflows, prefer the built-in Text List multilanguage column mechanism; it is engineered to handle language switching atomically and avoids script overhead.
6.2 Formatting Numeric Tags with Units
To format a temperature tag (e.g., Temp_C as Real) into a string with units and one decimal place:
Function FormatTemp()
Dim rVal
rVal = HmiRuntime.Tags("Temp_C").Read
HmiRuntime.Screens("Main").ScreenItems("txtTempFormatted").Text _
= "Process Temp: " & FormatNumber(rVal, 1) & " C"
End Function
6.3 Conditional Color Coding
Combine text and color updates for alarm-aware display:
Function UpdateStatusDisplay()
Dim oField
Dim iVal
Set oField = HmiRuntime.Screens("Main").ScreenItems("txtStatus")
iVal = HmiRuntime.Tags("StatusWord").Read
Select Case iVal
Case 0
oField.Text = "OK"
oField.BackColor = RGB(0, 200, 0) ' Green
Case 1
oField.Text = "WARNING"
oField.BackColor = RGB(255, 200, 0) ' Yellow
Case 2
oField.Text = "ALARM"
oField.BackColor = RGB(255, 0, 0) ' Red
End Select
End Function
7. Performance Optimization
| Technique | Impact | Recommended? |
|---|---|---|
| Text List lookup | <1 ms per update | Yes (default) |
| VBScript on Change_Value event | 2–10 ms per update | Yes when logic required |
| VBScript on constant cyclic trigger (e.g., 100 ms) | 10–30% CPU on TP277 | Avoid |
| Stacked Text Fields with visibility toggle | Negligible runtime cost, but layout-heavy | Acceptable for ≤4 states |
| Animation via "Appearance" property with tag linkage | Native, fast | Yes for color/animation |
If script execution exceeds 100 ms cumulatively on a panel, Siemens recommends moving logic to the PLC (e.g., use a STRING tag with the formatted text pre-built in the S7 program). Reference the S7-1200/1500 string handling notes in the Siemens S7-1200 Programming Manual.
8. Migration to TIA Portal WinCC (V15 and Later)
WinCC Comfort, WinCC Advanced, and WinCC Professional (TIA Portal) preserve the same VBScript semantics but expose additional capabilities:
- Unicode text fields – direct binding to WString PLC tags without code-page conversion.
- Script Debugger – breakpoints, watch windows, and step-through in the engineering environment.
- Global script libraries – shared functions across panels in a multi-HMI project.
When migrating a WinCC Flexible project via Project > Migrate to TIA Portal, all Change_Value event scripts are preserved as Value change triggers. Verify that any HmiRuntime.Screens(...).ScreenItems(...) access resolves correctly; renamed screen objects are a common source of runtime errors after migration. Run the integrated compiler in TIA Portal V17 or later to catch these issues pre-deployment.
9. Verification Procedure
- Compile the WinCC Flexible project (Project > Compiler > All) and confirm zero errors and zero warnings.
- Start the WinCC Flexible Runtime simulator (Start > Runtime).
- Open the HMI Tag Simulator and toggle the source tag value (0 → 1 → 2).
- Confirm the target text field updates within one screen refresh cycle.
- Switch the project language (View > Language) and verify multilingual text lists render correctly.
- Open the Trace Viewer and confirm each
Change_Valueevent fires exactly once per tag write. - Download to the physical panel (TP177, TP277, KTP1200, etc.) and repeat steps 3–6 with the PLC online.
10. Troubleshooting Matrix
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Text never updates | Wrong ScreenItem name passed to function | Use the DumpScreenItems() diagnostic to enumerate names; check spelling |
| Runtime error "Object required" | Screen not yet loaded when Change_Value fires | Guard with If HmiRuntime.ActiveScreen.Name = "Target" Then
|
| Text flickers or updates twice | Script wired to both Change_Value and a cyclic trigger | Remove the cyclic trigger; use Change_Value exclusively |
| Multilingual text shows wrong language | @Language tag not refreshed | Bind a button or area to SetLanguage system function |
| Compiler warns "Implicit conversion" | Numeric tag passed where string expected | Wrap with CStr() before string concatenation |
| Script works in simulator but not on panel | Panel firmware too old | Update panel image to the version matching the ES (SP level) |
| Performance degradation after adding scripts | Too many Change_Value scripts firing | Consolidate logic into one global script triggered by a single "status update" tag |
11. Best Practice Summary
- Use Text Lists for any value-to-string mapping that does not require runtime computation.
- Trigger scripts from tag events, not from cyclic timers.
- Always guard ScreenItem access with
HmiRuntime.ActiveScreenchecks to handle navigation timing. - Write all formatting logic into named project functions for reuse and testability.
- Test multilingual behavior before deployment; language-switch bugs are the most common field complaints.
- Pre-compute complex strings in the PLC if the panel CPU is constrained (TP177 Basic, OP77A).
What is the difference between a Text List and a Text Library in WinCC Flexible?
A Text List maps specific tag values (or value ranges) to user-defined display strings and is bound to a Symbolic I/O Field. A Text Library is a reusable pool of strings referenced by index but requires a tag to point at the desired entry. Text Lists are simpler for value-to-string mapping; Text Libraries are useful when the same string is referenced from many places.
Can I change text without using a Text List or VBScript in WinCC Flexible?
Yes. You can stack multiple Text Field objects on the same screen position and toggle their Visible property through tag linkage under Animations > Appearance. This works for up to 4 states without layout issues but is less maintainable than a Text List for larger state counts.
Why does my VBScript not fire when the tag value changes?
The most common causes are (1) the function is wired to the wrong tag, (2) the tag's acquisition cycle is set to "On Demand" and the PLC has not polled it, or (3) the screen containing the screen item is not the active screen at the moment the event fires. Verify the tag's polling mode is "Cyclic Continuous" or "Cyclic in Operation" and add a screen-name guard at the start of the script.
Is VBScript in WinCC Flexible supported on all Siemens panels?
No. Scripting is supported only on panels running the WinCC Flexible Runtime or WinCC Comfort/Advanced/Professional (TIA Portal). Basic line panels such as the KTP400 Basic mono and OP77A do not support VBScript. Refer to the panel's datasheet in the Siemens HMI Selection Tool to confirm script support before designing the project.
How do I migrate my WinCC Flexible VBScript project to TIA Portal?
Use Project > Migrate to TIA Portal in TIA Portal V15 or later. All Change_Value event handlers migrate as Value change triggers. Recompile, address any renamed ScreenItems, and test the script debugger breakpoints to validate runtime behavior on the new platform.