Skip to content

Connection Options

The ConnectionOptions data class encapsulates all parameters needed to connect to an MQTT broker, including authentication, connection behavior, Last Will and Testament (LWT), and auto-subscription settings.

Overview

Connection options are passed to ConnectCommand to establish an MQTT broker connection.

data class ConnectionOptions(
    val serverUri: String,
    val clientId: String,
    val username: String? = null,
    val password: String? = null,
    val connectionTimeoutSeconds: Int = 60,
    val keepAliveIntervalSeconds: Int = 30,
    val cleanSession: Boolean = false,
    val automaticReconnect: Boolean = false,
    val willTopic: String? = null,
    val willMessage: String? = null,
    val willQos: Int = 1,
    val willRetain: Boolean = false,
    val autoSubscriptionConfig: AutoSubscriptionConfig = AutoSubscriptionConfig()
)

Parameters

serverUri (Required)

Type: String

The MQTT broker URI. Supports multiple protocols:

Protocol Format Port Use Case
TCP tcp://broker.example.com:1883 1883 Standard unencrypted
WebSocket ws://broker.example.com:9001 9001 HTTP-based
WebSocket Secure wss://broker.example.com:9443 9443 HTTPS-based

Examples

// TCP (standard)
serverUri = "tcp://broker.hivemq.com:1883"

// WebSocket
serverUri = "ws://broker.example.com:9001"

// WebSocket Secure
serverUri = "wss://broker.example.com:9443"

clientId (Required)

Type: String

Unique identifier for this MQTT client. Must be unique across all clients connecting to the same broker.

username (Optional)

Type: String? (Default: null)

Username for broker authentication. Set to null if broker doesn't require authentication.

username = "mqtt_user"

password (Optional)

Type: String? (Default: null)

Password for broker authentication. Set to null if broker doesn't require authentication.

password = "secure_password"

connectionTimeoutSeconds

Type: Int (Default: 60)

Maximum time to wait for connection establishment in seconds.

connectionTimeoutSeconds = 30  // 30 seconds timeout

keepAliveIntervalSeconds

Type: Int (Default: 30)

Interval for sending MQTT ping messages to keep the connection alive.

keepAliveIntervalSeconds = 60  // Ping every 60 seconds

How It Works

  • Client sends PINGREQ every keepAliveIntervalSeconds
  • Broker responds with PINGRESP
  • If no response within 1.5× interval, connection is considered lost

cleanSession

Type: Boolean (Default: false)

Controls session persistence on the broker.

automaticReconnect

Type: Boolean (Default: false)

Enables Paho's built-in automatic reconnection on connection loss.

automaticReconnect = true

Pulse MQTT Network Monitoring

Pulse MQTT has its own network-aware reconnection via NetworkMonitoringConfig. You can use either or both:

  • Paho's automatic reconnect: Immediate, protocol-level
  • Pulse MQTT network monitoring: Smart, waits for network availability

Last Will and Testament (LWT)

LWT allows the broker to send a message on behalf of the client if it disconnects ungracefully.

willTopic

Type: String? (Default: null)

Topic where LWT message will be published.

willTopic = "device/${deviceId}/status"

willMessage

Type: String? (Default: null)

Message content for LWT.

willMessage = """{"status": "offline", "timestamp": ${System.currentTimeMillis()}}"""

willQos

Type: Int (Default: 1)

QoS level for LWT message (0, 1, or 2).

willQos = 1  // At least once delivery

willRetain

Type: Boolean (Default: false)

Whether LWT message should be retained by broker.

willRetain = true  // Retain "offline" status

Complete LWT Example

val connectionOptions = ConnectionOptions(
    serverUri = "tcp://broker.example.com:1883",
    clientId = "device-123",
    willTopic = "devices/device-123/status",
    willMessage = """{"status": "offline", "reason": "unexpected"}""",
    willQos = 1,
    willRetain = true  // Last known status persists
)

LWT Use Cases

  1. Device Status Monitoring 

    willTopic = "devices/${deviceId}/presence"
willMessage = """{"online": false}"""
willRetain = true

  2. User Presence 

    willTopic = "users/${userId}/status"
willMessage = """{"status": "offline", "lastSeen": ${timestamp}}"""

  3. Emergency Alerts 

    willTopic = "alerts/critical"
willMessage = """{"device": "${deviceId}", "alert": "connection_lost"}"""
willQos = 2  // Exactly once

autoSubscriptionConfig

Type: AutoSubscriptionConfig (Default: AutoSubscriptionConfig())

Configuration for automatic topic resubscription after connection loss and recovery.

See AutoSubscriptionConfig section below.

autoSubscriptionConfig = AutoSubscriptionConfig(
    enabled = true,
    subscribeCommandRetryPolicy = RetryPolicy.exponential(maxRetries = 3),
    subscribeCommandTimeout = 30_000L
)

AutoSubscriptionConfig Details

Eliminates manual resubscription after connection loss.

Structure

data class AutoSubscriptionConfig(
    val enabled: Boolean = false,
    val subscribeCommandRetryPolicy: RetryPolicy = RetryPolicy.none(),
    val subscribeCommandTimeout: Long = 60_000L,
    val subscriptionStore: HashMap<String, TopicTypeConfig<*>>? = null
)

Parameters

enabled

Type: Boolean (Default: false)

Enables/disables automatic resubscription.

enabled = true  // Auto-resubscribe after reconnection

subscribeCommandRetryPolicy

Type: RetryPolicy (Default: RetryPolicy.none())

Retry policy for resubscription attempts.

subscribeCommandRetryPolicy = RetryPolicy.exponential(
    maxRetries = 3,
    baseDelayMillis = 1000
)

subscribeCommandTimeout

Type: Long (Default: 60000L)

Timeout for each resubscription attempt in milliseconds.

subscribeCommandTimeout = 30_000L  // 30 seconds

subscriptionStore

Type: HashMap<String, TopicTypeConfig<*>>? (Default: null)

Optional pre-populated subscription store for initial subscriptions.

val subscriptionStore = hashMapOf(
    "orders/updates" to TopicTypeConfig(
        messageType = OrderUpdate::class.java,
        qosLevel = QOSLevel.QOS_1
    ),
    "rider/location" to TopicTypeConfig(
        messageType = RiderLocation::class.java,
        qosLevel = QOSLevel.QOS_0
    )
)

autoSubscriptionConfig = AutoSubscriptionConfig(
    enabled = true,
    subscriptionStore = subscriptionStore
)

Complete Auto-Subscription Example

// Define subscription store
val subscriptions = hashMapOf(
    "orders/+/updates" to TopicTypeConfig(
        messageType = OrderUpdate::class.java,
        qosLevel = QOSLevel.QOS_1
    )
)

// Configure connection with auto-subscription
val connectionOptions = ConnectionOptions(
    serverUri = "tcp://broker.example.com:1883",
    clientId = "rider-app-${userId}",
    cleanSession = false,  // Keep session for persistence
    autoSubscriptionConfig = AutoSubscriptionConfig(
        enabled = true,
        subscribeCommandRetryPolicy = RetryPolicy.exponential(
            maxRetries = 3,
            baseDelayMillis = 1000,
            maxDelayMillis = 30000
        ),
        subscribeCommandTimeout = 30_000L,
        subscriptionStore = subscriptions
    )
)

// Connect - subscriptions will be automatically restored after any reconnection
pulseMqttKit.submitCommand(ConnectCommand(connectionOptions = connectionOptions))

See Also