Machine Data

We collect many different data points from all connected machines. We call the stream of observations about a specific state or property of a machine a "metric". A single observation is called an event. In other words: each event represents an observation of a value at a certain point in time, the eventTime. The value can either be a scalar (numeric, string) or expressed as a set of attributes (e.g., x, y, and z). There are different categories of data which we describe in the following chapter.

Each machine has an identifier machineRef which is an integer that is unique across all machines within MachineMetrics. Every metric that is captured from a machine has a metricKey that is unique within the context of the entire machine's metric space. In other words: each metric is globally identified by the combination of machineRef and metricKey. Metrics are of a specific type and sometimes an additional subtype. These Types and Subtypes (see table below for reference) are common across all equipment. However, many metrics can be available on some pieces of equipment while absent on others. Additional context can be used to related metrics to each other using a Component Type and Component Name.

Data Categories

Events are stored in different places depending on their data category. The data category of a metric is determined by its type and subtype. The following table summarizes the categorization.

Data Category	Type	Subtype	GraphQL Objects
QUANTITY	one of Sample RotaryVelocity Feedrate ProgramProgress AccumulatedTime Override Flow Pressure Humidity Amplitude EquipmentTimer	not PATH_POSITION	aggregatedQuantities latestQuantitiesByMachine
POSITION	Sample	PATH_POSITION	positions latestPositionsByMachine
STATE	one of Execution Info Program ProgramComment SpindleRotating Cutting ControllerMode OutputSignal EmergencyStop EquipmentMode HEARTBEAT	any	stateIntervals currentStatesByMachine
ALARM	Condition	any	alarmIntervals currentAlarmsByMachine
COUNT	PartCount	any	partCounts aggregatedpPartCounts

The events of metrics with the types ScrapCount and NonconformCount are not available through the GraphQL API.

Quantities

Quantities are commanded or sampled physical properties of a machine.

Examples

{
  "machineRef": 1234,
  "metricKey": "path_feedrate",
  "eventTime": "2021-04-28T21:04:23.87+00:00",
  "value": 12.225
}

Characteristics

• These metrics usually express physical quantities.
• The number of possible values is generally unbounded (but might be limited by technical properties, eg. number precision).
• The values themselves can be bounded (eg. non-negative).
• The value between observations is generally unknown but sometimes follow the laws of physics and can be interpolated (eg. temperature)
• The usability of the data is dependent on the frequency of the observations (higher frequency for Anomaly detection).
• Path Positions are a special subset of quantities as they have three numeric values: x, y, and z.

Data Access

Quantities can be queried using aggregates: aggregatedQuantities or latestQuantitiesByMachine .

States

Example

Execution State:

{
  "machineRef": 1234,
  "metricKey": "execution",
  "eventTime": "2021-04-28T21:06:14.021+00:00",
  "value": "ACTIVE"
}

Characteristics

• Only state changes are relevant. But the data can contain records of unchanged states.
• Observations carry forward (the machine is in the state that was last reported).
• Observations with the same value than the previous one can be dismissed.
• Multiple different states can be reported on the same timestamp. The order of those states is important.
• Metrics have a limited number of distinct values (enumerations).
• State data is categorical (https://en.wikipedia.org/wiki/Categorical_variable)
• State changes might be restricted by rules (a “state machine” in the computer science sense).
• The state change might be triggered by an event having a new state or by an explicit state change. Some states are cleared by a “NORMAL” value on the specific native_code or on an empty native_code (for all).

Heartbeats are a special subset of states and have the following, additional characteristics:

• They are expected to be observed in regular, predefined intervals.
• A missing observation of a heartbeat has a specific meaning (eg. UNAVAILABLE)

Execution State

The machine's execution state state is driven by metrics typed as Execution. Metrics with this Type can have a value representing one of the following states:

• ACTIVE
• FEED_HOLD
• INTERRUPTED
• OPTIONAL_STOP
• PROGRAM_STOPPED
• PROGRAM_OPTIONAL_STOP
• STOPPED
• PROGRAM_COMPLETED
• UNAVAILABLE
• READY

The order above is relevant. Here's why.

Many machines come with multiple execution paths which often translates to multiple metrics independently reporting their state. MachineMetrics produces an artificial metric to reflect the entire machine's status with a key of MasterExecution. This machine-wide execution status is generated by taking the state across all metrics with an Execution Type that is highest in the above list of states.

For example, if the machine has two metrics (execution, and execution2) representing the status of each of the two paths on the machine with execution reporting a state of ACTIVE and execution2 reporting a state of FEED_HOLD. MasterExecution will be reported as ACTIVE. If execution is reporting STOPPED and execution2 is reporting FEED_HOLD, MasterExecution will be reported as FEED_HOLD.

For most use cases, you can consider this data to represent 3 states: ACTIVE, INACTIVE (or IDLE), and UNAVAILABLE.

Machine Alarms (Conditions)

Example

Machine Condition:

{
  "machineRef": 1234,
  "metricKey": "system",
  "eventTime": "2021-04-28T21:05:43.931+00:00",
  "label": "WARNING",
  "nativeCode": "EX1021",
  "description": "AUTOMATIC BAR FEEDER NOT READY"
}

Characteristics

Machine conditions are captured as metrics with a type of Condition with a variety of Subtypes shown below:

• POSITION
• TEMPERATURE
• LOAD
• ACTUATOR
• ANGLE
• PRESSURE
• LEVEL
• COMMUNICATIONS
• HARDWARE
• SYSTEM
• MOTION_PROGRAM
• LOGIC_PROGRAM

More importantly, each Condition metric can track any number of distinct Native Codes (or Alarm Codes). These Native Codes are unique to the Make/Model/Family of equipment they are retrieved from. Further, MachineMetrics Adapter Scripts can be used to augment machine data to produce custom "Alarms" for a variety of use cases like historical reporting of Feed Rate Overrides exceeding certain thresholds, to notifying other systems via Webhooks of other condition-based metrics diverging from specified standards.

Any number of distinct Native Codes can be in one of three states on a Condition metrics:

• FAULT
• WARNING
• UNAVAILABLE
• NORMAL

In addition to the Native Code, Condition metrics can (but are not required to) report a severity, message (or label), and qualifier.

Infos

Characteristics

• The value is a string.
• The number of possible of values can vary from a single one (manufacturer) to unbounded (G-Code).
• State changes can be restricted by domain level rules (monotonically increasing firmware version).
• Some info metrics can be interepreted as streams of state changes and thus translated into intervals with a defined start and end time.

Counts

Counts share the following characteristics:

• The value is usually an integer.
• Values can be absolute or differential (change to previous absolute value).
• Values generally grow monotonically (but can be reset periodically).

The machine's part count is driven by metrics typed as PartCount. Machines have multiple counters with different purposes which are distinguished by the following Subtypes:

• TOTAL
• ALL
• GOOD
• BAD
• TARGET
• REMAINING

Machines report the value of their part counters which, in the case of all but REMAINING, increase as parts are made:

2020-11-12T12:05|part_count|4
2020-11-12T12:07|part_count|5
2020-11-12T12:09|part_count|6
2020-11-12T12:11|part_count|7
2020-11-12T12:13|part_count|8

MachineMetrics continuously calculates the delta change of each PartCount metric. By default, all PartCount metrics with a Subtype of ALL contribute to the parts MachineMetrics recognizes. If there is a specific PartCount metric, it can be configured as the explicit counter metric for the machine. Due to the fact that there may be use cases that can take advantage of the other counters, they are all available through our various APIs and export mechanisms; however, the value returned from these systems will be the delta and not the original counter value.

General Notes

The Meaning of UNAVAILABLE

In cases where MachineMetrics is not able to retrieve data from the equipment, the value for every metric will be reported as UNAVAILABLE. There are some exceptions to this depending on what mechanisms you are using to retrieve data; however, that is how the data is ingested into our system. One example of an exception to this relates to how the data is exposed via GraphQL. GraphQL is backed by a time-series database where the information is organized in appropriately typed tables based on the value space of the metric. Because of this, metrics representing numerical values (quantities) will have gaps in data where data is UNAVAILABLE.

Sampling Rate

Data is typically sampled from equipment at a rate of 1Hz. Only changes are reported. However, values are refreshed every few minutes to ensure accuracy so repeated values are normal. Because of this behavior, depending on your use case, different interpolation techniques may be necessary.

Carry-forward interpolation is usually sufficient for State metrics like Execution.

Linear or polynomial interpolation might be visually appealing for a timeline when displaying temperature data, but for truly accurate LOAD data (for example), data sampled at a much higher frequency (1KHz) might be necessary. Contact support@machinemetrics.com if your use case has these requirements.

Types and Subtypes

A large portion of the capabilities within MachineMetrics are driven by the Types and Subtypes mentioned above, but there are many more that can be used to classify metrics for more unique use cases. This table is a comprehensive list of all Types and Subtypes currently supported. If you have equipment and use case that requires something that is not listed, please contact support@machinemetrics.com.

Type	Subtype	Values
PartCount	TOTAL, ALL, GOOD, BAD, TARGET, REMAINING	Counter
ScrapCount		Counter
NonconformCount		Counter
Execution		ACTIVE, FEED_HOLD, INTERRUPTED, OPTIONAL_STOP, PROGRAM_STOPPED, PROGRAM_OPTIONAL_STOP, STOPPED, PROGRAM_COMPLETED, UNAVAILABLE, READY
SpindleRotating		ON, UNAVAILABLE, OFF
Cutting		ON, UNAVAILABLE, OFF
EmergencyStop		ARMED, UNAVAILABLE, TRIGGERED
ControllerMode		MANUAL, MANUAL_DATA_INPUT, SEMI_AUTOMATIC, EDIT, UNAVAILABLE, AUTOMATIC
AccumulatedTime	TOTAL_OPERATING_TIME, TOTAL_RUNNING_TIME, TOTAL_CUTTING_TIME, TOTAL_SPINDLE_RUN_TIME, OPERATING_TIME, RUNNING_TIME, CUTTING_TIME, SPINDLE_RUN_TIME	String
ProgramProgress		Scalar
Feedrate	ACTUAL, COMMANDED, JOG, PROGRAMMED, RAPID	Scalar
RotaryVelocity	ACTUAL, COMMANDED, PROGRAMMED	Scalar
Program	PROGRAM, SUBPROGRAM, MAIN_NAME, SUB_NAME	String
ProgramComment	PROGRAM, SUBPROGRAM	String
Variables	COMMON	String
Register		Scalar
MacMan	PANEL_HISTORY	String
OutputSignal	DRY_RUN, MACHINE_LOCK	String
Amplitude	ACTUAL, TARGET	Scalar
Flow	ACTUAL, TARGET	Scalar
Pressure	ACTUAL, TARGET, TARGET_LOW, TARGET_HIGH	Scalar
EquipmentTimer	LOADED, WORKING, OPERATING, POWERED, DELAY	Scalar
EquipmentMode	LOADED, WORKING, OPERATING, POWERED, DELAY	ON, OFF
Humidity	ABSOLUTE, RELATIVE, SPECIFIC	Scalar
CutSize	LENGTH, RADIAL	Scalar
Condition	POSITION, TEMPERATURE, LOAD, ACTUATOR, ANGLE, PRESSURE, LEVEL, COMMUNICATIONS, HARDWARE, SYSTEM, MOTION_PROGRAM, LOGIC_PROGRAM	FAULT, WARNING, UNAVAILABLE, NORMAL
Sample	ACCELERATION, ANGULAR_ACCELERATION, ANGULAR_VELOCITY, AMPERAGE, ANGLE, AXIS_FEEDRATE, CLOCK_TIME, CONCENTRATION, CONDUCTIVITY, DISPLACEMENT, ELECTRICAL_ENERGY, FILL_LEVEL, FLOW, FREQUENCY, LENGTH, LINEAR_FORCE, LOAD, MASS, PATH_FEEDRATE, PATH_POSITION, PH, POSITION, POWER_FACTOR, PRESSURE, RESISTANCE, ROTARY_VELOCITY, SOUND_LEVEL, STRAIN, SURFACE_SPEED, TEMPERATURE, TILT, TOOL_LENGTH, TOOL_RADIUS, TORQUE, VOLT_AMPERE, VOLT_AMPERE_REACTIVE, VELOCITY, VISCOSITY, VOLTAGE, WATTAGE, MM_CURRENT_TRANSDUCER, MM_SENSOR_1, MM_SENSOR_2, MM_SENSOR_3, MM_AMPLITUDE	Scalar
Override	RotaryVelocity, Feed, Rapid, Jog	Scalar
Info	ACTUATOR_STATE, ACTIVE_AXES, AVAILABILITY, AXIS_COUPLING, AXIS_INTERLOCK, AXIS_STATE, BLOCK, CHUCK_INTERLOCK, CHUCK_STATE, CONTROLLER_MODE, COUPLED_AXES, DIRECTION, DOOR_STATE, END_OF_BAR, FIRMWARE_VERSION, FUNCTIONAL_MODE, INTERFACE_STATE, LINE, MATERIAL, MANUFACTURER, MESSAGE, MODEL, OPERATOR_ID, PALLET_ID, PART_ID, PART_NUMBER, PATH_MODE, POWER_STATE, PROGRAM, PROGRAM_EDIT, PROGRAM_EDIT_NAME, PROGRAM_COMMENT, PROGRAM_HEADER, ROTARY_MODE, SERIAL_NUMBER, SPINDLE_INTERLOCK, SPINDLE_MODE, TOOL_ASSET_ID, TOOL_NUMBER, VERSION_NUMBER, WORKHOLDING_ID, MS_BLOCK_DELETE, MS_COOLANT, MS_DRY_RUN, MS_OPERATION_MODE, MS_OPTIONAL_STOP, MS_RESET, MS_SINGLE_BLOCK, MAZAK_TOOL_GROUP, MAZAK_TOOL_SUFFIX, MAZAK_SEQUENCE_NUMBER, MAZAK_UNIT_NUMBER, BRE_WORKPIECE, BRE_NUMBER_ACTIVE_AXES, BRE_LOADED_PROGRAM_NAME, BRE_INT_COOLANT, BRE_EXT_COOLANT, MM_SYSTEM_TYPE, MM_ADAPTER_INFO, MM_DEVICE_ADDRESS, MM_MACHINE_NAME, MM_MACHINE_STATUS, MM_MESSAGE_EVENT, MM_DOWNTIME_CODE, MM_CYCLE_RATE, MM_WORK_COUNTER_CODES, MM_SCAN_INTERVAL, MM_INTERLOCK, MM_TOOL_CUTS, MM_OPERATION_COUNT, BUL_CHUCK_SELECT, BUL_CUT_AREA, BUL_CALIBRATION_INTERLOCK, BUL_OPERATOR_INTERLOCK, BUL_REWORK_COUNT, BUL_OPERATION_MODE, BUL_CUTTING_MODE, BUL_SUPERVISOR_OVERRIDE, BUL_CYCLE_START,	String