Serving as a bridge between COM and OPC UA components, the Alarms and Events proxy and wrapper enable existing A&E COM Clients and Servers to connect to UA Alarms and Conditions components.
Simply stated, there are two aspects to the migration strategy. The first aspect enables a UA Alarms and Conditions Client to connect to an existing Alarms and Events COM Server via a UA Server wrapper. This wrapper is notated from this point forward as the A&E COM UA Wrapper. The second aspect enables an existing Alarms and Events COM Client to connect to a UA Alarms and Conditions Server via a COM proxy. This proxy is notated from this point forward as the A&E COM UA Proxy.
An Alarms and Events COM Client is notated from this point forward as A&E COM Client.
A UA Alarms and Conditions Server is notated from this point forward as UA A & C Server.
The mappings describe generic A&E COM interoperability components. It is recommended that vendors use this mapping if they develop their own components, however, some applications may benefit from vendor specific mappings.
Event Areas in the A&E COM Server are represented in the A&E COM UA Wrapper as Objects with a TypeDefinition of BaseObjectType. The EventNotifier Attribute for these Objects always has the SubscribeToEvents flag set to True.
The root Area is represented by an Object with a BrowseName that depends on the UA Server. It is always the target of a HasNotifier Reference from the Server Node. The root Area allows multiple A&E COM Servers to be wrapped within a single UA Server.
The Area hierarchy is discovered with the BrowseOPCAreas and the GetQualifiedAreaName Methods. The Area name returned by BrowseOPCAreas is used as the BrowseName and DisplayName for each Area Node. The QualifiedAreaName is used to construct the NodeId. The NamespaceURI qualifying the NodeId and BrowseName is a unique URI assigned to the combination of machine and COM Server.
Each Area is the target of HasNotifier Reference from its parent Area. It may be the source of one or more HasNotifier References to its child Areas. It may also be a source of a HasEventSource Reference to any sources in the Area.
The A&E COM Server may not support filtering by Areas. If this is the case then no Area Nodes are shown in the UA Server address space. Some implementations could use the AREAS Attribute to provide filtering by Areas within the A&E COM UA Wrapper.
Event Sources in the A&E COM Server are represented in the A&E COM UA Wrapper as Objects with a TypeDefinition of BaseObjectType. If the A&E COM Server supports source filtering then the SubscribeToEvents flag is True and the Source is a target of a HasNotifier Reference. If source filtering is not supported the SubscribeToEvents flag is False and the Source is a target of a HasEventSource Reference.
The Sources are discovered by calling BrowseOPCAreas and the GetQualifiedSourceName Methods. The Source name returned by BrowseOPCAreas is used as the BrowseName and DisplayName. The QualifiedSourceName is used to construct the NodeId. Event Source Nodes are always targets of a HasEventSource Reference from an Area.
Event Categories in the A&E COM Server are represented in the UA Server as ObjectTypes which are subtypes of BaseEventType. The BrowseName and DisplayName of the ObjectType Node for Simple and Tracking Event Types are constructed by appending the text ‘EventType’ to the Description of the Event Category. For Condition Event Types the text ‘AlarmType’ is appended to the Condition Name.
These ObjectType Nodes have a super type which depends on the A&E Event Type, the Event Category Description and the Condition Name; however, the best mapping requires knowledge of the semantics associated with the Event Categories and Condition Names. If an A&E COM UA Wrapper does not know these semantics then Simple Event Types are subtypes of BaseEventType, Tracking Event Types are subtypes of AuditEventType and Condition Event Types are subtypes of the AlarmType. Table D.1 defines mappings for a set of “well known” Category description and Condition Names to a standard super type.
Table D.1 – Mapping from standard Event categories to OPC UA Event types
COM A&E Event Type |
Category Description |
Condition Name |
OPC UA EventType |
Simple |
--- |
--- |
BaseEventType |
Simple |
Device Failure |
--- |
DeviceFailureEventType |
Simple |
System Message |
--- |
SystemEventType |
Tracking |
--- |
--- |
AuditEventType |
Condition |
--- |
--- |
AlarmType |
Condition |
Level |
--- |
LimitAlarmType |
Condition |
Level |
PVLEVEL |
ExclusiveLevelAlarmType |
Condition |
Level |
SPLEVEL |
ExclusiveLevelAlarmType |
Condition |
Level |
HI HI |
NonExclusiveLevelAlarmType |
Condition |
Level |
HI |
NonExclusiveLevelAlarmType |
Condition |
Level |
LO |
NonExclusiveLevelAlarmType |
Condition |
Level |
LO LO |
NonExclusiveLevelAlarmType |
Condition |
Deviation |
--- |
NonExclusiveDeviationAlarmType |
Condition |
Discrete |
--- |
DiscreteAlarmType |
Condition |
Discrete |
CFN |
OffNormalAlarmType |
Condition |
Discrete |
TRIP |
TripAlarmType |
There is no generic mapping defined for A&E COM sub-Conditions. If an Event Category is mapped to a LimitAlarmType then the sub Condition name in the Event are be used to set the state of a suitable State Variable. For example, if the sub-Condition name is “HI HI” then that means the HighHigh state for the LimitAlarmType is active
For Condition Event Types the Event Category is also used to define subtypes of BaseConditionClassType.
Figure D.1 illustrates how ObjectType Nodes created from the Event Categories and Condition Names are placed in the standard OPC UA HasNotifier hierarchy.
Figure D.1 – The type model of a wrapped COM AE server
Event Attributes in the A&E COM Server are represented in the UA Server as Variables which are targets of HasProperty References from the ObjectTypes which represent the Event Categories. The BrowseName and DisplayName are the description for the Event Attribute. The data type of the Event Attribute is used to set DataType and ValueRank. The NodeId is constructed from the EventCategoryId, ConditionName and the AttributeId.
The A&E COM UA Wrapper creates a Subscription with the COM AE Server the first time a MonitoredItem is created for the Server Object or one of the Nodes representing Areas. The Area filter is set based on the Node being monitored. No other filters are specified.
If all MonitoredItems for an Area are disabled then the Subscription will be deactivated.
The Subscription is deleted when the last MonitoredItem for the Node is deleted.
When filtering by Area the A&E COM UA Wrapper needs to add two Area filters: one based on the QualifiedAreaName which forms the NodeId and one with the text ‘/*’ appended to it. This ensures that Events from sub areas are correctly reported by the COM AE Server.
A simple A&E COM UA Wrapper will always request all Attributes for all Event Categories when creating the Subscription. A more sophisticated wrapper may look at the EventFilter to determine which Attributes are actually used and only request those.
Table D.2 lists how the fields in the ONEVENTSTRUCT that are used by the A&E COM UA Wrapper are mapped to UA BaseEventType Variables.
Table D.2 – Mapping from ONEVENTSTRUCT fields to UA BaseEventType Variables
UA Event Variable |
ONEVENTSTRUCT Field |
Notes |
EventId |
szSource szConditionName ftTime ftActiveTime dwCookie |
A ByteString constructed by appending the fields together. |
EventType |
dwEventType dwEventCategory szConditionName |
The NodeId for the corresponding ObjectType Node. The szConditionName maybe omitted by some implementations. |
SourceNode |
szSource |
|
SourceName |
szSource |
- |
Time |
ftTime |
- |
ReceiveTime |
- |
Set when the Notification is received by the wrapper. |
LocalTime |
- |
Set based on the clock of the machine running the wrapper. |
Message |
szMessage |
Locale is the default locale for the COM AE Server. |
Severity |
dwSeverity |
- |
Table D.3 lists how the fields in the ONEVENTSTRUCT that are used by the A&E COM UA Wrapper are mapped to UA AuditEventType Variables.
Table D.3 – Mapping from ONEVENTSTRUCT fields to UA AuditEventType Variables
UA Event Variable |
ONEVENTSTRUCT Field |
Notes |
ActionTimeStamp |
ftTime |
Only set for tracking Events. |
Status |
- |
Always set to True. |
ServerId |
- |
Set to the COM AE Server NamespaceURI |
ClientAuditEntryId |
- |
Not set. |
ClientUserId |
szActorID |
- |
Table D.4 lists how the fields in the ONEVENTSTRUCT that are used by the A&E COM UA Wrapper are mapped to UA AlarmType Variables.
Table D.4 – Mapping from ONEVENTSTRUCT fields to UA AlarmType Variables
UA Event Variable |
ONEVENTSTRUCT Field |
Notes |
ConditionClassId |
dwEventType |
Set to the NodeId of the ConditionClassType for the Event Category of a Condition Event Type. Set to the NodeId of BaseConditionClassType Node for non-Condition Event Types. |
ConditionClassName |
dwEventType |
Set to the BrowseName of the ConditionClassType for the Event Category of Condition Event Type. To set “BaseConditionClass" non-Condition Event Types. |
ConditionName |
szConditionName |
- |
BranchId |
- |
Always set to NULL. |
Retain |
wNewState |
Set to True if the OPC_CONDITION_ACKED bit is not set or OPC_CONDITION_ACTIVE bit is set. |
EnabledState |
wNewState |
Set to "Enabled" or "Disabled" |
EnabledState.Id |
wNewState |
Set to True if OPC_CONDITION_ENABLED is set |
EnabledState. EffectiveDisplayName |
wNewState |
A string constructed from the bits in the wNewState flag. The following rules are applied in order to select the string: "Disabled" if OPC_CONDITION_ENABLED is not set. "Unacknowledged" if OPC_CONDITION_ACKED is not set. "Active" if OPC_CONDITION_ACKED is set. "Enabled" if OPC_CONDITION_ENABLED is set. |
Quality |
wQuality |
The COM DA Quality converted to a UA StatusCode. |
Severity |
dwSeverity |
Set based on the last Event received for the Condition instance. Set to the current value if the last Event is not available. |
Comment |
- |
The value of the ACK_COMMENT Attribute |
ClientUserId |
szActorID |
- |
AckedState |
wNewState |
Set to "Acknowledged" or "Unacknowledged " |
AckedState.Id |
wNewState |
Set to True if OPC_CONDITION_ACKED is set |
ActiveState |
wNewState |
Set to "Active" or "Inactive" |
ActiveState.Id |
wNewState |
Set to True if OPC_CONDITION_ACTIVE is set |
ActiveState.TransitionTime |
ftActiveTime |
This time is set when the ActiveState transitions from False to True. Note: Additional logic applies to exclusive limit alarms, in that the LimitState.TransitionTime also needs to be set, but this is set each time a limit is crossed (multiple limits might exist). For the initial transition to True the ftActiveTime is used for both LimitState.TransitionTime and ActiveState.TransitionTime. For subsequent transition the ActiveState.Transition time does not change, but the LimitState.TransitionTime will be updated with the new ftActiveTime. For example, if an alarm has Hi and HiHi limits, when the Hi limit is crossed and the alarm goes active the ftActiveTime is used for both times, but when the HiHi limit is later crossed, the ftActiveTime is only be used for the LimitState.TransitionTime. Note: The ftActiveTime is part of the key for identifying the unique event in the A&E server and needs to be saved for processing any commands back to the A&E Server. |
|
|
|
The A & C Condition Model defines other optional Variables which are not needed in the A&E COM UA Wrapper. Any additional fields associated with Event Attributes are also reported.
Condition instances do not appear in the UA Server address space. Conditions can be acknowledged by passing the EventId to the Acknowledge Method defined on the AcknowledgeableConditionType.
Conditions cannot be enabled or disabled via the COM A&E Wrapper.
The COM A&E Wrapper does not store the state of Conditions. When ConditionRefresh is called the Refresh Method is called on all COM AE Subscriptions associated with the ConditionRefresh call. The wrapper needs to wait until it receives the call back with the bLastRefresh flag set to True in the OnEvent call before it can tell the UA Client that the Refresh has completed.
As illustrated in the figure below, the A&E COM UA Proxy is a COM Server combined with a UA Client. It maps the Alarms and Conditions address space of UA A & C Server into the appropriate COM Alarms and Event Objects.
Subclauses D.3.2 through D.3.9 identify the design guidelines and constraints used to develop the A&E COM UA Proxy provided by the OPC Foundation. In order to maintain a high degree of consistency and interoperability, it is strongly recommended that vendors, who choose to implement their own version of the A&E COM UA Proxy, follow these same guidelines and constraints.
The A&E COM Client simply needs to address how to connect to the UA A & C Server. Connectivity approaches include the one where A&E COM Clients connect to a UA A & C Server with a CLSID just as if the target Server were an A&E COM Server. However, the CLSID can be considered virtual since it is defined to connect to intermediary components that ultimately connect to the UA A & C Server. Using this approach, the A&E COM Client calls co-create instance with a virtual CLSID as described above. This connects to the A&E COM UA Proxy components. The A&E COM UA Proxy then establishes a secure channel and session with the UA A & C Server. As a result, the A&E COM Client gets a COM Event Server interface pointer.
The A&E COM UA Proxy reads the UA A & C Server status from the Server Object Variable Node. Status enumeration values that are returned in ServerStatusDataType structure can be mapped 1 for 1 to the A&E COM Server status values with the exception of UA A & C Server status values Unknown and Communication Fault. These both map to the A&E COM Server status value of Failed.
The VendorInfo string of the A&E COM Server status is mapped from ManufacturerName.
Since all Alarms and Conditions Events belong to a subtype of BaseEventType, the A&E COM UA Proxy maps the subtype as received from the UA A & C Server to one of the three A&E Event types: Simple, Tracking and Condition. Figure D.2 shows the mapping as follows:
- Those A & C Events which are of subtype AuditEventType are marked as A&E Event type Tracking.
- Those A & C Events which are ConditionType are marked as A&E Event type Condition.
- Those A & C Events which are of any subtype except AuditEventType or ConditionType are marked as A&E Event type Simple.
Figure D.2 – Mapping UA Event Types to COM A&E Event Types
Note that the Event type mapping described above also applies to the children of each subtype.
Each A&E Event type (e.g. Simple, Tracking, Condition) has an associated set of Event categories which are intended to define groupings of A&E Events. For example, Level and Deviation are possible Event categories of the Condition Event type for an A&E COM Server. However, since A & C does not explicitly support Event categories, the A&E COM UA Proxy uses A & C Event types to return A&E Event categories to the A&E COM Client. The A&E COM UA Proxy builds the collection of supported categories by traversing the type definitions in the address space of the UA A & C Server. Figure D.3 shows the mapping as follows:
- A&E Tracking categories consist of the set of all Event types defined in the hierarchy of subtypes of AuditEventType and TransitionEventType, including AuditEventType itself and TransitionEventType itself.
- A&E Condition categories consist of the set of all Event types defined in the hierarchy of subtypes of ConditionType, including ConditionType itself.
- A&E Simple categories consist of the set of Event types defined in the hierarchy of subtypes of BaseEventType excluding AuditEventType and ConditionType and their respective subtypes.
Figure D.3 – Example mapping of UA Event Types to COM A&E categories
Category name is derived from the display name Attribute of the Node type as discovered in the type hierarchy of the UA A & C Server.
Category description is derived from the description Attribute of the Node type as discovered in the type hierarchy of the UA A & C Server.
The A&E COM UA Proxy assigns Category IDs.
The collection of Attributes associated with any given A&E Event is encapsulated within the ONEVENTSTRUCT. Therefore, the A&E COM UA Proxy populates the Attribute fields within the ONEVENTSTRUCT using corresponding values from UA Event Notifications either directly (e.g., Source, Time, Severity) or indirectly (e.g., OPC COM Event category determined by way of the UA Event type). Table D.5 lists the Attributes currently defined in the ONEVENTSTRUCT in the leftmost column. The rightmost column of Table D.5 indicates how the A&E COM UA proxy defines that Attribute.
Table D.5 – Event category attribute mapping table
A&E ONEVENTSTRUCT “attribute” |
A&E COM UA Proxy Mapping |
The following items are present for all A&E event types |
|
szSource |
UA BaseEventType Property: SourceName |
ftTime |
UA BaseEventType Property: Time |
szMessage |
UA BaseEventType Property: Message |
dwEventType |
See Clause D.3.3 |
dwEventCategory |
See Clause D.3.4 |
dwSeverity |
UA BaseEventType Property: Severity |
dwNumEventAttrs |
Calculated within A&E COM UA Proxy |
pEventAttributes |
Constructed within A&E COM UA Proxy |
The following items are present only for A&E Condition-Related Events |
|
szConditionName |
UA ConditionType Property: ConditionName |
szSubConditionName |
UA ActiveState Property: EffectiveDisplayName |
wChangeMask |
Calculated within Alarms and Events COM UA proxy |
wNewState: OPC_CONDITION_ACTIVE |
A & C AlarmConditionType Property: ActiveState Note that events mapped as non-Condition Events and those that do not derive from AlarmConditionType are set to ACTIVE by default. |
wNewState: OPC_CONDITION_ENABLED |
A & C ConditionType Property: EnabledState Note, Events mapped as non-Condition Events are set to ENABLED (state bit mask = 0x1) by default. |
wNewState: OPC_CONDITION_ACKED |
A & C AcknowledgeableConditionType Property: AckedState Note that A & C Events mapped as non-Condition Events or which do not derive from AcknowledgeableConditionType are set to UNACKNOWLEDGED and AckRequired = False by default. |
wQuality |
A & C ConditionType Property: Quality Note that Events mapped as non-Condition Events are set to OPC_QUALITY_GOOD by default.
In general, the Severity field of the StatusCode is used to map COM status codes OPC_QUALITY_BAD, OPC_QUALITY_GOOD and OPC_QUALITY_UNCERTAIN. When possible, specific status' are mapped directly. These include (UA => COM):
Bad status codes Bad_ConfigurationError => OPC_QUALITY_CONFIG_ERROR Bad_NotConnected => OPC_QUALITY_NOT_CONNECTED Bad_DeviceFailure => OPC_QUALITY_DEVICE_FAILURE Bad_SensorFailure => OPC_QUALITY_SENSOR_FAILURE Bad_NoCommunication => OPC_QUALITY_COMM_FAILURE Bad_OutOfService => OPC_QUALITY_OUT_OF_SERVICE
Uncertain status codes Uncertain_NoCommunicationLastUsableValue => OPC_QUALITY_LAST_USABLE Uncertain_LastUsableValue => OPC_QUALITY_LAST_USABLE Uncertain_SensorNotAccurate => OPC_QUALITY_SENSOR_CAL Uncertain_EngineeringUnitsExceeded => OPC_QUALITY_EGU_EXCEEDED Uncertain_SubNormal => OPC_QUALITY_SUB_NORMAL
Good status codes Good_LocalOverride => OPC_QUALITY_LOCAL_OVERRIDE |
bAckRequired |
If the ACKNOWLEDGED bit (OPC_CONDITION_ACKED) is set then the Ack Required Boolean is set to False, otherwise the Ack Required Boolean is set to True. If the Event is not of type AcknowledgeableConditionType or subtype then the AckRequired Boolean is set to False. |
ftActiveTime |
If the Event is of type AlarmConditionType or subtype and a transition from ActiveState of False to ActiveState to True is being processed then the TransitionTime Property of ActiveState is used. If the Event is not of type AlarmConditionType or subtype then this field is set to current time. Note: Additional logic applies to exclusive limit alarms, This value should be mapped to the LimitState.TransitionTime. |
dwCookie |
Generated by the A&E COM UA Proxy. These unique Condition Event cookies are not associated with any related identifier from the address space of the UA A & C Server. |
The following is used only for A&E tracking events and for A&E condition-relate events which are acknowledgement notifications |
|
szActorID |
|
Vendor specific Attributes – ALL |
|
ACK Comment |
|
AREAS |
All A&E Events are assumed to support the "Areas" Attribute. However, no Attribute or Property of an A & C Event is available which provides this value. Therefore, the A&E COM UA Proxy initializes the value of the Areas Attribute based on the MonitoredItem producing the Event. If the A&E COM Client has applied no area filtering to a Subscription, the corresponding A & C Subscription will contain just one MonitoredItem – that of the UA A & C Server Object. Events forwarded to the A&E COM Client on behalf of this Subscription will carry an Areas Attribute value of empty string. If the A&E COM Client has applied an area filter to a Subscription then the related UA A & C Subscription will contain one or more MonitoredItems for each notifier Node identified by the area string(s). Events forwarded to the A&E COM Client on behalf of such a Subscription will carry an areas Attribute whose value is the relative path to the notifier which produced the Event (i.e., the fully qualified area name). |
Vendor specific Attributes – based on category |
|
SubtypeProperty1 |
All the UA A & C subtype Properties that are not part of the standard set exposed by BaseEventType or ConditionType |
SubtypePropertyn |