Errata exists for this version of the document.
The CreateMonitoredItem Service allows specifying a filter for each MonitoredItem. The MonitoringFilter is an extensible parameter whose structure depends on the type of item being monitored. The parameterTypeIds are defined in Table 140. Other types can be defined by additional parts of this multi-part specification or other specifications based on OPC UA. The ExtensibleParameter type is defined in 7.12.
Each MonitoringFilter may have an associated MonitoringFilterResult structure which returns revised parameters and/or error information to clients in the response. The result structures, when they exist, are described in the section that defines the MonitoringFilter.
Table 140 – MonitoringFilter parameterTypeIds
|
Symbolic Id |
Description |
|
DataChangeFilter |
The change in a data value that shall cause a Notification to be generated. |
|
EventFilter |
If a Notification conforms to the EventFilter, the Notification is sent to the Client. |
|
AggregateFilter |
The Aggregate and its intervals when it will be calculated and a Notification is generated. |
The DataChangeFilter defines the conditions under which a DataChange Notification should be reported and, optionally, a range or band for value changes where no DataChange Notification is generated. This range is called Deadband. The DataChangeFilter is defined in Table 141.
|
Name |
Type |
Description |
|
DataChangeFilter |
structure |
|
|
trigger |
Enum DataChangeTrigger |
Specifies the conditions under which a data change notification should be reported. It has the following values: STATUS_0Report a notification ONLY if the StatusCode associated with the value changes. See Table 178 for StatusCodes defined in this standard. OPC 10000-8 specifies additional StatusCodes that are valid in particular for device data. STATUS_VALUE_1Report a notification if either the StatusCode or the value change. The Deadband filter can be used in addition for filtering value changes. For floating point values a Server shall check for NaN and only report a single notification with NaN when the value enters the NaN state. This is the default setting if no filter is set. STATUS_VALUE_TIMESTAMP_2Report a notification if either StatusCode, value or the SourceTimestamp change. If a Deadband filter is specified, this trigger has the same behaviour as STATUS_VALUE_1. If the DataChangeFilter is not applied to the monitored item, STATUS_VALUE_1 is the default reporting behaviour. |
|
deadbandType |
UInt32 |
A value that defines the Deadband type and behaviour. Value deadbandType None_0 No Deadband calculation should be applied. Absolute_1 AbsoluteDeadband (see below) Percent_2 PercentDeadband (This type is specified in OPC 10000-8). |
|
deadbandValue |
Double |
The Deadband is applied only if* the trigger includes value changes and* the deadbandType is set appropriately. Deadband is ignored if the status of the data item changes. DeadbandType = AbsoluteDeadband: For this type the deadbandValue contains the absolute change in a data value that shall cause a Notification to be generated. This parameter applies only to Variables with any Number data type. An exception that causes a DataChange Notification based on an AbsoluteDeadband is determined as follows: Generate a Notification if (absolute value of (last cached value - current value) > AbsoluteDeadband) The last cached value is defined as the last value pushed to the queue. If the item is an array of values, the entire array is returned if any array element exceeds the AbsoluteDeadband, or the size or dimension of the array changes. DeadbandType = PercentDeadband: This type is specified in OPC 10000-8 |
The DataChangeFilter does not have an associated result structure.
The EventFilter provides for the filtering and content selection of Event Subscriptions.
If an Event Notification conforms to the filter defined by the where parameter of the EventFilter, then the Notification is sent to the Client.
Each Event Notification shall include the fields defined by the selectClauses parameter of the EventFilter. The defined EventTypes are specified in OPC 10000-5.
The selectClauses and whereClause parameters are specified with the SimpleAttributeOperand structure (see 7.4.4.5). This structure requires the NodeId of an EventType supported by the Server and a path to an InstanceDeclaration. An InstanceDeclaration is a Node which can be found by following forward hierarchical references from the fully inherited EventType where the Node is also the source of a HasModellingRule reference. EventTypes, InstanceDeclarations and Modelling Rules are described completely in OPC 10000-3.
In some cases the same BrowsePath will apply to multiple EventTypes. If the Client specifies the BaseEventType in the SimpleAttributeOperand then the Server shall evaluate the BrowsePath without considering the Type.
Each InstanceDeclaration in the path shall be Object or Variable Node. The final Node in the path may be an Object Node; however, Object Nodes are only available for Events which are visible in the Server’s AddressSpace.
The SimpleAttributeOperand structure allows the Client to specify any Attribute; however, the Server is only required to support the Value Attribute for Variable Nodes and the NodeId Attribute for Object Nodes. That said, profiles defined in OPC 10000-7 may make support for additional Attributes mandatory.
The SimpleAttributeOperand structure is used in the selectClauses to select the value to return if an Event meets the criteria specified by the whereClause. A null value is returned in the corresponding event field in the Publish response if the selected field is not part of the Event or an error was returned in the selectClauseResults of the EventFilterResult. If the selected field is supported but not available at the time of the event notification, the event field shall contain a StatusCode that indicates the reason for the unavailability. For example, the Server shall set the event field to Bad_UserAccessDenied if the value is not accessible to the user associated with the Session. If a Value Attribute has an uncertain or bad StatusCode associated with it then the Server shall provide the StatusCode instead of the Value Attribute. The Server shall set the event field to Bad_EncodingLimitsExceeded if a value exceeds the maxResponseMessageSize. The EventId, EventType and ReceiveTime cannot contain a StatusCode or a null value.
The Server shall validate the selectClauses when a Client creates or updates the EventFilter. Any errors which are true for all possible Events are returned in the selectClauseResults parameter described in Table 143. Some Servers, like aggregating Servers, may not know all possible EventTypes at the time the EventFilter is set. These Servers do not return errors for unknown EventTypes or BrowsePaths. The Server shall not report errors that might occur depending on the state or the Server or type of Event. For example, a selectClauses that requests a single element in an array would always produce an error if the DataType of the Attribute is a scalar. However, even if the DataType is an array an error could occur if the requested index does not exist for a particular Event, the Server would not report an error in the selectClauseResults parameter if the latter situation existed.
The SimpleAttributeOperand is used in the whereClause to select a value which forms part of a logical expression. These logical expressions are then used to determine whether a particular Event should be reported to the Client. The Server shall use a null value if any error occurs when a whereClause is evaluated for a particular Event. If a Value Attribute has an uncertain or bad StatusCode associated with it, then the Server shall use a null value instead of the Value.
Any basic FilterOperator in Table 119 may be used in the whereClause, however, only the OfType_14 FilterOperator from Table 120 is permitted.
The Server shall validate the whereClause when a Client creates or updates the EventFilter. Any structural errors in the construction of the filter and any errors which are true for all possible Events are returned in the whereClauseResult parameter described in Table 143. Errors that could occur depending on the state of the Server or the Event are not reported. Some Servers, like aggregating Servers, may not know all possible EventTypes at the time the EventFilter is set. These Servers do not return errors for unknown EventTypes or BrowsePaths.
EventQueueOverflowEventType Events are special Events which are used to provide control information to the Client. These Events are only published to the MonitoredItems in the Subscription that produced the EventQueueOverflowEventType Event. These Events bypass the whereClause.
Table 142 defines the EventFilter structure.
Table 142 – EventFilter structure
|
Name |
Type |
Description |
|
EventFilter |
structure |
|
|
selectClauses [] |
SimpleAttribute Operand |
List of the values to return with each Event in a Notification. At least one valid clause shall be specified. See 7.4.4.5 for the definition of SimpleAttributeOperand. |
|
whereClause |
ContentFilter |
Limit the Notifications to those Events that match the criteria defined by this ContentFilter. The ContentFilter structure is described in 7.4. The AttributeOperand structure may not be used in an EventFilter. |
Table 143 defines the EventFilterResult structure. This is the MonitoringFilterResult associated with the EventFilter MonitoringFilter.
Table 143 – EventFilterResult structure
|
Name |
Type |
Description |
|
EventFilterResult |
structure |
|
|
selectClauseResults [] |
StatusCode |
List of status codes for the elements in the select clause. The size and order of the list matches the size and order of the elements in the selectClauses request parameter. The Server returns null for unavailable or rejected Event fields. |
|
selectClauseDiagnosticInfos [] |
DiagnosticInfo |
A list of diagnostic information for individual elements in the select clause. The size and order of the list matches the size and order of the elements in the selectClauses request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the select clauses. |
|
whereClauseResult |
ContentFilter Result |
Any results associated with the whereClause request parameter. The ContentFilterResult type is defined in 7.4.2. |
Table 144 defines values for the selectClauseResults parameter. Common StatusCodes are defined in Table 178.
Table 144 – EventFilterResult Result Codes
|
Symbolic Id |
Description |
|
Bad_TypeDefinitionInvalid |
See Table 178 for the description of this result code. The typeId is not the NodeId for BaseEventType or a subtype of it. |
|
Bad_NodeIdUnknown |
See Table 178 for the description of this result code. The browsePath is specified but it will never exist in any Event. |
|
Bad_BrowseNameInvalid |
See Table 178 for the description of this result code. The browsePath is specified and contains a null element. |
|
Bad_AttributeIdInvalid |
See Table 178 for the description of this result code. The node specified by the browse path will never allow the given AttributeId to be returned. |
|
Bad_IndexRangeInvalid |
See Table 178 for the description of this result code. |
|
Bad_TypeMismatch |
See Table 178 for the description of this result code. The indexRange is valid but the value of the Attribute is never an array. |
The AggregateFilter defines the Aggregate function that should be used to calculate the values to be returned. See OPC 10000-13 for details on possible Aggregate functions. It specifies a startTime of the first Aggregate to be calculated. The samplingInterval of the MonitoringParameters (see 7.16) defines how the Server should internally sample the underlying data source. The processingInterval specifies the size of a time-period where the Aggregate is calculated. The queueSize from the MonitoringAttributes specifies the number of processed values that should be kept.
The intention of the AggregateFilter is not to read historical data, the HistoryRead service should be used for this purpose. However, it is allowed that the startTime is set to a time that is in the past when received from the server. The number of Aggregates to be calculated in the past should not exceed the queueSize defined in the MonitoringAttributes since the values exceeding the queueSize would directly be discharged and never returned to the client.
The startTime and the processingInterval can be revised by the server, but the startTime should remain in the same boundary (startTime + revisedProcessingInterval * n = revisedStartTime). That behaviour simplifies accessing historical values of the Aggregates using the same boundaries by calling the HistoryRead service. The extensible Parameter AggregateFilterResult is used to return the revised values for the AggregateFilter.
Some underlying systems may poll data and produce multiple samples with the same value. Other systems may only report changes to the values. The definition for each Aggregate type explains how to handle the two different scenarios.
The MonitoredItem only reports values for intervals that have completed when the publish timer expires. Unused data is carried over and used to calculate a value returned in the next publish.
The ServerTimestamp for each interval shall be the time of the end of the processing interval.
The AggregateFilter is defined in Table 145.
Table 145 – AggregateFilter structure
|
Name |
Type |
Description |
|
AggregateFilter |
structure |
|
|
startTime |
UtcTime |
Beginning of period to calculate the Aggregate the first time. The size of each period used to calculate the Aggregate is defined by the samplingInterval of the MonitoringParameters (see 7.16). |
|
aggregateType |
NodeId |
The NodeId of the AggregateFunctionType Object that indicates the Aggregate to be used when retrieving processed data. See OPC 10000-13 for details. |
|
processingInterval |
Duration |
The period be used to compute the Aggregate. |
|
aggregateConfiguration |
Aggregate Configuration |
This parameter allows Clients to override the Aggregate configuration settings supplied by the AggregateConfiguration Object on a per monitored item basis. See OPC 10000-13 for more information on Aggregate configurations. If the Server does not support the ability to override the Aggregate configuration settings it shall return a StatusCode of Bad_AggregateListMismatch. This structure is defined in-line with the following indented items. |
|
useServerCapabilities Defaults |
Boolean |
If value = TRUE use Aggregate configuration settings as outlined by the AggregateConfiguration object. If value=FALSE use configuration settings as outlined in the following aggregateConfiguration parameters. Default is TRUE. |
|
treatUncertainAsBad |
Boolean |
As described in OPC 10000-13. |
|
percentDataBad |
Byte |
As described in OPC 10000-13. |
|
percentDataGood |
Byte |
As described in OPC 10000-13. |
|
useSloped Extrapolation |
Boolean |
As described in OPC 10000-13. |
The AggregateFilterResult defines the revised AggregateFilter the Server can return when an AggregateFilter is defined for a MonitoredItem in the CreateMonitoredItems or ModifyMonitoredItems Services. The AggregateFilterResult is defined in Table 146. This is the MonitoringFilterResult associated with the AggregateFilter MonitoringFilter.
Table 146 – AggregateFilterResult structure
|
Name |
Type |
Description |
|
AggregateFilterResult |
structure |
|
|
revisedStartTime |
UtcTime |
The actual StartTime interval that the Server shall use. This value is based on a number of factors, including capabilities of the Server to access historical data. The revisedStartTime should remain in the same boundary as the startTime (startTime + samplingInterval * n = revisedStartTime). |
|
revisedProcessingInterval |
Duration |
The actual processingInterval that the Server shall use.
The revisedProcessingInterval shall be at least twice the revisedSamplingInterval for the MonitoredItem. |
|
revisedAggregateConfiguration |
Aggregate Configuration |
The actual aggregrateConfiguration that the Server shall use. The structure is defined in Table 145. |