← Back to the chapter · Previous detail · Next detail →

Technical detail · MQTT Python: Reliable Client Patterns

Mosquitto connection limits and a capacity worksheet

An MQTT broker can refuse clients at its connection or resource limits.

These examples use the Mosquitto broker and Paho Python library. TCP (Transmission Control Protocol) supplies connections; TLS (Transport Layer Security) protects them. QoS (quality of service) selects delivery levels. Callbacks handle client events; reason codes report protocol outcomes. \$SYS names system topics; backoff increases retry waits.

The Mistake: Developers deploy IoT systems without considering broker connection limits. They test with 10-20 devices successfully, then deploy 500+ devices to production. New devices fail to connect with cryptic errors like “connection refused” or timeout, while existing connections work fine.

Why It Happens: MQTT brokers and host operating systems impose connection and resource limits that vary by deployment. Each TCP connection consumes a socket and broker memory; TLS and queued session state add more. At a configured limit, new connections may be refused or time out, depending on the broker and failure point.

The Fix: Calculate connection requirements before deployment. Configure broker limits explicitly. Implement connection health monitoring and alerting when approaching 80% capacity. Use connection pooling or MQTT bridge patterns for high-scale deployments.

# Inspect the deployed Mosquitto configuration and host file-descriptor limit
grep -R '^[[:space:]]*max_connections' /etc/mosquitto/
ulimit -n

# mosquitto.conf - Production configuration for 5,000 devices
max_connections 6000        # 20% headroom over expected devices
max_queued_messages 1000    # Per-client queue limit
max_inflight_messages 20    # In-flight QoS 1/2 messages
memory_limit 1073741824     # 1GB memory cap

# OS-level: Increase file descriptor limits
# /etc/security/limits.conf
# mosquitto soft nofile 65535
# mosquitto hard nofile 65535

# /etc/sysctl.conf
# net.core.somaxconn = 4096
# net.ipv4.tcp_max_syn_backlog = 4096
# Client-side connection monitoring
import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code == 0:
        print("Connected successfully")
    elif reason_code == 134:  # MQTT 5 reason 0x86
        print("ERROR: Connection refused - bad username or password")
    elif reason_code == 136:  # MQTT 5 reason 0x88
        print("ERROR: Server unavailable - inspect broker logs")
    elif reason_code == 0x9F:  # MQTT 5 connection rate exceeded
        print("ERROR: Connection rate exceeded - implement backoff")
    else:
        print(f"Connection refused: {reason_code}")

# Monitor broker capacity via $SYS topics
def monitor_broker_capacity(client):
    client.subscribe("$SYS/broker/clients/connected")
    client.subscribe("$SYS/broker/clients/maximum")

def on_sys_message(client, userdata, msg):
    if "connected" in msg.topic:
        connected = int(msg.payload.decode())
        max_clients = userdata.get("max_clients", 1024)
        usage_pct = (connected / max_clients) * 100
        if usage_pct > 80:
            print(f"WARNING: Broker at {usage_pct:.1f}% capacity ({connected}/{max_clients})")

Illustrative capacity worksheet: Assume 20% device headroom, two connections per backend service, and three per monitoring tool. For 1,000 devices, 5 backend services and 2 monitoring tools, that is (1000 x 1.2) + (5 x 2) + (2 x 3) = 1,216 planned connection slots. Validate the actual connection pattern and reconnect burst before setting a broker limit.

← Back to the chapter · Previous detail · Next detail →