Data Items
A DataItem is a piece of information that can be collected from a Device, Component, or subcomponent. A DataItem MAY report both a numeric value (a numeric quantity reported as either a Sample or Event category) and a health status (reported as a Condition category). A DataItem specifies the type of data being collected and an array of optional attributes that further defines that data. The value of the data is provided in the Streams response.
The Agent transmits data items associated with each Component to an application. The actual values for those data items are delivered in Streams.
Contents |
DataItem Schema
A DataItem MUST specify the type of data being collected, the id of the DataItem, and the category of the item. Since many data item types provide both a value (reported as either a Sample or Event category) and a health status (reported as a Condition category), each DataItem MUST report a category for each data type to aid the application in determining the specific meaning of the data. The DataItem MAY specify a Source sub-element to identify where the physical connection to the data source originates; ex. data relative to a servo motor may actually originate from a measurement made in the controller.
A DataItem MAY also specify a subtype to further qualify the type of data being provided. Subtypes are required for certain data items. For example, the Position has two subtypes: ACTUAL and COMMANDED. These are two separate DataItem(s) that can be reported independently. See the sections below addressing Sample, Event, and Condition for a complete list of type/subtype relations.
DataItem Attribtes
| Attribute | Description | Occurrence |
|---|---|---|
| id | The unique identifier for this DataItem. The id attribute MUST be unique across the entire document including the ids for components. An XML ID-type. | 1 |
| name | The name of the DataItem. A name is provided as an additional human readable identifier for this DataItem in addition to the id. It is not required and will be implementation dependent. An NMTOKEN XML type. | 0..1 |
| type | The type of data being measured. Examples of types are POSITION, VELOCITY, ANGLE, BLOCK, ROTARY_VELOCITY, etc. | 1 |
| subType | A sub-categorization of the data item type. For example, the subtypes of POSITION are ACTUAL and COMMANDED. Not all types have subtypes and this can be left off. | 0..1 |
| category | This is how the meaning of the data item will be determined. The available options are SAMPLE, EVENT, or CONDITION. | 1 |
| statistic | Data calculated specific to a DataItem. Examples of statistic are AVERAGE, MINIMUM, MAXIMUM, ROOT_MEAN_SQUARE, RANGE, MEDIAN, MODE, AND STANDARD_DEVIATION. | 0..1 |
| representation | Data consisting of multiple data points or samples or a file presented as a single DataItem. Each representation will have a unique format defined for each representation. Examples of representation are VALUE, TIME_SERIES, MP3, WAV, etc. Initially, the representation for TIME_SERIES and VALUE are defined. If a representation is not specified, it MUST be determined to be VALUE. | 0..1 |
| nativeUnits | The native units used by the Component. These units will be converted before they are delivered to the application. | 0..1 |
| units | Units MUST be present for all samples. If the data represented by a DataItem is a numeric value, except for line number and count, the units MUST be specified. | 0..1 |
| nativeScale | The multiplier for the native units. The received data MAY be divided by this value before conversion. If provided, the value MUST be numeric. | 0..1 |
| significantDigits | The number of significant digits in the reported value. This is used by applications to determine accuracy of values. This SHOULD be specified for all numeric values. | 0..1 |
| sampleRate | The rate at which successive samples of a DataItem are recorded. SampleRate 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 | 0..1** |
| coordinateSystem | The coordinate system being used. The available values for coordinateSystem is WORK and MACHINE | 0..1 |
DataItem Attribute: Category
MTConnect® provides three different categories of DataItem - SAMPLE, EVENT, and CONDITION. The category will indicate where the results will be reported in the XML Document as a response to a Sample or Current request.
SAMPLE
- A Sample is the reading of the value of a continuously variable or analog DataItem. A continuous value can be sampled at any point-in-time and will always produce a result. An example of a continuous DataItem is the Linear X axis position.
- A DataItem of the category Sample that are continuous are always scalar floating point or integers that can have an infinite number of possible values. This is different from state or discrete type DataItem that has a limited number of possible values. A DataItem of category Sample MUST have units.
EVENT
- A DataItem of the category Event comprises discrete information from the device. There are two types of Event: those representing state, with two or more discrete values; and those representing messages that contain plain text data. An example of a state type Event is a DoorStatus that can be either OPEN, UNLATCHED, or CLOSED. An example of a message type Event is a PROGRAM that can be any valid string of characters. A DataItem of category Event does not have intermediate values that vary over time, as do Samples. An Event can be thought of as streaming information that if taken at any point in time represents the current state of the device.
CONDITION
- A DataItem that communicates the device’s health and ability to function. A DataItem of category Condition can be one of UNAVAILABLE, NORMAL, WARNING, or FAULT. A DataItem of category Condition MAY report multiple active conditions at one time; whereas a DataItem of category Sample or Event can only have a single value at any one point in time.
DataItem Attribute: coordinateSystem
A DataItem can specify an optional coordinate system that is being used. If not specified, the Axes coordinates MUST be MACHINE and the Path coordinates MUST be WORK. The possible values of coordinates are:
MACHINE
- An unchangeable coordinate system that has machine zero as its origin.
WORK
- The coordinate system that represents the working area for a particular workpiece whose origin is shifted within the MACHINE coordinate system. If the WORK coordinates are not currently defined in the device, the MACHINE coordinates will be used.
DataItem Attribute: units
Units MUST be specified for any DataItem with category Sample. The nativeUnits MAY also be specified if they apply to the type of data and if they differ from the units. The Agent is responsible for converting the nativeUnits to the units before sending them to the applications. In addition, nativeUnits MAY be scaled using the nativeScale attribute; for example, if the device measures velocity in 100 ft/min, MTConnect® would represent it with the following attributes: nativeUnits=“FEET/MINUTE” and nativeScale=“100”.
For a complete list of DataItem Units, click here.
DataItem Attribute: statistic
The statistic attribute indicates that the data has been processed using a statistical operation like average, mean, or root square. statistic may be reported for any Sample type DataItem. These values are calculated values generated by the Component or Device providing additional data regarding a DataItem sampled over a specified period of time. All statistic data is reported in the standard units of the DataItem.
The value of statistic is periodically reset. When statistic values are reported as a Streams value, the value of the statistic MUST include an attribute Duration. Duration defines the time elapsed since the statistic calculation was last reset.
| Statistic | Description |
|---|---|
AVERAGE |
Mathematical Average value calculated for the DataItem during the calculation period |
KURTOSIS |
A measure of the “peakedness” of a probability distribution; i.e., the shape of the distribution curve |
MAXIMUM |
Maximum or peak value recorded for the DataItem during the calculation period |
MEDIAN |
The middle number of a series of numbers |
MINIMUM |
Minimum value recorded for the DataItem during the calculation period |
MODE |
The number in a series of numbers that occurs most often |
RANGE |
Difference between the Maximum and Minimum value of a DataItem during the calculation period. Also represents Peak-to-Peak measurement in a waveform. |
ROOT_MEAN_SQUARE |
Mathematical Root Mean Value (RMS) value calculated for the DataItem during the calculation period |
STANDARD_DEVIATION |
Statistical Standard Deviation value calculated for the DataItem during the calculation period |
DataItem Attribute: representation
The representation attribute defines the format for data consisting of multiple data points or a file presented as a single DataItem. Each representation will have a unique format defined for each representation. At this time, the only representations defined are TIME_SERIES and VALUE.
| Representation | Description |
|---|---|
VALUE |
The measured value of a sample. If no representation is specified for a DataItem, the representation MUST be determined to be VALUE. |
TIME_SERIES |
A series of sampled data. The data is collected for a specified number of samples and each sample is collected with a fixed period |
DataItem Attribute: nativeUnits
The nativeUnits attribute adds additional values to the units values. This is the list of nativeUnits currently supported by MTConnect® and the MTConnect® schema.
| Native Units | Description |
|---|---|
CENTIPOISE |
A measure of Viscosity |
DEGREE/MINUTE |
Rotational velocity in degrees per minute |
FAHRENHEIT |
Temperature in Fahrenheit |
FOOT |
Feet |
FOOT/MINUTE |
Feet per minute |
FOOT/SECOND |
Feet per second |
FOOT/SECOND^2 |
Acceleration in feet per second squared |
FOOT_3D |
A point in space identified by X, Y, and Z positions and represented by a space delimited set of numbers each expressed in feet. |
GALLON/MINUTE |
Gallons per minute. |
INCH |
Inches |
INCH/MINUTE |
Inches per minute |
INCH/SECOND |
Inches per second |
INCH/SECOND^2 |
Acceleration in inches per second squared |
INCH_3D |
A point in space identified by X, Y, and Z positions and represented by a space delimited set of numbers each expressed in inches. |
INCH_POUND |
A measure of torque in inch pounds. |
KILOWATT |
A measurement in kilowatt. |
KILOWATT_HOUR |
Kilowatt hours which is 3.6 mega joules. |
LITER |
Measurement of volume of a fluid |
LITER/MINUTE |
Measurement of rate of flow of a fluid |
MILLIMETER/MINUTE |
Velocity in millimeters per minute |
POUND |
US pounds |
POUND/INCH^2 |
Pressure in pounds per square inch (PSI). |
RADIAN |
Angle in radians |
RADIAN/SECOND |
Velocity in radians per second |
RADIAN/SECOND^2 |
Rotational acceleration in radian per second squared |
RADIAN/MINUTE |
Velocity in radians per minute. |
REVOLUTION/SECOND |
Rotational velocity in revolution per second |
OTHER |
Unsupported units |
DataItem Types
For a list of DataItem types for SAMPLE category, click here.
For a list of DataItem types for EVENT category, click here.
For a list of DataItem types for CONDITION category, click here.
Schema Structure for DataItems
The following document structure defines a typical machine with rotary and linear axes and a controller.
MTConnectDevices
Devices
Device
Components
Axes
Rotary [C]
DataItems
DataItem [Cvel]
Constraints SPINDLE
Linear [X]
DataItems
DataItem [Xpos]
Linear [Y]
DataItems
DataItem [Ypos]
Linear [Z]
DataItems
DataItem [Zpos]
Controller
Path
DataItems
DataItem [mode]
DataItem [execution]The above example shows how the various containers make it easier to address individual parts of the XML document. For example, if one wanted to retrieve only the DataItems for the Controller, you can express this using the following XPath: //Controller/DataItems/*. If you were interested in retrieving only the subcomponets of the Axes component, you would write the following XPath: //Axes/Components/*.
