# Difference between revisions of "Data Items"

Line 75: | Line 75: | ||

''Units'' MUST be specified for any ''[[Terminology|DataItem]]'' with category ''[[Terminology|Sample]]''. The ''nativeUnits'' MAY also be specified if they apply to the type of data and if they differ from the ''units''. The ''[[Terminology|Agent]]'' is responsible for converting the ''nativeUnits'' to the ''units'' before sending them to the [[Terminology|applications]]. In addition, ''nativeUnits'' MAY be scaled using the ''nativeScale'' [[Terminology|attribute]]; for example, if the [[Terminology|device]] measures velocity in 100 ft/min, MTConnect® would represent it with the following [[Terminology|attributes]]: ''nativeUnits''=“FEET/MINUTE” and ''nativeScale''=“100”. | ''Units'' MUST be specified for any ''[[Terminology|DataItem]]'' with category ''[[Terminology|Sample]]''. The ''nativeUnits'' MAY also be specified if they apply to the type of data and if they differ from the ''units''. The ''[[Terminology|Agent]]'' is responsible for converting the ''nativeUnits'' to the ''units'' before sending them to the [[Terminology|applications]]. In addition, ''nativeUnits'' MAY be scaled using the ''nativeScale'' [[Terminology|attribute]]; for example, if the [[Terminology|device]] measures velocity in 100 ft/min, MTConnect® would represent it with the following [[Terminology|attributes]]: ''nativeUnits''=“FEET/MINUTE” and ''nativeScale''=“100”. | ||

+ | |||

+ | For a complete list of [[Terminology|DataItem]] Units, [[Data Item Units|click here]]. | ||

=== DataItem Attribute: ''statistic'' === | === DataItem Attribute: ''statistic'' === |

## Latest revision as of 16:06, 9 August 2013

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/*.