Configuring WinCC Professional RotationAngle Property in VBScript

Overview

The RotationAngle property on WinCC Professional screen items lets you rotate a graphical object around a configurable pivot point at runtime through VBScript. This is the standard mechanism for building rotational animations on SIMATIC HMI panels and WinCC Runtime Professional - boom cranes, mixers, conveyor diverters, valve disks, and pointer gauges - that must mirror a real value held in a PLC tag.

In WinCC Runtime Professional the property is exposed on the COM-like HmiRuntime.Screens(...).ScreenItems(...) object and is writable in degrees (Int32, 0-360). The property is only available on a fixed set of geometric objects; not every screen item type supports rotation. The behavior also differs from WinCC Runtime Advanced, where the property is not exposed on the runtime API and a different engineering approach is required.

Supported Screen Item Types

The following table summarizes which WinCC Professional screen objects expose the RotationAngle property. Items not listed (for example Circle, Rectangle, GraphicView, or I/O Field) do not expose RotationAngle at runtime and must be animated through other mechanisms such as graphic lists, faceplate container rotations, or screen window swaps.

Runtime Editions: Professional vs Advanced

Siemens distributes two distinct HMI runtimes under the TIA Portal umbrella. The RotationAngle API is only available on the higher-tier runtime.

WinCC Runtime Professional

Exposes the full WinCC Professional object model through VBScript, including RotationAngle, RotationCenterLeft, and RotationCenterTop. This is the recommended platform for any rotational animation.

WinCC Runtime Advanced

The Advanced runtime does not expose RotationAngle on the runtime object model. Attempting to read or write the property raises a runtime error and the IntelliSense in the Script Editor will not list it. For Advanced targets the official workaround is to build a graphic list of pre-rendered frames in PowerPoint and step through the list using an integer tag - see the "Alternative: WinCC Advanced Workaround" section below.

To verify your runtime edition in TIA Portal: select the HMI device in the project tree, open Device properties > General > HMI device type or check the device configuration summary. A Comfort Panel with WinCC Runtime Advanced cannot be promoted to Professional - the choice is fixed at device selection time.

Prerequisites

1. Installed TIA Portal V15.1 or later (V16, V17, V18 supported). TIA Portal V18 release notes.
2. An HMI device configured with WinCC Professional or WinCC Runtime Advanced. Comfort Panels, Unified Comfort Panels, and RT Professional for PC qualify accordingly.
3. The WinCC Professional / Advanced "Scripting" option enabled in the project properties when working on a Compact or Panel PC without a script license.
4. An integer PLC tag holding the desired angle in degrees, sourced from an encoder, scaling block, or pointer calculation. The valid range for RotationAngle is Int32 (effectively -2147483648 to +2147483647); values outside the visual 0-360 range will continue to wrap mathematically because the runtime applies a modulo 360 reduction internally for rendering.
5. For RT Professional on a PC, the "WinCC RT Professional" runtime license installed on the target system.

VBScript Syntax and Properties

Three runtime properties govern rotation on supported screen items. All three are accessed through the standard HmiRuntime.Screens("ScreenName").ScreenItems("ItemName") path.

The pivot is defined in the item's local coordinate space, not the screen coordinate space. For a Line drawn from (0,0) to (100,0) (horizontal, 100 px long), a RotationCenterLeft of 0 rotates around the left endpoint; 100 rotates around the right endpoint; 50 rotates around the midpoint.

Minimal Script

' Rotate a Line by 45 degrees at runtime
Dim objLine
Set objLine = HmiRuntime.Screens("Root_1").ScreenItems("Line_1")

objLine.RotationCenterLeft = 0   ' pivot at left end of the line
objLine.RotationCenterTop  = 0
objLine.RotationAngle      = 45  ' clockwise, 0-360

Animating a Boom Crane Rotation - Step-by-Step

The use case driving this article is a boom crane whose base must rotate to follow a real PLC angle. The Line that represents the boom needs to spin around the crane base. The following procedure produces a working crane animation on a single screen.

1. Create the geometry. In the screen "Root_1" add a Line named Line_Boom. Draw it pointing straight up from the crane base: X1 = 200, Y1 = 200 (crane base anchor); X2 = 200, Y2 = 80 (boom tip). The line is therefore 120 px long and lies along the negative Y axis.
2. Configure the pivot. Set the line's RotationCenterLeft to 0 (the X start position of the line) and RotationCenterTop to 0 (the Y start position of the line). This anchors rotation at the boom base, not at the geometric center of the bounding box.
3. Create the PLC tag. In the HMI tag table add an Int32 tag named Crane_Angle_deg mapped to a PLC tag of the same name in the connected S7-1500/S7-1200 data block. The tag holds the angle in degrees, scaled by your crane's encoder or computed in the PLC's pointer calculation block.
4. Write the update script. Open the screen's event configuration and attach a VBScript action to the "Update" or a scheduled 100 ms timer event:

' Crane boom rotation - reads angle from PLC tag and applies it to the Line
Sub Update_Boom()
    Dim objBoom
    Set objBoom = HmiRuntime.Screens("Root_1").ScreenItems("Line_Boom")

    ' Wrap the raw tag value into a valid 0..359 range
    Dim rawAngle
    rawAngle = SmartTags("Crane_Angle_deg")

    objBoom.RotationAngle = rawAngle
End Sub

5. Handle wrap-around. Because the runtime applies modulo 360 internally, raw encoder values of 0-359 work without further math. If your PLC emits signed values (-180 to +180), add 360 to negative values before writing:

If rawAngle < 0 Then
    rawAngle = rawAngle + 360
End If
objBoom.RotationAngle = rawAngle

6. Trigger an initial paint. To avoid a flicker where the boom displays at 0 deg before the first update fires, call Update_Boom once from the screen's "Open" event so the boom is drawn at the correct angle on screen load.
7. Compile and simulate. Use Start > Run with HMI simulation (RT Professional) to verify the animation before deploying to the panel. Watch the boom track the simulated tag value.

Rotation Around a Custom Pivot Point

Rotating a long boom from its base works because the line's start point coincides with the desired pivot. For more complex graphics - for example a polygon that should rotate around a corner that is not the local (0,0) - the pivot must be set explicitly.

Consider a Polygon representing a valve disk drawn at screen coordinates (300,300) to (500,500), with the rotation pivot intended to be the disk center (400,400). Within the polygon's local bounding box the center is at (100,100) from the top-left corner of the bounding rectangle, so:

Dim objDisk
Set objDisk = HmiRuntime.Screens("Valve_Faceplate").ScreenItems("Polygon_Disk")

objDisk.RotationCenterLeft = 100   ' pixels from left of bounding box
objDisk.RotationCenterTop  = 100   ' pixels from top of bounding box
objDisk.RotationAngle      = SmartTags("Valve_Position_pct") * 3.6   ' 0-100 % to 0-360 deg

Verify the pivot by setting RotationAngle = 0 first and confirming visually that the bounding box sits where expected; then increment RotationAngle in 15 deg steps and confirm the object spins around the intended point. Misplaced pivots show as a wobbling or orbiting motion rather than a clean rotation.

Tag-Based Animation Cycle and Performance

The WinCC Professional runtime evaluates property writes asynchronously on the UI thread, but every RotationAngle assignment triggers a repaint of the affected screen item. For high-frequency updates the following guidance applies:

• Limit updates to 100 ms (10 Hz) or slower for typical visualization needs. The human eye cannot perceive changes faster than ~20 Hz.
• Avoid writing RotationAngle on every tag change event if the tag is updated faster than 10 Hz - debounce with a scheduled timer instead.
• For overlapping rotating items on the same screen, batch the writes in a single Sub to minimize script overhead:

Sub Update_Rotating_Group()
    Dim s
    Set s = HmiRuntime.Screens("Mixer_View")

    s.ScreenItems("Line_Agitator").RotationAngle = SmartTags("Agitator_Angle_deg")
    s.ScreenItems("Line_Baffle_1").RotationAngle = SmartTags("Agitator_Angle_deg") + 90
    s.ScreenItems("Line_Baffle_2").RotationAngle = SmartTags("Agitator_Angle_deg") + 180
    s.ScreenItems("Line_Baffle_3").RotationAngle = SmartTags("Agitator_Angle_deg") + 270
End Sub

SVG Reference - Boom Crane Rotation Geometry

The diagram shows a boom crane with three rotation states about the same base pivot: 0 deg (boom vertical, blue solid), 45 deg clockwise (red dashed), and -30 deg / 330 deg counter-clockwise (green dotted). All three share the same RotationCenterLeft/Top at the boom base, so only the RotationAngle changes between states.

Alternative: WinCC Advanced Workaround

If your target is a Comfort Panel running WinCC Runtime Advanced, the RotationAngle runtime API is unavailable. The Siemens-recommended workaround is to build a graphic list of pre-rendered frames in PowerPoint and animate by changing the list index.

1. Draw the rotating object (crane boom, mixer, disk) in PowerPoint.
2. Export 36 PNG frames at 10 deg increments from 0 to 350 deg. Name them frame_000.png through frame_350.png.
3. In TIA Portal create a Graphic list in the HMI project under Graphics > Graphic lists and import the 36 PNGs.
4. Add a GraphicView to the screen bound to that graphic list. The "Index" property of the GraphicView is dynamic and can be driven by an integer HMI tag.
5. From the PLC write floor(angle_deg / 10) into the HMI tag. The runtime swaps the displayed frame to match the angle. With 36 frames the visual quantization is 10 deg.

Siemens publishes the "Toolbox for HMI Projects in machine-based Area" entry which documents this rotation tool in detail - see the SIMATIC HMI Toolbox entry 106226404. PowerPoint-to-graphic-list workflow and example projects are described in the "Rotation tool" chapter under "Simplified Engineering".

Verification

After deploying the configured screen, validate the rotation using the following checks:

1. Static check: Open the screen on the panel or in the RT Professional simulator. Confirm the boom is rendered at the angle reported by the PLC tag (read the tag value via an I/O Field on the same screen).
2. Dynamic check: Force the PLC tag to 0, 90, 180, 270 deg in sequence (use a watch table in TIA Portal). The boom should snap to vertical, horizontal-right, vertical-down, and horizontal-left respectively. If the boom appears to orbit rather than rotate, the RotationCenterLeft/Top values are wrong.
3. Continuous check: Jog the crane from the PLC. Confirm the boom tracks the encoder smoothly without visible jitter. Jitter at slow tag-change rates usually indicates the timer event period is set too long; reduce it to 100 ms.
4. Wrap check: Move the crane from 359 deg to 1 deg through 0 deg. The boom must pass smoothly through vertical, not jump to 180 deg. This verifies the modulo-360 behavior.
5. Reload check: Switch screens and switch back. The boom must redraw at the current angle, not flicker to 0 deg. If flicker occurs, move the initial paint call to the screen Open event.

Troubleshooting Matrix

Field-Commissioning Notes

Three issues recur on site during first commissioning and are worth pre-empting:

• Scaling mismatch. The PLC's angle tag is often scaled in 0.1 deg units (e.g. 0-3600) to match an encoder. Apply SmartTags("Crane_Angle_deg") / 10 before assignment, or fix the scaling at the PLC side. Writing 3600 to RotationAngle renders as 360 deg (modulo applied) but obscures the bug.
• Initial frame. Comfort Panels and RT Professional can paint the screen with RotationAngle = 0 before the first PLC poll completes. For slow fieldbus connections (PROFIBUS at 1.5 Mbit/s, PROFINET with high update time) this flash can be visible. Cache the last-known angle in an HMI-internal tag and write it on screen open.
• Multi-screen consistency. If the same crane is shown on multiple screens (overview, faceplate, alarm view), each screen needs its own update Sub or a global script that references all of them. A common pattern is to publish the angle to a WinCC-internal tag and let each screen subscribe.

Related Siemens Documentation

The following official Siemens references were used while preparing this article and should be consulted for further detail on the runtime object model and the Advanced workaround:

• SIMATIC HMI Toolbox - Rotation tool (entry 106226404)
• TIA Portal V18 release notes