• Finalize KB-3 MQTT Programming with Python
  • Improve documentation on base/connect module

Readers will gather information to understand how messaging with MQTT can be set up for Python modules

Step-by-step guide

Simple plain style

The following code example show the minimal structure of a working mqtt-client which is able to send (publish) or receive (by subscribtion) mqtt messages. For FleFactor application it is strictly recommended to use the base/connect.py module, described in the following section, A detailed course is provided at steves-internet-guide.


Example code for a plain mqtt client app
""" Assume that the mqtt-server is located locally (localhost)"""
import paho.mqtt.client as mqtt 	# Step 1
client = mqtt.Client("client_id")	# Step 2
client.subscribe("topic")			# Step 3
client.connect("localhost")			# Step 4
client.loop_start()					# Step 5

# ...receive or publish messages	# step 6

client.disconnect()					# Step 7
client.loop_stop()
StepDescriptionReference
1

Import paho-mqtt library


2Instantiate an mqtt client
3Define subscriptions

on pub/sub

on topics

4

Connect to mqtt-server. In practice the script should evaluate the return code, since the execution have to wait for successfull estblishing the connection - otherwise data may get lost.

on connections
5

Start message publish and retrieval loop; this type will start a threaded infinite loop which handles publish and receiver requests. See document for further possibilities.

on loops
6

To react on incoming messages a on_message handler has to be defined. For each subscription a dedicated callback handle can be defined. Publishing requires a client.publish("topic", "payload")  command.


7At the end of the program, connection an loop should be ended gracefully.

Using flecsimo connect module

The flecsimo  base/connect module implements a wrapper class for the most relevant paho-mqtt functions and classes. The connect base class is called Connector, from which some special classes are derived to optimize different flecsimo applications.

Example code for a client using FlexFactory connect module
""" Assume that the mqtt-server is located locally (localhost)"""
from base import connect		 			# Step 1

broker = "..."								# Step 2
client_id = "..."
subscription = "..."

client = connect.Connector(id, broker)		# Step 3
client.will("...topic...", "...payload...") # Step 4

client.on_connect = on_connect				# Step 5
client.on_message = on_message
client.on_log = on_log
											# Step 6
client.add_callback("...topic...","...callback...")

client.start_connection("...topic...")		# Step 7
#
# ... do something
#
client.stop_connection()					# Step 8
StepDescriptionReference
1

Import FlexFctory base/connect module


2

Set variables for:

  • broker address (ip or 'localhost')
  • client id (used by mqtt server to identify client trafic)
  • one or more subscription (see ... to learn how subscriptions can be simplified using the flecsimo base/msg classes)

3Instantiate a base/connect client.


4

Optional: set a "last-will" message; this message will be shown at server if the connection of the client gets lost.

last will
5Optional: override paho-mqtt standard call back functions. Note: these functions have to be provided by the programmer. See examples.call backs
6

Optional: set individual call back function for specific topic. This allows to provide topic specific message handling and processing.

Note: these individual call backs have to be provided by the programmer.


7

Connect to the server and start the loop (with loop_start()). If a topic is provided with function call, the client will subscribe to that topic before loop start. This function will also handle return codes from connect.


8After work: stops loop and disconnects from server.
An excellent introduction is provided with Steve Copes Beginners Guide To The MQTT Protocol. The offical documentation of paho-mqqt con be found at www.eclipse.org/paho.