# MQTT Protocol

> The MTConnect.NET MQTT topics for Agents, Devices, Observations, and Assets.

URL: https://www.trakhound.com/docs/mtconnect-net/wire-formats/mqtt

## Overview

This is a protocol for accessing MTConnect data using MQTT that mimics the functionality of the MTConnect HTTP REST protocol. The main difference between the HTTP and MQTT protocols is that the MQTT protocol deals with the individual MTConnect entities directly (ex. Device, Observation, Asset).

### All Devices

![Reading every Device of every Agent, starting again when an Agent restarts or a Device Model changes.](https://www.trakhound.com/img/mtconnect-net/docs/mtconnect-mqtt-protocol-all-01.png)

### By Device

![Reading one Device, starting from the Agent that publishes it.](https://www.trakhound.com/img/mtconnect-net/docs/mtconnect-mqtt-protocol-by-device-01.png)

### Multiple Configurable Observation Intervals

This protocol lets clients receive Observations at several intervals. Each interval is a window in which at most one Observation per DataItem is published. This suits client applications such as dashboards. An interval of `0` publishes every change.

#### Observation Topics

The interval (in milliseconds) is specified in the brackets suffix for an Observations topic following the pattern below:

##### Observation Interval 1000ms

```
MTConnect/Devices/ff8fc5c5-206f-4d94-96a8-a03c70b682b8/Observations[1000]/#
```

##### Observation Interval 100ms

```
MTConnect/Devices/ff8fc5c5-206f-4d94-96a8-a03c70b682b8/Observations[100]/#
```

##### Observation Interval 0 ("Realtime")

```
MTConnect/Devices/ff8fc5c5-206f-4d94-96a8-a03c70b682b8/Observations/#
```

### Agent Connection Heartbeat

A connection heartbeat that represents the connection between the MTConnect Agent and the MQTT Broker can be read from the topic below:

```
MTConnect/Agents/[AGENT_UUID]/HeartbeatTimestamp
```

The payload is a simple 64 bit Integer representing the last timestamp (in Unix milliseconds) that the Agent sent a heartbeat.

Using this timestamp in combination with the HeartbeatInterval property found in the **MTConnect/Agents/[AGENT\_UUID]/Information** topic, the connection status of the MTConnect Agent can be determined. Typically, waiting for three missed heartbeats allows for temporary connection interruptions and follows a similar pattern of other MTConnect related heartbeat protocols.

### Entity-Level Agent InstanceId Support

Each MTConnect entity contains an InstanceId property which can be compared to the **InstanceId** property found in the **MTConnect/Agents/[AGENT\_UUID]/Information**. If the entity's InstanceId property differs, then it can be assumed that the Agent was restarted, reconfigured, etc. and the protocol should be restarted. This is similar to the MTConnect HTTP protocol.

## MQTT Topics

### Agents

Each MTConnect Agent upon connection to the MQTT Broker publishes to the two topics listed below:

#### Information

Topic Format:

```
MTConnect/Agents/[AGENT_UUID]/Information
```

Example 1:

```
MTConnect/Agents/d7e169c5-14bb-48a3-bf9f-521152df2c84/Information
```

The Information topic contains information about the MTConnect Agent that would typically be contained in the Header node in an MTConnect XML Response using HTTP. In addition to the standard MTConnect information, the Information payload also contains the configured "heartbeatInterval", "observationIntervals", and a list of the Device UUIDs that are published by this Agent.

Example Payload:

```json
{
  "uuid": "d7e169c5-14bb-48a3-bf9f-521152df2c84",
  "instanceId": 1687791189,
  "sender": "DESKTOP-HV74M4N",
  "version": "5.4.0.0",
  "deviceModelChangeTime": "2023-06-26T14:53:11.1293232Z",
  "heartbeatInterval": 1000,
  "observationIntervals": [
    0,
    1000
  ],
  "devices": [
    "d7e169c5-14bb-48a3-bf9f-521152df2c84",
    "5fd88408-7811-3c6b-5400-11f4026b6890",
    "OKUMA.Lathe.123456"
  ]
}
```

#### Heartbeat

Topic Format:

```
MTConnect/Agents/[AGENT_UUID]/Heartbeat
```

Example 1:

```
MTConnect/Agents/d7e169c5-14bb-48a3-bf9f-521152df2c84/Heartbeat
```

The Heartbeat topic contains the Unix Timestamp (in milliseconds) of the last time the MTConnect Agent sent a heartbeat message to the MQTT Broker. This is used together with the "heartbeatInterval" in the Information topic to detect if the MTConnect Agent is still connected to the MQTT Broker.

Example Payload:

```
1687796168175
```

### Devices

The Devices topics contain the data sent by the MTConnect Agent for each Device that the Agent is configured for. Each Device uses its configured UUID as the identifier.

Topic Format:

```
MTConnect/Devices/[DEVICE_UUID]
```

Example 1:

```
MTConnect/Devices/5fd88408-7811-3c6b-5400-11f4026b6890
```

The topics under each Device are listed below:

#### AgentUuid

The AgentUuid topic is used to contain the UUID of the Agent that is publishing for this Device. This creates a link back to the Agent in order to retrieve information about the Agent.

Topic Format:

```
MTConnect/Devices/[DEVICE_UUID]/AgentUuid
```

Example 1:

```
MTConnect/Devices/5fd88408-7811-3c6b-5400-11f4026b6890/AgentUuid
```

Example Payload:

```
d7e169c5-14bb-48a3-bf9f-521152df2c84
```

#### Device

The Device topic contains a JSON representation of the MTConnect Device Metadata that is typically returned from an HTTP Probe request.

Topic Format:

```
MTConnect/Devices/[DEVICE_UUID]/Device
```

Example 1:

```
MTConnect/Devices/5fd88408-7811-3c6b-5400-11f4026b6890/Device
```

Example Payload:

```
{
  "id": "d1",
  "type": "Device",
  "name": "M12346",
  "uuid": "5fd88408-7811-3c6b-5400-11f4026b6890",
  "instanceId": 1687791189,
  "description": {
    "manufacturer": "Mazak_Corporation",
    "serialNumber": "304141",
    "value": "Mill w/SMooth-G"
  },
  "dataItems": [
    {
      "category": "EVENT",
      "id": "avail",
      "type": "AVAILABILITY"
    },
    
    ...
```

> More information about the JSON representation can be found in [MTConnect.NET-JSON](https://github.com/TrakHound/MTConnect.NET/tree/master/libraries/MTConnect.NET-JSON).

#### Observations

The Observations topic(s) contain the MTConnect Observation data typically returned from either an HTTP Current or Sample request. Observation topics may have a "[xxxx]" suffix that denotes the interval (in milliseconds) that the topics are updated at. This is optional and is used to help filter high-frequency data based on the client requirements for the data. These topics map directly to the "observationIntervals" in the MTConnect/Agents/[AGENT\_UUID]/Information topic. This functionality is used to mimic the MTConnect HTTP protocol's Current request using the "Interval" query parameter.

If an Interval of 0 is specified, the topic does not contain the "[xxxx]" suffix and is updated as fast as the Agent is receiving new data. This should be used when a client needs to collect All changes and mimics the functionality of the MTConnect HTTP protocol's Sample request using the "Interval = 0" query parameter.

> More information about the topic structure of Observations can be found in [MTConnect.NET-MQTT](https://github.com/TrakHound/MTConnect.NET/tree/master/libraries/MTConnect.NET-MQTT).

Topic Format:

```
MTConnect/Devices/[DEVICE_UUID]/Observations[INTERVAL]
```

Example 1: Observations with no interval specified

```
MTConnect/Devices/5fd88408-7811-3c6b-5400-11f4026b6890/Observations
```

Example 2: Observations at a 1000 ms interval

```
MTConnect/Devices/5fd88408-7811-3c6b-5400-11f4026b6890/Observations[1000]
```

Example 3: Observations at a 250 ms interval

```
MTConnect/Devices/5fd88408-7811-3c6b-5400-11f4026b6890/Observations[250]
```

Example 4: Observations at a 5000 ms interval

```
MTConnect/Devices/5fd88408-7811-3c6b-5400-11f4026b6890/Observations[5000]
```

#### Assets

The Assets topic(s) contain the MTConnect Asset data typically returned from an HTTP Assets request for a specific Device.

Topic Format:

```
MTConnect/Devices/[DEVICE_UUID]/Assets/[ASSET_TYPE]/[ASSET_ID]
```

Example 1:

```
MTConnect/Devices/5fd88408-7811-3c6b-5400-11f4026b6890/Assets/CuttingTool/15010006.324
```

Example Payload:

```
{
  "assetId": "15010006.324",
  "type": "CuttingTool",
  "timestamp": "2023-06-26T16:44:20.6839267Z",
  "instanceId": 1687791189,
  "deviceUuid": "5fd88408-7811-3c6b-5400-11f4026b6890",
  "serialNumber": "324",
  "toolId": "15010006",
  "cuttingToolLifeCycle": {
    "cutterStatus": [
      "AVAILABLE",
      "NEW",
      "MEASURED"
    ],
    "location": {
      "type": "SPINDLE"
    },
    "programToolGroup": "5",
    "programToolNumber": "12",
    "measurements": [
      {
        "type": "FunctionalLength",
        "value": 7.6543,
        "units": "MILLIMETER",
        "code": "LF"
      },
      {
        "type": "CuttingDiameterMax",
        "value": 0.375,
        "units": "MILLIMETER",
        "code": "DC"
      }
    ]
  }
}
```

> More information about the JSON representation can be found in [MTConnect.NET-JSON](https://github.com/TrakHound/MTConnect.NET/tree/master/libraries/MTConnect.NET-JSON).
