MQTT Simulator

A MQTT simulator for publishing to a broker by simulating sensors, devices, and senarios.

mqtt-sim reads a TOML file and starts publishing realistic MQTT traffic: device state, sensor readings, lifecycle messages, file payloads, bursts, slow streams, fast streams, whatever you need for testing or demos.

Features | Quick Start | Install and Run | Configuration | History and Alternatives

Features

• Easy to configure simulator for publishing data to a MQTT broker
• Supports multiple brokers, clients, streams, and payload types in one config file
• Inline table output while the simulator is running

Quick Start

If you just want to see it work, use a broker on localhost:1883 and this config (better examples under examples/*):

config_version = 1

[brokers.main]
host = "localhost"

[clients.main]
broker = "main"
id = "demo-${device_id}"

[[streams]]
client = "main"
topic = "demo/${device_id}/status"
every = "1s"

[streams.expand]
device_id = { range = [1, 3] }

[streams.payload.json]
ok = { toggle = true }
temperature_c = { random = { type = "float", min = 18, max = 32, precision = 1 } }
ts = { time = "unix" }

Once installed, run:

mqtt-sim validate -c config.toml
mqtt-sim run -c config.toml

No broker running yet? If you cloned this repo, the fastest local one is:

docker compose up -d broker

Install and Run

Pick the path that matches how you want to use it.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install mqtt-simulator
mqtt-sim --help

mqtt-sim validate -c config.toml
mqtt-sim run -c config.toml

Configuration

See the configuration documentation for the current schema and configurable options.

For the schema used by the CLI, start with:

• examples/basic.toml
• examples/README.md

If you are mostly interested in the expression generator, there is a focused page for that too:

• docs/math_expression.md

The shipped examples are heavily commented on purpose, so you can read them top-down and copy only the sections you need.

If you want the full schema, see docs/configuration.md. If you just want something to steal and tweak reference existing config, the examples folder is usually the better starting point.

History and Alternatives

There are already great MQTT tools for quickly publishing something to a MQTT broker, but most of them solve a different problem than this project.

A big inspiration here is the original DamascenoRafael/mqtt-simulator project that I forked from. I wanted a quick way to simulate various types of devices and payloads close to the real devices I use at work.

Another big inspiration is EdJoPaTo/mqttui, which is a fantastic Rust TUI for MQTT. It is fast and great for interactive MQTT work in the terminal.

Before that, tools like MQTT Explorer, EasyMQTT, and mosquitto_pub / mosquitto_sub were all useful depending on the situation. There are also feature-rich CLI options like HiveMQ MQTT CLI and MQTTX CLI. They are great tools, but for my use case they are too complex. I wanted something simple.

That’s why this project exists: a MQTT simulator focused on generating many configurable payload streams (including file/binary payloads) with a inline status view. It is not trying to replace mqttui or other MQTT clients/viewers, it is focused on simulation.