MQTT v3 Connector
MQTT V3 Connector connects Banalytics to MQTT brokers using MQTT 3.1.1. Use it for legacy devices, broadly compatible IoT brokers, local MQTT servers, and cloud endpoints that expose the MQTT v3 protocol.
Connect Banalytics to an external MQTT broker
The connector is built on the HiveMQ client library. It can publish bytes, subscribe to topic filters through listener tasks, report connection status, and expose runtime counters for published and received messages.
MQTT 3.1.1
Use the v3 connector when the broker or device documentation lists MQTT 3.1.1 support.
Subscriptions
Attach MQTT Topic Listener tasks to turn incoming MQTT messages into Banalytics events.
Publishing
Use MQTT Set State actions to send commands, states, or small telemetry messages through this connector.
Adding an MQTT v3 connector
Choose the broker endpoint
Set host and port from the broker documentation. Use localhost for a local Banalytics MQTT Server on the same host, or a LAN/cloud hostname for external brokers.
Set a stable client ID
Many brokers use clientId to track sessions and reject duplicate active clients. Choose a predictable ID per connector instance.
Configure authentication
Use username/password authentication for broker-level credentials, or TLS/mTLS when certificate-based security is required.
Add listener tasks or actions
Use MQTTTopicListenerTask for inbound topics and MQTTSetStateAction for outbound state changes or device commands.
Choosing MQTT v3 for common integration paths
Legacy IoT broker
Use v3 when a gateway, PLC bridge, embedded broker, or cloud service supports MQTT 3.1.1 but not MQTT 5.
Local Banalytics broker
Connect to an MQTT Server using localhost or the LAN address. Use the matching plain or TLS port.
Cloud broker
Use the hostname, port, client ID, TLS, and authentication scheme provided by the cloud MQTT service.
TLS, mTLS, and username/password
clientAuthentication, set username and password, and keep mTLS disabled.useSsl and select a client keystore when the broker requires encrypted transport or certificate trust material.useSsl and mtlsAuthentication, then select a keystore that contains the client key and certificate.Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
MAC address | Yes | Device MAC address shown as read-only metadata. | Auto |
Title | Yes | Human-readable connector name inside Banalytics. | None |
Host | Yes | MQTT broker hostname or IP address. | localhost |
Port | Yes | MQTT broker port. Allowed range is 1-65535. | 1883 |
SSL/TLS | Yes | Enables SSL/TLS encrypted connection to the broker. | false |
mTLS authentication | Conditional | Enables mutual TLS client certificate authentication. Visible when SSL is enabled. | false |
Client keystore | Conditional | Reference to a JKS keystore that provides client certificate or trust material. Visible when SSL is enabled. | None |
Keystore Password | Conditional | Password for the selected client keystore. Visible when SSL is enabled. | None |
Username/password authentication | Conditional | Enables MQTT username/password authentication. Visible when mTLS is disabled. | false |
Client ID | Yes | Unique MQTT client identifier used by the broker for session tracking. | None |
Username | Conditional | MQTT authentication username. Visible when client authentication is enabled and mTLS is disabled. | None |
Password | Conditional | MQTT authentication password. Visible when client authentication is enabled and mTLS is disabled. | None |
Keep Alive Interval (sec) | Yes | Ping interval used to detect broken links. Allowed range is 5-600 seconds. | 60 |
Clean Session | Yes | Starts without broker-side session state when enabled. | true |
Connection Timeout (sec) | Yes | Startup connection timeout. Allowed range is 1-60 seconds. | 10 |
Session and connection tuning
Clean session
Keep cleanSession=true for stateless telemetry and command publishing. Set it to false only when broker-side subscriptions or queued QoS messages should survive reconnects.
Keep-alive interval
Short intervals detect broken links sooner; longer intervals reduce network chatter on slow or metered networks.
Connection timeout
Increase timeout for slow VPN, cellular, or satellite links so startup does not fail too aggressively.