MQTTastic-Client-KMP

0.3.8indexed

Fully-featured MQTT 5.0 client with complete packet/property support, QoS 0–2 state machine, TLS/WebSocket transports, asynchronous APIs with reactive message streams, immutable payloads, minimal dependencies and spec validation.

AndroidJVMNativeWasm·meshtastic/MQTTastic-Client-KMP

Stars

—

Used by

dependents

Health

/ 100

MQTTastic Client KMP

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.

MQTTastic sample app running on Android, connected to mqtt.meshtastic.org and streaming live mesh traffic
The bundled Compose Multiplatform sample app, live on tls://mqtt.meshtastic.org:8883.

Features

Why MQTTastic?

Platform Support

Architecture

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 (, , or both combined with ) via . Coroutines drive everything: functions for operations, for incoming messages, and for lifecycle observation.

Installation

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.5.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.

Groovy DSL

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

Single-platform (JVM / Android only)

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

Quick Start

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


 client = MqttClient() {
    transportFactory = TcpTransportFactory()   
    keepAliveSeconds = 
    autoReconnect = 
    defaultQos = QoS.AT_LEAST_ONCE  
}


client.use(MqttEndpoint.parse()) { c ->
    
    c.subscribe()

    
    c.publish(, )

    
    c.messagesForTopic().collect { msg ->
        println()
    }
}

Verbose equivalent (without convenience APIs)

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

client.connect(MqttEndpoint.Tcp(host = , port = ))
client.subscribe(, QoS.AT_LEAST_ONCE)
client.publish(
    MqttMessage(
        topic = ,
        payload = ByteString(.encodeToByteArray()),
        qos = QoS.AT_LEAST_ONCE,
    ),
)
client.messages.collect { msg ->
     (msg.topic == ) {
        println()
    }
}
client.close()

MQTT 3.1.1 Support

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.

Convenience APIs

The library ships several ergonomic extensions to reduce boilerplate:

Endpoint Parsing

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

Topic-Filtered Message Flows

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

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

Builder DSL

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
    }
}

Logging

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 =  : MqttLogger {
          {
            myAppLogger.log(level.name, , throwable)
        }
    },
    logLevel = MqttLogLevel.INFO,
)

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

Custom TLS trust

By default both transports validate the broker certificate against the platform CA store. To reach a broker behind a private or self-signed CA, pass a TLS customisation lambda to the transport factory you use — TcpTransportFactory, WebSocketTransportFactory, or both, since a factory without the lambda keeps validating against the platform store alone. It runs against ktor's TLSConfigBuilder:

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

val client = MqttClient("my-client") {
    transportFactory = TcpTransportFactory { trustManager = myPrivateCaTrustManager }
}
client.connect(MqttEndpoint.parse("mqtts://broker.internal:8883"))

The hook is applied after the SNI server name is resolved and before platform trust is configured. On Android that ordering means your trust manager is reached through the hostname-aware checkServerTrusted(chain, authType, hostname) overload, which the platform requires whenever network_security_config.xml holds any domain-specific configuration — rather than being discarded in favour of the platform wrapper.

Be clear about what that does not buy you. Installing your own trust manager replaces the platform's trust decision: your anchors are used instead of the platform's, and network_security_config.xml anchors, certificate pinning, and Certificate Transparency policy are then enforced only insofar as your manager enforces them itself. Those platform policies apply as before only if you leave trustManager unset. The wrapping preserves the hostname-aware call path, not the platform's policy.

RFC 6125 subject-name matching is separate again. Android's 3-arg overload uses the hostname for policy lookup, not for subject-name matching; that check comes from ktor and only runs when the SNI server name is set, so it is absent for IP-literal brokers such as mqtts://192.168.1.50:8883. On JVM and native targets there is no platform trust wrapping at all, so ktor's SNI-gated subject-name check is the only peer-identity verification beyond chain validation. If your trust manager accepts any chain, nothing else will stop a mismatched certificate.

On Android the manager must be one X509TrustManagerExtensions can wrap: either obtained from a TrustManagerFactory initialised with a KeyStore containing your CA, or declaring the three-arg checkServerTrusted(chain, authType, host) that the platform looks up reflectively. A hand-written X509TrustManager implementing only the two-arg overload cannot be wrapped, and the handshake fails with an IllegalArgumentException explaining this.

This scopes the extra trust to the MQTT connection alone. It replaces the app-wide workaround of adding <certificates src="user"/> to network_security_config.xml, which would affect every HTTPS connection the app makes.

The hook composes with transport selection as usual, and both transports take the same lambda type, so one trust manager can serve both:

transportFactory = TcpTransportFactory { trustManager = myPrivateCaTrustManager } +
    WebSocketTransportFactory { trustManager = myPrivateCaTrustManager }

TLSConfigBuilder comes from io.ktor:ktor-network-tls, exposed transitively by both mqtt-client-transport-tcp and mqtt-client-transport-ws — no extra dependency needed. trustManager specifically is available on the JVM and Android actuals of ; on Apple and Linux the hook still runs, but exposes a different set of properties there. The WebSocket hook is additionally ignored on Windows (the WinHttp engine has no TLS-configuration surface) and in the browser (which cannot influence trust) — see for the per-target table.

Android / KMP Integration

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

ViewModel-scoped client

Collecting in Compose

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

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

Version alignment

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

MQTT 5.0 Coverage

Protocol

Feature	Status	Spec Section
All 15 packet types	✅

Quality of Service

Session & Connection

Advanced Features

Observability

Feature	Status	Spec Section
Configurable logging (6 levels)	✅	—
Connection state observation	✅	—

Known Limitations

Limitation	Detail
Enhanced auth during CONNECT	Auth challenges are delivered only after the connection is established. SASL-style challenge/response during the CONNECT handshake (§4.12.1) is not yet supported.
Client-side session persistence	When `cleanStart=false`, the broker resumes session state, but the client does not persist in-flight QoS 1/2 messages across reconnects. Unacknowledged messages may be lost.

Building

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

Documentation

Contributing

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.

License

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

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

ksrpc★ 15

MonkopediaEnables JSON-like RPCs with simple service declarations, supporting various connection mechanisms. Integrates annotations for service mapping, and provides a flexible environment setup for hosting services.Shared: ktor, coroutines

Cache★ 1

netcosportsLibrary facilitates efficient HTTP response caching, utilizing Ktor and OkHttp clients with features like CoroutineLoader and SingleLoader to manage network and cached data responses seamlessly.Shared: ktor, coroutines

kotysa★ 134

ufoss-orgLight ORM enabling type-safe SQL with idiomatic syntax. Supports JDBC, R2DBC, Vertx sqlclient, and various databases including PostgreSQL, MySQL, and SQLite. No annotations or code generation required.Shared: ktor, coroutines

Saga★ 70

nomisrevManages data consistency across microservices using the saga design pattern. Facilitates distributed transactions with a convenient DSL, enabling automatic rollbacks and compensating actions for composed operations.Shared: ktor, coroutines

KoVibes★ 16

rubenquadrosKotlin wrapper simplifies interaction with Spotify Web API, offering methods to fetch Spotify data. Provides seamless authentication and customizable logging, with future expansion plans for additional APIs and platform support.Shared: ktor, coroutines

katbox★ 12

OlivkiOffers a wrapper for interacting with Catbox and Litterbox file hosting services, enabling anonymous and authenticated file uploads and album creation using coroutines.Shared: ktor, coroutines

Pure KMP	Single codebase, single API across all platforms	Wrappers around platform SDKs (Paho, Mosquitto)
MQTT 5.0 first	Built from the ground up for 5.0 — not retrofitted from 3.1.1	Bolt-on 5.0 support with incomplete property coverage
Coroutines-native	`suspend` functions and `Flow` everywhere — no callbacks, no blocking	Callback-heavy APIs requiring manual coroutine bridging
Zero platform deps	Only Ktor + kotlinx-coroutines + kotlinx-io	Bundles native C libraries or platform-specific SDKs
Immutable & validated	`ByteString` payloads, validated topic filters, range-checked properties	Mutable byte arrays, silent truncation, unchecked inputs

`MqttClient("id") { ... }`	`MqttClient(MqttConfig(clientId = "id", ...))`
`MqttEndpoint.parse("tcp://host:1883")`	`MqttEndpoint.Tcp(host, port, tls)`
`client.use(endpoint) { ... }`	Manual `connect` + `try/finally { close() }`
`msg.payloadAsString()`	`msg.payload.toByteArray().decodeToString()`
`client.messagesForTopic("x")`	`client.messages.filter { it.topic == "x" }`
`client.messagesMatching("x/+/y")`	Manual wildcard matching on `messages` flow
`client.publish(topic, payload)`	Constructing `MqttMessage` manually
`defaultQos` / `defaultRetain`	Repeating `qos = QoS.AT_LEAST_ONCE` on every publish
`will { topic = ...; payload("...") }`	`will = WillConfig(topic = ..., payload = ByteString(...))`

QoS 0 (at most once)	✅	§4.3.1
QoS 1 (at least once)	✅	§4.3.2
QoS 2 (exactly once)	✅	§4.3.3
Duplicate detection (DUP flag)	✅	§3.3.1.1

Session management (cleanStart)	✅	§3.1.2.4
Will messages & Will Delay	✅	§3.1.3.2
Keep-alive & PINGREQ/PINGRESP	✅	§3.1.2.10
Automatic reconnection	✅	—
Server redirect	✅	§4.13

Topic aliases	✅	§3.3.2.3.4
Enhanced authentication (AUTH)	✅	§4.12
Flow control (Receive Maximum)	✅	§3.3.4
Request/Response pattern	✅	§4.10
Shared subscriptions	✅	§4.8.2
Subscription identifiers	✅	§3.8.3.1
Topic filter validation	✅	§4.7

JVM	`jvm`	TCP/TLS, WebSocket	✅
Android	`android`	TCP/TLS, WebSocket	✅
iOS	`iosArm64`, `iosSimulatorArm64`	TCP/TLS, WebSocket	✅
macOS	`macosArm64`	TCP/TLS, WebSocket	✅
Linux	`linuxX64`, `linuxArm64`	TCP/TLS, WebSocket	✅
Windows	`mingwX64`	TCP/TLS, WebSocket	✅
Browser	`wasmJs`	WebSocket	✅

API Reference	meshtastic.github.io/MQTTastic-Client-KMP
Configuration Guide	docs/configuration.md
Topics & QoS Guide	docs/topics-and-qos.md
MQTT 5.0 Specification	OASIS MQTT v5.0
Changelog	CHANGELOG.md