Streams

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

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
Elements Description Occurrence
DeviceStream The stream of Samples, Events, and Condition for each device. 1..INF


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:

Attributes Description Occurrence
name The device’s name. An NMTOKEN XML type. 1
uuid The device’s unique identifier 1

DeviceStream Elements:

Element Description Occurrence
ComponentStream One component’s stream for each component with data 0..INF

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:

Attribute Description Occurrence
name This component’s name within the device. An NMTOKEN XML type. 1
nativeName The name the device manufacturer assigned to the component. If the native name is not provided it MUST be the name. 0..1
component The XLM element name for the component 1
uuid The component’s unique identifier 0..1
componentId Corresponds to the id attribute of the component in the probe request (Refer to Probe in Part 1). 1

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:

Element Description Occurrence
Events The events for this component stream 0..1
Samples The samples for this component 0..1
Condition The condition of the device. 0..1


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>