MQTTBridge Documentation

Everything you need to install, configure, and run MQTTBridge.

Prerequisites

Requirement	Details
Operating System	Windows 10/11 or Windows Server 2016+
.NET Runtime	.NET 10 ASP.NET Core Runtime (x64)
SQL Server	SQL Server 2016+ or SQL Server Express (free). The installer auto-detects localhost instances.
MQTT Broker	Any MQTT 3.1.1 or 5.0 broker (Mosquitto, HiveMQ, EMQX, etc.)

Installation

Step 1: Install .NET Runtime

Download and install the .NET 10 ASP.NET Core Runtime (x64) if not already installed.

Step 2: Install SQL Server

If you don't have SQL Server, download SQL Server Express (free). The default instance works fine.

Step 3: Run the Installer

Download MQTTBridge-Setup.msi from the product page and run it. The installer will:

• Install MQTTBridge as a Windows service
• Create the MQTTBridge database on your local SQL Server
• Create all required tables, views, and stored procedures
• Grant the service account database access
• Update the configuration with the detected SQL Server instance

If you need to specify a different SQL Server instance, use the command line:

msiexec /i MQTTBridge-Setup.msi SQL_SERVER=myserver\SQLEXPRESS DB_NAME=MQTTBridge

Step 4: Start the Service

The service is set to start automatically on boot. To start it now:

net start MQTTBridge

Or open services.msc, find "MQTT Bridge Service", and click Start.

First Login

Open your browser and go to http://localhost:8080

Field	Default Value
Username	admin
Password	admin

Change the default password after your first login from the Users section in the dashboard.

Configuration

MQTT Broker Connection

From the dashboard, go to the Configuration tab and enter your MQTT broker details:

• Broker Host (e.g., localhost or your broker's IP)
• Broker Port (default: 1883, or 8883 for TLS)
• Username and Password (if your broker requires authentication)
• Topic subscriptions (e.g., sensors/# to capture all sensor topics)

Database Connection

The installer configures this automatically. If you need to change it, go to the Configuration tab and update the database connection string. The default uses Windows Authentication:

Server=localhost;Database=MQTTBridge;Trusted_Connection=True;TrustServerCertificate=True;

Web Dashboard Port

Default port is 8080. To change it, edit appsettings.json in the install directory and update the WebManagement.Port value. Restart the service after changes.

RabbitMQ (Optional)

MQTTBridge can also consume messages from RabbitMQ. Configure the RabbitMQ connection from the Configuration tab if needed.

Performance Columns

Performance Columns let you extract JSON field values from message payloads into persisted computed columns on the MqttMessages table. Instead of parsing JSON on every query, SQL Server materializes the values at write time — turning expensive JSON_VALUE() calls into fast column reads.

Requirements: SQL Server 2016 or later, Professional or Enterprise license tier.

Creating a Performance Column

Open the Performance tab in the web dashboard. Fill in the form:

• Column Name — A name for the new column (letters, digits, and underscores, starting with a letter)
• JSON Path — The path to the value in your JSON payload (e.g., $.temperature, $.sensor.humidity)
• Data Type — The SQL Server type to cast the value to: FLOAT, INT, BIGINT, BIT, DATETIME2, or NVARCHAR(n)
• Create Index — Check this to add a nonclustered index for faster WHERE and ORDER BY queries on the column

Click Create Performance Column. MQTTBridge executes an ALTER TABLE to add the persisted computed column and optionally creates the index — all within a single transaction.

Example

If your MQTT payloads look like this:

{ "temperature": 22.5, "humidity": 61, "sensorId": "TH-042" }

You could create three performance columns:

Column Name	JSON Path	Data Type	Indexed
Temperature	$.temperature	FLOAT	Yes
Humidity	$.humidity	INT	No
SensorId	$.sensorId	NVARCHAR(50)	Yes

After creation, queries like SELECT * FROM MqttMessages WHERE Temperature > 30 use the indexed, persisted column instead of parsing JSON on every row.

REST API

Performance Columns can also be managed programmatically via the REST API:

Method	Endpoint	Description
GET	/api/performance-columns	List all performance columns
POST	/api/performance-columns	Create a new performance column
DELETE	/api/performance-columns/{columnName}	Remove a performance column

All endpoints require JWT authentication. See the Swagger docs at /swagger for full request/response schemas.

Removing a Performance Column

Click the delete button next to any column in the Performance tab. MQTTBridge drops the index (if present), removes the computed column from the table, and cleans up the registry entry — all in a single transaction.

Licensing

Trial Mode

MQTTBridge runs in Trial mode for 7 days with limited features (5 topics, 1 user). No license file needed.

Activating a License

1. Purchase a license from the pricing page
2. You'll receive a license key after purchase
3. In the MQTTBridge dashboard, go to the license activation panel
4. Enter your license key and click Activate
5. The license is applied immediately — no restart needed

Machine ID

Your Machine ID is shown on the Status tab. Licenses are locked to a specific machine. If you need to move a license to a different server, contact support.

Troubleshooting

Service won't start

• Check that .NET 10 ASP.NET Core Runtime is installed: dotnet --list-runtimes
• Check the Windows Event Log (Application) for error details
• Check the MQTTBridge log files in the install directory under logs/

Can't connect to database

• Verify SQL Server is running: services.msc → look for "SQL Server"
• Check that the MQTTBridge database exists in SQL Server
• Verify the service account has access: run Setup-SqlAccess.ps1 from the install directory in an elevated PowerShell

Messages tab shows "Failed to load messages"

• The database migration may not have been applied. Run Setup-SqlAccess.ps1 from the install directory
• Restart the MQTTBridge service after running the script

Dashboard not accessible

• Verify the service is running: sc query MQTTBridge
• Check if port 8080 is in use by another application
• Try accessing via http://127.0.0.1:8080 instead of localhost

MQTT broker not connecting

• Verify the broker is running and reachable from this machine
• Check the broker host, port, and credentials in the Configuration tab
• If using TLS, ensure the correct port (usually 8883) and certificate settings