On a live broker, sensors/+ is one level (sensors/lab yes, sensors/lab/temp no). sensors/# is the remainder of the path, including zero extra levels depending on how you read the spec in the wild—people argue about sensors/# vs sensors. # as the whole filter is “everything,” except that a real broker will not deliver $SYS/... on a # subscription. A file on disk has no $SYS policy. If the line is in the dump, a filter is just a function of two strings.

I first filtered with str.startswith, which is the wrong model for topic levels. topic.startswith("sensors") matches sensors_backup/foo. topic.startswith("sensors/") misses a topic that is exactly sensors. Treating # as any substring matches payloads, comments, and the word hash.

What goes wrong with regex: # is not “rest of path.” + is not “any characters.” A regex you write in thirty seconds will accept sensors/lab/temp for sensors/+ unless you anchor levels on /.

mqttlog implements the level walk in topic_match (mqttlog/record.py). Split both strings on /. + consumes one level. # is only legal as the last token and then succeeds. If the pattern is exhausted, the topic must be exhausted too—otherwise sensors/+ would accept sensors/lab/temp. Tests in tests/test_record.py are the cases that bit me, not a tutorial:

sensors/lab/temp  vs  sensors/#     → True
actuators/fan     vs  sensors/#     → False
sensors/lab       vs  sensors/+     → True
sensors/lab/temp  vs  sensors/+     → False

mqttlog csv and replay call that same topic_match:

$ PYTHONPATH=. python3 -m mqttlog csv lab.log --topic 'sensors/#' --out -
$ PYTHONPATH=. python3 -m mqttlog replay lab.log --topic 'sensors/+' --out out/

I also write comments in dumps (# swapped DHT at 20:04). A strict “three fields or die” parser raises on those. Skipping # and blank lines when slurping a whole file is not the interesting part of this tool. The interesting part is that the filter you would have used on mosquitto still means the same thing on a file from last weekend.

A 30-line filter_sensors.py is what I used before the package existed. It implements “starts with sensors/” only. It does not implement +. If you care about the difference, use the library.

Code, MIT, CI: nolan-alexander/mqttlog. I want that difference (file vs broker, + vs #) to be the thing a hiring reader remembers, not that I wrapped str.split in a module.

If the tests require the breadboard, they will not run on a PR. If they do not run on a PR, the CI badge is decoration. I wanted the opposite: a skeptical skim of mqttlog should see unittest actually exercise rotation, topic filters, and the CLI.

The cheap way out is to check in one golden sample.log and only test parse. That misses the rotator. Rotation depends on byte counts, not on “a file exists.” The tests write records in a temp dir with --max-bytes 40 so a handful of lines must spill into mqttlog-001.log. If that test only ran when I had the DHT plugged in, it would not exist.

mqttlog sim is a fixture generator, not a digital twin. It emits lab temp, RH, and a door contact on a 15s cadence in the same line format as a live dump. Door is open every fourth tick so the CSV is not a constant. Temp walks in 0.3° steps because a flat 20.0 looks like I forgot to write the loop. It is fake on purpose. CI should not pretend it smelled the room.

$ PYTHONPATH=. python3 -m mqttlog sim --count 8 --out /tmp/sim --max-bytes 120
wrote 8 records to /tmp/sim/mqttlog-001.log

The hardware still taught me something tests cannot. The CP2102 and the radio shared a cheap hub. Meter on TX dropped to 4.4V when the radio keyed. Python was innocent. Baud 115200 dropped characters; 57600 held. I keep that in a private note so the next time a dump looks “corrupted” I check 5V before I check select(). That story does not go in CI. CI gets the simulator.

python -m unittest discover -s tests -v covers parse, +/#, rotation, and CLI replay/csv. .github/workflows/ci.yml runs it on push. If you work on firmware-adjacent Python and you have been burned by “the test needs the board,” that is the design I am advertising: keep the I/O in files, fake the stream, never make Actions SSH to a Pi in my apartment.

On the bench Pi I run mosquitto on 1883 with no TLS (it is a LAN I can see). For a long time the “history” was a tmux pane:

mosquitto_sub -h 127.0.0.1 -t '#' -v >> ~/captures/lab.log

-v is topic, a space, then the payload. That looks like a log file until you treat it like one.

Payloads have spaces. A door payload of open with bounce makes awk '{print $3}' a lie. I leave notes in the file. # swapped DHT, yellow is data is not a topic. Replaying through a broker to filter is theatre. If the bytes are already on disk, starting mosquitto so I can subscribe to sensors/# is a round trip I do not need.

I tried the usual Unix-shaped mistakes. grep sensors lab.log also matches sensors inside a payload. awk '$2 ~ /^sensors\//' drops my comments and still cannot see a payload as one field. I once passed sensors/# to awk as if # were a regex. It is not; in MQTT it is a wildcard that only means something at a topic-filter parser.

Existing tools did not fit this job. MQTT Explorer wants a live session. mosquitto_sub is live. sqlite-plus-broker is a project, not a Thursday night. I wanted a line format I could tail, grep (carefully), rotate, and CSV without standing anything up.

The line format I settled on is three fields, payload allowed to contain spaces:

<iso-timestamp> <topic> <payload...>

Topic is one token. Payload is the rest of the line, spaces included. Lines starting with # are mine, not the bus. Rotation is by byte size because a 1 Hz stream fills a 4G card in a week if you never cut it (I did that once).

mqttlog is the CLI I use for that file. MIT, unittest, GitHub Actions. It is not a broker, not a time-series database, and not a replacement for MQTT Explorer. It is the missing “I already have the dump” path.

$ PYTHONPATH=. python3 -m mqttlog replay lab.log --topic 'sensors/#' --out logs/
wrote 128 records to logs/mqttlog-000.log

$ PYTHONPATH=. python3 -m mqttlog csv lab.log --topic 'sensors/+' --out -
ts,topic,payload
2026-10-13T20:11:00-07:00,sensors/lab/temp,20.0

A real capture (comments included) is in this gist. If you do the same thing with >> lab.log and then wish you had sensors/# after the fact, that is the hole this fills. I am in Portland; if you hire people who write small Python around sensors and serial, that repo is the thing I would rather you clone than a LeetCode dump.