MQTT

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for sensors and mobile devices, often used in the Internet of Things (IoT). It operates on a publish-subscribe model, where devices (clients) can publish messages to a broker, which then distributes these messages to other clients subscribed to a topic. MQTT requeres a broker to work.

Broker

MQTT needs a MQTT Broker to work. The UpBlue platform is a client that receives messages from a broker. The sensor or device we want to receives messages from, publish these messages to the broker.

Some popular MQTT brokers include:

• Mosquitto: An open-source broker that is lightweight and suitable for small-scale IoT projects.
• EMQX: Known for its high scalability and performance, making it ideal for large-scale deployments.
• HiveMQ: Offers both open-source and commercial versions, with features tailored for enterprise use.

Topics

Basics

A MQTT Client can subscribe or publish messages to a MQTT broker. This messages are written to a topic. A topic for example can be: /company/site1/line1/slitting.

Topics are useful for grouping or splitting datasets. In advance use cases, topics are used for defining access to a (part of) a topic. For example: a user can have acces to: /company/site1. But not to /company/site2.

A client can subscribe to a topic to receive data.

Wildcards

Wildcards can be used to subscribe to multiple topics with a single subscription. There are two types of wildcards: the single-level wildcard (+) and the multi-level wildcard (#).

1 Single-Level Wildcard (+):

• This wildcard matches one level in the topic hierarchy. For example, the topic sensors/+/temperature will match sensors/slitting/temperature and sensors/printing/temperature, but not sensors/slitting/humidity.
• the topic sensors/slitting/+ will match sensors/slitting/temperature and sensors/slitting/temperature, but not sensors/slitting/line1/temperature. This is because of the extra /

2 Multi-Level Wildcard (#):

• This wildcard matches any number of levels in the topic hierarchy, including the parent level. For example, the topic sensors/# will match sensors/slitting/temperature, sensors/printing/temperature, and sensors/slitting/humidity.

These wildcards make it easier to manage and subscribe to multiple related topics without needing to specify each one individually.

Create a Connection with MQTT

Connection details

Fields

Connection name

This is the name given earlier when creating the connection. This is only for identification in the UpBlue Management Environment.

Protocol

MQTT support two types of protocols: TCP (default) or Websocket. If you don’t know what protocol your broker is using, it is probably MQTT TCP. Websocket is primarily used when only http traffic is allowed and port 1883 or 8883 are closed. Since we are probably getting local MQTT traffic, this is not a issue.

Address

This is the address of the MQTT broker. This can be a http/https address for MQTT Websocket or TCP address for MQTT TCP. Ports frequently used by protocol;

• TCP: 1883
• Secure TCP: 8883
• Websocket: 80
• Secure Websocket: 443

No need to add http://, https:// or something else. Based on the selected Protocol and SSl enabled or not, the right prefix will be used.

Example or an MQTT address: 192.168.0.152:1883.

Username and Password

If the MQTT broker uses a username and/or password. Fill these fields. Leave empty for no authorization.

SSL

If the broker uses SSL, enable this option. If using a local broker, SSL is normally not used.

Test connection

Rules

A rule is configuration that will retrieve a specific set of information from the MQTT broker. It instructs the Collector to retrieve this information and send it to the Cloud.

Fields

Name

The name is only used for identification in the UpBlue Platform.

MQTT topic

This is the topic this rule will listing to. See the Topic section how topics work.

Tag source

The tag is the most important label. This definies what the value is. For example a tag can be “Temprature” of “Speed”. There are three ways to define a tag.

1. Manual
2. Extract from the topic name
3. Extract from the JSON payload

1. Manual

Just fill in what the tag is suppose to be. This is used when the selected topic only supplies values for one tag.

2. Extract from the topic name

When and wildcard is used in the topic, it can be useful to extract the tag name from the topic. For example the subscription topic is: sensors/slitting/+. The + is on the third(3) level. Set Topic level to extract from to 3 If a message is received on sensors/slitting/temprature, the tag will be temprature If a other messages is received on sensors/slitting/humidity, the tag will be humidity

In this use case, multiple tags can be processes by one rule!

3. Extract from the JSON payload

If the MQTT message is a JSON payload and the payload contains the tag, the tag can be extracted from the payload. This can only be used when Raw data is off.

For example payload is this;

{
  "value": 21.2,
  "tag": "temperature"
}

Set the “Add Tag” field to: tag Result sould be this;

if the JSON is this

{
  "value": 21.2,
  "meta": {
    "tag": "temperature"
  }
}

Result sould be this;

The tag will be retrieved from the json payload with the selected keys.

Time source

Each tag needs a time. There are two options to define the time.

1. Use the collector time
2. Extract the time from the JSON payload

1. Use the collector time

When a message is received, the time at that moment is used as time. There can be a slight delay between the moment the value is created by the sensor and the collector time. Also, it is important the time on the machine the collector is running on, is correct

2. Extract the time from the JSON payload

If the MQTT message is a JSON payload and the payload contains the time, the time can be extracted from the payload. This can only be used when Raw data is off. For example payload is this;

{
  "value": 21.2,
  "tag": "temperature",
  "time": "1681981694131000"
}

Result sould be this;

This time will be used as time for the value.

Time can be in the following formats;

• 2024-01-02 15:04:05.999
• 2023-04-10 14:35:43.188 +0200
• 2023-04-10 14:35:43 +0200
• 2024-01-02T15:04:05.999Z
• 2024-01-02 15:04:05
• 2024-01-02T15:04:05Z
• 2024-01-02 Will be rounded to midnight
• 1681981694131000000 nanoseconds
• 1681981694131000 microseconds
• 1681981694131 millisecond
• 1728904106 seconds

Raw data

If raw data is enabled, the assumption is that the data is will be the value itself. So the payload contains not a JSON structure. If raw data is off, the value needs to be extracted from the payload.

For example payload is this;

{
  "value": 21.2,
  "tag": "temperature",
  "time": "1681981694131000"
}

Result sould be this;

if the JSON is this

{
  "values": {
    "temperature": 21.2
  },
  "meta": {
    "tag": "temperature"
  }
}

Result sould be this;

if the JSON is like this:

{
  "values": {
    "temperature": 21.2,
    "humidity": 78.6
  },
  "meta": {
    "tag": "temperature"
  }
}

You need to create two rules. One for temperature, one for humidity.

Transform values

If the payload is not a value, but text, we can transform the text to a value. Text can be saved in the database by itself, but no calculations can be done on text in the dashboards. It is advice to transform text to values when possible.

You can map text to a value like so; Result sould be this;

Labels

You can override the labels Cell and Unit or add extra labels. Read more about this here.

Test rule

A new window will open with the test results. Green rows means test ok, this values will be saved to the UpBlue when the connection is send to the collector. Red rules are not ok. Open the Rule to see why the payload is ommited.