Skip to main content

Build Status codecov

Python MQTT client implementation.

Installation

The latest stable version is available in the Python Package Index (PyPi) and can be installed using

pip3 install gmqtt

Usage

Getting Started

Here is a very simple example that subscribes to the broker TOPIC topic and prints out the resulting messages:

import asyncio
import os
import signal
import time

from gmqtt import Client as MQTTClient

# gmqtt also compatibility with uvloop  
import uvloop
asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())


STOP = asyncio.Event()


def on_connect(client, flags, rc, properties):
    print('Connected')
    client.subscribe('TEST/#', qos=0)


def on_message(client, topic, payload, qos, properties):
    print('RECV MSG:', payload)


def on_disconnect(client, packet, exc=None):
    print('Disconnected')

def on_subscribe(client, mid, qos):
    print('SUBSCRIBED')

def ask_exit(*args):
    STOP.set()

async def main(broker_host, token):
    client = MQTTClient("client-id")

    client.on_connect = on_connect
    client.on_message = on_message
    client.on_disconnect = on_disconnect
    client.on_subscribe = on_subscribe

    client.set_auth_credentials(token, None)
    await client.connect(broker_host)

    client.publish('TEST/TIME', str(time.time()), qos=1)

    await STOP.wait()
    await client.disconnect()


if __name__ == '__main__':
    loop = asyncio.get_event_loop()

    host = 'mqtt.flespi.io'
    token = os.environ.get('FLESPI_TOKEN')

    loop.add_signal_handler(signal.SIGINT, ask_exit)
    loop.add_signal_handler(signal.SIGTERM, ask_exit)

    loop.run_until_complete(main(host, token))

MQTT Version 5.0

gmqtt supports MQTT version 5.0 protocol

Version setup

Version 5.0 is used by default. If your broker does not support 5.0 protocol version and responds with proper CONNACK reason code, client will downgrade to 3.1 and reconnect automatically. Note, that some brokers just fail to parse the 5.0 format CONNECT packet, so first check manually if your broker handles this properly. You can also force version in connect method:

from gmqtt.mqtt.constants import MQTTv311
client = MQTTClient('clientid')
client.set_auth_credentials(token, None)
await client.connect(broker_host, 1883, keepalive=60, version=MQTTv311)

Properties

MQTT 5.0 protocol allows to include custom properties into packages, here is example of passing response topic property in published message:

TOPIC = 'testtopic/TOPIC'

def on_connect(client, flags, rc, properties):
    client.subscribe(TOPIC, qos=1)
    print('Connected')

def on_message(client, topic, payload, qos, properties):
    print('RECV MSG:', topic, payload.decode(), properties)

async def main(broker_host, token):
    client = MQTTClient('asdfghjk')
    client.on_message = on_message
    client.on_connect = on_connect
    client.set_auth_credentials(token, None)
    await client.connect(broker_host, 1883, keepalive=60)
    client.publish(TOPIC, 'Message payload', response_topic='RESPONSE/TOPIC')

    await STOP.wait()
    await client.disconnect()
Connect properties

Connect properties are passed to Client object as kwargs (later they are stored together with properties received from broker in client.properties field). See example below.

  • session_expiry_interval - int Session expiry interval in seconds. If the Session Expiry Interval is absent the value 0 is used. If it is set to 0, or is absent, the Session ends when the Network Connection is closed. If the Session Expiry Interval is 0xFFFFFFFF (max possible value), the Session does not expire.
  • receive_maximum - int The Client uses this value to limit the number of QoS 1 and QoS 2 publications that it is willing to process concurrently.
  • user_property - tuple(str, str) This property may be used to provide additional diagnostic or other information (key-value pairs).
  • maximum_packet_size - int The Client uses the Maximum Packet Size (in bytes) to inform the Server that it will not process packets exceeding this limit.

Example:

client = gmqtt.Client("lenkaklient", receive_maximum=24000, session_expiry_interval=60, user_property=('myid', '12345'))
Publish properties

This properties will be also sent in publish packet from broker, they will be passed to on_message callback.

  • message_expiry_interval - int If present, the value is the lifetime of the Application Message in seconds.
  • content_type - unicode UTF-8 Encoded String describing the content of the Application Message. The value of the Content Type is defined by the sending and receiving application.
  • user_property - tuple(str, str)
  • subscription_identifier - int (see subscribe properties) sent by broker

Example:

def on_message(client, topic, payload, qos, properties):
    # properties example here: {'content_type': ['json'], 'user_property': [('timestamp', '1524235334.881058')], 'message_expiry_interval': [60], 'subscription_identifier': [42, 64]}
    print('RECV MSG:', topic, payload, properties)

client.publish('TEST/TIME', str(time.time()), qos=1, retain=True, message_expiry_interval=60, content_type='json')
Subscribe properties
  • subscription_identifier - int If the Client specified a Subscription Identifier for any of the overlapping subscriptions the Server MUST send those Subscription Identifiers in the message which is published as the result of the subscriptions.

Reconnects

By default, connected MQTT client will always try to reconnect in case of lost connections. Number of reconnect attempts is unlimited. If you want to change this behaviour, do the following:

client = MQTTClient("client-id")
client.set_config({'reconnect_retries': 10, 'reconnect_delay': 60})

Code above will set number of reconnect attempts to 10 and delay between reconnect attempts to 1min (60s). By default reconnect_delay=6 and reconnect_retries=-1 which stands for infinity. Note that manually calling await client.disconnect() will set reconnect_retries for 0, which will stop auto reconnect.

Asynchronous on_message callback

You can define asynchronous on_message callback. Note that it must return valid PUBACK code (0 is success code, see full list in constants)

async def on_message(client, topic, payload, qos, properties):
    pass
    return 0

Other examples

Check examples directory for more use cases.

Metadata

Release files for gmqtt 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gmqtt 0.4.1
File Size Uploaded Provenance Actions
gmqtt-0.4.1.tar.gz 20.8 kB Without provenance Details for gmqtt-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gmqtt 0.4.1
File Interpreter ABI Platform Actions
gmqtt-0.4.1-py3-none-any.whl Python 3 none any Details for gmqtt-0.4.1-py3-none-any.whl

Total release size: 48.4 kB

Release files / gmqtt-0.4.1.tar.gz

Download URL gmqtt-0.4.1.tar.gz
Size 20.8 kB
Tags Source
SHA-256 checksum
How to use checksums
998b9900af615efa2fbd5b9566ebd1f038ce1f326c1a4a08a12d21b6239b67f1
BLAKE2b-256 checksum
How to use checksums
6020d3fbce280a84a07f6fe8f38b80ada34a868fcbdcb679d78c98d57e5af133
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.13.0 pkginfo/1.5.0.1 requests/2.18.4 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.1 CPython/3.5.2

Release files / gmqtt-0.4.1-py3-none-any.whl

Download URL gmqtt-0.4.1-py3-none-any.whl
Size 27.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ffcd86a749a08af633c2859699acc94e767cbc60a10bebe7ba2dc43bcee078de
BLAKE2b-256 checksum
How to use checksums
03ca4e58fb67bcc4c260a329a8a763fb573ceed9b8a29dfb12affd2b171acfe2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.13.0 pkginfo/1.5.0.1 requests/2.18.4 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.1 CPython/3.5.2

Security for gmqtt 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.4.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page