Book a consultation

HiveMQ Community Edition and HiveMQ's Open-Source Footprint

HiveMQ MQTT Client, MQTT CLI and Swarm: Testing a UNS Before Go-Live

The HiveMQ MQTT Client for Java, MQTT CLI, Swarm and Testcontainers explained, with a pre-go-live test plan for a Unified Namespace and where it gets hard.

Vladimir Romanov


How does an engineering team prove an MQTT broker and a Unified Namespace before the first PLC connects? With a small set of ordinary tools: a scripted client that publishes the messages the plant will publish, a command line client for quick checks, a load tool for rate and failure tests, and a test harness that starts a disposable broker. HiveMQ publishes several of these. This page describes each, what is sourced about it, and a test plan for a namespace. It belongs to HiveMQ’s open-source footprint and the HiveMQ hub.

ToolLicenceJob in a testStatus as of 20 November 2026
MQTT Client for JavaApache 2.0Scripted publishers and subscribers1.4.2 in README examples, no date
MQTT CLIApache 2.0Quick publish, subscribe and broker feature testRelease version not shown
HiveMQ SwarmCommercial, licence not confirmedLoad and reliability testsVersion and licence unconfirmed
MQTT EssentialsFree education materialTeam onboardingPart 1 dated 9 February 2026
Testcontainers moduleNot applicableDisposable broker in Java testsHiveMQ repository archived 25 October 2023

The HiveMQ MQTT Client for Java

The HiveMQ MQTT Client is an open-source Java library under the Apache License 2.0. Its GitHub README states support for MQTT 3.1.1 and 5.0 and a Java 8 or higher requirement. It offers three API styles: blocking, which the README says is meant for quick starts and testing; asynchronous, with futures and callbacks; and reactive, with RxJava and Reactor support. The README examples name version 1.4.2, with no release date on the page, so check the releases page before pinning.

For a test rig the useful parts are the ones a real client needs too. The README describes automatic reconnect with message redelivery, resubscribe when a session has expired, backpressure for QoS 1 and 2 (with possible drops at QoS 0), TLS up to 1.3 with mutual authentication, WebSocket support as an optional module, and MQTT 5 enhanced authentication. In our view, a test client that exercises the same TLS and authentication path as the production clients finds more problems than one that connects anonymously on a lab port.

Where to be careful. A Java library is only as maintained as its dependencies, so keep the client current and scan it like any dependency.

MQTT CLI

MQTT CLI is HiveMQ’s Apache 2.0 command line client, supporting MQTT 5.0 and 3.1.1. The GitHub page lists four commands: pub to publish, sub to subscribe and print messages, sh for an interactive shell, and test, which runs tests against a broker to determine its features and limitations. The page shows no release version, so install from the project’s releases and note the version in your test record.

A commissioning engineer would use it like this: subscribe to # on a lab broker to watch a topic tree fill in, publish a retained message to a topic and subscribe from a second terminal to prove it is delivered on connect, and run test against the broker to see which MQTT features it reports. Use # only on a test broker with a test account; on a production broker a wildcard subscription from an engineer’s laptop is the same exposure that security studies flag in misconfigured brokers.

Clamp meter lying among coiled cables, pliers and a junction box on a tiled floor
Test tools earn their place by being on hand during commissioning: a terminal client is the broker equivalent of a clamp meter.

HiveMQ Swarm and the benchmark claims

HiveMQ Swarm is described on its product page as a distributed load and reliability testing tool for MQTT systems, meant to find scalability, performance and reliability problems before production. HiveMQ states that it can test millions of MQTT clients, millions of messages and hundreds of thousands of topic names, that scenarios mimicking device behaviour can be reused in a development pipeline, that custom data generators reproduce your data patterns, and that results come with reports and a predefined Grafana dashboard. HiveMQ states deployment to public clouds such as AWS and Azure or on-premise Kubernetes.

HiveMQ also publishes a benchmark page on 10 million connections. Those are vendor numbers, produced on HiveMQ’s chosen hardware and scenario. We did not verify Swarm’s current version or licence, and its documentation root did not load for us. In our view a plant rarely needs millions of clients, and the useful Swarm-style test is smaller: your real client count, your real publish rates, and a deliberate broker or network failure.

MQTT Essentials and Testcontainers

MQTT Essentials is HiveMQ’s education series: ten parts covering the core of MQTT, with Part 1 dated 9 February 2026 on HiveMQ’s blog. The parts include topics and wildcards, QoS levels, persistent sessions, retained messages, Last Will and Testament, and keep alive with client take-over. It is a vendor tutorial, and a good one for onboarding a team before a namespace workshop. The series page numbering is slightly inconsistent, so link to the blog entry rather than a series number.

Testcontainers. HiveMQ’s hivemq-testcontainer repository, which started a broker container for Java tests, was archived on 25 October 2023 and is marked deprecated. Its README says the module moved into the testcontainers-java project from version 1.17.0. For a Java team with automated tests, a disposable broker in a test run is the cheapest way to catch a topic or payload regression. Take the current module from the Testcontainers documentation, not from the archived repository. We did not confirm which broker image the module runs.

How a team tests a UNS before go-live

An illustrative plan for a single site, using the tools above. The example topic names are ours.

Pre-go-live test rig for a Unified Namespace broker Three stages from left to right. Scripted publishers, built with the Java client or MQTT CLI, emulate PLCs and gateways and publish to a test broker that runs the production configuration. Subscribers then check the topic tree, retained messages, permissions and payloads. A load and failure test using a load tool or scripted clients adds rate and forced broker restarts below the broker. Scripted publishers Java client or MQTT CLI emulate PLCs and gateways same TLS and credentials Test broker production configuration same version, same ACLs disposable, no plant link Checking subscribers topic tree as designed retained on connect denied topics stay denied Load and failure stage real client count and publish rate forced broker restart, dropped network Swarm-style tool or scripted clients Run the whole rig before any PLC or gateway connects
The rig is a copy of production in miniature: same broker version and permissions, scripted clients in place of the plant, and a failure stage that is run on purpose.
  1. Fix the namespace on paper. Write the topic tree for one line, for instance enterprise/site1/area1/line1/cell1/status, with the payload shape for each leaf.
  2. Start a disposable broker from the production configuration: the same version, listeners, authentication and topic permissions. Use a throwaway container so a mistake costs nothing.
  3. Publish from scripts that stand in for the PLC and gateway clients, using the Java client for structured tests and MQTT CLI for quick ones. Publish retained messages where the design uses them.
  4. Check delivery. A fresh subscriber should receive the retained state on connect. A client without permission to a topic should be refused, which proves the ACLs.
  5. Check payload rules. Send one well-formed and one malformed payload. If a broker-side validation feature is planned, confirm it rejects the bad one; see Data Hub.
  6. Break it on purpose. Restart the broker, drop the network, and let clients reconnect. Confirm sessions, retained messages and Last Will messages behave as designed, and for Sparkplug that consumers recover state; see Sparkplug on HiveMQ.
  7. Raise the rate to the real client count and publish rate, then to twice that, and watch latency and broker metrics.
  8. Record versions and results, then rerun the rig after any broker or Java upgrade.

On the plant side, the PLC scan and polling choices behind what you publish are covered in PLC scan cycles and polling.

Where it gets hard

  • Test brokers drift from production. A rig built on Community Edition cannot prove clustering behaviour, because CE has no clustering. Match the edition you will run, or state the gap.
  • Emulated clients are kinder than real ones. Real PLCs and gateways reconnect in bursts, publish at odd moments and carry firmware quirks. Pair the rig with a bench test using one real device.
  • Vendor load numbers do not transfer. A benchmark on HiveMQ’s hardware says little about your site network and your payload sizes.
  • Version facts need dating. The client and CLI pages show no release dates, and Swarm’s current version is unconfirmed. Record the exact versions you tested.
  • A passing test is not an audit. For the network zones and exposure around the broker, see OT network segmentation.

Back to the parent, HiveMQ Community Edition and the open-source footprint. The sibling comparison is HiveMQ vs Mosquitto. We design and test MQTT and Unified Namespace architectures as part of IT/OT integration work, and we are independent of HiveMQ with no commercial relationship.

Frequently asked questions

What is the HiveMQ MQTT Client?

It is an open-source MQTT client library for Java, published by HiveMQ under the Apache License 2.0. It supports MQTT 3.1.1 and 5.0, needs Java 8 or higher, and offers blocking, asynchronous and reactive APIs. The README examples show version 1.4.2 with no release date, so check the releases page for the current version.

What is MQTT CLI used for?

MQTT CLI is an Apache 2.0 command-line client from HiveMQ. It publishes and subscribes from a terminal, offers an interactive shell, and has a test command that checks a broker's features and limits. It is useful for quick checks of topics, retained messages and permissions without writing code.

Is HiveMQ Swarm free?

HiveMQ describes Swarm as a distributed load and reliability testing tool, and we found no public price or open-source licence for it. Its product page and HiveMQ's 10 million connection benchmark page are the sources. Treat it as a commercial product and ask HiveMQ about licensing, version and limits before planning a test around it.

How do I test a Unified Namespace broker before go-live?

Run a copy of the production broker configuration, publish scripted messages that match the namespace, and check what arrives: topic tree, retained messages, permissions, payload shape and behaviour when clients drop. Then repeat with realistic message rates and a forced broker restart. Do it before PLCs and gateways connect, not after.

Is the HiveMQ Testcontainers module still maintained?

The hivemq-testcontainer repository was archived on 25 October 2023 and marked deprecated. Its README says the module moved into the testcontainers-java project from version 1.17.0. Use the Testcontainers documentation for the current HiveMQ module rather than the archived repository.

References and further reading

  1. hivemq-mqtt-client on GitHub · HiveMQLicence, API styles, TLS and reconnect behaviour.
  2. mqtt-cli on GitHub · HiveMQCommands and the broker test function.
  3. HiveMQ Swarm · HiveMQHiveMQ's own description of the load testing product.
  4. Benchmark: 10 million MQTT connections · HiveMQA vendor benchmark. Read the setup before reusing the number.
  5. Introducing the MQTT Protocol: MQTT Essentials, Part 1 · HiveMQFirst of the ten-part education series.
  6. hivemq-testcontainer on GitHub (archived) · HiveMQDeprecation notice and move to testcontainers-java.

← Open Source

Have a project that needs technical ownership?

Send us the situation. If it is not something we should take on, we will say so.

The Plant-Side Brief

The weekly brief for the people who own a plant’s control systems.

One email every Wednesday for engineering and operations leaders responsible for controls, SCADA, MES and OT networks. Skim the top in two minutes; read the Deep Dive when you have fifteen.

  • One modernization problem, worked through to cost, risk and a schedule you can defend. The Deep Dive.
  • End-of-support dates before they reach your plant Windows, servers, controllers and HMI software. Lifecycle Watch.
  • A checklist your engineers can run that week not a framework to admire. Field Kit.
  • Every number sourced, no vendor agenda we are paid by plants, never by vendors.