Difference between revisions of "Samples, Events, and Condition"

From MTConnect® User's Portal
Jump to: navigation, search
Line 7: Line 7:
 
The ''[[Terminology|Samples]]'' [[Terminology|XML]] element MUST contain at least one ''[[Terminology|Sample]]'' element. The ''[[Terminology|Samples]]'' [[Terminology|XML]] element acts only as a container for all the ''[[Terminology|Sample]]'' [[Terminology|XML]] elements to provide a logical structure to the [[Terminology|XML]] Document.
 
The ''[[Terminology|Samples]]'' [[Terminology|XML]] element MUST contain at least one ''[[Terminology|Sample]]'' element. The ''[[Terminology|Samples]]'' [[Terminology|XML]] element acts only as a container for all the ''[[Terminology|Sample]]'' [[Terminology|XML]] elements to provide a logical structure to the [[Terminology|XML]] Document.
  
[[File:SampleElement.PNG|none|500px|thumb|''Sample'' Element]]
+
'''''Sample'' Element:'''
 +
 
 +
{|class="wikitable"
 +
!style="background-color:#028080;color:white"|Element
 +
!style="background-color:#028080;color:white"|Description
 +
!style="background-color:#028080;color:white"|Occurrence
 +
|-
 +
|Sample||The sub-element of Samples for this component stream||1..INF
 +
|}
  
 
If two adjacent [[Terminology|samples]] for the same ''[[Terminology|Component]]'' and ''[[Terminology|DataItem]]'' have the same value, the second [[Terminology|sample]] MUST NOT be sent to the client [[Terminology|application]] and does not need to be retained by the MTConnect ''[[Terminology|Agent]]''. This will greatly reduce the amount of information sent to the [[Terminology|application]]. The [[Terminology|application]] can always assume that if the [[Terminology|sample]] is not present, it has the previous value.
 
If two adjacent [[Terminology|samples]] for the same ''[[Terminology|Component]]'' and ''[[Terminology|DataItem]]'' have the same value, the second [[Terminology|sample]] MUST NOT be sent to the client [[Terminology|application]] and does not need to be retained by the MTConnect ''[[Terminology|Agent]]''. This will greatly reduce the amount of information sent to the [[Terminology|application]]. The [[Terminology|application]] can always assume that if the [[Terminology|sample]] is not present, it has the previous value.
Line 17: Line 25:
 
The same concepts are used for time-series [[Terminology|samples]] as well where the timestamp of the series is set to the time the last value was recorded and the timestamp minus the duration is the time the first [[Terminology|sample]] was recorded.
 
The same concepts are used for time-series [[Terminology|samples]] as well where the timestamp of the series is set to the time the last value was recorded and the timestamp minus the duration is the time the first [[Terminology|sample]] was recorded.
  
[[File:SampleSchema.PNG|left|500px|thumb|''Sample'' Schema]]
+
[[File:SampleSchema.PNG|center|500px|thumb|''Sample'' Schema]]
[[File:SampleAttributes.PNG|center|500px|thumb|''Sample'' Attributes]]
+
 
 +
'''''Sample'' Attributes:'''
 +
 
 +
{|class="wikitable"
 +
!style="background-color:#028080;color:white"|Attribute
 +
!style="background-color:#028080;color:white"|Description
 +
!style="background-color:#028080;color:white"|Occurrence
 +
|-
 +
|name||The name MUST match the name of the DataItem this Sample is associated with. It MUST be an NMTOKEN XML type.||0..1
 +
|-
 +
|sequence||The sequence number of this event. The value MUST be represented as an unsigned 64 bit with valid values from 1 to 2^64-1.||1
 +
|-
 +
|timestamp||The time the sample value was reported or the statistics were computed. The timestamp MUST always represent the end of the collection interval when a duration or a TimeSeries is provided. The most accurate time available to the device MUST be used for the timestamp.||1
 +
|-
 +
|dataItemID||The id attribute of the corresponding data retrieved in the probe request.||1
 +
|-
 +
|subType||The sub-type of the DataItem|| 0..1
 +
|-
 +
|sampleRate||The rate at which successive samples of a DataItem are recorded. Sample rate is expressed in terms of samples per second.  If the sample rate is smaller than one, the number can be represented as a floating point number. For example, a rate 1 per 10 seconds would be 0.1. The sampleRate attribute MUST be included in the TimeSeries streams element if it is not constant OR if it is not in the DataItem. If the sampleRate is constant it MAY be placed in the DataItem and does not need to be repeated in the streams element.||0..1
 +
|-
 +
|statistic||The type of statistical calculation specified for the DataItem||0..1
 +
|-
 +
|duration||The time elapsed since the statistic calculation was last reset||0..1
 +
|}
  
 
A ''[[Terminology|Sample]]'' MUST contain ''[[Terminology|CDATA]]'' as the content between the element [[Terminology|tags]].  A position is formatted like this:
 
A ''[[Terminology|Sample]]'' MUST contain ''[[Terminology|CDATA]]'' as the content between the element [[Terminology|tags]].  A position is formatted like this:
Line 36: Line 67:
 
The [[Terminology|XML]] element of the ''[[Terminology|Sample]]'' for a ''[[Terminology|DataItem]]'' with an [[Terminology|attribute]] of ''representation'' will be the transformation of the ''[[Terminology|DataItem]]'' type by capitalizing the first character of each word and then removing the underscore and adding the representation type.  For example, ''ANGULAR_VELOCITY''  with ''representation'' defined as ''TimeSeries'' MUST be ''AngularVelocityTimeSeries''.  If ''representation'' is not defined or it is VALUE, then the transformation MUST be ''AngularVelocity''.
 
The [[Terminology|XML]] element of the ''[[Terminology|Sample]]'' for a ''[[Terminology|DataItem]]'' with an [[Terminology|attribute]] of ''representation'' will be the transformation of the ''[[Terminology|DataItem]]'' type by capitalizing the first character of each word and then removing the underscore and adding the representation type.  For example, ''ANGULAR_VELOCITY''  with ''representation'' defined as ''TimeSeries'' MUST be ''AngularVelocityTimeSeries''.  If ''representation'' is not defined or it is VALUE, then the transformation MUST be ''AngularVelocity''.
  
[[File:TimeSeriesSchema.PNG|none|500px|thumb|''Time Series'' Schema]]
+
[[File:TimeSeriesSchema.PNG|center|500px|thumb|''Time Series'' Schema]]
[[File:TimeSeriesAttributes.PNG|none|500px|thumb|''Time Series'' Attributes]]
+
 
 +
'''Time Series Attributes:'''
 +
 
 +
{|class="wikitable"
 +
!style="background-color:#028080;color:white"|Attribute
 +
!style="background-color:#028080;color:white"|Description
 +
!style="background-color:#028080;color:white"|Occurrence
 +
|-
 +
|sampleCount||The number of readings of a DataItem provided in a Time Series.||0..1
 +
|}
 +
 
  
 
=== Sample XML Element Tag Names ===
 
=== Sample XML Element Tag Names ===
  
 
For a list of [[Terminology|XML]] elements that can be placed in the ''[[Terminology|Samples]]'' section of the ''ComponentStream'', [[XML Element Tag Names - Sample|click here]].
 
For a list of [[Terminology|XML]] elements that can be placed in the ''[[Terminology|Samples]]'' section of the ''ComponentStream'', [[XML Element Tag Names - Sample|click here]].
 +
 +
=== Extensibility ===
 +
 +
Additional ''[[Terminology|Sample]]'' types can be added by extending the ''[[Terminology|Sample]]'' type in the [[Terminology|XML]] schema.  The ''[[Terminology|Samples]]'' presented here are the official ''[[Terminology|Sample]]'' types that will be supported by all MTConnect ''[[Terminology|Agents]]''.  Any non-sanctioned extensions will not be guaranteed to have consistency across implementations.
  
 
== Events ==
 
== Events ==
 +
 +
An ''[[Terminology|Event]]'' is an abstract type.  This means there will never be an actual element called ''[[Terminology|Event]]'', but any [[Terminology|XML]] element that is a sub-type of ''[[Terminology|Event]]'' can be used in place of ''[[Terminology|Event]]''.  Examples of [[Terminology|event]] sub-types are ''Block'', ''Execution'', and ''Line''.  ''[[Terminology|Event]]'' types MAY have values defined by a [[Terminology|controlled vocabulary]] or MAY contain a character string representing data provided by the [[Terminology|device]].
 +
 +
The ''[[Terminology|Events]]'' [[Terminology|XML]] element MUST contain at least one ''[[Terminology|Event]]'' element. The ''[[Terminology|Events]]'' element acts only as a container for all the ''[[Terminology|Event]]'' [[Terminology|XML]] elements to provide a logical structure to the [[Terminology|XML]] Document.
 +
 +
{|class="wikitable"
 +
!style="background-color:#028080;color:white"|Element
 +
!style="background-color:#028080;color:white"|Description
 +
!style="background-color:#028080;color:white"|Occurrence
 +
|-
 +
|Event||The subtype of Event for this component stream||1..INF
 +
|}
 +
 +
An ''[[Terminology|Event]]'' is similar to a ''[[Terminology|Sample]]'', but its values are going to be changing with unpredictable frequency.  ''[[Terminology|Events]]'' do not have intermediate values. When ''Availability'' transitions from ''UNAVAILABLE'' to ''AVAILABLE'', there is no intermediate state that can be inferred. Therefore, most ''[[Terminology|Events]]'' have a [[Terminology|controlled vocabulary]] as their content.
 +
 +
[[File:EventsSchema.PNG||center||500px|thumb|''Event'' Schema]]
 +
 +
'''''Event'' Attributes:'''
 +
 +
{|class="wikitable"
 +
!style="background-color:#028080;color:white"|Attribute|
 +
!style="background-color:#028080;color:white"|Description
 +
!style="background-color:#028080;color:white"|Occurrence
 +
|-
 +
|name||The name MUST match the name of the DataItem this sample is associated with. It MUST be an NMTOKEN XML type.||0..1
 +
|-
 +
|sequence||The sequence number of this event. The value MUST be represented as an unsigned 64 bit with valid values from 1 to 2^64-1.||1
 +
|-
 +
|timestamp||The timestamp of the sample. The most accurate time available to the device MUST be used for the timestamp||1
 +
|-
 +
|dataItemID||The id attribute of the corresponding data retrieved in the probe request.||1
 +
|-
 +
|subType||The sub-type of the dataItem||0..1
 +
|}
 +
 +
=== Event Element Tag Names ===
 +
 +
The ''[[Terminology|Event]]'' [[Terminology|XML]] elements represent the state of various [[Terminology|device]] [[Terminology|attributes]]. For a list of all the [[Terminology|event]] elements that may be placed within the ''[[Terminology|Events]]'' section of the ''ComponentStream'', [[XML Element Tag Names - Event|click here]].
 +
 +
== Condition ==
 +
 +
''[[Terminology|Condition]]'' provides a method by which the machine can communicate its health and ability to function.  A [[Terminology|condition]] can be one of ''Normal'', ''Warning'', ''Fault'', or ''Unavailable''.  A ''[[Terminology|Component]]'' MAY have multiple active conditions at one time whereas a ''[[Terminology|Sample]]'' or ''[[Terminology|Event]]'' can only have a single value at a point in time.
 +
 +
=== Types of Condition ===
 +
 +
'''Normal'''
 +
:The item being monitored is operating normally and no action is required.  ''Normal'' also indicates a ''Fault'' or ''Warning'' condition has been cleared if the item was previously identified with ''Fault'' or ''Warning''.
 +
 +
'''Warning'''
 +
:The item being monitored is moving into the abnormal range and should be observed.  No action is required at this time.  Transition to a ''Normal'' condition indicates that the ''Warning'' condition has been cleared.
 +
 +
'''Fault'''
 +
:The item has failed and intervention is required to return to a ''Normal'' condition. Transition to a ''Normal'' condition indicates that the ''Fault'' condition has been cleared.  A ''Fault'' condition is something that always needs to be acknowledged before operation can continue.  Faults are sometimes noted as an alarm.
 +
 +
'''Unavailable'''
 +
:The value of the item is in an indeterminate state since the data source is no longer providing data.  This will also be the initial state of the ''Condition'' before a connection is established with the data source.  The ''Condition'' MUST be ''Unavailable'' when the value is unknown.

Revision as of 09:53, 12 August 2013

All Samples and Events values MUST be able to provide UNAVAILABLE as a valid value when the data source is not connected or the data source is unable to retrieve information. The UNAVAILABLE value will persist until the connection is restored and a new value can be retrieved. This state does not imply the device is no longer operational, it only implies that the state cannot be determined.

Contents

Samples

A Sample is an abstract type. This means there will never be an actual element called Sample, but any XML element that is a sub-type of Sample can be used as a sub-element of Samples. Examples of sample sub-types are Position, Load, and Angle. Sample types MUST have numeric values.

The Samples XML element MUST contain at least one Sample element. The Samples XML element acts only as a container for all the Sample XML elements to provide a logical structure to the XML Document.

Sample Element:

Element Description Occurrence
Sample The sub-element of Samples for this component stream 1..INF

If two adjacent samples for the same Component and DataItem have the same value, the second sample MUST NOT be sent to the client application and does not need to be retained by the MTConnect Agent. This will greatly reduce the amount of information sent to the application. The application can always assume that if the sample is not present, it has the previous value.

For DataItems containing an attribute for Duration, the timestamp associated with the sample references the time the sample value was reported or the statistics were computed, NOT the time the interval began. The time the interval began can be computed by subtracting the duration from the timestamp. Two samples can have overlapping intervals as in the case where statistics are computed at various frequencies.

For example, a one minute average and a five minute average can both have the same start time (Lets say 05:10:00), but their timestamps will be 05:11:00 with a duration of 60 seconds for the one minute average and a timestamp of 05:15:00 with a duration of 300 seconds for the five minute average. This allows for varying statistical methods to be applied with different interval lengths without having duplicate timestamps and durations. If a statistical data item does not report for a period greater than the previous duration, it can be assumed the computed value has not changed since the last value.

The same concepts are used for time-series samples as well where the timestamp of the series is set to the time the last value was recorded and the timestamp minus the duration is the time the first sample was recorded.

Sample Schema

Sample Attributes:

Attribute Description Occurrence
name The name MUST match the name of the DataItem this Sample is associated with. It MUST be an NMTOKEN XML type. 0..1
sequence The sequence number of this event. The value MUST be represented as an unsigned 64 bit with valid values from 1 to 2^64-1. 1
timestamp The time the sample value was reported or the statistics were computed. The timestamp MUST always represent the end of the collection interval when a duration or a TimeSeries is provided. The most accurate time available to the device MUST be used for the timestamp. 1
dataItemID The id attribute of the corresponding data retrieved in the probe request. 1
subType The sub-type of the DataItem 0..1
sampleRate The rate at which successive samples of a DataItem are recorded. Sample rate is expressed in terms of samples per second. If the sample rate is smaller than one, the number can be represented as a floating point number. For example, a rate 1 per 10 seconds would be 0.1. The sampleRate attribute MUST be included in the TimeSeries streams element if it is not constant OR if it is not in the DataItem. If the sampleRate is constant it MAY be placed in the DataItem and does not need to be repeated in the streams element. 0..1
statistic The type of statistical calculation specified for the DataItem 0..1
duration The time elapsed since the statistic calculation was last reset 0..1

A Sample MUST contain CDATA as the content between the element tags. A position is formatted like this:

1.	<Position sequence=”112” timestamp=”2007-08-09T12:32:45.1232” name=”Xabs” dataItemId=”10”>123.3333</Position>

In this example the 123.3333 is the CDATA for the position. All the CDATA in a Sample is typed, meaning that it can be validated using an XML parser. This restricts the format of the values to a specific pattern.

Time Series

A Time Series is a Sample which includes multiple readings of a DataItem taken at a specified sample rate. A time series can be used for collecting high frequency samples of a DataItem and then providing the series of samples to an application as a single DataItem. A time series contains the same attributes as a Sample, plus one additional attribute sampleCount. For a Time Series, sampleRate defines the time period (frequency) for the collection of each reading of the DataItem and sampleCount defines the total number of readings being transmitted. The CDATA MUST be a series of floating point numbers. The number of readings MUST match the sampleCount. The units for a Time Series MUST be the same as specified for the DataItem.

The XML element of the Sample for a DataItem with an attribute of representation will be the transformation of the DataItem type by capitalizing the first character of each word and then removing the underscore and adding the representation type. For example, ANGULAR_VELOCITY with representation defined as TimeSeries MUST be AngularVelocityTimeSeries. If representation is not defined or it is VALUE, then the transformation MUST be AngularVelocity.

Time Series Schema

Time Series Attributes:

Attribute Description Occurrence
sampleCount The number of readings of a DataItem provided in a Time Series. 0..1


Sample XML Element Tag Names

For a list of XML elements that can be placed in the Samples section of the ComponentStream, click here.

Extensibility

Additional Sample types can be added by extending the Sample type in the XML schema. The Samples presented here are the official Sample types that will be supported by all MTConnect Agents. Any non-sanctioned extensions will not be guaranteed to have consistency across implementations.

Events

An Event is an abstract type. This means there will never be an actual element called Event, but any XML element that is a sub-type of Event can be used in place of Event. Examples of event sub-types are Block, Execution, and Line. Event types MAY have values defined by a controlled vocabulary or MAY contain a character string representing data provided by the device.

The Events XML element MUST contain at least one Event element. The Events element acts only as a container for all the Event XML elements to provide a logical structure to the XML Document.

Element Description Occurrence
Event The subtype of Event for this component stream 1..INF

An Event is similar to a Sample, but its values are going to be changing with unpredictable frequency. Events do not have intermediate values. When Availability transitions from UNAVAILABLE to AVAILABLE, there is no intermediate state that can be inferred. Therefore, most Events have a controlled vocabulary as their content.

Event Schema

Event Attributes:

Attribute| Description Occurrence
name The name MUST match the name of the DataItem this sample is associated with. It MUST be an NMTOKEN XML type. 0..1
sequence The sequence number of this event. The value MUST be represented as an unsigned 64 bit with valid values from 1 to 2^64-1. 1
timestamp The timestamp of the sample. The most accurate time available to the device MUST be used for the timestamp 1
dataItemID The id attribute of the corresponding data retrieved in the probe request. 1
subType The sub-type of the dataItem 0..1

Event Element Tag Names

The Event XML elements represent the state of various device attributes. For a list of all the event elements that may be placed within the Events section of the ComponentStream, click here.

Condition

Condition provides a method by which the machine can communicate its health and ability to function. A condition can be one of Normal, Warning, Fault, or Unavailable. A Component MAY have multiple active conditions at one time whereas a Sample or Event can only have a single value at a point in time.

Types of Condition

Normal

The item being monitored is operating normally and no action is required. Normal also indicates a Fault or Warning condition has been cleared if the item was previously identified with Fault or Warning.

Warning

The item being monitored is moving into the abnormal range and should be observed. No action is required at this time. Transition to a Normal condition indicates that the Warning condition has been cleared.

Fault

The item has failed and intervention is required to return to a Normal condition. Transition to a Normal condition indicates that the Fault condition has been cleared. A Fault condition is something that always needs to be acknowledged before operation can continue. Faults are sometimes noted as an alarm.

Unavailable

The value of the item is in an indeterminate state since the data source is no longer providing data. This will also be the initial state of the Condition before a connection is established with the data source. The Condition MUST be Unavailable when the value is unknown.