Messages
For each message topic you will find a short description what the message is used for and which structure it has, as well as what structure the payload is excepted to have.
Introduction
The United Manufacturing Hub provides a specific structure for messages/topics, each with its own unique purpose.
By adhering to this structure, the UMH will automatically calculate KPIs for you, while also making it easier to maintain
consistency in your topic structure.
1 - activity
activity messages are sent when a new order is added.
This is part of our recommended workflow to create machine states. The data sent here will not be stored in the database automatically, as it will be required to be converted into a state. In the future, there will be a microservice, which converts these automatically.
Topic
ia/<customerID>/<location>/<AssetID>/activity
ia.<customerID>.<location>.<AssetID>.activity
Usage
A message is sent here each time the machine runs or stops.
Content
key | data type | description |
---|
timestamp_ms | int | unix timestamp of message creation |
activity | bool | true if asset is currently active, false if asset is currently inactive |
JSON
Examples
The asset was active during the timestamp of the message:
{
"timestamp_ms":1588879689394,
"activity": true,
}
Schema
Producers
Consumers
2 - addOrder
AddOrder messages are sent when a new order is added.
Topic
ia/<customerID>/<location>/<AssetID>/addOrder
ia.<customerID>.<location>.<AssetID>.addOrder
Usage
A message is sent here each time a new order is added.
Content
key | data type | description |
---|
product_id | string | current product name |
order_id | string | current order name |
target_units | int64 | amount of units to be produced |
- The product needs to be added before adding the order. Otherwise, this message will be discarded
- One order is always specific to that asset and can, by definition, not be used across machines. For this case one would need to create one order and product for each asset (reason: one product might go through multiple machines, but might have different target durations or even target units, e.g. one big 100m batch get split up into multiple pieces)
JSON
Examples
One order was started for 100 units of product “test”:
{
"product_id":"test",
"order_id":"test_order",
"target_units":100
}
Schema
{
"$schema": "http://json-schema.org/draft/2019-09/schema",
"$id": "https://learn.umh.app/content/docs/architecture/datamodel/messages/addOrder.json",
"type": "object",
"default": {},
"title": "Root Schema",
"required": [
"product_id",
"order_id",
"target_units"
],
"properties": {
"product_id": {
"type": "string",
"default": "",
"title": "The product id to be produced",
"examples": [
"test",
"Beierlinger 30x15"
]
},
"order_id": {
"type": "string",
"default": "",
"title": "The order id of the order",
"examples": [
"test_order",
"HA16/4889"
]
},
"target_units": {
"type": "integer",
"default": 0,
"minimum": 0,
"title": "The amount of units to be produced",
"examples": [
1,
100
]
}
},
"examples": [{
"product_id": "Beierlinger 30x15",
"order_id": "HA16/4889",
"target_units": 1
},{
"product_id":"test",
"order_id":"test_order",
"target_units":100
}]
}
Producers
Consumers
3 - addParentToChild
AddParentToChild messages are sent when child products are added to a parent product.
Topic
ia/<customerID>/<location>/<AssetID>/addParentToChild
ia.<customerID>.<location>.<AssetID>.addParentToChild
Usage
This message can be emitted to add a child product to a parent product.
It can be sent multiple times, if a parent product is split up into multiple child’s or multiple parents are combined into one child. One example for this if multiple parts are assembled to a single product.
Content
key | data type | description |
---|
timestamp_ms | int64 | unix timestamp you want to go back from |
childAID | string | the AID of the child product |
parentAID | string | the AID of the parent product |
JSON
Examples
A parent is added to a child:
{
"timestamp_ms":1589788888888,
"childAID":"23948723489",
"parentAID":"4329875"
}
Schema
{
"$schema": "http://json-schema.org/draft/2019-09/schema",
"$id": "https://learn.umh.app/content/docs/architecture/datamodel/messages/scrapCount.json",
"type": "object",
"default": {},
"title": "Root Schema",
"required": [
"timestamp_ms",
"childAID",
"parentAID"
],
"properties": {
"timestamp_ms": {
"type": "integer",
"default": 0,
"minimum": 0,
"title": "The unix timestamp you want to go back from",
"examples": [
1589788888888
]
},
"childAID": {
"type": "string",
"default": "",
"title": "The AID of the child product",
"examples": [
"23948723489"
]
},
"parentAID": {
"type": "string",
"default": "",
"title": "The AID of the parent product",
"examples": [
"4329875"
]
}
},
"examples": [
{
"timestamp_ms":1589788888888,
"childAID":"23948723489",
"parentAID":"4329875"
},
{
"timestamp_ms":1589788888888,
"childAID":"TestChild",
"parentAID":"TestParent"
}
]
}
Producers
Consumers
4 - addProduct
AddProduct messages are sent when a new product is produced.
Topic
ia/<customerID>/<location>/<AssetID>/addProduct
ia.<customerID>.<location>.<AssetID>.addProduct
Usage
A message is sent each time a new product is produced.
Content
key | data type | description |
---|
product_id | string | current product name |
time_per_unit_in_seconds | float64 | the time it takes to produce one unit of the product |
See also notes regarding adding products and orders in /addOrder
JSON
Examples
A new product “Beilinger 30x15” with a cycle time of 200ms is added to the asset.
{
"product_id": "Beilinger 30x15",
"time_per_unit_in_seconds": "0.2"
}
Schema
{
"$schema": "http://json-schema.org/draft/2019-09/schema",
"$id": "https://learn.umh.app/content/docs/architecture/datamodel/messages/scrapCount.json",
"type": "object",
"default": {},
"title": "Root Schema",
"required": [
"product_id",
"time_per_unit_in_seconds"
],
"properties": {
"product_id": {
"type": "string",
"default": "",
"title": "The product id to be produced"
},
"time_per_unit_in_seconds": {
"type": "number",
"default": 0.0,
"minimum": 0,
"title": "The time it takes to produce one unit of the product"
}
},
"examples": [
{
"product_id": "Beierlinger 30x15",
"time_per_unit_in_seconds": "0.2"
},
{
"product_id": "Test product",
"time_per_unit_in_seconds": "10"
}
]
}
Producers
Consumers
5 - addShift
AddShift messages are sent to add a shift with start and end timestamp.
Topic
ia/<customerID>/<location>/<AssetID>/addShift
ia.<customerID>.<location>.<AssetID>.addShift
Usage
This message is send to indicate the start and end of a shift.
Content
key | data type | description |
---|
timestamp_ms | int64 | unix timestamp of the shift start |
timestamp_ms_end | int64 | optional unix timestamp of the shift end |
JSON
Examples
A shift with start and end:
{
"timestamp_ms":1589788888888,
"timestamp_ms_end":1589788888888
}
And shift without end:
{
"timestamp_ms":1589788888888
}
Schema
{
"$schema": "http://json-schema.org/draft/2019-09/schema",
"$id": "https://learn.umh.app/content/docs/architecture/datamodel/messages/scrapCount.json",
"type": "object",
"default": {},
"title": "Root Schema",
"required": [
"timestamp_ms"
],
"properties": {
"timestamp_ms": {
"type": "integer",
"description": "The unix timestamp, of shift start"
},
"timestamp_ms_end": {
"type": "integer",
"description": "The *optional* unix timestamp, of shift end"
}
},
"examples": [
{
"timestamp_ms":1589788888888,
"timestamp_ms_end":1589788888888
},
{
"timestamp_ms":1589788888888
}
]
}
Producers
Consumers
6 - count
Count Messages are sent everytime an asset has counted a new item.
Topic
ia/<customerID>/<location>/<AssetID>/count
ia.<customerID>.<location>.<AssetID>.count
Usage
A count message is send everytime an asset has counted a new item.
Content
key | data type | description |
---|
timestamp_ms | int64 | unix timestamp of message creation |
count | int64 | amount of items counted |
scrap | int64 | optional amount of defective items. In unset 0 is assumed |
JSON
Examples
One item was counted and there was no scrap:
{
"timestamp_ms":1589788888888,
"count":1,
"scrap":0
}
Ten items where counted and there was five scrap:
{
"timestamp_ms":1589788888888,
"count":10,
"scrap":5
}
Schema
{
"$schema": "http://json-schema.org/draft/2019-09/schema",
"$id": "https://learn.umh.app/content/docs/architecture/datamodel/messages/count.json",
"type": "object",
"default": {},
"title": "Root Schema",
"required": [
"timestamp_ms",
"count"
],
"properties": {
"timestamp_ms": {
"type": "integer",
"default": 0,
"minimum": 0,
"title": "The unix timestamp of message creation",
"examples": [
1589788888888
]
},
"count": {
"type": "integer",
"default": 0,
"minimum": 0,
"title": "The amount of items counted",
"examples": [
1
]
},
"scrap": {
"type": "integer",
"default": 0,
"minimum": 0,
"title": "The optional amount of defective items",
"examples": [
0
]
}
},
"examples": [{
"timestamp_ms": 1589788888888,
"count": 1,
"scrap": 0
},{
"timestamp_ms": 1589788888888,
"count": 1
}]
}
Producers
Consumers
7 - deleteShift
DeleteShift messages are sent to delete a shift that starts at the designated timestamp.
Topic
ia/<customerID>/<location>/<AssetID>/deleteShift
ia.<customerID>.<location>.<AssetID>.deleteShift
Usage
deleteShift
is generated to delete a shift that started at the designated timestamp.
Content
key | data type | description |
---|
timestamp_ms | int32 | unix timestamp of the shift start |
JSON
Example
The shift that started at the designated timestamp is deleted from the database.
{
"begin_time_stamp": 1588879689394
}
Producers
Consumers
8 - detectedAnomaly
detectedAnomaly messages are sent when an asset has stopped and the reason is identified.
This is part of our recommended workflow to create machine states. The data sent here will not be stored in the database automatically, as it will be required to be converted into a state. In the future, there will be a microservice, which converts these automatically.
Topic
ia/<customerID>/<location>/<AssetID>/detectedAnomaly
ia.<customerID>.<location>.<AssetID>.detectedAnomaly
Usage
A message is sent here each time a stop reason has been identified automatically or by input from the machine operator.
Content
key | data type | description |
---|
timestamp_ms | int | Unix timestamp of message creation |
detectedAnomaly | string | reason for the production stop of the asset |
JSON
Examples
The anomaly of the asset has been identified as maintenance:
{
"timestamp_ms":1588879689394,
"detectedAnomaly":"maintenance",
}
Producers
Consumers
9 - endOrder
EndOrder messages are sent whenever a new product is produced.
Topic
ia/<customerID>/<location>/<AssetID>/endOrder
ia.<customerID>.<location>.<AssetID>.endOrder
Usage
A message is sent each time a new product is produced.
Content
key | data type | description |
---|
timestamp_ms | int64 | unix timestamp of message creation |
order_id | int64 | current order name |
See also notes regarding adding products and orders in /addOrder
JSON
Examples
The order “test_order” was finished at the shown timestamp.
{
"order_id":"test_order",
"timestamp_ms":1589788888888
}
Schema
{
"$schema": "http://json-schema.org/draft/2019-09/schema",
"$id": "https://learn.umh.app/content/docs/architecture/datamodel/messages/endOrder.json",
"type": "object",
"default": {},
"title": "Root Schema",
"required": [
"order_id",
"timestamp_ms"
],
"properties": {
"timestamp_ms": {
"type": "integer",
"description": "The unix timestamp, of shift start"
},
"order_id": {
"type": "string",
"default": "",
"title": "The order id of the order",
"examples": [
"test_order",
"HA16/4889"
]
}
},
"examples": [{
"order_id": "HA16/4889",
"timestamp_ms":1589788888888
},{
"product_id":"test",
"timestamp_ms":1589788888888
}]
}
Producers
Consumers
10 - modifyProducedPieces
ModifyProducesPieces messages are sent whenever the count of produced and scrapped items need to be modified.
Topic
ia/<customerID>/<location>/<AssetID>/modifyProducedPieces
ia.<customerID>.<location>.<AssetID>.modifyProducedPieces
Usage
modifyProducedPieces
is generated to change the count of produced items and scrapped items at the named timestamp.
Content
key | data type | description |
---|
timestamp_ms | int64 | unix timestamp of the time point whose count is to be modified |
count | int32 | number of produced items |
scrap | int32 | number of scrapped items |
JSON
Example
The count and scrap are overwritten to be to each at the timestamp.
{
"timestamp_ms": 1588879689394,
"count": 10,
"scrap": 10
}
Producers
Consumers
11 - modifyState
ModifyState messages are generated when a state of an asset during a certain timeframe needs to be modified.
Topic
ia/<customerID>/<location>/<AssetID>/modifyState
ia.<customerID>.<location>.<AssetID>.modifyState
Usage
modifyState
is generated to modify the state from the starting timestamp to the end timestamp. You can find a list of all supported states here.
Content
key | data type | description |
---|
timestamp_ms | int32 | unix timestamp of the starting point of the timeframe to be modified |
timestamp_ms_end | int32 | unix timestamp of the end point of the timeframe to be modified |
new_state | int32 | new state code |
JSON
Example
The state of the timeframe between the timestamp is modified to be 150000: OperatorBreakState
{
"timestamp_ms": 1588879689394,
"timestamp_ms_end": 1588891381023,
"new_state": 150000
}
Producers
Consumers
12 - processValue
ProcessValue messages are sent whenever a custom process value with unique name has been prepared. The value is numerical.
Topic
ia/<customerID>/<location>/<AssetID>/processValue
or: ia/<customerID>/<location>/<AssetID>/processValue/<tagName>
ia.<customerID>.<location>.<AssetID>.processValue
or: ia.<customerID>.<location>.<AssetID>.processValue.<tagName>
If you have a lot of processValues, we’d recommend not using the /processValue
as topic, but to append the tag name as well, e.g., /processValue/energyConsumption
. This will structure it better for usage in MQTT Explorer or for data processing only certain processValues.
For automatic data storage in kafka-to-postgresql both will work fine as long as the payload is correct.
Please be aware that the values may only be int or float, other character are not valid, so make sure there is no quotation marks or anything
sneaking in there. Also be cautious of using the JavaScript ToFixed() function, as it is converting a float into a string.
Usage
A message is sent each time a process value has been prepared. The key has a unique name.
Content
key | data type | description |
---|
timestamp_ms | int64 | unix timestamp of message creation |
<valuename> | int64 or float64 | Represents a process value, e.g. temperature |
Pre 0.10.0:
As <valuename>
is either of type ´int64´ or ´float64´, you cannot use booleans. Convert to integers as needed; e.g., true = “1”, false = “0”
Post 0.10.0:
<valuename>
will be converted, even if it is a boolean value.
Check integer literals and floating-point literals for other valid values.
JSON
Example
At the shown timestamp the custom process value “energyConsumption” had a readout of 123456.
{
"timestamp_ms": 1588879689394,
"energyConsumption": 123456
}
Producers
Consumers
13 - processValueString
ProcessValueString messages are sent whenever a custom process value is prepared. The value is a string.
This message type is not functional as of 0.9.5!
Topic
ia/<customerID>/<location>/<AssetID>/processValueString
ia.<customerID>.<location>.<AssetID>.processValueString
Usage
A message is sent each time a process value has been prepared. The key has a unique name. This message is used when the datatype of the process value is a string instead of a number.
Content
key | data type | description |
---|
timestamp_ms | int64 | unix timestamp of message creation |
<valuename> | string | Represents a process value, e.g. temperature |
JSON
Example
At the shown timestamp the custom process value “customer” had a readout of “miller”.
{
"timestamp_ms": 1588879689394,
"customer": "miller"
}
Producers
Consumers
14 - productTag
ProductTag messages are sent to contextualize processValue messages.
Topic
ia/<customerID>/<location>/<AssetID>/productTag
ia.<customerID>.<location>.<AssetID>.productTag
Usage
productTagString
is usually generated by contextualizing a processValue
.
Content
key | data type | description |
---|
AID | string | AID of the product |
name | string | Name of the product |
value | float64 | key of the processValue |
timestamp_ms | int64 | unix timestamp of message creation |
JSON
Example
At the shown timestamp the product with the shown AID had 5 blemishes recorded.
{
"AID": "43298756",
"name": "blemishes",
"value": 5,
"timestamp_ms": 1588879689394
}
Producers
Consumers
15 - productTagString
ProductTagString messages are sent to contextualize processValueString messages.
Topic
ia/<customerID>/<location>/<AssetID>/productTagString
ia.<customerID>.<location>.<AssetID>.productTagString
Usage
ProductTagString
is usually generated by contextualizing a processValueString
.
Content
key | data type | description |
---|
AID | string | AID of the product |
name | string | Key of the processValue |
value | string | value of the processValue |
timestamp_ms | int64 | unix timestamp of message creation |
JSON
Example
At the shown timestamp the product with the shown AID had the processValue of “test_value”.
{
"AID": "43298756",
"name": "shirt_size",
"value": "XL",
"timestamp_ms": 1588879689394
}
Producers
Consumers
16 - recommendation
Recommendation messages are sent whenever rapid actions would quickly improve efficiency on the shop floor.
Topic
ia/<customerID>/<location>/<AssetID>/recommendation
ia.<customerID>.<location>.<AssetID>.recommendation
Usage
recommendation
are action recommendations, which require concrete and rapid action in order to quickly eliminate efficiency losses on the store floor.
Content
key | data type | description |
---|
uid | string | UniqueID of the product |
timestamp_ms | int64 | unix timestamp of message creation |
customer | string | the customer ID in the data structure |
location | string | the location in the data structure |
asset | string | the asset ID in the data structure |
recommendationType | int32 | Name of the product |
enabled | bool | - |
recommendationValues | map | Map of values based on which this recommendation is created |
diagnoseTextDE | string | Diagnosis of the recommendation in german |
diagnoseTextEN | string | Diagnosis of the recommendation in english |
recommendationTextDE | string | Recommendation in german |
recommendationTextEN | string | Recommendation in english |
JSON
Example
A recommendation for the demonstrator at the shown location has not been running for a while, so a recommendation is sent to either start the machine or specify a reason why it is not running.
{
"UID": "43298756",
"timestamp_ms": 15888796894,
"customer": "united-manufacturing-hub",
"location": "dccaachen",
"asset": "DCCAachen-Demonstrator",
"recommendationType": "1",
"enabled": true,
"recommendationValues": { "Treshold": 30, "StoppedForTime": 612685 },
"diagnoseTextDE": "Maschine DCCAachen-Demonstrator steht seit 612685 Sekunden still (Status: 8, Schwellwert: 30)" ,
"diagnoseTextEN": "Machine DCCAachen-Demonstrator is not running since 612685 seconds (status: 8, threshold: 30)",
"recommendationTextDE":"Maschine DCCAachen-Demonstrator einschalten oder Stoppgrund auswählen.",
"recommendationTextEN": "Start machine DCCAachen-Demonstrator or specify stop reason.",
}
Producers
Consumers
17 - scrapCount
ScrapCount messages are sent whenever a product is to be marked as scrap.
Topic
ia/<customerID>/<location>/<AssetID>/scrapCount
ia.<customerID>.<location>.<AssetID>.scrapCount
Usage
Here a message is sent every time products should be marked as scrap. It works as follows: A message with scrap and timestamp_ms is sent. It starts with the count that is directly before timestamp_ms. It is now iterated step by step back in time and step by step the existing counts are set to scrap until a total of scrap products have been scraped.
Content
timestamp_ms
is the unix timestamp, you want to go back fromscrap
number of item to be considered as scrap.
- You can specify maximum of 24h to be scrapped to avoid accidents
- (NOT IMPLEMENTED YET) If counts does not equal scrap, e.g. the count is 5 but only 2 more need to be scrapped, it will scrap exactly 2. Currently, it would ignore these 2. see also #125
- (NOT IMPLEMENTED YET) If no counts are available for this asset, but uniqueProducts are available, they can also be marked as scrap.
JSON
Examples
Ten items where scrapped:
{
"timestamp_ms":1589788888888,
"scrap":10
}
Schema
{
"$schema": "http://json-schema.org/draft/2019-09/schema",
"$id": "https://learn.umh.app/content/docs/architecture/datamodel/messages/scrapCount.json",
"type": "object",
"default": {},
"title": "Root Schema",
"required": [
"timestamp_ms",
"scrap"
],
"properties": {
"timestamp_ms": {
"type": "integer",
"default": 0,
"minimum": 0,
"title": "The unix timestamp you want to go back from",
"examples": [
1589788888888
]
},
"scrap": {
"type": "integer",
"default": 0,
"minimum": 0,
"title": "Number of items to be considered as scrap",
"examples": [
10
]
}
},
"examples": [
{
"timestamp_ms": 1589788888888,
"scrap": 10
},
{
"timestamp_ms": 1589788888888,
"scrap": 5
}
]
}
Producers
Consumers
18 - scrapUniqueProduct
ScrapUniqueProduct messages are sent whenever a unique product should be scrapped.
Topic
ia/<customerID>/<location>/<AssetID>/scrapUniqueProduct
ia.<customerID>.<location>.<AssetID>.scrapUniqueProduct
Usage
A message is sent here everytime a unique product is scrapped.
Content
key | data type | description |
---|
UID | string | unique ID of the current product |
JSON
Example
The product with the unique ID 22 is scrapped.
Producers
Consumers
19 - startOrder
StartOrder messages are sent whenever a new order is started.
Topic
ia/<customerID>/<location>/<AssetID>/startOrder
ia.<customerID>.<location>.<AssetID>.startOrder
Usage
A message is sent here everytime a new order is started.
Content
key | data type | description |
---|
order_id | string | name of the order |
timestamp_ms | int64 | unix timestamp of message creation |
- See also notes regarding adding products and orders in /addOrder
- When startOrder is executed multiple times for an order, the last used timestamp is used.
JSON
Example
The order “test_order” is started at the shown timestamp.
{
"order_id":"test_order",
"timestamp_ms":1589788888888
}
Producers
Consumers
20 - state
State messages are sent every time an asset changes status.
Topic
ia/<customerID>/<location>/<AssetID>/state
ia.<customerID>.<location>.<AssetID>.state
Usage
A message is sent here each time the asset changes status. Subsequent changes are not possible. Different statuses can also be process steps, such as “setup”, “post-processing”, etc. You can find a list of all supported states here.
Content
key | data type | description |
---|
state | uint32 | value of the state according to the link above |
timestamp_ms | uint64 | unix timestamp of message creation |
JSON
Example
The asset has a state of 10000, which means it is actively producing.
{
"timestamp_ms":1589788888888,
"state":10000
}
Producers
Consumers
21 - uniqueProduct
UniqueProduct messages are sent whenever a unique product was produced or modified.
Topic
ia/<customerID>/<location>/<AssetID>/uniqueProduct
ia.<customerID>.<location>.<AssetID>.uniqueProduct
Usage
A message is sent here each time a product has been produced or modified. A modification can take place, for example, due to a downstream quality control.
There are two cases of when to send a message under the uniqueProduct topic:
- The exact product doesn’t already have a UID (-> This is the case, if it has not been produced at an asset incorporated in the digital shadow). Specify a space holder asset = “storage” in the MQTT message for the uniqueProduct topic.
- The product was produced at the current asset (it is now different from before, e.g. after machining or after something was screwed in). The newly produced product is always the “child” of the process. Products it was made out of are called the “parents”.
Content
key | data type | description |
---|
begin_timestamp_ms | int64 | unix timestamp of start time |
end_timestamp_ms | int64 | unix timestamp of completion time |
product_id | string | product ID of the currently produced product |
isScrap | bool | optional information whether the current product is of poor quality and will be sorted out. Is considered false if not specified. |
uniqueProductAlternativeID | string | alternative ID of the product |
JSON
Example
The processing of product “Beilinger 30x15” with the AID 216381 started and ended at the designated timestamps. It is of low quality and due to be scrapped.
{
"begin_timestamp_ms":1589788888888,
"end_timestamp_ms":1589788893729,
"product_id":"Beilinger 30x15",
"isScrap":true,
"uniqueProductAlternativeID":"216381"
}
Producers
Consumers