Overview
If an MQTT project does not already have a formal points list, the fastest intake path is often to subscribe to the broker, capture the topics and representative payloads, and send that capture to Chipkin support. We can use that file as the starting point for a QuickServer configuration that republishes the data into BACnet or Modbus.
This procedure uses mosquitto_sub to write one JSON object per line into a .jsonl capture file. Each line includes a timestamp, topic, QoS, retained flag, and payload.
Before You Start
- Confirm the broker hostname or IP address.
- Confirm the port number and whether the broker uses plain MQTT (
1883) or MQTT over TLS (8883). - Confirm the topic filter you want to capture. Use
#only if you really want the full broker tree. - Confirm whether the broker requires a username and password.
- Make sure you can leave the capture running long enough to see all required topics at least once.
[!NOTE] If the publishers use retained messages, you may receive a useful current-state snapshot as soon as you subscribe. If the publishers do not retain messages, you must wait for each topic to publish again.
[!CAUTION] A broker capture may include credentials, asset names, site naming conventions, or sensitive operational values. Review the topic scope before capturing
#on a production broker.
Step 1: Install Mosquitto
Download and install Mosquitto from mosquitto.org/download.
The article uses the mosquitto_sub.exe command-line subscriber that is included with the Windows installer.
Step 2: Open Windows Terminal
Open Windows Terminal and start a PowerShell tab.
The commands below deliberately call cmd.exe /c for the final redirection step. That avoids PowerShell writing the log as UTF-16, which can make the .jsonl file appear to contain non-printable characters or null bytes in some editors and tools.
Step 3: Start the Capture
Update the broker settings, then run this command:
cmd.exe /c '"C:\Program Files\mosquitto\mosquitto_sub.exe" -h broker.hivemq.com -p 1883 -t "test/#" -F "%j" >> "%USERPROFILE%\Desktop\capture.jsonl"'If your broker requires authentication, add the username and password options:
cmd.exe /c '"C:\Program Files\mosquitto\mosquitto_sub.exe" -h broker.hivemq.com -p 1883 -t "test/#" -u "mqtt-user" -P "mqtt-password" -F "%j" >> "%USERPROFILE%\Desktop\capture.jsonl"'If your broker uses MQTT over TLS on port 8883, use the secure port and add certificate options if the broker uses a private CA:
cmd.exe /c '"C:\Program Files\mosquitto\mosquitto_sub.exe" -h broker.hivemq.com -p 8883 -t "test/#" --cafile "C:\certs\broker-ca.pem" -u "mqtt-user" -P "mqtt-password" -F "%j" >> "%USERPROFILE%\Desktop\capture.jsonl"'What Each Parameter Does
| Parameter | Meaning | Notes |
|---|---|---|
mosquitto_sub.exe | Starts the MQTT subscriber client | Update the path if Mosquitto was installed elsewhere |
-h broker.example.com | Broker hostname or IP address | Replace with the actual broker target |
-p 1883 | Broker port | Typical values are 1883 for plain MQTT and 8883 for MQTT over TLS |
-t "#" | Topic filter to subscribe to | # captures the full tree; use a narrower filter when possible test/# |
-u "mqtt-user" | Username | Optional; only use if the broker requires login |
-P "mqtt-password" | Password | Optional; only use with -u |
--cafile "C:\certs\broker-ca.pem" | CA certificate file | Optional; needed when the broker uses TLS with a private or non-default CA |
-F "%j" | Output format | %j produces JSON output with an escaped payload, which is safer than building JSON manually |
cmd.exe /c '...' | Runs the subscription command under Command Prompt | Keeps the file output in normal text form instead of PowerShell UTF-16 redirection |
>> "%USERPROFILE%\Desktop\capture.jsonl" | Appends output to a file | Creates capture.jsonl on the desktop if it does not already exist |
Why %j Is Better Than a Hand-Built JSON String
Mosquitto supports a built-in JSON formatter. Using -F "%j" avoids the common problem where a payload contains quotes or special characters that would break hand-built JSON.
Each output line will look similar to this:
{"tst":"2026-04-09T10:14:52.000000-0700","topic":"building/ahu-1/supply-air-temp","qos":0,"retain":0,"payload":"55.2"}Step 4: Let the System Publish Long Enough
Leave the subscriber running until you are confident every required topic has published at least once.
This matters because many MQTT systems publish in one of these patterns:
- Fixed interval, such as every 5 seconds, 1 minute, or 15 minutes
- Change-of-value only, where no new message appears until the source value changes
- Retained-message startup snapshot plus periodic updates
- Daily or shift-based status reporting
If your publishers only transmit on change, force representative state changes while the capture is running. For example, adjust a setpoint, toggle a command, or wait for equipment state to move through occupied and unoccupied modes. The goal is not just to see topic names. The goal is to capture realistic payload examples that show data type and expected value range.
[!TIP] For a usable QuickServer intake, try to capture at least one example of each major point type: temperatures, setpoints, status booleans, alarms, counters, and command topics if writes are expected later.
Step 5: Stop the Capture and Review the File
Press Ctrl+C in the terminal to stop the subscriber.
The capture file will be on your desktop as capture.jsonl unless you changed the filename.
You can inspect the first few lines in PowerShell with:
Get-Content "$env:USERPROFILE\Desktop\capture.jsonl" -TotalCount 5You can count the total number of captured lines with:
(Get-Content "$env:USERPROFILE\Desktop\capture.jsonl" | Measure-Object).CountDuplicate topics are normal. A live broker capture usually includes multiple samples for the same topic. That is useful because it shows whether values are static, boolean, enumerated, numeric, or structured JSON.
If you open the file and see null bytes or non-printable characters between each letter, rerun the capture using the cmd.exe /c form shown above. That symptom usually means PowerShell handled >> and wrote the file as UTF-16LE instead of plain UTF-8 or ANSI-style text.
What to Send to Chipkin Support
Send these items together:
- The
capture.jsonlfile - The broker hostname or IP address and port
- The topic filter used during capture
- Any authentication or TLS requirements that apply to the real deployment
- A short note describing the target conversion, for example MQTT to BACnet/IP or MQTT to Modbus TCP
- Any known point-count expectation or destination BMS point naming rules
[!TIP] Large
.jsonlcaptures usually compress very well. If the file is too large for email or portal upload, zip it before sending.
On Windows, you can create a zip archive with PowerShell:
Compress-Archive -Path "$env:USERPROFILE\Desktop\capture.jsonl" -DestinationPath "$env:USERPROFILE\Desktop\capture.zip" -ForceThat is usually enough for Chipkin to scope the job and start building the QuickServer configuration file.
Troubleshooting
| Symptom | Likely Cause | Action |
|---|---|---|
| File is not created | Wrong output path or Mosquitto path | Confirm the mosquitto_sub.exe path and desktop path, then run again |
| Broker connection fails immediately | Wrong host, port, username, password, or TLS settings | Recheck broker details and test with a known-good topic |
| Capture file stays empty | No publishers are active or the topic filter is too narrow | Broaden the filter or wait for the source system to publish |
| Capture includes too much traffic | Topic filter is too broad | Replace # with the exact site or equipment subtree |
Log shows non-printable characters or 00 bytes | PowerShell redirected native command output as UTF-16LE | Run the cmd.exe /c version of the command so cmd handles >> |
| Payloads are hard to interpret | The payload is structured JSON or vendor-specific text | Keep the raw capture anyway; the topic name and sample payload still help with intake |