PPMP Specification

Rationale

Noticeably in recent years, there is a continuous increase in demand, price pressure and complexity in manufacturing. Things need to move faster, be more flexible, and fulfill higher quality standards forcing manufacturers to optimize their processes.

Production facilities and their performance have a huge impact on the overall performance of manufacturing processes. However, to identify bottlenecks and possibilities for improvements detailed data from machines are required.

Such data is surely provided by machines either via modern protocols such as OPC UA or via proprietary access methods but it is not provided in a common and easily accessible format, which can be used to do performance analysis and optimization. This renders holistic process improvement efforts infeasible for many, especially smaller organizations.

The Production Performance Management Protocol (PPMP) specifies a format that allows to capture data that is required to do performance analysis of production facilities. It allows monitoring backends to collect and evaluate key metrics of machines in the context of a production process. It is doing that by allowing to relate the machine status with currently produced parts.

The specification is structured into three payload formats: Measurement payload, message payload and process payload. The Measurement payload contains measurements from machines such as the temperature of a machine at a specific point in time together with the currently produced part. The message payload contains arbitrary messages sent by a machine, e.g. alerts or the like. A process message consists of information about a discrete e.g. tightening or welding processes with all their characterising data which are need to describe and analyze it.

The payload is meant to be transported via http as a json object. This allows for an easy integration into various backend systems.

Communicating Parties

Two parties are involved in a PPMP message exchange: the sender and the receiver. The sender pushes a message to the receiver. Usually the sender is a machine or a sensor of a machine.

The receiver waits for messages. It offers a API that allows for sending either measurement payloads or message payloads.

The communication is unidirectional. Only the sender can contact the receiver and send messages. No feedback from receiver to sender is provided.

Overview PPMP

Measurement Payload

The measurement message is the format to exchange simple (non-structured, non-complex ) measurement data. It also allows to transport multiple measurement data (eg. values over time), called 'series'.

Class diagram of the measurement payload
{
"content-spec": "urn:spec://eclipse.org/unide/measurement-message#v2",
"device": {
"deviceID": "a4927dad-58d4-4580-b460-79cefd56775b"
},
"measurements": [{
"ts": "2002-05-30T09:30:10.123+02:00",
"series": {
"$_time": [ 0, 23, 24 ],
"temperature": [ 45.4231, 46.4222, 44.2432]
}
}, {
"ts": "2002-05-30T09:30:10.123+02:00",
"series": {
"$_time": [ 0, 13, 26 ],
"pressure": [ 52.4, 46.32, 44.2432 ]
}
}]
}

Machine Message Payload

The main purpose of the machine message format is to allow devices and integrators to send messages containing an interpretation of measurement data or status.

Class diagram of the message payload
{
"content-spec":"urn:spec://eclipse.org/unide/machine-message#v2",
"device": {
"deviceID": "2ca5158b-8350-4592-bff9-755194497d4e"
},
"messages": [{
"ts": "2002-05-30T09:30:10.123+02:00",
"code": "190ABT"
}]
}
{
"content-spec":"urn:spec://eclipse.org/unide/machine-message#v2",
"device": {
"deviceID": "2ca5158b-8350-4592-bff9-755194497d4e",
"operationalStatus": "normal",
"metaData":{
"swVersion": "2.0.3.13",
"swBuildID": "41535"
}
},
"messages": [{
"origin": "sensor-id-992.2393.22",
"ts": "2002-05-30T09:30:10.123+02:00",
"type": "DEVICE",
"severity": "HIGH",
"code": "190ABT",
"title": "control board damaged",
"description": "Electronic control board or its electrical connections are damaged",
"hint": "Check the control board",
"metaData": {
"firmware": "20130304_22.020"
}
}, {
"ts": "2002-05-30T09:30:10.125+02:00",
"type": "TECHNICAL_INFO",
"severity": "HIGH",
"code": "33-02",
"title": "Disk size limit reached",
"description": "Disk size has reached limit. Unable to write log files."
}]
}

Process Payload

The process message is the format to exchange data out of discrete processes. It also allows to transport process information, part information and measurement data for each phase of the process.

Class diagram of the process data payload
{
"content-spec": "urn:spec://eclipse.org/unide/process-message#v2",
"device": {
"deviceID": "a4927dad-58d4-4580-b460-79cefd56775b"
},
"process": {
"ts": "2002-05-30T09:30:10.123+02:00"
},
"measurements": [
{
"ts": "2002-05-30T09:30:10.123+02:00",
"series": {
"force": [26, 23, 24],
"pressure": [52.4, 46.32, 44.2432]
}
}
]
}
{
"content-spec": "urn:spec://eclipse.org/unide/process-message#v2",
"device": {
"deviceID": "a4927dad-58d4-4580-b460-79cefd56775b",
"operationalStatus": "normal",
"metaData": {
"swVersion": "2.0.3.13",
"swBuildId": "41535"
}
},
"part": {
"type": "SINGLE",
"partTypeID": "F00VH07328",
"partID": "420003844",
"result": "NOK",
"code": "HUH289",
"metaData": {
"toolId": "32324-432143"
}
},
"process": {
"externalProcessId": "b4927dad-58d4-4580-b460-79cefd56775b",
"ts": "2002-05-30T09:30:10.123+02:00",
"result": "NOK",
"shutoffPhase": "phase 1",
"program": {
"id": "1",
"name": "Programm 1",
"lastChangedDate": "2002-05-30T09:30:10.123+02:00"
},
"shutoffValues": {
"force": {
"ts": "2002-05-30T09:30:11.123+02:00",
"value": 24,
"upperError": 26,
"lowerError": 22
},
"pressure": {
"value": 50,
"upperError": 52,
"lowerError": 48
}
},
"metaData": {
"name": "Tightening"
}
},
"measurements": [
{
"ts": "2002-05-30T09:30:10.123+02:00",
"phase": "phasen name",
"result": "OK",
"code": "0000 EE01",
"limits": {
"pressure": {
"upperError": 4444,
"lowerError": 44,
"upperWarn": 2222,
"lowerWarn": 46,
"target": 35
},
"force": {
"upperError": [27, 24, 25],
"lowerError": [25, 22, 23]
}
},
"specialValues": {
"pressure": {
"value": 24
},
"force": {
"time": 24,
"value": 50
}
},
"series": {
"time": [30, 36, 42],
"force": [26, 23, 24],
"pressure": [52.4, 46.32, 44.2432],
"temperature": [45.4243, 46.42342, 44.2432]
}
}
]
}

Fields definition

content-spec
Definition: Defines the format version
Possible values:
  • "urn:spec://eclipse.org/unide/machine-message#v2"
  • "urn:spec://eclipse.org/unide/measurement-message#v2"
  • "urn:spec://eclipse.org/unide/process-message#v2"
Required: no
Size restriction: no
Note: enum indicating the type of this payload.
Example:
...
"content-spec": "urn:spec://eclipse.org/unide/measurement-message#v2"
...

device
Definition: Contains information about the device
Required: yes
Size restriction: no
Note:
Sub Fields:
Example:
...
"device": {
"deviceID": "0815"
}
...

deviceID
Definition: The unique ID of the device. As this is used to identify a device independently from time or location. The ID itself must be stable and unique. The recommendation is to use a universally unique identifier (UUID).
Required: true
Size restriction: 36
Note: reprentation could follow GIAI, UUID or others
Example:
...
"deviceID": "6e7807d0-5491-11e6-9d32-02423234b390"
...

operationalStatus
Definition: The operationalStatus describes the status of a device. It is a string matching a definition in the respective backend application.
Required: no
Size restriction: no
Note:
Example:
...
"operationStatus": "MM" //Maintenance Mode
...

metaData
Definition: Additional key-value pairs in a JSON structure format. Key and value must be strings.
Required: no
Size restriction: no
Note: subfields can be any key/string value pair
Example:
...
"metaData": {
"swVersion": "2.0.3.13", //software (firmware) version
"swBuildID": "41535" //software (firmware) build identifier/number
}
...

part
Definition: Contains information regarding the part which this payload relates to
Required: no
Size restriction: no
Note:
Sub Fields:
Example:
...
"part": {
"partTypeID": "F00VH07328",
"partID": "420003844",
"result": "OK",
"code": "HUH289",
"metaData": {
"lotID": "845849",
"toolID": "32324-432143"
}
}
...

partTypeID
Definition: Identifies the type of the part
Required: no
Size restriction: no
Note:
Example:
...
"partTypeID": "F00VH07328"
...

partID
Definition: Identifies a part. This ID comes from a 3rd party system and thus we have no guarantees if this is unique or not.
Required: no
Size restriction: 256
Note:
Example:
...
"partID": "420003844"
...

result
Definition: Information if the quality of the produced part was ok or not
Possible values:
  • "UNKNOWN"
  • "OK"
  • "NOK"
Required: no
Size restriction: no
Note: Default value is "UNKNOWN"
Example:
...
"result": "OK"
...

type
Definition: Describes the type of the part. Type SINGLE means a single item is processed. Type BATCH means multiple items of the same type are processed. Default value is SINGLE
Possible values:
  • "SINGLE"
  • "BATCH"
Required: no
Size restriction: no
Note:
Example:
...
"type": "SINGLE"
...

code
Definition: The code is an addendum to the result which allows to pass information in the case the result was NOK.
Required: no
Size restriction: 36
Note: The value often stems from the integrated system e.g. a PLC code
Example:
...
"code": "HUH289"
...

measurements
Definition: A list of sensor readings
Required: yes
Size restriction: no
Note: if sensor readings have the same timestamp/-offsets, they can be combined in one measurement block. Otherwise they are added to the measurements list as individual block.
Sub Fields:
Example:
...
"measurements": [{
"ts": "2002-05-30T09:30:10.123+02:00",
"series": {
"$_time": [ 0, 23, 24 ],
"temperature": [ 45.4231, 46.4222, 44.2432]
}
}]
...

ts
Definition: Start time of the the data measurment in ISO 8601 format
Required: yes
Size restriction: no
Note: http://www.w3.org/TR/NOTE-datetime
Example:
...
"ts": "2002-05-30T09:30:10.123+02:00"
...

limits
Definition: Provides information about limits for data provided in the series element. The limits is an JSON object where the key is the name of a Measurement Point (see also series element) and the value is a structure of different upper/lower limits.
Required: no
Size restriction: no
Note: each subfield key corresponds to one measurement point and holds an object with the error/warning levels.
Sub Fields:
Example:
...
"limits": {
"temperature": {
"upperError": 4444,
"lowerError": 44,
"upperWarn": 2222,
"lowerWarn": 46
}
}
...

upperError
Definition: Indicates the upper error threshold, given by the device/integrator
Required: no
Size restriction: no
Note:
Example:
...
"upperError": 4444
...

lowerError
Definition: Indicates the lower error threshold, given by the device/integrator
Required: no
Size restriction: no
Note:
Example:
...
"lowerError": 44
...

upperWarn
Definition: Indicates the upper warning threshold, given by the device/integrator
Required: no
Size restriction: no
Note:
Example:
...
"upperWarn": 2222
...

lowerWarn
Definition: Indicates the lower warning threshold, given by the device/integrator
Required: no
Size restriction: no
Note:
Example:
...
"lowerWarn": 46
...

series
Definition: The series data collected for the measurements. Every subfield key matches a measurement point of the device type. Every subfield value is an array. All arrays are of equal length and an entry at a given index corresponds to another arrays value at this index
Required: yes
Size restriction: no
Note: In the case of a time series, one column contains the time offset (positive values in ascending order starting with 0). In this case the key is $_time`.
Sub Fields:
Example:
...
"ts": "2015-07-23T16:04:10.223+02:00",
"series": {
"$_time": [0, 22, 24, 27],
"temperature": [33, 34, 33, 32],
"pressure": [1, 1.001. 2.52. 3.2]
}
...

$_time
Definition: An array of time offsets in miliseconds from the ts field of this series
Required: yes
Size restriction: no
Note: the offsets are of unsigned long integer values
Example:
...
"$_time": [0, 22, 24, 27]
...

messages
Definition: A list of machine messages
Required: yes
Size restriction: no
Note:
Sub Fields:
Example:
...
"messages": [{
"ts": "2002-05-30T09:30:10.123+02:00",
"code": "190ABT"
}]
...

origin
Definition: The origin of the message if not the device identified by deviceID in the header element.
Required: Could be used to identify a subsystem or a particular sensor/part of the device where the
message actually relates to.
Size restriction: no
Note:
Example:
...
"origin": "sensor-id-992.2393.22"
...

type
Definition: The type of message. Default is DEVICE but can be set to TECHNICAL_INFO indicating a problem with the integration of the actual device.
Possible values:
  • "DEVICE"
  • "TECHNICAL_INFO"
Required: no
Size restriction: no
Note:
Example:
...
"type": "DEVICE"
...

severity
Definition: Severity of the message.
Possible values:
  • "HIGH"
  • "MEDIUM"
  • "LOW"
  • "UNKNOWN"
Required: no
Size restriction: no
Note: Default is "UNKNOWN"
Example:
...
"severity": "HIGH"
...

code
Definition: Code identifying the problem described in the message.
Required: yes
Size restriction: 36
Note: The value often stems from the machine e.g. a PLC code. Is similar to code in measurement interface.
Example:
...
"code": "190ABT"
...

title
Definition: The title of the message
Required: no
Size restriction: 1000
Note:
Example:
...
"title": "control board damaged"
...

description
Definition: The description is used to describe the purpose of the message, e.g. the problem
Required: no
Size restriction: 2000
Note:
Example:
...
"description": "Electronic control board or its electrical connections are damaged"
...

hint
Definition: In case a problem is reported, the hint can be used to point out a possible solution.
Required: no
Size restriction: 2000
Note:
Example:
...
"hint": "Check the control board"
...

type
Definition: Describes the type of the part.
Possible values:
  • "SINGLE"
  • "BATCH"
Required: no
Size restriction: no
Note: Type SINGLE means a single item is processed. Type BATCH means multiple items of the same type are processed. Default value is SINGLE
Example:
...
"type": "SINGLE"
...

process
Definition: Contains information about the process
Required: no
Size restriction: no
Note:
Sub Fields:
Example:
...
"process": {
"externalProcessId": "b4927dad-58d4-4580-b460-79cefd56775b",
"ts": "2002-05-30T09:30:10.123+02:00",
"result": "NOK",
"shutoffPhase": "phase 1",
"program": {
"id": "1",
"name": "Program 1",
"lastChangedDate": "2002-05-30T09:30:10.123+02:00"
},
"shutoffValues": {
"force": {
"ts": "2002-05-30T09:30:11.123+02:00",
"value": 24,
"upperError": 26,
"lowerError": 22
},
"pressure": {
"value": 50,
"upperError": 52,
"lowerError": 48
}
},
"metaData": {
"name": "Tightening"
}
}
...

externalProcessId
Definition: The process Id identifies the process as part of long living process Format: alphanumeric string dash as special character
Required: no
Size restriction: 36
Note: The process Id can be used to connect multiple processes in a manufacturing chain. The Id has to be set and tracked by the different devices in the chain.
Example:
...
"externalProcessId": "b4927dad-58d4-4580-b460-79cefd56775b"
...

ts
Definition: Start time of the process
Required: no
Size restriction: no
Note: Format: ISO 8601 format
Example:
...
"ts": "2002-05-30T09:30:11.123+02:00"
...

result
Definition: Result of the whole process
Possible values:
  • "UNKNOWN"
  • "OK"
  • "NOK"
Required: no
Size restriction: no
Note: Default value is "UNKNOWN"
Example:
...
"result": "OK"
...

shutoffPhase
Definition: The ID of the phase that led to stop the process. The shutOffPhase is the phase of the process in which either pre-defined parameters are met to successfully finish the process or an error that stopped the process. That is not necessarily the last phase.
Required: no
Size restriction: no
Note: The phase which should be sent with last process phase in measurements.
Example:
...
"shutoffPhase": "phase 1"
...

program
Definition: Contains information about the program that was used in the process
Required: no
Size restriction: no
Note:
Sub Fields:
Example:
...
"program": {
"id": "1",
"name": "Program 1",
"lastChangedDate": "2002-05-30T09:30:10.123+02:00"
}
...

id
Definition: The ID of the program Format: alphanumeric string (dash allowed e.g. UUID)
Required: no
Size restriction: 36
Note: The ID of the program for unique identification
Example:
...
"id": "b4927dad-58d4-4580-b460-79cefd56775b"
...

name
Definition: The name of the program Format: alphanumeric string (dash allowed e.g. UUID)
Required: yes
Size restriction: 256
Note: The name of the program if existing
Example:
...
"name": "welding_1"
...

lastChangedDate
Definition: The date when the program was last changed
Required: no
Size restriction: no
Note: Format: ISO 8601 format
Example:
...
"ts": "2002-05-30T09:30:11.123+02:00"
...

shutoffValues
Definition: The shutoff values contain the values of the process that stopped the process.
Required: no
Size restriction: no
Note: The shutoffValues is a JSON object where the key is the name of a Measurement Point (see also series element) and the value is a structure of different upper/lower limits and the actual value as described.
Sub Fields:
Example:
...
"shutoffValues": {
"force": {
"ts": "2002-05-30T09:30:11.123+02:00",
"value": 24,
"upperError": 26,
"lowerError": 22
},
"pressure": {
"value": 50,
"upperError": 52,
"lowerError": 48
}
}
...

value
Definition: The final value of the process
Required: no
Size restriction: no
Note:
Example:
...
"value": 24
...

measurements
Definition: Contains the measurements of the different phases
Required: yes
Size restriction: no
Note: Each phase represents an execution step in the process and contains information about that specific execution step. All phases should be sorted by the timestamp of the phase.
Sub Fields:
Example:
...
"measurements": [{
"ts": "2002-05-30T09:30:10.123+02:00",
"phase": "phase name 2",
"name": "Turn left 500 degrees",
"result": "NOK",
"code": "0000 EE01",
"limits": {
"temperature": {
"upperError": 4444,
"lowerError": 44,
"upperWarn": 2222,
"lowerWarn": 46,
"target": 35
}
},
"specialValues": {
"pressure": {
"time": 24,
"value": 44.2432
},
"force": {
"time": 24,
"value": 24
}
},
"series": {
"time": [0, 23, 24],
"force": [26, 23, 24],
"pressure": [52.4, 46.32, 44.2432],
"temperature": [45.4243, 46.42342, 44.2432]
}
}]
...

phase
Definition: The ID of the process phase.
Required: no
Size restriction: 256
Note: Format: alphanumeric string (dash allowed e.g. UUID)
Example:
...
"phase": "b4927dad-58d4-4580-b460-79cefd56775b"
...

name
Definition: The name of the process phase.
Required: no
Size restriction: 256
Note: Format: alphanumeric string
Example:
...
"phase": "phase name 1"
...

limits
Definition: Provides information about limits for data provided in the series element.
Required: no
Size restriction: no
Note: The limits is an JSON object where the key is the name of a Measurement Point (see also series element) and the value is a structure of different upper/lower limits described below. The limit is either a single value or an array of values. If the limit is array of values the array size has to be the same as the series.
Sub Fields:
Example:
...
"limits": {
"temperature": {
"upperError": 4444,
"lowerError": 44,
"upperWarn": 2222,
"lowerWarn": 46,
"target": 35
},
"force": {
"upperError": [27, 24, 25],
"lowerError": [25, 22, 23]
}
}
...

target
Definition: Information about the expected final value
Required: no
Size restriction: no
Note:
Example:
...
"target": 35
...

specialValues
Definition: Provides information about special or interesting values during the process phase.
Required: no
Size restriction: no
Note: There is an option to set a time offset value related to the start time of the process phase. By setting this it is possible to using these value analog to one measurement value.
Sub Fields:
Example:
...
"specialValues": {
"pressure": {
"value": 24,
"time": 0
}
"force": {
"value": 50
}
}
...