library/org.meshtastic.mqtt/probe

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.

Spins up a transient MqttConnection, performs the CONNECT/CONNACK handshake, tears it back down, and reports the outcome as a ProbeResult. This API never throws for connectivity errors — see ProbeResult for the exhaustive outcome hierarchy. Cancellation of the calling coroutine is propagated normally.

The probe uses clientId = "" (broker-assigned) and cleanStart = true by default; override via configure if your broker enforces specific credentials or client identifiers. autoReconnect is forced to false regardless of the configure block — probes are always single-shot.

Example

val result = MqttClient.probe(
    endpoint = MqttEndpoint.Tcp("broker.example.com", 8883, tls = true),
    timeoutMs = 3_000,
) {
    username = "diag"
    password = ByteString("hunter2".encodeToByteArray())
}

Return

A ProbeResult describing the outcome.

Parameters

endpoint

The broker endpoint to probe.

timeoutMs

Total wall-clock budget for the probe, in milliseconds. Default: DEFAULT_PROBE_TIMEOUT_MS.

configure

Optional configuration block applied to the transient client (clientId, username, password, …). autoReconnect is always overridden to false after the block runs.