Samples, Events, and Condition

From MTConnect® User's Portal
Jump to: navigation, search

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.
Condition Schema

Condition Attributes:

Attribute Description Occurrence
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
name The name MUST match the name of the event's associated DataItem. An NMTOKEN XML type. 0..1
type The DataItem type this Condition refers to. 1
sub-type The sub-type of the DataItem this Condition refers to. 0..1
qualifier Qualifies the Condition and adds context or additional clarification. This optional attribute can be used to convey information like HIGH, LOW, … 0..1
nativeCode The native code for the piece of equipment. This is the way the Condition is represented by the component. 0..1
nativeSeverity The pass thru severity from the device manufacturer. 0..1
statistic The type of statistical calculation specified for the DataItem 0..1
xs:lang An optional attribute that specifies language of the alarm or condition text. Refer to IETF RFC 4646 (http://www.ietf.org/rfc/rfc4646.txt) or successor for a full definition of the values for this attribute. Does not appear in the Header schema diagrams 0..1

Condition Contents CDATA

The contents are the optional text from the data source in the un-interpreted form. The text is provided for informational purpose only for interpretation by the application or other client software.

Condition Types

All existing DataItem types MAY be used as types for the Condition types. There are some additional types that have been added that represent logical parts of the device architecture and allow for better association and representation of the device’s health. The following are the types specifically added for the Condition:

Data Item type/qualifier Description
ACTUATOR A condition with the motion drive, servo, or actuator.
COMMUNICATIONS A communications failure indicator.
HARDWARE The operational condition of the hardware subsystem of the component.
LOGIC_PROGRAM An error occurred in the logic program or PLC (programmable logic controller).
MOTION_PROGRAM An error occurred in the motion program.
SYSTEM A condition representing something that is not the operator, program, or hardware. This is often used to represent operating system issues.

Condition Examples

For abbreviated examples of the use of Condition elements in XML, click here.