MQTT Mock Server

Mock Alpha includes an embedded MQTT broker (powered by aedes). It starts automatically with the dashboard and lets you push mock events to your app — either manually from the dashboard or automatically when an HTTP endpoint is hit.

Any MQTT 3.1.1 client works — Paho (Android/Java), CocoaMQTT (iOS), mqtt_client (Flutter), MQTT.js (web/Node), mosquitto CLI.

Connection details

The connection details are shown on the MQTT page of each project. Browsers can only use the WebSocket port; native clients can use either.

Authentication

Each project has its own MQTT namespace. Clients authenticate using the project credentials.

Kotlin (Paho):

val options = MqttConnectOptions().apply {
    userName = "<project-id>"
    password = "<api-key>".toCharArray()
    isCleanSession = true
}

val client = MqttClient("tcp://mock-alpha.duckdns.org:1883", MqttClient.generateClientId())
client.connect(options)

JavaScript (MQTT.js, browser or Node):

import mqtt from 'mqtt'

const client = mqtt.connect('ws://mock-alpha.duckdns.org:1884', {
  username: '<project-id>',
  password: '<api-key>',
})

Topic isolation

Topics are isolated per project. When you configure a topic as devices/status, Mock Alpha internally prefixes it with {projectId}/devices/status. Your app subscribes and receives messages on devices/status — the prefix is transparent.

// Subscribe to the raw topic — no project prefix needed
client.subscribe("devices/status") { topic, message ->
    val payload = String(message.payload)
    // handle event
}

client.subscribe('devices/status')
client.on('message', (topic, payload) => {
  // handle event
})

Configuring topics

On the MQTT page of your project:

1. Click + Add Topic
2. Enter the topic path (e.g., devices/status)
3. Enter the JSON payload — you can use response templates
4. Optionally link it to an HTTP endpoint for auto-publish
5. Set an optional delay in milliseconds before publishing

Manual publish

Click Publish Now on any topic row to immediately push the payload to all connected clients subscribed to that topic.

Auto-publish on HTTP hit

Link a topic to an HTTP endpoint. Whenever Mock Alpha serves a mock response for that endpoint, it automatically publishes the MQTT topic payload — after the HTTP response is returned (fire-and-forget, no latency impact).

Example flow:

App → GET /api/mock/devices/123
    │
    ├── HTTP response returned immediately (from scenario)
    │
    └── [async] MQTT publish: topic=devices/status
                              payload={"deviceId":"123","event":"polled"}

This lets you simulate workflows where an HTTP action triggers a real-time event.

Template placeholders in MQTT payloads

Use {{request.X}} placeholders in the payload JSON:

{
  "deviceId": "{{request.path.id}}",
  "requestedBy": "{{request.header.x-user-id}}",
  "event": "status-requested"
}

The same request context that resolved the HTTP response is used to resolve the MQTT payload.

Publish log

The Publish Log tab shows a history of all MQTT publishes with:

• Timestamp
• Topic
• Payload (expandable)
• Triggered by (Manual / endpoint name)

The log auto-refreshes every 5 seconds.

Network requirements

Ports 1883 (TCP) and 1884 (WebSocket) must be reachable from your network. If you cannot connect, check firewalls/VPNs between your device and the instance — HTTP mocking keeps working even when MQTT is unreachable.

QoS and limitations

The current release uses QoS 0 (fire-and-forget) for all publishes. The following are not yet supported:

• Retained messages
• QoS 1 or QoS 2
• Persistent sessions
• Wildcard subscriptions from the dashboard
• Scheduled / recurring auto-publish
• Incoming MQTT → HTTP trigger (reverse direction)