MQTT Simulator
A virtual device lab to simulate MQTT device behavior, edge cases and failures — so you can test faster, automate scenarios and ship integrations with confidence.
-
Scenario-driven testing (faults, delays, reconnect storms)
-
Snapshots for reproducible debugging & regression
-
Automation-ready for CI/CD pipelines
SPX platform overview
SPX is the engineering environment behind this MQTT simulator — a portable, Docker-based virtual device lab for building and testing realistic device behavior. It supports multiple industrial protocols, code-defined simulations, physics-driven dynamics, and scenario-based validation, so you can run model-in-the-loop style workflows without a physical lab.
Everything is designed for reproducibility and automation, with an LLM-friendly project structure that helps you extend models, scenarios, and tests faster — from engineers, for engineers.
Technical capabilities
These capabilities focus on repeatability, protocol realism, and automation—so you can ship embedded integrations with confidence.
SPX lets you simulate MQTT devices with protocol-level behavior that matters in production:
-
QoS per binding (0/1/2) with validation — publish and subscribe flows use the configured QoS.
-
Retained messages per binding — ideal for state topics (e.g., last known sensor values).
-
LWT / availability support — simulate online/offline signaling reliably (including Home Assistant-style availability for mqtt-ha).
-
Device-like topic structure — model state and event topics separately for realistic consumers.
communication:
- mqtt:
broker: "mqtt.example.local"
port: 1883
client_id: "spx-demo-1"
lwt:
topic: "spx/devices/demo/status"
payload: "offline"
qos: 1
retained: true
bindings:
- name: temperature
direction: outbound
topic: "spx/devices/demo/temperature"
value_codec: float
qos: 1
retained: true
read_attribute: "#attr(temperature_c)"
- name: setpoint
direction: inbound
topic: "spx/devices/demo/setpoint"
value_codec: float
qos: 1
retained: false
write_attribute: "#attr(k__setpoint_c)"-
When you debug integrations, observability is everything. SPX supports logging that helps you understand what happened and why:
• Per-topic message visibility — inspect what is published/subscribed on specific topics.
• Structured logs suitable for debugging and reporting (payloads, timing, direction).
• Repeatable runs — compare logs between runs to detect regressions.
• Integration-friendly — logs can be used as evidence in QA workflows and troubleshooting.
SPX is not only message simulation — it can model device behavior as it would occur in the real world:
• Environmental dynamics (e.g., temperature trends, wind/rain patterns, occupancy changes).
• Noise and signal imperfections — emulate sensor noise, drift, or jitter.
• Device response logic — state machines and behavior rules that match real equipment.
• More realistic testing — validate filtering, smoothing, thresholding, alarms, and UI logic.This capability is shared across SPX protocol modules and packs — so your tests stay realistic even when you switch protocols.
actions:
- noise: $out(temperature_c)
name: Temperature Sensor Noise
description: Adds small proportional jitter to temperature.
std: 0.02
mode: proportional
Scenario-driven simulation lets you test what usually breaks integrations:
• Predefined scenarios bundled with packs (e.g., “Summer Storm”).
• Sequenced events — controlled transitions like normal → degraded → offline → recovery.
• Fault injection — simulate conditions that are hard to reproduce with physical devices.
• Deterministic outcomes — reproduce the same scenario across machines and teams.Use scenarios to validate: availability handling, automation triggers, dashboards, alerting, and edge-case parsing.
scenarios:
warmup_ramp:
display_name: "Warmup ramp"
duration: 30.0
actions:
- function: $out(temperature_c)
params:
start_c: 20.0
end_c: 35.0
t0: 0.0
t1: 30.0
call: |
(lambda t:
start_c + (end_c - start_c) * min(1.0, max(0.0, (t - t0) / max(0.1, t1 - t0)))
)($attr(timer.time))SPX projects can be structured to work efficiently with LLM-assisted development, so you can extend simulations faster while keeping them consistent:
-
LLM-ready specs — a clear, versioned specification that describes models, bindings, scenarios, and expected behavior.
-
Consistent project conventions — predictable structure for packs, device models, and integration tests.
-
Change-friendly iteration — refine specs first, then generate or update models and tests from the specification.
-
Reviewable outputs — LLM-generated changes are easy to validate because behavior is defined and testable.
-
Automation alignment — specs + tests support a tight loop: generate → run scenarios → verify → iterate.
-
SPX is designed to fit modern test pipelines:
-
Python client wrapper to drive simulations programmatically from tests.
-
CI/CD integration — start simulations, run scenarios, assert outcomes, and collect logs automatically.
-
Docker-based distribution for consistent environments across developer machines and build agents.
-
Repeatable test setups — the same simulator behavior locally and in CI.
This enables practical integration testing: bring up the simulator, connect your client/gateway, run a scenario, and verify behavior — all as part of your pipeline.
-
Protocol simulation for embedded software testing
Protocol simulators (including MQTT) are often the missing link in embedded software testing. They let you validate firmware behavior, integration flows, and edge cases without physical hardware, while keeping test environments deterministic and CI-ready. If you want the full workflow—how we combine simulation models, runtime smoke checks, and automation with spx-python—see our overview here: Embedded Software Testing with SPX.
