01 Getting Started

Getting Started

MQTTProbe is a cross-platform MQTT monitoring and testing tool. It supports live topic browsing, payload inspection, subscriptions, publishing, Sparkplug B emulation, and multi-connection support.

Platform Support

Platform	How it runs
Web browser	Blazor Server — self-host on any machine or server
Docker	Official docker-compose.yml included
iOS	MAUI app (built from source on macOS)
Android	MAUI app
Windows desktop	MAUI app
macOS	MAUI app (built from source on macOS)

Prerequisites

• .NET 10 SDK (version 10.0.301 or later)
• Docker (optional, for containerized deployment)

Quick Start — Web Host

# Clone the repository
git clone https://github.com/bluegrassiot/mqttprobe.git
cd mqttprobe

# Run with hot reload
dotnet watch --project src/MqttProbe.Web

Open https://localhost:5001 in your browser. On first launch, you'll be redirected to /Setup to create an admin password.

Quick Start — Docker

# Start MQTTProbe (and optionally a local Mosquitto broker)
docker compose up -d

# Open in browser
# http://localhost:8080

Quick Start — Production (TLS)

# Copy and edit environment file
cp .env.example .env
# Set MQTTPROBE_HOST to your server hostname or IP

# Start with Caddy reverse proxy for TLS
docker compose -f docker-compose.prod.yml up -d

Architecture

MqttProbe.slnx
├── src/
│   ├── MqttProbe.Shared          # Blazor components, models, services (shared by all hosts)
│   ├── MqttProbe.Web             # ASP.NET Core web host (web + Docker)
│   └── MqttProbe.Maui            # .NET MAUI host (iOS, Android, Windows)
└── tests/
    ├── MqttProbe.Tests              # NUnit + bUnit unit & component tests
    ├── MqttProbe.IntegrationTests   # Testcontainers integration tests
    └── MqttProbe.E2ETests           # Playwright end-to-end tests

Key Libraries

• MQTTnet v4 — MQTT client (pinned; SparkplugNet depends on v4)
• MudBlazor — UI component library
• Blazor-ApexCharts — Real-time charts
• SparkplugNet — Sparkplug B emulation
• Google.Protobuf — Sparkplug B payload decoding
• MessagePack-CSharp — MessagePack payload detection/decoding
• FluentValidation — Connection form validation
• ASP.NET Core Data Protection — Server-side secret encryption

First-Run Setup

1. Launch the app (web or MAUI)
2. You'll be redirected to /Setup
3. Create an admin username and password
4. You're ready to connect to an MQTT broker

Configuration

All configuration is stored in config/appsettings.json. Secrets (MQTT broker passwords) are encrypted separately in config/secrets.dat using ASP.NET Data Protection.

On Linux/macOS, the config file is restricted to owner-only access (mode 600).

Running Tests

# All tests
dotnet test

# Unit + component tests only (fast, no external dependencies)
dotnet test tests/MqttProbe.Tests

# Integration tests (requires Docker for Testcontainers)
dotnet test tests/MqttProbe.IntegrationTests

# E2E tests (requires Docker + Playwright browsers)
dotnet test tests/MqttProbe.E2ETests