A fully-featured MQTT 5.0 and 3.1.1 client library for Kotlin Multiplatform — connecting JVM, Android, iOS, macOS, Linux, Windows, and browsers through a single, idiomatic Kotlin API.

The bundled Compose Multiplatform sample app, live on tls://mqtt.meshtastic.org:8883.

• 📦 Full MQTT 5.0 + 3.1.1 — all 15 packet types, properties, reason codes, and enhanced auth (5.0); backward-compatible 3.1.1 support
• 🔄 All QoS levels — QoS 0, 1, and 2 with complete state machine handling
• 🌍 True multiplatform — one codebase, 9 targets (see Platform Support)
• 🔒 TLS/SSL — secure connections on all native/JVM targets
• 🌐 WebSocket — binary WebSocket transport on all platforms (behind LBs, CDNs, firewalls)
• ⚡ Coroutines-first — suspend functions and Flow-based message delivery
• 🪶 Minimal dependencies — only Ktor (transport) + kotlinx-coroutines + kotlinx-io
• 🛡️ Immutable by design — ByteString payloads, validated inputs, data class models
• 📝 Configurable logging — zero-overhead MqttLogger interface with level filtering
• ✅ Spec-validated — topic filter wildcards, reserved bits, and packet structure per MQTT 5.0

All protocol logic — packet encoding/decoding, the client state machine, QoS flows, and property handling — lives in the mqtt-client-core module as pure commonMain Kotlin, with zero transport dependencies. Each transport ships as its own artifact, so a consumer pulls in only what it uses. Every bug fix, feature, and optimization in core applies to all 9 targets simultaneously.

┌─────────────────────────────────────────────┐
│  mqtt-client-core                           │  ← public API: suspend + Flow
│  MqttClient / MqttConnection / QoS machines │  ← protocol logic, keepalive
│  MqttPacket / Encoder / Decoder             │  ← MQTT 5.0 wire format
│  MqttTransport / MqttTransportFactory (SPI) │  ← the transport seam
└───────────────────────┬─────────────────────┘
            ▲            │  api(core)            ▲
            │            ▼                       │
┌───────────┴───────────┐   ┌───────────────────┴───────────┐
│ mqtt-client-          │   │ mqtt-client-transport-ws       │
│   transport-tcp       │   │ WebSocketTransport(Factory)    │
│ TcpTransport(Factory) │   │ ktor-client-websockets         │
│ ktor-network + TLS    │   │ all targets incl. browser      │
│ (no browser)          │   │                                │
└───────────────────────┘   └────────────────────────────────┘

MqttTransport / MqttTransportFactory are the public service-provider interface — the sole platform abstraction boundary. Core has no compile-time dependency on any transport module; you supply a factory (TcpTransportFactory, WebSocketTransportFactory, or both combined with +) via MqttConfig.Builder.transportFactory. Coroutines drive everything: suspend functions for operations, SharedFlow<MqttMessage> for incoming messages, and StateFlow<ConnectionState> for lifecycle observation.

Artifacts are published to Maven Central under the org.meshtastic group. Depend on mqtt-client-core plus the transport(s) you need. The mqtt-client-bom pins every module to one version so you don't repeat it:

// settings.gradle.kts
repositories {
    mavenCentral()
}

// build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(platform("org.meshtastic:mqtt-client-bom:0.3.0"))
            implementation("org.meshtastic:mqtt-client-core")
            // Pick the transport(s) you actually use:
            implementation("org.meshtastic:mqtt-client-transport-tcp") // TCP/TLS — every target except browser
            implementation("org.meshtastic:mqtt-client-transport-ws")  // WebSocket — every target incl. browser
        }
    }
}

Then supply the matching factory when building the client (combine with + if you use both):

val client = MqttClient("my-client") {
    transportFactory = TcpTransportFactory() + WebSocketTransportFactory()
}

Browser (wasmJs) can only use mqtt-client-transport-ws — raw TCP is unavailable there.

// build.gradle
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation platform('org.meshtastic:mqtt-client-bom:0.3.0')
                implementation 'org.meshtastic:mqtt-client-core'
                implementation 'org.meshtastic:mqtt-client-transport-tcp'
                implementation 'org.meshtastic:mqtt-client-transport-ws'
            }
        }
    }
}

dependencies {
    implementation(platform("org.meshtastic:mqtt-client-bom:0.3.0"))
    implementation("org.meshtastic:mqtt-client-core")
    implementation("org.meshtastic:mqtt-client-transport-tcp")
}

import org.meshtastic.mqtt.*
import org.meshtastic.mqtt.transport.tcp.TcpTransportFactory

// Create a client with the factory DSL
val client = MqttClient("my-client") {
    transportFactory = TcpTransportFactory()   // from mqtt-client-transport-tcp
    keepAliveSeconds = 30
    autoReconnect = true
    defaultQos = QoS.AT_LEAST_ONCE  // all publishes default to QoS 1
}

// Connect, work, and auto-close
client.use(MqttEndpoint.parse("tcp://broker.example.com:1883")) { c ->
    // Subscribe
    c.subscribe("sensors/temperature")

    // Publish (uses defaultQos from config)
    c.publish("sensors/temperature", "22.5")

    // Collect messages
    c.messagesForTopic("sensors/temperature").collect { msg ->
        println("Received: ${msg.payloadAsString()}")
    }
}

val config = MqttConfig(
    clientId = "my-client",
    keepAliveSeconds = 30,
    autoReconnect = true,
    transportFactory = TcpTransportFactory(),
)
val client = MqttClient(config)

client.connect(MqttEndpoint.Tcp(host = "broker.example.com", port = 1883))
client.subscribe("sensors/temperature", QoS.AT_LEAST_ONCE)
client.publish(
    MqttMessage(
        topic = "sensors/temperature",
        payload = ByteString("22.5".encodeToByteArray()),
        qos = QoS.AT_LEAST_ONCE,
    ),
)
client.messages.collect { msg ->
    if (msg.topic == "sensors/temperature") {
        println("Received: ${msg.payload.toByteArray().decodeToString()}")
    }
}
client.close()

By default, the client automatically negotiates the protocol version. It connects with MQTT 5.0 first and, if the broker rejects it with UNSUPPORTED_PROTOCOL_VERSION, seamlessly retries with MQTT 3.1.1 on a fresh connection — no configuration needed:

// Auto-negotiation is on by default — works with both 5.0 and 3.1.1 brokers
val client = MqttClient("my-client") {
    transportFactory = TcpTransportFactory()
    keepAliveSeconds = 30
}

client.use(MqttEndpoint.parse("tcp://any-broker:1883")) { c ->
    // After connect, check which version was negotiated:
    println("Connected with ${c.negotiatedProtocolVersion}")
    c.subscribe("sensors/#")
    c.messagesForTopic("sensors/#").collect { msg ->
        println("Received: ${msg.payloadAsString()}")
    }
}

To force a specific version or disable negotiation:

// Force MQTT 3.1.1 (no negotiation)
val v311Client = MqttClient("my-client") {
    protocolVersion = MqttProtocolVersion.V3_1_1
}

// Force MQTT 5.0 only (disable fallback)
val v5OnlyClient = MqttClient("my-client") {
    negotiateVersion = false
}

MQTT 3.1.1 mode automatically:

• Omits properties sections from all packets
• Uses 3.1.1 CONNACK return codes (mapped to ReasonCode)
• Encodes subscribe options as QoS-only (no noLocal, retainAsPublished, retainHandling)
• Sends a body-less DISCONNECT on close
• Skips topic aliases and flow control (Receive Maximum)

5.0-only config options (sessionExpiryInterval, authenticationMethod) are rejected at config-build time when V3_1_1 is explicitly selected. When using auto-negotiation, fallback is skipped if the config uses 5.0-only features — the original rejection is re-thrown so you know the broker doesn't support your configuration.

The library ships several ergonomic extensions to reduce boilerplate:

Parse broker URIs instead of constructing endpoints manually:

MqttEndpoint.parse("tcp://broker:1883")       // Plain TCP
MqttEndpoint.parse("ssl://broker:8883")       // TCP + TLS
MqttEndpoint.parse("mqtts://broker")          // TLS, default port 8883
MqttEndpoint.parse("wss://broker/mqtt")       // Secure WebSocket

// Exact topic match
client.messagesForTopic("sensors/temperature").collect { ... }

// Wildcard filter (supports + and #)
client.messagesMatching("sensors/+/temperature").collect { ... }

Use the builder DSL for complex configurations (annotated with @MqttDsl for scope safety, like Ktor's @KtorDsl):

val config = MqttConfig.build {
    clientId = "sensor-hub-01"
    keepAliveSeconds = 30
    cleanStart = false
    autoReconnect = true
    defaultQos = QoS.AT_LEAST_ONCE
    logger = MqttLogger.println()
    logLevel = MqttLogLevel.DEBUG
    will {
        topic = "sensors/status"
        payload("offline")
        qos = QoS.AT_LEAST_ONCE
        retain = true
    }
}

The library provides a zero-overhead logging interface. When no logger is configured (the default), message lambdas are never evaluated:

// Built-in println logger for quick debugging
val config = MqttConfig(
    clientId = "debug-client",
    logger = MqttLogger.println(),
    logLevel = MqttLogLevel.DEBUG,
)

// Custom logger (e.g., forwarding to your app's logging framework)
val config = MqttConfig(
    clientId = "production-client",
    logger = object : MqttLogger {
        override fun log(level: MqttLogLevel, tag: String, message: String, throwable: Throwable?) {
            myAppLogger.log(level.name, "[$tag] $message", throwable)
        }
    },
    logLevel = MqttLogLevel.INFO,
)

Log levels from most to least verbose: TRACE → DEBUG → INFO → WARN → ERROR → NONE.

The library is designed as a drop-in MQTT client for KMP projects. Consumer ProGuard/R8 rules are bundled automatically.

class MqttViewModel : ViewModel() {
    private val client = MqttClient("my-device") {
        // broker URI may be tcp:// or ws://, so accept either transport
        transportFactory = TcpTransportFactory() + WebSocketTransportFactory()
        autoReconnect = true
        keepAliveSeconds = 30
    }

    val connectionState = client.connectionState

    fun connect(broker: String) {
        viewModelScope.launch {
            client.connect(MqttEndpoint.parse(broker))
            client.subscribe("msh/2/e/#", QoS.AT_LEAST_ONCE)
        }
    }

    fun observeMessages() = client.messagesMatching("msh/2/e/+/!/#")

    override fun onCleared() {
        viewModelScope.launch { client.close() }
    }
}

@Composable
fun MqttScreen(viewModel: MqttViewModel) {
    val state by viewModel.connectionState.collectAsStateWithLifecycle()

    LaunchedEffect(Unit) {
        viewModel.observeMessages().collect { msg ->
            // Process message
        }
    }
}

The library uses Ktor 3.4.2 and kotlinx-coroutines 1.10.2. If your project uses the same versions, no conflicts will arise. Pin versions in your libs.versions.toml to avoid Gradle resolution surprises.

See CONTRIBUTING.md for build setup, development workflow, and the full command reference.

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on:

• Setting up your development environment
• Code style and conventions
• Submitting pull requests

For vulnerability reports, see the Security Policy. All participants are expected to follow the Code of Conduct.

This project is licensed under the GNU General Public License v3.0, consistent with all repositories in the Meshtastic organization.