mqtt_client

When using mqtt_client in a Flutter environment on iOS, you must grant permission to access the local network to discover Bonjour services. Add the following keys to your ios/Runner/Info.plist file:

<key>NSLocalNetworkUsageDescription</key>
<string>Looking for local tcp Bonjour service</string>
<key>NSBonjourServices</key>
<array>
  <string>mqtt.tcp</string>
</array>

When using mqtt_client in a Flutter environment on Android, you must ensure the application has permission to access the internet and network state. Add the following permissions to your android/app/src/main/AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

The MqttClient supports automatic reconnection if autoReconnect is set to true.

• autoReconnect: If true, the client will attempt to reconnect indefinitely after an unexpected disconnect. This mechanism is only triggered if an initial connection was successfully established.
• resubscribeOnAutoReconnect: If true (default), the client automatically re-subscribes to all previously confirmed subscriptions during the reconnection process. If set to false, you must manually handle re-subscriptions using the provided callbacks.

client.autoReconnect = true;
client.resubscribeOnAutoReconnect = true;

To use the mqtt_client package, you must instantiate either an MqttClientServer or an MqttBrowserClient (do not instantiate MqttClient directly). The client requires a server hostname and a unique client identifier. You can also specify a custom port.

Use the default constructor for the standard MQTT port (1883) or MqttClient.withPort to specify a different port.

// Using default port (1883)
final client = MqttClientServer('your.broker.hostname', 'unique_client_id');

// Using a custom port
final client = MqttClientServer.withPort('your.broker.hostname', 'unique_client_id', 1883);

To maintain a connection and monitor health, use the Keep Alive settings:

• keepAlivePeriod: The interval in seconds for ping requests. Set to a valid value to enable keep alive.
• disconnectOnNoResponsePeriod: The number of seconds to wait for a ping response (pong) before forcibly disconnecting. Default is 0 (disabled).
• pingCallback: Callback triggered when a ping request is sent.
• pongCallback: Callback triggered when a ping response is received.
• lastCycleLatency: Returns the latency of the last ping/pong cycle in milliseconds.
• averageCycleLatency: Returns the average latency of all cycles in the current connection period.

You can control how long the client waits for network operations:

• socketTimeout: Specifies the maximum time in milliseconds to wait for a socket connection (TCP only). Setting this disables connectTimeoutPeriod.
• connectTimeoutPeriod: Specifies the time period in milliseconds between successive connection attempts. Defaults to 5000ms. Minimum value is 1000ms.

You can assign callback functions to handle various lifecycle events:

• onConnected: Called on successful connection.
• onDisconnected: Called on unsolicited disconnects (broker termination).
• onAutoReconnect: Called before the auto-reconnect process begins.
• onAutoReconnected: Called after the auto-reconnect process completes.
• onFailedConnectionAttempt: Called on every failed attempt if autoReconnect is NOT set.
• onSubscribed / onSubscribeFail: Called when subscription requests are acknowledged or fail.
• onUnsubscribed: Called when an unsubscription is confirmed.

The MqttVariableHeader class serves as the base class for the Variable Header portion of MQTT messages. It manages common fields such as protocol name, protocol version, keep alive timers, and message identifiers.

Developers can instantiate a header using the default constructor or populate it from an existing byte stream using MqttVariableHeader.fromByteBuffer(MqttByteBuffer headerStream).

// Initialize a new header with default protocol settings
var header = MqttVariableHeader();

// Or initialize from a byte stream
var headerFromStream = MqttVariableHeader.fromByteBuffer(myMqttByteBuffer);

You can enable or disable logging for the client using the logging() method. You can also control whether the message payloads are included in the logs.

// Enable logging with payloads
client.logging(on: true, logPayloads: true);

// Enable logging without payloads
client.logging(on: true, logPayloads: false);

MQTT 'Will' messages (Last Will and Testament) allow the broker to notify other clients if the connection is unexpectedly lost. You can configure this using the following methods:

• will(): Sets the willFlag to true.
• withWillQos(MqttQos qos): Sets the Quality of Service for the Will message.
• withWillRetain(): Sets the willRetain flag.
• withWillTopic(String willTopic): Sets the topic for the Will message (automatically calls will()).
• withWillMessage(String willMessage): Sets the payload for the Will message (automatically calls will()).

message.withWillTopic('clients/status')
       .withWillMessage('unexpected_disconnect')
       .withWillQos(MqttQos.atLeastOnce)
       .withWillRetain();