The UMH datamodel / MQTT

All events or subsequent changes in production are transmitted via MQTT in the following data model

Introduction

All events or subsequent changes in production are transmitted via MQTT in the following data model. This ensures that all participants are always informed about the latest status.

The data model in the MQTT Broker can be divided into four levels. In general, the higher the level, the lower the data frequency and the more the data is prepared.

If you do not know the idea of MQTT (important keywords: “broker”, “subscribe”, “publish”, “topic”), we recommend reading the wikipedia article first.

All MQTT messages consist out of one JSON with at least two elements in it:

KeyData type/formatDescription
timestamp_msintthe amount of milliseconds since the 1970-01-01 (also called UNIX timestamp in milliseconds)
<valueName>int, str, dicta value that can be int, str, or even in dict format

1st level: Raw data

Data from this level are all raw data, which are not yet contextualized(i.e., assigned to a machine). These are, in particular, all data from sensorconnect and cameraconnect.

Topic: ia/raw/

Topic structure: `ia/raw/.+'

All raw data coming in via sensorconnect.

Topic: ia/rawImage/

Topic structure: ia/rawImage/<TransmitterID>/<MAC Adress of Camera>

All raw data coming in via cameraconnect.

keydata typedescription
image_idstra unique identifier for every image acquired (e.g. format:<MACaddress>_<timestamp_ms>)
image_bytesstrbase64 encoded image in JPG format in bytes
image_heightintheight of the image in pixel
image_widthintwidth of the image in pixel
image_channelsintamount of included color channels (Mono: 1, RGB: 3)

2nd level: Contextualized data

In this level the data is already assigned to a machine.

Topic structure: ia/<customerID>/<location>/<AssetID>/<Measurement> e.g. ia/dccaachen/aachen/demonstrator/count.

An asset can be a step, machine, plant or line. It uniquely identifies the smallest location necessary for modeling the process.

By definition all topic names should be lower case only!

/count

Topic: ia/<customerID>/<location>/<AssetID>/count

Here a message is sent every time something has been counted. This can be, for example, a good product or scrap.

count in the JSON is an integer. scrap in the JSON is an integer, which is optional. It means scrap pieces of count are scrap. If not specified it is 0 (all produced goods are good).

keydata typedescription
countintquantity of produced item

/scrapCount

Topic: ia/<customerID>/<location>/<AssetID>/scrapCount

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.

scrap in the JSON is an integer.

keydata typedescription
scrapintNumber of item from count that is considered as scrap. When scrap is equal to 0, that means all produced goods are good quality

/barcode

Topic: ia/<customerID>/<location>/<AssetID>/barcode

keydata typedescription
barcodestrA message is sent here each time the barcode scanner connected to the transmitter via USB reads a barcode via barcodescanner

/activity

Topic: ia/<customerID>/<location>/<AssetID>/activity

keydata typedescription
activityboolA message is sent here every time the machine runs or stops (independent whether it runs slow or fast, or which reason the stop has. This is covered in state)

/detectedAnomaly

Topic: ia/<customerID>/<location>/<AssetID>/detectedAnomaly

keydata typedescription
detectedAnomalystrA message is sent here each time a stop reason has been identified automatically or by input from the machine operator (independent whether it runs slow or fast, or which reason the stop has. This is covered in state)

/addShift

Topic: ia/<customerID>/<location>/<AssetID>/addShift

keydata typedescription
timestamp_ms_endintA message is sent here each time a new shift is started. The value represents a UNIX timestamp in milliseconds

/addOrder

Topic: ia/<customerID>/<location>/<AssetID>/addOrder

A message is sent here each time a new order is started.

keydata typedescription
product_idstrRepresents the current product name
order_idstrRepresents the current order name
target_unitsintRepresents the amount of target units to be produced (in the same unit as count)

/addProduct

Topic: ia/<customerID>/<location>/<AssetID>/addProduct

A message is sent here each time a new product is added.

keydata typedescription
product_idstrRepresents the current product name
time_per_unit_in_secondsfloatSpecifies the target time per unit in seconds

/startOrder

Topic: ia/<customerID>/<location>/<AssetID>/startOrder

A message is sent here each time a new order is started.

keydata typedescription
order_idstrRepresents the order name

/endOrder

Topic: ia/<customerID>/<location>/<AssetID>/endOrder

A message is sent here each time a new order is started.

keydata typedescription
order_idstrRepresents the order name

/processValue

Topic: ia/<customerID>/<location>/<AssetID>/processValue

A message is sent here every time a process value has been prepared. Unique naming of the key.

keydata typedescription
<valueName>int or floatRepresents a process value, e.g. temperature.

/productImage

Topic structure: ia/<customer>/<location>/<assetID>/productImage

/productImage has the same data format as ia/rawImage, only with a changed topic.

/productImage can be acquired in two ways, either from ia/rawImage or /rawImageClassification. In the case of /rawImageClassification, only the Image part is extracted to /productImage, while the classification information is stored in the relational database.

keydata typedescription
image_idstra unique identifier for every image acquired (e.g. format:<MACaddress>_<timestamp_ms>)
image_bytesstrbase64 encoded image in JPG format in bytes
image_heightintheight of the image in pixel
image_widthintwidth of the image in pixel
image_channelsintamount of included color channels (Mono: 1, RGB: 3)

/productTag

Topic structure: ia/<customer>/<location>/<assetID>/productTag

/productTag is usually generated by contextualizing a processValue to a product.

keydata typedescription
AIDstrlorem ipsum
namestrlorem ipsum
valueintlorem ipsum

See also Digital Shadow for more information how to use this message

/productTagString

Topic structure: ia/<customer>/<location>/<assetID>/productTagString

/productTagString is usually generated by contextualizing a processValue to a product.

keydata typedescription
AIDstrlorem ipsum
namestrlorem ipsum
valuestrlorem ipsum

See also Digital Shadow for more information how to use this message

/addParentToChild

Topic structure: ia/<customer>/<location>/<assetID>/addParentToChild

/productTagString is usually generated whenever a product is transformed into another product. It can be used multiple times for the same child to model that one product can consists out of multiple parents.

keydata typedescription
childAIDstrThe AID of the child
parentAIDstrThe AID of the parent

See also Digital Shadow for more information how to use this message

3rd level: production data

This level contains only highly aggregated production data.

/state

Topic: ia/<customerID>/<location>/<AssetID>/state

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

keydata typedescription
stateintValue of state according to this datamodel

/cycleTimeTrigger

Topic: ia/<customerID>/<location>/<AssetID>/cycleTimeTrigger

A message should be sent under this topic whenever an assembly cycle is started.

currentStation in the JSON is a string lastStation in the JSON is a string sanityTime_in_s in the JSON is a integer

keydata typedescription
currentStationstr
lastStationstr
sanityTime_in_sint

/uniqueProduct

Topic: ia/<customerID>/<location>/<AssetID>/uniqueProduct

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”.
keydata typedescription
begin_timestamp_msintStart time
end_timestamp_msintCompletion time
product_idstrThe product ID that is currently produced
isScrapboolInformation whether the current product is of poor quality and will be sorted out. Default value (if not specified otherwise) is false
uniqeProductAlternativeIDstrlorem ipsum

See also Digital Shadow for more information how to use this message

/scrapUniqueProduct

Topic: ia/<customerID>/<location>/<AssetID>/scrapUniqueProduct

A message is sent here each time a unique product has been scrapped.

keydata typedescription
UIDstrUnique ID of the current single product

4th level: Recommendations for action

/recommendations

Topic: ia/<customerID>/<location>/<AssetID>/recommendations

Shopfloor insights are recommendations for action that require concrete and rapid action in order to quickly eliminate efficiency losses on the store floor.

keydata type/formatdescription
recommendationUIDintUnique ID of the recommendation. Used to subsequently deactivate a recommendation (e.g. if it has become obsolete)
recommendationTypeintThe ID / category of the current recommendation. Used to narrow down the group of people
recommendationValuesdictValues used to form the actual recommendation set

Explanation of IDs

There are various different IDs that you can find in the MQTT messages. This section is designed to give an overview.

Namedata type/formatdescription
product_idintThe type of product that should be produced in an order for a specific asset. Can be used to retrieve the target speed.
order_idintOrder ID, which provides the type of product (see product_id) and the amount of pieces that should be produced.
uniqeProductAlternativeIDintIn short: AID. Used to describe a single product of the type product_id in the order order_id. This is the ID that might be written on the product (e.g., with a physical label, lasered, etc.) and is usually the relevant ID for engineers and for production planning. It usually stays the same.
UIDintShort for unique product ID. Compared to the AID the UID changes whenever a product changes its state. Therefore, a product will change its UID everytime it is placed on a new asset. It is used mainly on the database side to lookup a specific product in a specific state.

These IDs are linked together in the database.

TimescaleDB structure

Here is a scheme of the timescaleDB structure:

(open the image using the right click for a better resolution)