You can connect your CircuitPython device to any MQTT broker of your choice. MQTT brokers generally fall in three categories: Commercial hosted (Paid), Free hosted (Adafruit IO's MQTT broker lives on servers owned by Adafruit - we have a free tier), or Free and self-hosted (bring your own server!).
Commercial Brokers
These large-scale commercial (paid) brokers come with a higher data-rate speed and usually include device management features.
These brokers can also connect to CircuitPython devices running MiniMQTT. The primary advantage of using one of these services over your own broker or Adafruit IO is integration with a larger suite of cloud-hosted tools. For example, if you are sending data to an Azure IoT Hub via MQTT, you could visualize sensor data using PowerBI or run machine learning models on it from Azure.
Self-Hosted Brokers
There are plenty of tools out there to host your own MQTT broker. We like Eclipse's Mosquitto - it's an open-source broker which implements the MQTT protocol. There are images for Mac, Linux, Windows and Raspberry Pi.
Secrets File Setup
While you created a secrets file and connected to the Internet in the previous step, you'll need to edit the secrets.py file to include information about your MQTT broker.
Add the following code to your secrets.py file, replacing _your_broker_url_or_ip
with the URL or IP Address of the MQTT broker you'd like to connect to.
If your MQTT broker requires authentication, replace _your_mqtt_broker_username_
with the username you use to log into the broker.
Then, replace _your_mqtt_broker_password_
with the password you use to authenticate your username with the broker.
If your MQTT broker does not require authentication, you may remove these fields.
secrets = { 'ssid' : '_your_wifi_ssid_', 'password' : '_your_wifi_password_', 'broker' : '_your_mqtt_broker_url_or_ip', 'user' : '_your_mqtt_broker_username_', 'pass' : '_your_mqtt_broker_password_' }
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT import ssl import socketpool import wifi import adafruit_minimqtt.adafruit_minimqtt as MQTT # Add a secrets.py to your filesystem that has a dictionary called secrets with "ssid" and # "password" keys with your WiFi credentials. DO NOT share that file or commit it into Git or other # source control. # pylint: disable=no-name-in-module,wrong-import-order try: from secrets import secrets except ImportError: print("WiFi secrets are kept in secrets.py, please add them there!") raise # Set your Adafruit IO Username and Key in secrets.py # (visit io.adafruit.com if you need to create an account, # or if you need your Adafruit IO key.) aio_username = secrets["aio_username"] aio_key = secrets["aio_key"] print("Connecting to %s" % secrets["ssid"]) wifi.radio.connect(secrets["ssid"], secrets["password"]) print("Connected to %s!" % secrets["ssid"]) ### Topic Setup ### # MQTT Topic # Use this topic if you'd like to connect to a standard MQTT broker mqtt_topic = "test/topic" # Adafruit IO-style Topic # Use this topic if you'd like to connect to io.adafruit.com # mqtt_topic = secrets["aio_username"] + '/feeds/temperature' ### Code ### # Define callback methods which are called when events occur # pylint: disable=unused-argument, redefined-outer-name def connect(mqtt_client, userdata, flags, rc): # This function will be called when the mqtt_client is connected # successfully to the broker. print("Connected to MQTT Broker!") print("Flags: {0}\n RC: {1}".format(flags, rc)) def disconnect(mqtt_client, userdata, rc): # This method is called when the mqtt_client disconnects # from the broker. print("Disconnected from MQTT Broker!") def subscribe(mqtt_client, userdata, topic, granted_qos): # This method is called when the mqtt_client subscribes to a new feed. print("Subscribed to {0} with QOS level {1}".format(topic, granted_qos)) def unsubscribe(mqtt_client, userdata, topic, pid): # This method is called when the mqtt_client unsubscribes from a feed. print("Unsubscribed from {0} with PID {1}".format(topic, pid)) def publish(mqtt_client, userdata, topic, pid): # This method is called when the mqtt_client publishes data to a feed. print("Published to {0} with PID {1}".format(topic, pid)) def message(client, topic, message): # Method called when a client's subscribed feed has a new value. print("New message on topic {0}: {1}".format(topic, message)) # Create a socket pool pool = socketpool.SocketPool(wifi.radio) # Set up a MiniMQTT Client mqtt_client = MQTT.MQTT( broker=secrets["broker"], port=secrets["port"], username=secrets["aio_username"], password=secrets["aio_key"], socket_pool=pool, ssl_context=ssl.create_default_context(), ) # Connect callback handlers to mqtt_client mqtt_client.on_connect = connect mqtt_client.on_disconnect = disconnect mqtt_client.on_subscribe = subscribe mqtt_client.on_unsubscribe = unsubscribe mqtt_client.on_publish = publish mqtt_client.on_message = message print("Attempting to connect to %s" % mqtt_client.broker) mqtt_client.connect() print("Subscribing to %s" % mqtt_topic) mqtt_client.subscribe(mqtt_topic) print("Publishing to %s" % mqtt_topic) mqtt_client.publish(mqtt_topic, "Hello Broker!") print("Unsubscribing from %s" % mqtt_topic) mqtt_client.unsubscribe(mqtt_topic) print("Disconnecting from %s" % mqtt_client.broker) mqtt_client.disconnect()
Before running your code, you'll need to make a few small changes for your configuration.
First, replace mqtt_topic
with the mqtt topic you'd like to subscribe to. For example, if you are building a weather station and want to subscribe to its temperature.
Change the mqtt_topic
from
mqtt_topic = 'test/topic'
to
mqtt_topic= 'weatherstation/temperature'
- For more information about MQTT topic naming, check out this page here.
MiniMQTT Port Configuration
By default, MiniMQTT connects to port 8883 (Secure/SSL). If you'd like to connect to a different port on the broker, use the following code to initialize the client.
# Set up a MiniMQTT Client client = MQTT.MQTT(broker = secrets['broker'], username = secrets['user'], password = secrets['pass'], port = 1883)
Code Usage
After setting up your topic and broker configuration, it's time to connect. Save the code.py file and open the serial monitor.
The client attempts to connect to the MQTT broker you specified.
Attempting to connect to io.adafruit.com Connected to MQTT Broker! Flags: 0 RC: 0
The client subscribes to the mqtt_topic
you specified.
Subscribed to user/topic with QOS level 1
And notifies you that it subscribed to mqtt_topic
with a quality of service level of 1. You can set the quality of service level by modifying the call to subscribe
(read the docs about this method here).
The client publishes the string Hello Broker to the mqtt_topic
.
Published to user/topic with PID 11
The client unsubscribes from the mqtt_topic
.
Unsubscribed from user/topic with PID 22
Finally, the client disconnects from the MQTT broker
Disconnected from MQTT Broker!
The code tests all the primary methods of the MiniMQTT client. We'll walk through the code to understand how this example works.