Difference between revisions of "Streams"

From MTConnect® User's Portal
Jump to: navigation, search
Line 49: Line 49:
 
The sequence numbers are unique across the two [[Terminology|devices]] in the example above.  The [[Terminology|applications]] MUST NOT assume that the [[Terminology|event]] and [[Terminology|sample]] sequence numbers are strictly in sequence.  All sequence numbers MAY NOT be included.  An example of this case would occur when a Path argument is provided and all the ''[[Terminology|Samples]]'', ''[[Terminology|Events]]'', and ''Condition'' are not selected or when the ''[[Terminology|Agent]]'' is supporting more than one [[Terminology|device]] and data from only one [[Terminology|device]] is requested. Refer to the [[Protocol]] section for more information.
 
The sequence numbers are unique across the two [[Terminology|devices]] in the example above.  The [[Terminology|applications]] MUST NOT assume that the [[Terminology|event]] and [[Terminology|sample]] sequence numbers are strictly in sequence.  All sequence numbers MAY NOT be included.  An example of this case would occur when a Path argument is provided and all the ''[[Terminology|Samples]]'', ''[[Terminology|Events]]'', and ''Condition'' are not selected or when the ''[[Terminology|Agent]]'' is supporting more than one [[Terminology|device]] and data from only one [[Terminology|device]] is requested. Refer to the [[Protocol]] section for more information.
  
== DeviceStreams ==
+
== DeviceStream ==
  
 
A ''DeviceStream'' is created to hold the [[Terminology|device]]-specific information so it does not need to be repeated for every [[Terminology|event]] and [[Terminology|sample]].  This is done to reduce the size of each [[Terminology|event]] and [[Terminology|sample]] so they only carry the information that is being reported.  A ''DeviceStream'' MAY contain one or more ''ComponentStream'' elements.  If the request is valid and there are no [[Terminology|events]] or [[Terminology|samples]] that match the criteria, an empty ''DeviceStream'' element MUST be created to indicate that the [[Terminology|device]] exists, but there was no data available.
 
A ''DeviceStream'' is created to hold the [[Terminology|device]]-specific information so it does not need to be repeated for every [[Terminology|event]] and [[Terminology|sample]].  This is done to reduce the size of each [[Terminology|event]] and [[Terminology|sample]] so they only carry the information that is being reported.  A ''DeviceStream'' MAY contain one or more ''ComponentStream'' elements.  If the request is valid and there are no [[Terminology|events]] or [[Terminology|samples]] that match the criteria, an empty ''DeviceStream'' element MUST be created to indicate that the [[Terminology|device]] exists, but there was no data available.
Line 58: Line 58:
  
 
[[File:DeviceStreamElements.PNG|none|500px|thumb|''DeviceStream'' Elements]]
 
[[File:DeviceStreamElements.PNG|none|500px|thumb|''DeviceStream'' Elements]]
 +
 +
== ComponentStream ==
 +
 +
[[File:ComponentStreamSchema.PNG|none|500px|thumb|''ComponentStream'' Schema]]
 +
 +
A ''ComponentStream'' is similar to the ''DeviceStream''.  It contains the information specific to the [[Terminology|component]] within the ''[[Terminology|Device]]''.  The [[Terminology|uuid]] only needs to be specified if the ''[[Terminology|Component]]'' has a [[Terminology|uuid]] assigned.
 +
 +
[[File:ComponentStreamAttributes.PNG|none|500px|thumb|''ComponentStream'' Attributes]]
 +
 +
The [[Terminology|XML]] elements of the ''ComponentStream'' classify the data into ''[[Terminology|Events]]'', ''[[Terminology|Samples]]'', and ''Condition''. The ''ComponentStream'' MUST NOT be empty.  It MUST include an ''[[Terminology|Events]]'' and/or a ''[[Terminology|Samples]]'' [[Terminology|XML]] element.
 +
 +
[[File:ComponentStreamElements.PNG|none|500px|thumb|''ComponentStream'' Elements]]
 +
 +
== Types and Subtypes of Data Items ==
 +
 +
What follows is the association between the various types and subtypes of [[Terminology|data items]].  Each [[Terminology|data item]] type MUST be translated into a ''[[Terminology|Sample]]'', ''[[Terminology|Event]]'', or ''Condition'' with the following rules:
 +
 +
:* The type name will be all in capitals with an underscore (_) between words.
 +
:* The [[Terminology|XML]] element of the [[Terminology|event]] or [[Terminology|sample]] will be the transformation of the [[Terminology|data item]] type by capitalizing the first character of each word and then removing the underscore.  For example, the [[Terminology|data item]] type ''DOOR_STATE'' is ''DoorState'', ''POSITION'' is ''Position'', and  ''ROTARY_VELOCITY'' is ''RotaryVelocity''.
 +
:* The font used for the type name and the [[Terminology|XML]] element MUST be ''Courier New''.
 +
 +
The following example shows the transformation between the ''[[Terminology|DataItem]]'' name as returned in a ''[[Terminology|Probe]]'' request and the corresponding structured data returned in a ''[[Terminology|Stream]]'' [[Terminology|XML]] element returned from a ''[[Terminology|Current]]'' or ''[[Terminology|Sample]]'' request. In the ''[[Terminology|Probe]]'' request, each ''[[Terminology|DataItem]]'' defines its ''[[Terminology|DataItem]]'' type, category, and (if applicable) the ''subType''.
 +
 +
The ''[[Terminology|probe]]'' request will return the response below:
 +
 +
<source lang="xml">
 +
 +
<Path name="path" id="p1">
 +
  <DataItems>
 +
      <DataItem type="PATH_POSITION" category="EVENT" id="p2" subType="ACTUAL" name="Zact"/>
 +
      <DataItem type="CONTROLLER_MODE" category="EVENT" id="p3" name="mode" />
 +
      <DataItem type="PROGRAM" category="EVENT" id="p4" name="program" />
 +
      <DataItem type="EXECUTION" category="EVENT" id="p5" name="execution" />
 +
      <DataItem type="BLOCK" category="EVENT" id="p6" name="block" />
 +
  </DataItems>
 +
</Path>
 +
 +
</source>
 +
 +
The transformation from the ''[[Terminology|Probe]]''to the ''[[Terminology|Current]]'' or ''[[Terminology|Sample]]'' will occur per the example below.  This example also illustrates how the ''subType'' is placed in the ''ComponentStream''.  In the ''[[Terminology|Current]]'' and ''[[Terminology|Sample]]'' request, [[Terminology|data items]] will be returned in the ''ComponentStream'' grouped into their respective categories.  Also note how the ''CONTROLLER_MODE'' was changed to ''ControllerMode'' in the [[Terminology|current]] request below.
 +
 +
<source lang="xml">
 +
 +
<ComponentStream componentId="p1" component="Path"
 +
    name="path">
 +
  <Events>
 +
    <PathPosition dataItemId="p2" timestamp="2009-03-04T19:45:50.458305" subType="ACTUAL" name="Zact" sequence="150651130">7.02</PathPosition>
 +
    <Block dataItemId="p6" timestamp="2009-03-04T19:45:50.458305" name="block" sequence="150651134">x0.371524 y-0.483808</Block>
 +
    <ControllerMode dataItemId="p3" timestamp="2009-02-26T02:02:35.716224" name="mode" sequence="182">AUTOMATIC</ControllerMode>
 +
  </Events>
 +
</ComponentStream>
 +
 +
</source>

Revision as of 14:36, 7 August 2013

The MTConnect Agent collects data from various sources and delivers it to applications in response to Sample or Current requests. (See Protocol for more information) All the data is collected into streams and organized by device and then by component.

Every MTConnect® response MUST contain a header as the first XML element below the root element of any MTConnect® XML Document sent back to an application.

Header Schema Diagram for MTConnectStreams

Contents

Streams Structure

A Streams XML element is the high level container for all device streams. Its function is to contain DeviceStream sub-elements. There MUST be no attributes or other type XML elements within the Streams element.

Streams Schema Diagram
StreamsElements2.PNG

Streams MUST have at least one DeviceStream and the DeviceStream MAY have one or more ComponentStream elements, depending on whether there are events or samples available for the component. If there are no ComponentStream elements, then no data will be delivered for this request.

The following diagram illustrates the structure of the Streams with some Samples, Events, and Condition at the lowest level:

Streams Example Structure

Below is an example XML Document response for an Agent with two devices, mill-1 and mill-2. The data is reported in two separate device streams.

<MTConnectStreams>
  <Header/>
  <Streams>
    <DeviceStream name="mill-1" uuid="1">
      <ComponentStream component="Device" name="mill-1" componentId="d1">
        <Events>
          <Availability dataItemId="avail1" name=="avail" sequence="5" 
              timestamp="2010-04-06T06:19:35.153141">AVAILABLE</Availability>
        </Events>
      </ComponentStream>
    </DeviceStream>
    <DeviceStream name="mill-2" uuid="2">
      <ComponentStream component="Device" name="mill-2" componentId="d2">
        <Events>
          <Availability dataItemId="avail2" name="avail" sequence="15" 
              timestamp="2010-04-06T06:19:35.153141">AVAILABLE</Availability>
        </Events>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The sequence numbers are unique across the two devices in the example above. The applications MUST NOT assume that the event and sample sequence numbers are strictly in sequence. All sequence numbers MAY NOT be included. An example of this case would occur when a Path argument is provided and all the Samples, Events, and Condition are not selected or when the Agent is supporting more than one device and data from only one device is requested. Refer to the Protocol section for more information.

DeviceStream

A DeviceStream is created to hold the device-specific information so it does not need to be repeated for every event and sample. This is done to reduce the size of each event and sample so they only carry the information that is being reported. A DeviceStream MAY contain one or more ComponentStream elements. If the request is valid and there are no events or samples that match the criteria, an empty DeviceStream element MUST be created to indicate that the device exists, but there was no data available.

DeviceStream Schema
DeviceStream Attributes
DeviceStream Elements

ComponentStream

ComponentStream Schema

A ComponentStream is similar to the DeviceStream. It contains the information specific to the component within the Device. The uuid only needs to be specified if the Component has a uuid assigned.

ComponentStream Attributes

The XML elements of the ComponentStream classify the data into Events, Samples, and Condition. The ComponentStream MUST NOT be empty. It MUST include an Events and/or a Samples XML element.

ComponentStream Elements

Types and Subtypes of Data Items

What follows is the association between the various types and subtypes of data items. Each data item type MUST be translated into a Sample, Event, or Condition with the following rules:

  • The type name will be all in capitals with an underscore (_) between words.
  • The XML element of the event or sample will be the transformation of the data item type by capitalizing the first character of each word and then removing the underscore. For example, the data item type DOOR_STATE is DoorState, POSITION is Position, and ROTARY_VELOCITY is RotaryVelocity.
  • The font used for the type name and the XML element MUST be Courier New.

The following example shows the transformation between the DataItem name as returned in a Probe request and the corresponding structured data returned in a Stream XML element returned from a Current or Sample request. In the Probe request, each DataItem defines its DataItem type, category, and (if applicable) the subType.

The probe request will return the response below:

<Path name="path" id="p1">
   <DataItems>
      <DataItem type="PATH_POSITION" category="EVENT" id="p2" subType="ACTUAL" name="Zact"/> 
      <DataItem type="CONTROLLER_MODE" category="EVENT" id="p3" name="mode" /> 
      <DataItem type="PROGRAM" category="EVENT" id="p4" name="program" /> 
      <DataItem type="EXECUTION" category="EVENT" id="p5" name="execution" /> 
      <DataItem type="BLOCK" category="EVENT" id="p6" name="block" /> 
   </DataItems>
</Path>

The transformation from the Probeto the Current or Sample will occur per the example below. This example also illustrates how the subType is placed in the ComponentStream. In the Current and Sample request, data items will be returned in the ComponentStream grouped into their respective categories. Also note how the CONTROLLER_MODE was changed to ControllerMode in the current request below.

<ComponentStream componentId="p1" component="Path" 
    name="path">
  <Events>
     <PathPosition dataItemId="p2" timestamp="2009-03-04T19:45:50.458305" subType="ACTUAL" name="Zact" sequence="150651130">7.02</PathPosition> 
     <Block dataItemId="p6" timestamp="2009-03-04T19:45:50.458305" name="block" sequence="150651134">x0.371524 y-0.483808</Block>
     <ControllerMode dataItemId="p3" timestamp="2009-02-26T02:02:35.716224" name="mode" sequence="182">AUTOMATIC</ControllerMode>
  </Events>
</ComponentStream>