Reading OPC Tag Quality Codes in Siemens WinCC Runtime

1. Problem Overview

When a Siemens WinCC station acts as an OPC Data Access (DA) client, two different "status" concepts coexist in the runtime:

• Link Quality — describes the health of the connection between the OPC server process and the WinCC client process. This is what WinCC Explorer > Tag Management > mouse-over tooltip reports, and it normally shows "Connection OK" even when the underlying field device is unreachable.
• Tag Quality (OPC Quality Code) — carried per-tag as a 16-bit code defined by the OPC DA specification. It tells the consumer whether the value is Good, Bad, or Uncertain, with subcodes that report sensor failures, out-of-range, communication loss, etc.

Operators need the per-tag quality, not just the link state, especially on unstable media such as radio modems where the OPC server may keep the link alive but every tenth read attempt returns a stale or out-of-range value.

2. OPC DA Quality Code Model

Every OPC DA item carries a 16-bit quality word. The semantics are fixed by the OPC Data Access 3.0 specification, so a Siemens WinCC client reading a third-party server (e.g. Lectus Modbus OPC) still receives the same encoded severity / substatus / limit bits.

Common sub-status values you will encounter on a radio / serial media:

The full table is replicated in Siemens TIA Portal V20 documentation under the OPC UA connection topic for WinCC Runtime Professional.

3. Why Tag Management Tooltips Are Not Enough

The WinCC Explorer shows two indication surfaces:

1. Tag Management tooltip — paints a green/red icon based on whether the WinCC internal tag exists and is linked. This state is updated by the OPC client daemon inside WinCC; it does not look at the per-item quality coming back from the read.
2. Internal OPC diagnostic channel — visible only on dedicated diagnostic pictures that subscribe to the server's own status groups.

For a customer-facing HMI picture you must surface a per-IO-field warning that mirrors the OPC sub-status. This is done by calling the WinCC C-API helpers described in Section 4 from a scheduler (1 s) or value-driven trigger.

4. WinCC Runtime API for Quality Codes

The C-script / VBS-script API exposes several quality-aware variants of the standard tag read functions. Each one returns the raw 16-bit OPC quality word in an output parameter, not a Boolean — this is critical because a project may want to differentiate the four severity buckets (Good / Uncertain-not-limited / Uncertain-limited / Bad).

All seven families share the same signature pattern: the variable parameters are received by pointer so the function can write multiple outputs, and they return TRUE on success and FALSE if the tag was not found in Tag Management.

5. C-Script Implementation Template

The following action is suitable for an ApDiagnostics-style picture. It evaluates three tags from a Lectus Modbus OPC channel and writes aggregated severity into internal flags that drive a status bar.

/* ------------------------------------------------------------------
 * project : apdiag.c
 * triggered : 1 s scheduler in WinCC Graphics
 * purpose  : Decode OPC DA quality codes and raise operator warnings
 * valid for: WinCC V6.0 SP3 .. V7.5 SP2
 * ------------------------------------------------------------------ */
#include "apdefap.h"

#define OPC_Q_MASK           0x00C0   /* bits 7-6 = severity */
#define OPC_Q_BAD            0x0000
#define OPC_Q_UNCERTAIN      0x0040
#define OPC_Q_GOOD           0x00C0

#define OPC_SS_COMMFAIL      0x08     /* sub-status 0x08 = comm fail    */
#define OPC_SS_NOTCONNECTED  0x02     /* sub-status 0x02 = not linked   */
#define OPC_SS_LASTUSABLE    0x60     /* sub-status 0x60 = stale value  */

BOOL UpdateQuality(const char* tag, BYTE* qOut)
{
    DWORD rawValue  = 0;
    BYTE  quality   = 0;
    BYTE  state     = 0;

    /* Choose the correct function variant for the tag's data type */
    BOOL ok = GetTagDWordStateQC(tag, &rawValue, &quality, &state);
    if (!ok) {
        *qOut = 0xFF;                /* 0xFF = WinCC client-side error  */
        return FALSE;
    }

    *qOut = quality;
    return TRUE;
}

void OnTimer(void)
{
    BYTE qTankLevel, qModbusLink, qRemoteValve;
    DWORD opFlags = 0;               /* bits packed into "opStatus" tag */

    UpdateQuality("OPC_TankLevel",   &qTankLevel);
    UpdateQuality("OPC_ModbusLink",  &qModbusLink);
    UpdateQuality("OPC_RemoteValve", &qRemoteValve);

    if ((qTankLevel   & OPC_Q_MASK) == OPC_Q_BAD        ||
        (qTankLevel   & 0x0F)        == OPC_SS_COMMFAIL ||
        (qModbusLink  & OPC_Q_MASK) == OPC_Q_BAD)
        opFlags |= 0x01;             /* bit 0 = "radio link lost"       */

    if ((qRemoteValve & 0x0F) == OPC_SS_NOTCONNECTED)
        opFlags |= 0x02;             /* bit 1 = "valve channel offline" */

    if ((qTankLevel   & OPC_Q_MASK) == OPC_Q_UNCERTAIN  &&
        (qTankLevel   & 0x0F)        == OPC_SS_LASTUSABLE)
        opFlags |= 0x04;             /* bit 2 = "stale level - last value" */

    SetTagDWord("opStatus", opFlags);
}

The internal tag opStatus is then evaluated on the picture by three coloured graphic objects that show different text strings based on (opStatus & 0x01), (opStatus & 0x02), (opStatus & 0x04).

6. VB-Script Equivalent

WinCC V7 onwards allows picture-level VBScript. The same logic in scripting language is shorter and easier for plant electricians to maintain:

'-------------------------------------------------------------
' Picture script - WM event when "opStatus" tag changes
'-------------------------------------------------------------
Dim qMask, qByte, sText

qByte = SmartTags("opQuality_TankLevel")
qMask = qByte And &H00C0

Select Case qMask
    Case &H00C0 : sText = "OK"
    Case &H0040
        Select Case (qByte And &H0F)
            Case &H60 : sText = "Stale (last good)"
            Case &H40 : sText = "Substitute value"
            Case Else : sText = "Uncertain"
        End Select
    Case &H0000
        Select Case (qByte And &H0F)
            Case &H02 : sText = "Channel offline"
            Case &H04 : sText = "Device failure"
            Case &H08 : sText = "Comms failure"
            Case Else : sText = "Bad (other)"
        End Select
    Case Else   : sText = "n/a"
End Select

SmartTags("txtQualityHint") = sText
ShowSymbol "picWarn", (qMask = &H0000)

Drive SmartTags("opQuality_TankLevel") from an internal tag that is filled by an internal OPC subscription using the quality check-box in the tag properties dialog of WinCC Tag Management.

7. Migration Path: V5.1 / V6.0 SP3 / V7.x / TIA Unified

The OPC client API surface changed considerably across releases. The table below is the supported implementation route per release.

8. Configuring OPC UA Tags in WinCC Unified

The TIA Portal V20 documentation for WinCC Runtime Unified walks the project-tree path below when you need the per-tag quality to travel from the OPC UA server into a faceplate:

1. Open the project tree, expand "HMI tags", double-click the tag table.
2. In the Name column, double-click "Add".
3. Set the connection to the existing OPC UA connection (formerly created under "Connections" > OPC UA).
4. Browse to the remote OPC UA node. The dialog shows the Quality column; tick "Use server-supplied quality".
5. On the faceplate, bind the value display to the tag and bind a separate visibility property to (Quality == Good). The quality is available as tag.Quality in JavaScript / VB script.

For WinCC Professional (TIA) the procedure is documented at docs.tia.siemens.cloud. For WinCC Unified (TIA) the same firm's portal provides the matching reference at docs.tia.siemens.cloud.

9. Channel Status vs. Device Status Decision Matrix

10. Troubleshooting Matrix

Note: scenarios where a deleted OPC-UA client keeps reporting Good quality for a stale value are a known class of edge cases; see Inductive Automation knowledge base for a vendor-neutral description of this behaviour that also applies to OPC DA based wrappers and the rationale for always trusting sub-status rather than the top-level severity alone.

11. Commissioning Verification Checklist

1. Open the diagnostic picture apdiag.pdl, set the picture-cycle update to 500 ms.
2. Disconnect the field cable or power down the radio modem. Confirm the opStatus bit pattern changes within 1 s.
3. Use the WinCC Online Trend Control to plot the qByte value; verify it walks through 0xC0 → 0x48 → 0x08 as the device degrades from "OK" to "Uncertain-not-limited" to "Bad-comm-failure".
4. Restart the OPC server process while WinCC is running. Verify the link-quality tooltip updates within 10 s (server dependent) and the per-tag quality returns to Good once the cache invalidates.
5. In WinCC Unified, simulate a broken UA subscription by remapping the node to a non-existent path and confirm that the faceplate's quality expression evaluates to Bad.
6. For each release, archive the C / VBScript project in the customer archive so the quality-evaluation source can be re-deployed during a plant re-commissioning.

12. Frequently Asked Questions