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.
settings.toml File Setup for Adafruit IO
While you created a settings.toml file and connected to the internet in the previous step, as described in the Create Your settings.toml File page earlier in the guide. You'll need to edit the settings.toml file to include your Adafruit IO Username and Active Key.
Add the following lines to your settings.toml file, replacing _your_adafruit_io_username with your Adafruit IO username.
Then, replace _your_big_huge_super_long_aio_key_ with your Adafruit IO Active Key.
CIRCUITPY_WIFI_SSID = "your-ssid-here" CIRCUITPY_WIFI_PASSWORD = "your-ssid-password-here" aio_username = "_your_adafruit_io_username_" aio_key = "_your_big_huge_super_long_aio_key_"
Make sure you save this file before proceeding as settings.toml in the root directory of your board CIRCUITPY drive.
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
from os import getenv
import adafruit_connection_manager
import board
import busio
from adafruit_esp32spi import adafruit_esp32spi
from digitalio import DigitalInOut
import adafruit_minimqtt.adafruit_minimqtt as MQTT
# Get WiFi details and Adafruit IO keys, ensure these are setup in settings.toml
# (visit io.adafruit.com if you need to create an account, or if you need your Adafruit IO key.)
ssid = getenv("CIRCUITPY_WIFI_SSID")
password = getenv("CIRCUITPY_WIFI_PASSWORD")
aio_username = getenv("ADAFRUIT_AIO_USERNAME")
aio_key = getenv("ADAFRUIT_AIO_KEY")
# If you are using a board with pre-defined ESP32 Pins:
esp32_cs = DigitalInOut(board.ESP_CS)
esp32_ready = DigitalInOut(board.ESP_BUSY)
esp32_reset = DigitalInOut(board.ESP_RESET)
# If you have an externally connected ESP32:
# esp32_cs = DigitalInOut(board.D9)
# esp32_ready = DigitalInOut(board.D10)
# esp32_reset = DigitalInOut(board.D5)
spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)
print("Connecting to AP...")
while not esp.is_connected:
try:
esp.connect_AP(ssid, password)
except RuntimeError as e:
print("could not connect to AP, retrying: ", e)
continue
print("Connected to", esp.ap_info.ssid, "\tRSSI:", esp.ap_info.rssi)
### 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 = f"{aio_username}/feeds/temperature"
### Code ###
# Define callback methods which are called when events occur
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(f"Flags: {flags}\n RC: {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(f"Subscribed to {topic} with QOS level {granted_qos}")
def unsubscribe(mqtt_client, userdata, topic, pid):
# This method is called when the mqtt_client unsubscribes from a feed.
print(f"Unsubscribed from {topic} with PID {pid}")
def publish(mqtt_client, userdata, topic, pid):
# This method is called when the mqtt_client publishes data to a feed.
print(f"Published to {topic} with PID {pid}")
def message(client, topic, message):
print(f"New message on topic {topic}: {message}")
pool = adafruit_connection_manager.get_radio_socketpool(esp)
ssl_context = adafruit_connection_manager.get_radio_ssl_context(esp)
# Set up a MiniMQTT Client
mqtt_client = MQTT.MQTT(
broker="io.adafruit.com",
username=aio_username,
password=aio_key,
socket_pool=pool,
ssl_context=ssl_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(f"Attempting to connect to {mqtt_client.broker}")
mqtt_client.connect()
print(f"Subscribing to {mqtt_topic}")
mqtt_client.subscribe(mqtt_topic)
print(f"Publishing to {mqtt_topic}")
mqtt_client.publish(mqtt_topic, "Hello Broker!")
print(f"Unsubscribing from {mqtt_topic}")
mqtt_client.unsubscribe(mqtt_topic)
print(f"Disconnecting from {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="io.adafruit.com",
username=aio_username,
password=aio_key,
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.
Page last edited January 22, 2025
Text editor powered by tinymce.
