Calling VB Scripts from PLC Tag Value Changes in TIA Portal

Overview

Engineers routinely need a WinCC HMI to react to PLC events the moment they occur - not on a timer poll, not on a screen open, but exactly when a tag transitions. The canonical Siemens pattern is a tag-triggered VB script: configure an HMI tag (the mirror of a PLC tag) so that a configured event fires a Sub in the project's VB script library. This pattern is available on every TIA Portal version that ships WinCC Comfort/Advanced and on every WinCC Professional Runtime target.

This article walks through three runtime targets:

1. Comfort Panels (TP700 Comfort, TP1500 Comfort, KP1500 Comfort, KTP Comfort) running in the integrated HMI runtime.
2. WinCC Advanced Runtime on a PC (RT Advanced) where the runtime is hosted on Windows.
3. WinCC Professional Runtime on a PC or WinCC Server where Global Scripts and the Scheduled Tasks editor are available.

The same logic applies whether the source tag is Bool, Int, Word, Real, DInt, or String. Misconceptions that "VB scripts cannot run on Bool tags" originate from confusing the typed Function List trigger (where a parameter data type matters) with the untyped Value Change event (which accepts any tag).

The reference configuration was originally documented against TIA Portal V13 SP1 / WinCC Advanced V13 SP1 on a TP700 Comfort panel. The mechanism is unchanged through TIA Portal V17, V18, V19, V20, and V21; only navigation labels shift slightly between versions.

Prerequisites

• TIA Portal V13 SP1 or later with WinCC Comfort/Advanced or WinCC Professional installed.
• A configured HMI device (Comfort Panel or PC Runtime) added to the project.
• An HMI tag already connected to a PLC tag (drag from PLC tag table onto HMI tag table, or manually via the connection editor).
• Project editor permission to create scripts (engineering station account on WinCC Professional; unrestricted on Comfort Panels).
• For bulk import / scripted deployment: TIA Portal Openness API installed on the engineering station.

Runtime Target Selection Matrix

Choose Scheduled Tasks whenever the script must run independent of the currently displayed screen - common for logging, alarming escalation, recipe save, audit trail, or sending a record to the PLC. Choose tag properties → Value change when the action only makes sense while the operator is interacting with a specific screen.

Tag Configuration and Acquisition Modes

The trigger fires when WinCC detects the tag value has changed within its acquisition cycle. Three acquisition modes exist for HMI tags and each governs how often the runtime samples the value:

For any tag that triggers a VB script, set the acquisition mode to Cyclic continuous in HMI Tags → [tag] → Properties → General. Pair it with an Update Cycle of 250 ms for fast reactions or 1 s for routine logging. Faster cycles (100 ms, 50 ms) are permitted but increase HMI ↔ PLC load; avoid sub-100 ms unless the application explicitly demands it.

Step-by-Step: Triggering VB on a Comfort Panel from a PLC Tag

1. Author the VB script. In the project tree, expand your HMI device → "Scripts" → double-click "VB Scripts" (or right-click → Add new VB function). The VBScript editor opens. Define a public procedure, for example:

   ' Module: Logging
   Public Sub LogMeasurementComplete()
       Dim bReady As Boolean
       bReady = SmartTags("HMI_MeasurementReady")
       If bReady = False Then Exit Sub          ' Rising-edge guard
   
       ' Write a line to the alarm / logging buffer
       Dim sUser As String
       sUser = SmartTags("HMI_CurrentUser")
       HMIRuntime.Trace("Measurement logged by " & sUser & " @ " & Now, 0)
   
       ' Acknowledge back to PLC so the next cycle can re-trigger
       SmartTags("HMI_AckLogBit") = True
   End Sub

2. Save and compile. Use the menu "Scripts → Check Syntax" (or Ctrl+F7 in V13 SP1; the same key binding persists in V17/V18/V19/V20/V21). Resolve any compile errors before continuing.
3. Open the tag. In the project tree, expand "HMI Tags" and double-click the tag that mirrors the PLC boolean, e.g. HMI_MeasurementReady.
4. Set acquisition mode. Under Properties → General → Acquisition mode, choose Cyclic continuous. Set Update cycle to 1 s (or your application-specific value).
5. Attach the event. Switch to the Events tab. Expand "Value change". Click the empty cell on the right; the selection button (three dots or a function icon, depending on version) opens a picker. Choose Scripts → VB function → [Module].LogMeasurementComplete.
6. Compile the HMI project. Click "Compile" in the toolbar. The event binding is generated into the runtime database.
7. Download to the panel. Transfer the project (RT → "Download to device → Software"). The runtime will now call LogMeasurementComplete() every time HMI_MeasurementReady changes.

Step-by-Step: Triggering Global VB in WinCC Professional

1. Author the script globally. In the project tree of the WinCC Professional HMI device, expand "Global Scripts" → "VB Actions" (or "VB Functions"). Create a new module and procedure as shown above. Global procedures are visible to the entire runtime, not just one screen.
2. Open Scheduled Tasks. Expand "Global Scripts" → "Scheduled Tasks" and add a new task. Give it a recognizable name (e.g. Task_LogMeasurementComplete).
3. Bind the VB function. In the task properties → General, select the function list type and choose your VB procedure.
4. Configure the tag trigger. Switch to the Triggers tab. Click "Add" and select Tag Trigger. Configure:
   • Tag: HMI_MeasurementReady
   • Trigger condition: On change (fires on every change) or On rising edge (fires only on 0→1). On Professional, both options are selectable; on Comfort panels, use the rising-edge guard in code instead.
   • Acquisition cycle: inherit from the tag, or override here. 1 s is typical.
5. Set the execution scope. In the task's "Properties → Runtime" tab, ensure the task is enabled. Set the start condition to "Start with Runtime" so the task is active immediately.
6. Compile and download. Build the WinCC Professional project and download to the RT or WinCC Server.

The scheduled-task approach is what most professional WinCC deployments use for cross-screen automation. It survives navigation events, supports multiple triggers per task, and exposes a centralized audit point in the project tree.

Boolean vs Integer Tags: Clearing the Confusion

Operators new to TIA Portal often report that the function-list picker disables Bool tags while Int / Word / Real remain selectable. The cause is the difference between two trigger mechanisms:

For a Bool trigger, author a parameterless Sub as in the example above and bind it via the Scripts (not Function list) selector. The Bool tag is read inside the script via SmartTags("..."), which always returns a Variant that coerces correctly.

Sample Patterns

Pattern A: Rising-Edge Latch with Acknowledgement

' PLC sets "HMI_RequestLog"=TRUE after a measurement completes.
' Script latches the request, writes to log, sets "HMI_LogAck"=TRUE so the PLC drops the request.
Public Sub HandleLogRequest()
    If SmartTags("HMI_RequestLog") = False Then Exit Sub
    Dim sPath As String
    sPath = SmartTags("HMI_LogPath") & "\meas_" & Format(Now, "yyyymmdd_hhnnss") & ".csv"
    SmartTags("HMI_ResultString") = SmartTags("PLC_ResultString")
    HMIRuntime.Trace("Logged to " & sPath, 0)
    SmartTags("HMI_LogAck") = True
End Sub

Pattern B: Integer Threshold Crossing

' Runs when "PLC_CycleCount" changes; logs only when crossing 100, 200, 300...
Public Sub TrackCycleCount()
    Dim iCycles As Integer
    iCycles = SmartTags("PLC_CycleCount")
    If (iCycles Mod 100) <> 0 Then Exit Sub
    HMIRuntime.Trace("Cycle milestone: " & CStr(iCycles), 0)
End Sub

Pattern C: Reading Multiple Tags in One Trigger

' Trigger from "PLC_AutoStep" changing; read a block of related values in one call.
Public Sub CaptureAutoStep()
    Dim iStep As Integer
    iStep = SmartTags("PLC_AutoStep")
    HMIRuntime.Trace("Auto Step entered: " & CStr(iStep), 0)
    If iStep >= 10 And iStep <= 19 Then
        SmartTags("HMI_ShowSubstepScreen") = True
    End If
End Sub

Automation via TIA Portal Openness API

For projects with hundreds of tag-triggered scripts, manual configuration does not scale. The TIA Portal Openness API exposes the same binding logic for automation. The official documentation covers the script import surface used when scripts are stored outside the project file:

• Requirement: the TIA Portal Openness application is connected to the TIA Portal and a project is open. See Importing VB scripts - TIA Portal Openness API V21.
• Use the Openness API to enumerate HMI devices, walk tag properties, and attach a ValueChange event handler programmatically. This is the recommended path for engineering shops that regenerate HMI projects from a master template.
• The Openness API is available for TIA Portal V15.1 and later (with progressive feature additions in V16, V17, V18, V19, V20, and V21). The script import endpoint documented in the URL above targets the V21 surface; earlier versions require manual binding or a vendor tool.

Troubleshooting Matrix

Verification Procedure

1. Simulate the tag change in PLCSIM. With the panel connected to PLCSIM or a soft PLC, force the source PLC tag to TRUE and then FALSE. Confirm the HMI tag mirrors the transition in the tag diagnostics window.
2. Inspect the runtime trace. Use HMIRuntime.Trace "...", 0 in the script and view the output via WinCC's diagnostic tools (e.g. "Tools → Trace Viewer" in Engineering, or the runtime's diagnosis page). Each call leaves a timestamped line.
3. Verify the acknowledgement handshake. If the script writes back to the PLC, monitor the PLC tag in PLCSIM and confirm it goes TRUE within one update cycle of the trigger.
4. Load-test the trigger. Use the HMI's diagnostic script to toggle the source tag 100 times in a loop and confirm the count of HMIRuntime.Trace lines matches expectations.
5. Stress the HMI. Navigate between screens rapidly while the trigger source is being driven externally. Confirm the script continues to fire - this validates that the trigger is attached to the tag (survives navigation) rather than to a screen event (lost on navigation).

Performance and Engineering Notes

• One trigger per logical event. Avoid stacking two Value-Change events on the same tag that call the same script. The runtime will execute it twice per change.
• Avoid tag-triggered scripts on tags updated faster than 100 ms. This starves the HMI's main thread and delays screen refresh. Offload fast loops to a PLC task instead.
• Prefer integer/word tags for high-frequency triggers. Bool tag updates may be coalesced by some PLCs if the underlying DB is updated faster than the HMI's cycle; an Int with a counter is more robust.
• Guard against re-entrancy. If a script can be re-entered before the previous call completes (e.g. via a second trigger source), add a static Boolean guard at module level: Static bBusy As Boolean.
• Document the trigger in the tag comment. TIA Portal does not surface event bindings in the tag list. Always annotate the tag with "Triggers: LogMeasurementComplete" in the Comment column so the binding is discoverable.
• Migrate V13 SP1 projects carefully. When upgrading from V13 SP1 to V17/V18/V19/V20/V21, event bindings are preserved but the underlying script GUIDs change if the script body is edited. Re-compile the HMI before downloading.

FAQ