Eclipse Paho MQTT Python Client

Warnings

• breaking Version 2.0.0 introduced versioned user callbacks. If you omit the `callback_api_version` argument when creating `mqtt_client.Client`, it might default to `VERSION1` for positional arguments, leading to `Unsupported callback API version` errors, especially when migrating. In v2.1.0, it defaults to `VERSION1` if positional arguments are used, but `VERSION2` is recommended.
  Fix: Initialize the client with `mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION2, client_id)`. If you need to retain older callback signatures, explicitly use `mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION1, client_id)` but plan for migration to `VERSION2` as `VERSION1` is deprecated and will be removed in v3.0.
• breaking Version 2.0.0 dropped official support for Python 2.7, 3.5, and 3.6. The minimum supported Python version is now 3.7.
  Fix: Upgrade your Python environment to version 3.7 or newer.
• breaking The `connect_srv()` method signature changed in version 2.0.0 to include an additional `bind_port` parameter.
  Fix: Update calls to `connect_srv()` to include the `bind_port` argument.
• gotcha When checking return codes (e.g., from `on_connect` or `publish`), version 2.0.0 introduced `IntEnum` objects (like `ReasonCode` and `MQTT_ERR_SUCCESS`) instead of raw integers. Direct comparison using `is` (e.g., `rc is 0`) will likely fail, while `==` (e.g., `rc == 0`) will work correctly.
  Fix: Always use `==` for comparison with return codes (e.g., `if rc == 0:`).
• gotcha For non-durable MQTT clients, subscriptions are lost if the connection to the broker drops and is re-established. Placing subscription logic outside the `on_connect` callback can lead to missed messages after a reconnection.
  Fix: Always include `client.subscribe()` calls within your `on_connect` callback function. This ensures that subscriptions are automatically renewed upon successful reconnection to the broker.
• deprecated The `CallbackAPIVersion.VERSION1` (the historical API used before v2.0.0) is deprecated and is scheduled for removal in `paho-mqtt` version 3.0.
  Fix: Migrate your callback functions to use the `CallbackAPIVersion.VERSION2` signature and explicitly pass `mqtt_client.CallbackAPIVersion.VERSION2` to the `Client` constructor to prepare for future library updates.

Install

• pip install paho-mqtt Install stable version

Imports

• Client

  from paho.mqtt import client as mqtt_client

  Aliasing `paho.mqtt.client` to `mqtt_client` is a common convention for brevity and clarity.
• CallbackAPIVersion

  from paho.mqtt import client as mqtt_client

• publish.single

  from paho.mqtt import publish

• subscribe.simple

  from paho.mqtt import subscribe

Quickstart

This quickstart demonstrates how to connect to an MQTT broker, subscribe to a topic, and publish messages using the `paho-mqtt` client. It configures `on_connect` and `on_message` callbacks and uses `loop_start()` to handle network traffic in a background thread. It explicitly uses `CallbackAPIVersion.VERSION2` for modern MQTTv5 features and future compatibility. Environment variables are used for broker host/port for easy configuration.

import os
import time
from paho.mqtt import client as mqtt_client

broker = os.environ.get('MQTT_BROKER_HOST', 'broker.hivemq.com')
port = int(os.environ.get('MQTT_BROKER_PORT', 1883))
topic = os.environ.get('MQTT_TOPIC', "python/mqtt/test")
client_id = f'python-mqtt-subscriber-{time.time()}'

def on_connect(client, userdata, flags, rc, properties=None):
    if rc == 0:
        print("Connected to MQTT Broker!")
        client.subscribe(topic)
    else:
        print(f"Failed to connect, return code {rc}\n")

def on_message(client, userdata, msg):
    print(f"Received `{msg.payload.decode()}` from `{msg.topic}`")

def run():
    # Use CallbackAPIVersion.VERSION2 for MQTTv5 compatibility and future-proofing
    client = mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION2, client_id)
    # Optional: Set username/password if your broker requires it
    # client.username_pw_set(os.environ.get('MQTT_USERNAME', ''), os.environ.get('MQTT_PASSWORD', ''))
    client.on_connect = on_connect
    client.on_message = on_message
    client.connect(broker, port)
    client.loop_start() # Start background thread for network traffic

    # Publish a message after connection is established
    msg_count = 0
    while True:
        time.sleep(1)
        msg = f"messages: {msg_count}"
        result = client.publish(topic, msg)
        status = result[0]
        if status == 0:
            print(f"Sent `{msg}` to topic `{topic}`")
        else:
            print(f"Failed to send message to topic {topic}")
        msg_count += 1
        if msg_count >= 5: # Stop after 5 messages for quickstart example
            break
    
    client.loop_stop() # Stop the background thread
    client.disconnect()
    print("Disconnected from MQTT Broker.")

if __name__ == '__main__':
    run()