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.
