MQTT Server
The MQTT Server component turns the Banalytics Agent into an embedded MQTT broker for IoT, industrial, and local automation workloads. It supports publish/subscribe messaging without requiring an external broker, and can be configured with TLS, password authentication, mutual TLS, WebSocket access, persistence, and runtime statistics.
Run an embedded MQTT broker inside the agent
MQTT Server uses the Moquette broker engine to accept MQTT clients, route published messages to subscribers, track connected clients, and expose operational API methods. It can serve local-only clients, LAN devices, browser-based WebSocket clients, or industrial edge systems that need a broker close to the data source.
Publish/subscribe
Devices, scripts, connectors, and Banalytics components exchange messages through MQTT topics.
Secure transport
The broker can terminate SSL/TLS and optionally require mutual TLS client certificates.
Runtime visibility
The UI tracks connected clients, users, topics, message counters, last payloads, and timestamps.
ANONYMOUS only on loopback, a trusted lab network, or an isolated segment. Any reachable client can connect and publish or subscribe when anonymous access is enabled.
Adding an MQTT server
Choose the bind address
Use 127.0.0.1 when only local Banalytics components, scripts, or containers should connect. Use 0.0.0.0 when devices on the LAN or VPN must reach the broker.
Set MQTT and WebSocket ports
Use 1883 for a standard MQTT listener unless it conflicts with another broker. Enable WebSocket transport only when browser-based MQTT clients need to connect.
Select authentication
Start with PASSWORD or MTLS for reachable networks. Use a DataSource for identity lookup when password or certificate authentication is enabled.
Decide on persistence and payload size
Enable persistence when broker state should survive restarts, and increase the maximum message size only for clients that really publish larger payloads.
Choosing settings for common deployments
Local embedded broker
Bind to 127.0.0.1 when the broker is only a local message bus for Banalytics components, scripts, or containers on the same host.
LAN IoT hub
Bind to 0.0.0.0, use stable topic prefixes such as site/zone/device/state, and connect sensors or controllers directly to the agent.
Browser clients
Enable WebSocket transport when dashboards, browser tools, or web-based MQTT clients need to connect through WS or WSS.
Industrial edge scenarios
Broker near the equipment
Run the broker on the same edge host as acquisition and processing tasks to reduce dependency on a remote broker during network interruptions.
Shared automation bus
Use the server as a central local message bus for PLC gateways, sensors, Banalytics actions, and external automation services.
Predictable topic structure
Use explicit prefixes by site, zone, line, device, and signal type so topic statistics and downstream automation remain readable.
Authentication and transport protection
Choose authentication based on who can reach the broker and how devices should prove their identity. For untrusted or shared networks, enable TLS and avoid anonymous access.
serverKeystoreThing must contain the server key material, and keystorePassword must match the keystore and key manager password. PASSWORD and MTLS modes require a working DataSource.
Balancing restart tolerance and message size
Persistence and payload limits affect both reliability and resource usage. Keep defaults for normal telemetry, then increase only when the client workload actually requires it.
Persistent broker state
Enable persistence when retained messages, subscriptions, or broker state should survive restart.
Large payload devices
Increase mqttMaxMessageSizeKb for JSON snapshots, device shadows, images, or binary payloads.
Memory protection
Keep the limit small for ordinary telemetry to reduce accidental memory pressure from oversized messages.
Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
ID | Yes | A unique identifier automatically generated for this component instance. Read-only. | Auto |
Title | Yes | Display name of this MQTT broker inside Banalytics. | None |
Host | Yes | Bind address for the MQTT listener. Use 127.0.0.1 for local-only access or 0.0.0.0 for LAN/VPN access. | 0.0.0.0 |
Port | Yes | MQTT listener port. Allowed range is 1-65535. | 1883 |
Enable SSL | Yes | Enables SSL/TLS on the MQTT listener. Required for mutual TLS authentication. | false |
Server Keystore | Conditional | Reference to a JKS keystore component providing the server private key and certificate chain. Visible when SSL is enabled. | None |
Keystore Password | Conditional | Password for the selected server keystore. Visible when SSL is enabled. | None |
WebSocket Enabled | Yes | Enables WebSocket transport for browser-based MQTT clients. | false |
WebSocket Port | Conditional | WebSocket listener port. If SSL is disabled the listener is WS; if SSL is enabled it is WSS. Visible when WebSocket is enabled. | 8083 |
Authentication Type | Yes | Authentication mode: ANONYMOUS, PASSWORD, or MTLS. MTLS requires SSL. | ANONYMOUS |
Data Source | Conditional | DataSource used to look up user credentials or accepted client certificates. Visible when authentication is PASSWORD or MTLS. | Local data source |
Persistence Enabled | Yes | Enables on-disk broker persistence for retained messages, subscriptions, or broker state. | false |
Max message size (kb) | Yes | Maximum accepted MQTT message size in kilobytes. Allowed range is 8-10240. | 16 |
Operations available from the server UI
The component exposes operational methods for status, client listing, client disconnection, user and topic listing, and internal message publishing.
Restart behavior and troubleshooting
Restart-required settings
Changing host, ports, SSL, WebSocket, authentication, persistence, keystore, data source, or maximum message size requires a server restart because these values are passed to the broker at startup.
Authentication lookup failures
Check that the DataSource is available and that identities are enabled for this server instance when password or certificate authentication fails.
mTLS certificate issues
Verify the presented client certificate serial number and issuer DN match the registered identity metadata.
Related MQTT pages
Use these pages to connect the embedded broker to Banalytics MQTT clients, incoming topic events, and outbound publishing actions.