MQTT

The MQTT connection allows the Intelligence Hub to connect to MQTT brokers for reading and writing messages. This page describes the connection, input, and output settings, and supported features.

Connection Settings

Setting Description
Client ID The ID to identify the connection with the broker. Leave blank to generate a random ID. Each client must have a unique ID.
Username and Password The username and password required by the MQTT broker.
Connection Timeout Maximum time to wait for a connection to respond. Valid range is 1–300 seconds.
Keep Alive Maximum time to wait without sending a request to the broker. Valid range is 10–43200 seconds.
Request Timeout (ms) How long to wait for a read or write to complete before failing.
Redundant Brokers A list of brokers to connect to if the primary connection is fails. Each broker in the list must contain the protocol, host, and port in the following format: tcp://127.0.0.1:8884 or ssl://127.0.0.1:8885.

In the event that the primary connection fails the connection attempts the next broker in the list, and continues in round robin fashion until a connection is made. Once a connection is established the connector will continue to use the connection until it fails or the connection is re-saved.
Use SSL Enable for MQTT brokers that require transport layer security. See additional SSL options below.
Input Discovery Topic The topic the connection listens on to auto-discover topics. Leave blank to disable auto-discovery. When left blank, auto-discovery is disabled. When enabled, the connection subscribes on startup to the topic and the Browse Input feature shows all topics that have published data.
Clean Session When enabled, the connection is not persisted. Events sent while not connected will not be received. When disabled, the connection is persisted using the provided Client ID. Use a unique Client ID and set QoS for inputs to 2 for reliable delivery.

SSL Options:

  • Ignore Self-Signed Certificate: Accepts any certificate returned from the broker. Use only for testing.
  • CA Certificate: The MQTT Broker certificate file (e.g., groupCA.pem) imported into the certificate store.
  • Client Certificate: The public certificate for the client authentication (e.g., mycert.pem).
  • Client Key: The private key for the client authentication (e.g., mycert.key.pem).

Input Settings

Setting Description
Input Type Controls what is read. Last Publish returns only the last message published on a topic. Branch requires the topic to include a wildcard and returns all the currently known topics and values that meet the topic filter. See the Branch read example below.
Topic The topic to subscribe to for MQTT messages.
Include Topic Specifies if the MQTT topic should be included in the read data. When enabled, the topic is included at the root of the payload. See example below.
Payload Type The type of MQTT payload to process. See options below.

Payload Type Options

Type Description
Any The payload can be JSON, String, or Binary
JSON The payload is deserialized as JSON. Non-JSON payloads ignored.
String (UTF-8) The payload is treated as a string.
Binary The payload is treated as a byte array.

Branch Read Example

Assume the broker has two topics, machine1Pressure with a value of 100, and machine2Pressure with a value of 200. A Branch read with a topic of # returns the following.

{
	"machine1Pressure": 100,
	"machine2Pressure": 200
}

Include Topic Example

{
	"_topic": "deviceid",
	"value": {
		"deviceid": "press1",
		"other": 10
	}
}

Output Settings

Setting Description
Topic The topic to publish MQTT messages to. Topics can be static or dynamic. Use # to include the source input or instance name, or {{this.attribute}} to include data from the payload.
QoS Specifies the quality of service for publishing the output.
Named Root Controls how the instance name appears in the output value. When enabled, output values are nested under the instance name.
Retain Specifies whether the MQTT broker should cache the last value sent.
Breakup Arrays When enabled, array data is sent as individual messages for each element. Otherwise, the entire array is sent in one publish.
Template If blank, the default JSON output format is used. See Output Templates for details.

AWS IoT Core

When using SSL, specifically with AWS IoT Core, AWS IoT Greengrass, or any broker that has a self-signed certificate, you will need to import the certificate into the HighByte Intelligence Hub certificate store. See the “Managing Certificates” section on how to import the certificates. You will need to import the self-signed CA certificate. You may also need to add the Client Certificate (as a certificate) and Client Key (as a key) if the broker is using certificate-based authentication.