CocoaMQTT Documentation

Mutual TLS allows the client to present its own certificate to the broker.

Transport Support

• TCP: Use CocoaMQTT or CocoaMQTT5.
• WSS (WebSockets): CocoaMQTTWebSocket automatically uses Apple's URLSessionWebSocketTask on modern OS versions (macOS 10.15+, iOS 13+, tvOS 13+, visionOS 1+). On older versions, it falls back to Starscream, which does not support client identities.

Configuration Methods

You can configure client identity using either PEM/DER or PKCS#12 formats before calling connect():

1. PEM/DER: certificateData accepts a DER certificate, a single PEM certificate, or a PEM bundle (leaf first, then intermediates). privateKeyData accepts RSA PKCS#1 (RSA PRIVATE KEY) or unencrypted RSA PKCS#8 (PRIVATE KEY).
2. PKCS#12: A password-protected identity container supported by Apple's SecPKCS12Import.

Security Best Practices

• Do not ship unencrypted PEM private keys in your application bundle.
• Do not embed PKCS#12 files with their passwords in the bundle.
• Use secure provisioning, user input, or Keychain-backed storage for long-lived secrets.

Key Properties

• tlsServerName: Use this when the connection host differs from the DNS name in the broker certificate.
• clientIdentity: Configures the client's identity (certificate and private key).
• trustedServerCertificates and usesSystemTrustStore: Configure how the client validates the broker.

To establish a connection using WebSockets, initialize a CocoaMQTTWebSocket with the desired URI and pass it as the socket parameter to the CocoaMQTT (MQTT 3.1.1) or CocoaMQTT5 (MQTT 5.0) constructor.

MQTT 5.0 Example

let websocket = CocoaMQTTWebSocket(uri: "/mqtt")
let mqtt5 = CocoaMQTT5(clientID: clientID, host: host, port: 8083, socket: websocket)
let connectProperties = MqttConnectProperties()
connectProperties.topicAliasMaximum = 0
mqtt5.connectProperties = connectProperties
_ = mqtt5.connect()

MQTT 3.1.1 Example

let websocket = CocoaMQTTWebSocket(uri: "/mqtt")
let mqtt = CocoaMQTT(clientID: clientID, host: host, port: 8083, socket: websocket)
_ = mqtt.connect()

///MQTT 5.0
let websocket = CocoaMQTTWebSocket(uri: "/mqtt")
let mqtt5 = CocoaMQTT5(clientID: clientID, host: host, port: 8083, socket: websocket)
let connectProperties = MqttConnectProperties()
connectProperties.topicAliasMaximum = 0
// ...
mqtt5.connectProperties = connectProperties
// ...

_ = mqtt5.connect()

///MQTT 3.1.1
let websocket = CocoaMQTTWebSocket(uri: "/mqtt")
let mqtt = CocoaMQTT(clientID: clientID, host: host, port: 8083, socket: websocket)

// ...

_ = mqtt.connect()

To react to MQTT events (connection, publishing, receiving messages, etc.) when using WebSockets, implement the CocoaMQTTDelegate protocol.

Key delegate methods include:

• mqtt(_:didConnectAck:): Called when connection is acknowledged.
• mqtt(_:didReceiveMessage:id:): Called when a message is received.
• mqtt(_:didPublishMessage:id:): Called when a message is successfully published.
• mqtt(_:didSubscribeTopics:failed:): Called after subscription attempts.
• mqttDidDisconnect(_:): Called when the client disconnects.

import CocoaMQTT
import CocoaMQTTWebSocket

class WebSocketManager {
    
    private var mqttClient: CocoaMQTT?
    var message: String = ""
    var token: String = ""

    func setupMQTTClient(with token: String) {
        let socket = CocoaMQTTWebSocket(uri: "/mqtt")
        socket.enableSSL = true
        mqttClient = CocoaMQTT(clientID: token, host: "host", port: 443, socket: socket)
        mqttClient?.delegate = self
    }

    func connect() {
        guard let mqttClient = mqttClient else { return }
        mqttClient.connect()
    }
    
}

extension WebSocketManager: CocoaMQTTDelegate {

    func mqtt(_ mqtt: CocoaMQTT, didPublishAck id: UInt16) {
        print("Published message with ID: \(id)")
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didUnsubscribeTopics topics: [String]) {
        print("Unsubscribed from topics: \(topics)")
    }
    
    func mqttDidPing(_ mqtt: CocoaMQTT) {
        print("MQTT did ping")
    }
    
    func mqttDidReceivePong(_ mqtt: CocoaMQTT) {
        print("MQTT did receive pong")
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didDisconnectAck ack: CocoaMQTTConnAck) {
        print("Connected to MQTT broker with acknowledgment: \(ack)")
    }

    func mqtt(_ mqtt: CocoaMQTT, didReceiveMessage message: CocoaMQTTMessage, id: UInt16) {
        if let messageString = message.string {
            DispatchQueue.main.async {
                self.message = messageString
            }
            print("Received message: \(messageString) on topic: \(message.topic)")
        }
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didPublishMessage message: CocoaMQTTMessage, id: UInt16) {
        print("Published message: \(message.string ?? "") with ID: \(id)")
    }

    func mqtt(_ mqtt: CocoaMQTT, didSubscribeTopics success: NSDictionary, failed: [String]) {
        print("Subscribed to topics: \(success), failed to subscribe to: \(failed)")
    }

    func mqtt(_ mqtt: CocoaMQTT, didDisconnectWithError err: Error?) {
        print("Disconnected from MQTT broker with error: \(String(describing: err))")
    }
    
}

When using the built-in Apple URLSessionWebSocketTask transport, there is a 1 MiB buffering limit. To handle larger messages, set maximumMessageSize on the CocoaMQTTWebSocket instance. Setting it to 0 removes the limit entirely (use with caution as it allows unbounded buffering).

You can also provide custom HTTP headers for the WebSocket connection.

Configuration Example

let websocket = CocoaMQTTWebSocket(uri: "/mqtt")
// Set limit to 10 MiB
websocket.maximumMessageSize = 10 * 1024 * 1024 + 1 

// Add custom headers
websocket.headers = [
    "x-api-key": "value"
]

// Enable SSL (WSS)
websocket.enableSSL = true

let mqtt = CocoaMQTT(clientID: clientID, host: host, port: 8083, socket: websocket)
_ = mqtt.connect()

let websocket = CocoaMQTTWebSocket(uri: "/mqtt")
websocket.maximumMessageSize = 10 * 1024 * 1024 + 1 // Accept up to 10 MiB.

websocket.headers = [
            "x-api-key": "value"
        ]
        websocket.enableSSL = true

let mqtt = CocoaMQTT(clientID: clientID, host: host, port: 8083, socket: websocket)

_ = mqtt.connect()