Complete Guide

How MQTTBridge works

From creating your account to streaming live sensor data — and pulling it into your own projects with an API key. Everything is covered here.

Overview Step-by-step Data formats Publishing data Alerts Groups Sharing API & Code Webhooks WebSocket stream Limits & tips

Overview

What MQTTBridge actually does

MQTTBridge sits between your device and your browser. It maintains a live MQTT connection to your broker so you don't have to manage one yourself.

🏭

Your Device

PLC / Sensor / Pi

→

📡

MQTT Broker

EMQX / HiveMQ / any

→

⚙️

MQTTBridge Backend

Subscribes · Translates · Stores

→

🗄️

Database

Supabase Postgres

→

🖥️

Your Dashboard

Live · Alerts · Export

Your device publishes data

Your PLC, ESP32, Raspberry Pi, or any MQTT-capable device publishes messages to a topic on an MQTT broker — public or private.

Backend subscribes and translates

MQTTBridge connects to your broker and subscribes to your topic. Every incoming message is decoded according to your chosen format (JSON, Hex, Binary, or Plain) and stored with a timestamp.

Dashboard streams it live

Your dashboard reads from the database via Supabase Realtime — messages appear the moment they arrive. Switch to dashboard view for live value tiles and a time-series chart.

Step-by-step guide

From zero to live data

Create a free account

Go to the Sign Up page and register with an email and password. You'll receive a confirmation email — click the link to activate your account, then sign back in.

📬

Check your spam folder

The confirmation email sometimes lands in spam. If you don't see it within 2 minutes, check your spam/junk folder. The confirmation link expires after 24 hours.

Have an MQTT broker your device publishes to

MQTTBridge connects to your broker — it doesn't host one. You need a broker your device already publishes to, or you can point your device at one of these free public brokers:

EMQX PublicRecommended

mqtt://broker.emqx.iomqtts://broker.emqx.ioPort 1883 · TLS: 8883

HiveMQ PublicReliable

mqtt://broker.hivemq.commqtts://broker.hivemq.comPort 1883 · TLS: 8883

⚠️

Public brokers are shared spaces — anyone can subscribe to any topic. Never publish personal data to a public broker. Use a unique topic prefix like yourname/project/sensor to avoid accidentally receiving other users' messages.

💡

Have a private broker? That works too. Enter your username and password in the credentials section when creating a subscription. They are encrypted with AES-256 before being stored — never in plain text.

Create a subscription

Once signed in, open your Dashboard and click + New Subscription. Fill in the form:

Label

optional

A friendly name like "Factory Line 1 Temp" so you can identify it in the sidebar. Optional but recommended.

Broker URL

required

Full URL of your broker. e.g. mqtt://broker.emqx.io or mqtts://broker.emqx.io for TLS.

Topic

required

The exact topic your device publishes to. e.g. factory/line1/temperature. Wildcards like # and + are supported.

Data Format

required

Choose the format your device sends: JSON, Hex, Binary, or Plain. See the Data Formats section below.

Username / Password

optional

Only needed for private brokers that require authentication. Credentials are encrypted before storage.

Click Subscribe → and the backend connects to your broker immediately. The subscription appears in your dashboard sidebar within seconds.

Publish data from your device

Your device (PLC, ESP32, Raspberry Pi, Node-RED, or any MQTT client) publishes to the same broker and topic you registered. Here are working examples for common platforms:

python — paho-mqtt

# Python — paho-mqtt (pip install paho-mqtt)
import paho.mqtt.client as mqtt, json
client = mqtt.Client()
client.connect('broker.emqx.io', 1883)
payload = json.dumps({'temperature': 23.4, 'humidity': 61})
client.publish('yourname/sensors/env', payload)

arduino / esp32 — PubSubClient

// Arduino / ESP32 — PubSubClient library
#include <PubSubClient.h>
client.connect("esp32-device");
// Plain text value
client.publish("yourname/sensors/temp", "23.4");
// Or a JSON string
client.publish("yourname/sensors/env", "{\"temp\":23.4,\"rh\":61}");

node.js — mqtt package

// Node.js — npm install mqtt
const mqtt = require('mqtt');
const client = mqtt.connect('mqtt://broker.emqx.io');
client.on('connect', () => {
  client.publish('yourname/sensors/temp',
    JSON.stringify({ temperature: 23.4 }));
});

⏱️

Throttle — one message stored every 2 seconds

MQTTBridge uses a 2-second throttle per subscription. The latest message in each 2-second window is saved — messages arriving faster are received by the backend but not persisted. This means up to 30 readings per minute are stored, which is more than enough for real-time monitoring and charting. Your device can publish at any rate without causing errors. The dashboard loads the last 100 messages into the live feed, giving the chart enough data points to detect trends and anomalies. Older messages are always accessible via the 'Load older messages' button.

Watch your data stream live

Select your subscription in the sidebar. Messages appear in real time as they arrive, translated into readable values. The topbar shows connection status, message count, and controls.

≡

List view

Scrollable feed of every message with timestamp and translated value. Click a JSON message to expand the full pretty-printed payload.

⊞

Dashboard view

Live value tiles (gauge, boolean, progress, stat, sparkline, map and more) plus a time-series chart with anomaly detection. Choose line, area or bar chart, overlay multiple fields, and toggle min/avg/max reference lines.

⏸

Pause / Resume

Pause a subscription to stop receiving messages without deleting it. The broker connection closes cleanly and reopens on resume.

↓

Export

Download the last 50 messages as JSON or CSV from the topbar at any time.

Data formats

How your data gets translated

Choose the format that matches what your device sends when creating a subscription. Every message is decoded automatically — no code needed on your end.

JSON

Input payload

{"temperature":23.4,"humidity":61,"unit":"C"}

Translated to

temperature: 23.4
humidity: 61
unit: C

JSON objects are flattened into key: value pairs, one per line. Nested objects are flattened with a pipe separator. Arrays of primitives are listed inline.

HEX

Input payload

0x0041

Translated to

65 (0x0041)

Strips the 0x prefix and whitespace, validates hex characters, attempts UTF-8 decode. If the result is printable text it returns text (0xHEX) — otherwise converts to decimal using BigInt and returns decimal (0xHEX).

BINARY

Input payload

01000001

Translated to

65 [0x41]

Interprets by byte length: 1 byte → uint8, 2 bytes → uint16 + int16, 4 bytes → float32 or uint32, 8 bytes → float64. Output shows the interpreted value alongside a hex dump.

PLAIN

Input payload

23.4

Translated to

23.4

The raw payload string is passed through exactly as received. Use this for sensors that publish a single number, a status string, or any value that needs no decoding.

⚠️

Format mismatch: If your device sends a format that doesn't match your selection (e.g. you chose JSON but your device sends plain text), the raw payload is displayed as-is without crashing. You can delete and re-add the subscription with the correct format at any time.

Publishing data

Send commands back to your device

MQTTBridge is two-way. You can publish a message to your broker from the dashboard or via the API — useful for sending commands, resetting values, or triggering actions on your device.

From the dashboard

Select a subscription in the sidebar

Click the ↑ Publish button in the topbar

Choose the payload format (Plain, JSON, Hex, or Binary)

Optionally change the topic — by default it publishes to the same topic the subscription listens on

Type your payload and click Publish ↑ (or press ⌘ Enter)

💡

You can publish to a different topic than the one your subscription listens on. For example, your subscription might listen on factory/sensor/temp but you publish a command to factory/device/control — as long as both are on the same broker.

Payload validation by format

Plain

Any string up to 64 KB. Sent as-is.

JSON

Must be valid JSON. Rejected if malformed — you'll see the error inline.

Hex

Must contain only hex characters (0–9, a–f). Spaces are stripped before sending.

Binary

Must contain only 0s and 1s. Spaces are stripped before sending.

Alert Rules

Get notified when a value goes out of range

Set threshold rules per subscription. When a message triggers a rule, you're notified on your dashboard and optionally via Telegram.

How to create an alert rule

Select a subscription in the sidebar

Click the 🔔 Rules button in the topbar

Give the rule a name (optional), set the condition and threshold value

For JSON subscriptions, enter the field name to watch (e.g. "temperature"). Leave blank to match on the whole translated payload.

Set a cooldown — the minimum time between alerts from this rule (1–1440 minutes, default 10 min)

Toggle "Notify via Telegram" if you want a Telegram message when it fires

Click + Add Rule

> Greater than

Temp above 80°C

< Less than

Pressure below 10 bar

= Equals

Status is "FAULT"

≠ Not equals

Mode changed from normal

∋ Contains

Message includes "error"

Setting up Telegram notifications

When a condition that triggered an alert is no longer met, MQTTBridge automatically sends an ✅ All Clear notification — both on the dashboard and via Telegram — so you know the issue has resolved without checking manually.

You can add up to 5 named Telegram recipients per account — your own phone, a colleague, a group chat, or any combination. Every alert fans out to all of them simultaneously. Each can be tested individually from Settings.

Open Telegram and search for @BotFather

Send /newbot and follow the prompts to create a bot — Save the bot token BotFather gives you.

Start a conversation with your new bot — Send it any message (e.g. "hello").

Get your Chat ID — Visit api.telegram.org/bot<YOUR_TOKEN>/getUpdates in a browser — find "chat":{"id": 123456789} in the response.

Go to Settings → Telegram Alerts in your dashboard — Click your avatar in the bottom-left of the sidebar.

Add a recipient with a label and your Chat ID — e.g. label "My Phone", Chat ID 123456789. Repeat for any additional recipients.

Click Test to verify each recipient — You'll receive a confirmation message immediately if it's working.

📱

What the Telegram message looks like

🚨 MQTTBridge Alert
Rule: Temp too high
Value: 85.3
Time: 27/05/2026, 14:32:00

📧Email alerts

Enable email delivery on any alert rule by ticking the Email (5/day) checkbox when creating the rule. You'll receive a branded email showing the rule name, triggering value, subscription, timestamp, and a direct link back to your dashboard.

·Daily limit — 5 emails per user per day — further alerts still appear on the dashboard and via Telegram

·All-clear emails — When an alert resolves, an all-clear email fires too (green header, value shown in green)

·Per-rule opt-in — Email is off by default — you choose which rules send emails, not all of them

·Cooldown respected — The rule's cooldown period applies to email delivery too — no repeat emails within the cooldown window

Anomaly Detection on the Chart

Separate from alert rules, the dashboard chart automatically detects statistical outliers in your data using the 2-standard-deviation rule — no configuration needed.

How it worksFor all values in the current chart window, MQTTBridge calculates the mean and standard deviation. Any point where the value is more than 2σ away from the mean is flagged as an anomaly.

Visual markerAnomalous points appear as red glowing dots on the chart line — a pulsing outer ring, a solid red dot, and a small ! above the point. Normal dots are unaffected.

Tooltip warningHovering an anomalous point shows an ⚠ ANOMALY DETECTED banner in the tooltip alongside the value. The tooltip border also turns red.

ToggleA count badge appears in the chart toolbar (e.g. "● 3") when anomalies are detected. Click it to hide or show them. The standard deviation σ is shown in the stats bar below the chart.

Relationship to alertsAlert rules fire in real-time and notify you. Anomaly detection is visual and statistical — it helps you spot historical irregularities you may not have set a rule for.

🔔Notification centre

Click the 🔔 bell icon in the sidebar footer to open the notification centre — a slide-in panel showing all recent alert activity with full filtering and search.

🔍

Filter tabs

Switch between All, Unread, and Cleared to focus on what matters

🔎

Search alerts by rule name or value when you have more than 5 entries

🟢

Visual distinction

Trigger alerts show red, all-clears show green, acknowledged entries are dimmed

📊

Stats footer

Total triggers, all-clears, and total count shown at the bottom

Subscription Groups

Organise by device, share as one

If a single device publishes to several topics — temperature, humidity, pressure, battery — you can group those subscriptions together under one name. The group appears as a collapsible section in your sidebar with a colour dot and count badge.

📂

Create a group

Click "📦 Groups" in the sidebar, then "Create Group". Give it a name (e.g. "Weather Station") and pick a colour. Existing subscriptions appear as checkboxes — tick to assign.

🔗

Share the whole group

Click the 🔗 icon on a group header to generate one shared link for all subscriptions inside it. Recipients see a sidebar listing each subscription and can switch between them.

🔒

Password protect

When sharing — whether a single subscription or a group — you can optionally set a password. Recipients see a lock screen before the dashboard loads. Leave the field empty for a public link.

Good to know

·A subscription can only belong to one group at a time.
·Deleting a group unassigns its subscriptions — the subscriptions themselves are not deleted.
·Group shared links work exactly like subscription links — no login needed, real-time updates, revoke anytime.
·The shared group view shows a left sidebar on desktop and a hamburger menu on mobile for switching between subscriptions.

API Keys & Code Integration

Use your data in your own projects

Generate a personal API key and pull live or historical sensor data into any frontend, script, or automation tool — no backend or session needed.

How to generate an API key

Open your Dashboard — Click your email / avatar in the bottom-left of the sidebar to open Settings.

Click the "API Keys" tab

Enter a label for the key — e.g. "My Grafana Dashboard", "Raspberry Pi script". This helps you remember which key belongs to which project.

Click Generate Key — Copy it immediately and store it safely — you can see the key again from the keys list at any time.

Use it in your code via the x-api-key header — See the examples below.

📋 Finding your Subscription ID

Every API request for messages or publishing requires your subscription ID — a UUID that identifies which subscription you're referencing. There are two ways to get it:

1. Via the API: Call GET /api/subscriptions with your API key — it returns all your subscriptions including their IDs.

2. From the dashboard URL: Open your dashboard, select a subscription — the URL will contain the subscription ID in some implementations. Or check your browser dev tools for the ID in network requests.

Available API endpoints

All endpoints use the header x-api-key: mqttb_your_key_here. Click any endpoint to expand the full details.

Code examples

Replace the highlighted variables with your own values. Your API key starts with mqttb_ and is found in Settings → API Keys.

Read the latest sensor value

YOUR_API_KEYYOUR_BACKEND_URLSUBSCRIPTION_ID

fetch-latest.js

// Replace these three variables with your own values
const API_KEY         = 'mqttb_your_key_here';
const BASE_URL        = 'https://api.mqttbridge.site';
const SUBSCRIPTION_ID = 'your-subscription-uuid';
const res = await fetch(
  `${BASE_URL}/api/messages/${SUBSCRIPTION_ID}/latest`,
  { headers: { 'x-api-key': API_KEY } }
);
if (!res.ok) throw new Error(`API error: ${res.status}`);
const message = await res.json();
console.log(message.translated_payload); // 'temp: 23.4'
console.log(message.received_at);        // '2026-05-27T14:32:00Z'

Read message history (last 100)

fetch-history.js

const API_KEY         = 'mqttb_your_key_here';
const BASE_URL        = 'https://api.mqttbridge.site';
const SUBSCRIPTION_ID = 'your-subscription-uuid';
const res = await fetch(
  `${BASE_URL}/api/messages/${SUBSCRIPTION_ID}?limit=100`,
  { headers: { 'x-api-key': API_KEY } }
);
const messages = await res.json();
// Array of messages, newest first
messages.forEach(msg => {
  console.log(msg.translated_payload, msg.received_at);
});

Publish a command to your device

publish.js

const API_KEY         = 'mqttb_your_key_here';
const BASE_URL        = 'https://api.mqttbridge.site';
const SUBSCRIPTION_ID = 'your-subscription-uuid';
const res = await fetch(`${BASE_URL}/api/publish`, {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    subscription_id: SUBSCRIPTION_ID,
    payload: 'SET_TEMP:22',
    // topic: 'factory/device/control', // optional override
  }),
});
const result = await res.json();
// { ok: true, topic: '...', message: 'Published successfully' }

Get your subscription IDs

get-subscriptions.js

const API_KEY = 'mqttb_your_key_here';
const BASE_URL = 'https://api.mqttbridge.site';
const res = await fetch(`${BASE_URL}/api/subscriptions`, {
  headers: { 'x-api-key': API_KEY }
});
const subscriptions = await res.json();
subscriptions.forEach(sub => {
  console.log(sub.id, sub.label, sub.topic);
  // Copy the id — that's your SUBSCRIPTION_ID
});

🔒

Security — what your API key can and cannot access

Your API key is scoped strictly to your own account. It can only read your subscriptions and messages, and publish via your connections. It cannot access any other user's data. You can revoke any key at any time from Settings → API Keys. Keys are stored as SHA-256 hashes — the raw key is never stored, so keep a copy somewhere safe.

Webhooks

Forward messages to any HTTP endpoint

Webhooks let MQTTBridge push every incoming message to a URL of your choice — automatically, in real time. Use them to connect to Home Assistant, n8n, Zapier, or your own backend.

How to add a webhook

Select a subscription in the sidebar

Click the 🔗 Webhooks button in the topbar

Enter the endpoint URL your server is listening on

Optionally add a label and a signing secret

Click + Add Webhook — it activates immediately

📦

Payload sent to your endpoint

Every delivery is a POST request with this JSON body:

{
  "subscription_id": "uuid",
  "topic": "sensors/temp",
  "format": "json",
  "raw_payload": "{"temp":23.4}",
  "translated_payload": "temp: 23.4",
  "received_at": "2026-06-09T12:00:00Z"
}

Verifying the signature

If you add a signing secret, every request includes an X-MQTTBridge-Signature header containing an HMAC-SHA256 of the request body. Verify it on your server to confirm the request came from MQTTBridge and wasn't tampered with.

verify-signature.js

// Node.js — verify the webhook signature
const crypto = require('crypto');
function verifySignature(body, secret, signature) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

💡

You can view the last 50 delivery logs for each webhook directly in the panel — click the logs button next to any webhook. Each log shows the HTTP status code, any error message, and the delivery timestamp.

WebSocket streaming

Real-time stream for your own code

Open a persistent WebSocket connection to receive every message the moment it arrives — no polling, no delays.

Getting your stream URL

Go to Settings → API Keys → Generate a key. Copy it — it's shown only once.

In the dashboard, select a subscription. Click the ⚡ Stream URL button in the topbar — it copies the full wss:// URL for that subscription.

Or: get your subscription ID by clicking the ID button on any subscription in the sidebar.

Append your API key: wss://api.mqttbridge.site/stream/{subscriptionId}?key=mqttb_...

Connecting

connect.js

// Open a WebSocket stream for one subscription
const ws = new WebSocket(
  `wss://api.mqttbridge.site/stream/${SUBSCRIPTION_ID}?key=${API_KEY}`
);
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'connected') {
    console.log('Stream ready:', msg.topic);
  } else {
    console.log(msg.translated_payload);
  }
};

Message format

Each message pushed to your client contains the same fields as the webhook payload — plus a type field that is connected on the first frame and message on every subsequent frame.

{
  "subscription_id": "uuid",
  "topic":           "sensors/temp",
  "format":          "json",
  "raw_payload":     "{"temp":23.4}",
  "translated_payload": "temp: 23.4",
  "received_at":     "2026-06-09T12:00:00Z"
}

Python example — react to live data

stream.py

# pip install websocket-client
import websocket, json
def on_message(ws, message):
    msg = json.loads(message)
    if msg.get('type') == 'connected':
        print('Connected to', msg['topic'])
        return
    payload = msg['translated_payload']
    print('New reading:', payload)
ws = websocket.WebSocketApp(
    f'wss://api.mqttbridge.site/stream/{SUBSCRIPTION_ID}?key={API_KEY}',
    on_message=on_message
)
ws.run_forever()

Connection close codes

4001Missing API key — add ?key=your_key to the URL4003Invalid API key — check your key in Settings4004Subscription not found or you do not own it4029Too many connections from your IP — wait 1 minute1001Server restarting — reconnect after a few seconds

Limits & tips

What to know before you build

⏱️2-second throttle

One message is stored every 2 seconds per subscription — the latest reading in each window. This prevents database flooding while still giving you up to 30 readings per minute, which is rich enough for live monitoring and charting.

📦1,000 messages per subscription

The free plan stores up to 1,000 messages per subscription, retained for 30 days. The dashboard shows 50 at a time with "Load older messages" pagination. The API returns up to 100 per request with cursor-based pagination.

🔄Auto-reconnect with backoff

If a broker connection drops, the backend reconnects automatically using exponential backoff — 5s, 10s, 30s, 60s. After 10 failed attempts the subscription is marked inactive and you're notified via Telegram if configured.

⏸Paused = broker disconnected

When you pause a subscription the backend cleanly disconnects from that broker+topic. No messages are received or stored until you resume.

🔁Heartbeat sync every 30s

A background process checks every 30 seconds that in-memory connection state matches the database. This self-heals any drift after server restarts.

🛡️Request body limit: 10 KB

API request bodies are capped at 10 KB. Published payloads are capped at 64 KB separately. This prevents abuse and protects the backend from oversized payloads.

💡 Tips for best results

→

Use EMQX as your public broker: broker.emqx.io is the most reliable of the free public options — fewest disconnects, lowest latency.

→

Make your topic unique: Public brokers are shared. Use a prefix like your username: johnsmith/factory/line1/temp — this prevents accidentally receiving strangers' messages.

→

Match your data format exactly: If your device sends JSON, pick JSON. If it sends a raw number, pick Plain. A mismatch shows the raw value but makes dashboard view less useful.

→

Use /latest for live dashboards: If you're building a frontend showing current sensor state, /api/messages/{id}/latest is more efficient than fetching all 50 and taking the first element.

→

Export before clearing: The Clear button permanently deletes all stored messages for a subscription. Use the JSON or CSV export in the topbar first if you want the history.

→

Alerts have a cooldown: Each rule has a configurable cooldown (default 10 min). If your value crosses the threshold repeatedly, you won't get flooded — only one alert fires per cooldown window.

Ready to connect your first device?

Create your free account and have live data on your dashboard in under 5 minutes.

Create free account →Back to home

How MQTTBridge works

What MQTTBridge actually does

Your device publishes data

Backend subscribes and translates

Dashboard streams it live

From zero to live data

Create a free account

Have an MQTT broker your device publishes to

Create a subscription

Publish data from your device

Watch your data stream live

How your data gets translated

Send commands back to your device

From the dashboard

Payload validation by format

Get notified when a value goes out of range

How to create an alert rule

Setting up Telegram notifications

Organise by device, share as one

Share your data with anyone

Use your data in your own projects

How to generate an API key

Available API endpoints

Code examples

Forward messages to any HTTP endpoint

How to add a webhook

Verifying the signature

Real-time stream for your own code

Getting your stream URL

Connecting

Message format

Python example — react to live data

Connection close codes

What to know before you build

💡 Tips for best results

Ready to connect your first device?