core/org.meshtastic.mqtt

Package-level declarations

Public MQTT 5.0 client API. Everything consumers need to connect, subscribe, publish, and observe messages.

Key entry points:

MqttClient — the top-level client.
MqttConfig — builder-style configuration.
MqttEndpoint — TCP vs WebSocket, with parse(uri) for tcp://, tls://, ws://, wss:// URIs.
MqttMessage — immutable message model backed by kotlinx.io.bytestring.ByteString.
QoS — quality-of-service levels.
MqttException — sealed error hierarchy.
MqttLogger — pluggable logging SAM.

Types

data class AuthChallenge(val reasonCode: ReasonCode, val authenticationMethod: String?, val authenticationData: ByteString?)

Represents an authentication challenge received from the broker during enhanced authentication (§4.12).

ConnectionState

sealed class ConnectionState

Observable connection lifecycle state for MqttClient.

MqttClient

class MqttClient(config: MqttConfig, scope: CoroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.Default))

MQTT 5.0 client for Kotlin Multiplatform.

MqttConfig

data class MqttConfig(val protocolVersion: MqttProtocolVersion = MqttProtocolVersion.V5_0, val negotiateVersion: Boolean = true, val clientId: String = "", val keepAliveSeconds: Int = 60, val cleanStart: Boolean = true, val username: String? = null, val password: ByteString? = null, val will: WillConfig? = null, val sessionExpiryInterval: Long? = null, val receiveMaximum: Int = 65535, val maximumPacketSize: Long? = null, val topicAliasMaximum: Int = 0, val useOutboundTopicAliases: Boolean = false, val requestResponseInformation: Boolean = false, val requestProblemInformation: Boolean = true, val userProperties: List<Pair<String, String>> = emptyList(), val authenticationMethod: String? = null, val authenticationData: ByteString? = null, val autoReconnect: Boolean = true, val reconnectBaseDelayMs: Long = 1000, val reconnectMaxDelayMs: Long = 30000, val maxReconnectAttempts: Int = 0, val defaultQos: QoS = QoS.AT_MOST_ONCE, val defaultRetain: Boolean = false, val logger: MqttLogger? = null, val logLevel: MqttLogLevel = MqttLogLevel.NONE, val transportFactory: MqttTransportFactory? = null)

Configuration for an MQTT 5.0 client connection.

MqttDsl

@DslMarker

@Target(allowedTargets = [AnnotationTarget.CLASS])

annotation class MqttDsl

DSL marker for MQTTastic builder scopes.

MqttEndpoint

sealed interface MqttEndpoint

Describes how to reach an MQTT broker.

MqttException

sealed class MqttException : Exception

Base exception for all MQTT client errors.

MqttLogger

interface MqttLogger

Logging interface for MQTTastic library consumers.

MqttLogLevel

enum MqttLogLevel : Enum<MqttLogLevel>

Log levels for the MQTTastic library, ordered from most verbose to least verbose.

MqttMessage

data class MqttMessage(val topic: String, val payload: ByteString, val qos: QoS = QoS.AT_MOST_ONCE, val retain: Boolean = false, val properties: PublishProperties = PublishProperties())

Represents a received or outgoing MQTT message with full MQTT 5.0 properties.

MqttProtocolVersion

enum MqttProtocolVersion : Enum<MqttProtocolVersion>

MQTT protocol version for the client connection.

MqttTransport

interface MqttTransport

Abstract byte-level transport for MQTT connections.

MqttTransportFactory

interface MqttTransportFactory

Creates the MqttTransport for a given MqttEndpoint.

ProbeResult

sealed class ProbeResult

Outcome of a one-shot connectivity probe issued via MqttClient.probe.

ProbeServerInfo

data class ProbeServerInfo(val assignedClientIdentifier: String? = null, val serverKeepAliveSeconds: Int? = null, val maximumQosOrdinal: Int? = null, val retainAvailable: Boolean? = null, val wildcardSubscriptionAvailable: Boolean? = null, val sharedSubscriptionAvailable: Boolean? = null, val subscriptionIdentifiersAvailable: Boolean? = null, val maximumPacketSize: Long? = null, val receiveMaximum: Int? = null, val topicAliasMaximum: Int? = null, val serverReference: String? = null, val responseInformation: String? = null)

Curated, public-API subset of the broker capabilities advertised in CONNACK properties (§3.2.2.3), surfaced via ProbeResult.Success. Mirrors the internal MqttProperties shape but exposes only fields that are actionable for a probe diagnostic UI.

PublishProperties

data class PublishProperties(val messageExpiryInterval: Long? = null, val topicAlias: Int? = null, val contentType: String? = null, val responseTopic: String? = null, val correlationData: ByteString? = null, val payloadFormatIndicator: Boolean = false, val userProperties: List<Pair<String, String>> = emptyList(), val subscriptionIdentifiers: List<Int> = emptyList())

MQTT 5.0 properties that can accompany a PUBLISH packet (§3.3.2.3).

QoS

enum QoS : Enum<QoS>

Quality of Service levels for MQTT message delivery per §4.3.

ReasonCode

enum ReasonCode : Enum<ReasonCode>

MQTT 5.0 reason codes per §2.4.

RetainHandling

enum RetainHandling : Enum<RetainHandling>

Controls when the broker sends retained messages for a subscription (§3.8.3.1).

WillConfig

data class WillConfig(val topic: String, val payload: ByteString = ByteString(), val qos: QoS = QoS.AT_MOST_ONCE, val retain: Boolean = false, val willDelayInterval: Long? = null, val messageExpiryInterval: Long? = null, val contentType: String? = null, val responseTopic: String? = null, val correlationData: ByteString? = null, val payloadFormatIndicator: Boolean = false, val userProperties: List<Pair<String, String>> = emptyList())

Configuration for an MQTT 5.0 Will Message (§3.1.3.2).

Properties

DEFAULT_PROBE_TIMEOUT_MS

const val DEFAULT_PROBE_TIMEOUT_MS: Long

Default timeout for MqttClient.probe, in milliseconds.

Functions

messagesForTopic

fun MqttClient.messagesForTopic(topic: String): Flow<MqttMessage>

Returns a Flow of messages filtered to a specific topic.

messagesMatching

fun MqttClient.messagesMatching(topicFilter: String): Flow<MqttMessage>

Returns a Flow of messages whose topic matches the given MQTT topicFilter.

MqttClient

fun MqttClient(clientId: String, scope: CoroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.Default), configure: MqttConfig.Builder.() -> Unit = {}): MqttClient

Creates an MqttClient with the given clientId and optional configuration.

plus

operator fun MqttTransportFactory.plus(other: MqttTransportFactory): MqttTransportFactory

Combine two factories into one that delegates to whichever supports the endpoint, trying the left-hand factory first. Use this to accept more than one endpoint type (e.g. both TCP and WebSocket) from a single client.

probe

suspend fun MqttClient.Companion.probe(endpoint: MqttEndpoint, timeoutMs: Long = DEFAULT_PROBE_TIMEOUT_MS, configure: MqttConfig.Builder.() -> Unit = {}): ProbeResult

Run a one-shot connectivity probe against endpoint without disturbing any live client.

use

suspend fun <T> MqttClient.use(endpoint: MqttEndpoint, block: suspend (MqttClient) -> T): T

Connect, execute block, then close — structured resource management.