mqtt-tap — print a building broker's topic tree, read-only

One file, standard library only. No pip, no paho-mqtt, no broker client library, nothing to install on a machine you do not own. It was written and run on Python 3.12.

--port is 1883 by default and 8883 with --tls. --user takes a username and --pass-env takes the name of an environment variable to read the password out of, so the password never appears in ps output or in your shell history. TLS is --tls, with --ca for a private site certificate authority, --cert and --cert-key for mutual TLS, and --insecure to skip verification, which warns you loudly about what you just gave up. --topic is repeatable and sets what is subscribed to; --filter is a different thing, a client-side narrowing that only applies to --watch.

Ask the person who owns the broker before you connect to it — not because the tool is dangerous, but because an unannounced new client on a building broker is the sort of thing that gets a firewall rule written about you.

The tree. Every topic that published while the tap was running, collapsed into its levels, so a broker somebody else designed becomes legible in a minute rather than a morning. With a count and a rate per topic, which is what tells you the difference between a sensor, a heartbeat and a gateway republishing its whole state every second. The rate is messages divided by the window, and the output says so: it is not an instantaneous rate.

The payload shape, guessed from the bytes, because MQTT 3.1.1 carries no type information at all: a JSON object, a JSON array, a bare number, a boolean, a string, an empty payload, or binary with a byte count and the first bytes in hex. This is the question that decides how much work an integration is, and it is nearly always answered wrongly from the documentation.

The last value on each topic, so you can see whether the units are what the schedule claims and whether the number is plausible.

Which topics were retained. The broker hands a new subscriber the last retained message on every matching topic immediately, then nothing more until someone publishes. A topic that arrives in that first instant and never updates again is the shape of a dead sensor, a decommissioned gateway or a device somebody unplugged in March — and it is the finding people are most surprised by, because every dashboard upstream is still showing that value as current. What the tool reports is "nothing updated this while I watched", which is evidence; it does not tell you a sensor is dead, and it says so in the output.

Real output, from the fixture broker that ships with the tool's test suite, bound to 127.0.0.1. No real broker was contacted at any point; the survey below is a twelve-second window, and the per-topic table and the Sparkplug summary that followed it are trimmed here for width:

And --stale on a ten-second window over the same fixture. Note what the last line does, which is refuse to draw the conclusion the table is inviting:

What the fixture did cover, deliberately awkwardly: a PUBLISH written one byte at a time and several PUBLISHes in one read; a 27 kB payload reassembled byte for byte; a multi-byte remaining-length varint, cross-checked against a second implementation over 5,010 lengths; QoS 1 delivery with one PUBACK each; every MQTT 3.1.1 connect-refusal code turned into a sentence; a broker that refuses a topic filter, and one that accepts # and then sends nothing; a keepalive that goes unanswered; a broker that hangs up mid-window; non-ASCII topics and payloads; and the $SYS tree correctly withheld from a wildcard subscription.

TLS was verified against a certificate authority and a certificate pair generated locally for the test, on loopback: verification passing, verification correctly failing on an untrusted certificate, --insecure warning and proceeding, and mutual TLS with a client certificate. It has not been tested against a public certificate chain, an intermediate, a commercial broker's TLS, or a TLS 1.2-only server.

Not tested, and therefore not claimed: any real broker product; MQTT 5 beyond accepting a connect acknowledgement; QoS 2; session resumption; IPv6; Windows; macOS; and scale — the largest survey run had fifteen topics over a few seconds of fixture traffic. There is no performance number on this page, because none was measured anywhere that would make one meaningful.

The usual findings are a topic tree nobody documented, payloads that do not match the integration spec, a gateway republishing far more often than anything needs, and retained values that stopped being true a long time ago.

Getting that into a station properly is a module or driver job more often than people expect, because the stock MQTT driver has real limits and a payload decoder is usually where the work is: what the Niagara MQTT driver will and will not do is the honest version, and bringing LoRaWAN and MQTT data into a station covers decoding, topic design and buffering. If the traffic is going the other way, getting data out of a station is the one to read.

Send the tree and the payload sample. Whether it is a driver, a decoder or a topic design somebody needs to be talked out of is usually clear in half an hour.

Reading an unfamiliar MQTT broker in a building is the protocol behind this page: how the retain flag lets you tell a stored value from a live one, why an empty payload is not a bug, and the two ways a read-only client can still break something. The other program is bacnet-sweep, and both of them are listed here.

Published here so the download is checkable rather than trusted. Both figures are read off the file served at /tools/mqtt-tap.py when this page is built, so they cannot disagree with it.

To check it, on Linux sha256sum mqtt-tap.py, on macOS shasum -a 256 mqtt-tap.py, on Windows certutil -hashfile mqtt-tap.py SHA256. A different digest means a different file — not necessarily a hostile one, but not this one.