MQTT Simulator

A lightweight, easy-to-configure MQTT simulator written in Python 3 for publishing JSON objects to a broker, simulating sensors and devices.

Features • Getting Started • Configuration • Main contributors

Features

• Lightweight and easy-to-configure simulator for publishing data to an MQTT broker
• Simple setup with a single JSON configuration file
• Publish data on predefined fixed topics
• Publish data on multiple topics that have a variable id or items at the end
• Simulated random variation of data based on configurable parameters
• Real-time event logging during simulation

Getting Started

Running using Python

Run the simulator with the default settings file (config/settings.json):

python3 mqtt-simulator/main.py 

Or specify a custom settings file:

python3 mqtt-simulator/main.py -f <path/settings.json>

To install all dependencies with a virtual environment before using:

python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt

Running using uv

Run the simulator with uv, a fast Python package and project manager - no need to manually setup a virtual environment:

uv run mqtt-simulator/main.py -f <path/settings.json>

Running using Docker

Additionally, you can run the simulator via Docker using the provided Dockerfile.

Build the image:

docker build -t mqtt-simulator .

Run the container:

docker run mqtt-simulator -f <path/settings.json>

Configuration

See the configuration documentation for detailed usage instructions.

You can also check a full settings file example at: settings.json.

Below is a minimal configuration file that connects to the mqtt.eclipseprojects.io broker and publishes data to the /place/roof and /place/basement topics. The simulator generates temperature variations based on the provided parameters:

{
  "BROKER_URL": "mqtt.eclipseprojects.io",
  "TOPICS": [
    {
      "TYPE": "list",
      "PREFIX": "place",
      "LIST": ["roof", "basement"],
      "TIME_INTERVAL": 8,
      "DATA": [
        {
          "NAME": "temperature",
          "TYPE": "float",
          "MIN_VALUE": 20,
          "MAX_VALUE": 55,
          "MAX_STEP": 3,
          "RETAIN_PROBABILITY": 0.5,
          "INCREASE_PROBABILITY": 0.6
        }
      ]
    }
  ]
}

Main contributors