# MQTT in CircuitPython
## Overview
**So, you have a CircuitPython project and want to connect it to the internet? You may want to consider adding MQTT to your project. MQTT is an extremely popular and lightweight protocol which can connect your project to the internet and quickly process network events.**
[MQTT](https://mqtt.org) is a small, lightweight protocol which is incredibly easy to use in scenarios where bandwidth is at a premium, your project is sending a small amount of data every so often, or if you'd like to process network events incredibly quickly (clicking a button would cause your project to do something).
- **If you'd like to learn more about MQTT** - [check out its section in the All The Internet of Things: Protocols guide](https://learn.adafruit.com/alltheiot-protocols/mqtt).
**We've built a robust MQTT module for CircuitPython called Adafruit [CircuitPython MiniMQTT](https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/)** to quickly get you started connecting your projects to the internet and sending data around.
**In this guide, you will set up your CircuitPython board with the necessary libraries, connect to the internet and connect your CircuitPython board to either a MQTT broker of your choice or the free Adafruit IO MQTT broker. We've included code-walkthrough and advanced usage sections to this guide so you can roll your own MiniMQTT project!**
# Parts
You'll need a CircuitPython board which either has network connectivity built-in or external network hardware .
## All-in-One CircuitPython WiFi Boards
_Don't want to add extra hardware to your project?_ Consider grabbing a board which has an ESP32 WiFi co-processor built-in!
### Adafruit Metro M4 Express AirLift (WiFi) - Lite
[Adafruit Metro M4 Express AirLift (WiFi) - Lite](https://www.adafruit.com/product/4000)
Give your next project a lift with _AirLift_ - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the **Adafruit Metro M4** featuring the **Microchip ATSAMD51** , with it's 120MHz Cortex M4 with...
In Stock
[Buy Now](https://www.adafruit.com/product/4000)
[Related Guides to the Product](https://learn.adafruit.com/products/4000/guides)
### Adafruit PyPortal - CircuitPython Powered Internet Display
[Adafruit PyPortal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4116)
**PyPortal** , our easy-to-use IoT device that allows you to create all the things for the “Internet of Things” in minutes. Make custom touch screen interface GUIs, all open-source, and Python-powered using tinyJSON / APIs to get news, stock, weather, cat photos,...
In Stock
[Buy Now](https://www.adafruit.com/product/4116)
[Related Guides to the Product](https://learn.adafruit.com/products/4116/guides)
## Externally Connected CircuitPython Network Hardware
**If you already have a project which uses a CircuitPython board without internet connectivity, you can easily add WiFi connectivity with an externally connected AirLift module**.
### **WiFi**
**If you're using an Adafruit Feather** , adding WiFi connectivity to your project is as easily as snapping the the AirLift FeatherWing on top.
### Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor
[Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor](https://www.adafruit.com/product/4264)
Give your Feather project a _lift_ with the Adafruit AirLift FeatherWing - a FeatherWing that lets you use the powerful ESP32 as a WiFi co-processor. You probably have your favorite Feather ([like the Feather M4](https://www.adafruit.com/product/3857)) that comes with its own...
In Stock
[Buy Now](https://www.adafruit.com/product/4264)
[Related Guides to the Product](https://learn.adafruit.com/products/4264/guides)
**If you're using a CircuitPython board with an Arduino form-factor** , you'll want to pick up an AirLift Shield.
### Adafruit AirLift Shield - ESP32 WiFi Co-Processor
[Adafruit AirLift Shield - ESP32 WiFi Co-Processor](https://www.adafruit.com/product/4285)
Give your Arduino project a _lift_ with the Adafruit AirLift Shield - a shield that lets you use the powerful ESP32 as a WiFi co-processor. You probably have your favorite Arduino-compatible ([like the Metro M4](https://www.adafruit.com/product/3382) or the classic
In Stock
[Buy Now](https://www.adafruit.com/product/4285)
[Related Guides to the Product](https://learn.adafruit.com/products/4285/guides)
If none of the form factors above work for your project - we also have a breakout board which can connect to any microcontroller over SPI.
### Adafruit AirLift – ESP32 WiFi Co-Processor Breakout Board
[Adafruit AirLift – ESP32 WiFi Co-Processor Breakout Board](https://www.adafruit.com/product/4201)
Give your plain ol' microcontroller project a _lift_ with the Adafruit AirLift - a breakout board that lets you use the powerful ESP32 as a WiFi co-processor. You probably have your favorite microcontroller (like the ATmega328 or ATSAMD51), awesome peripherals and lots of libraries....
In Stock
[Buy Now](https://www.adafruit.com/product/4201)
[Related Guides to the Product](https://learn.adafruit.com/products/4201/guides)
### Ethernet
Wireless is wonderful, but sometimes you want the strong reliability of a wired connection. If your project is going to be part of a permanent installation, you'll want to add ethernet networking to your project.
- For more information about using Ethernet for CircuitPython with Wiznet5k, [please see our guide here...](https://learn.adafruit.com/ethernet-for-circuitpython)
### Adafruit Ethernet FeatherWing
[Adafruit Ethernet FeatherWing](https://www.adafruit.com/product/3201)
Wireless is wonderful, but sometimes you want the strong reliability of a wire. If your Feather board is going to be part of a permanent installation, this **Ethernet FeatherWing** will let you add quick and easy wired Internet. Just plug in a standard
In Stock
[Buy Now](https://www.adafruit.com/product/3201)
[Related Guides to the Product](https://learn.adafruit.com/products/3201/guides)
# MQTT in CircuitPython
## CircuitPython Setup
MQTT devices, like your CircuitPython board, connect to a broker with a client library.
We've written an awesome CircuitPython MQTT client library called **[Adafruit MiniMQTT](https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT).**
This library is based off previous work by pfalcon on [uMQTT](https://github.com/micropython/micropython-lib/blob/master/umqtt.simple/umqtt/simple.py) (and the [umqtt port to ESP32SPI by beachbc](https://github.com/beachbc/esp32spi_mqtt)). MiniMQTT's primary difference from MicroPython's uMQTT library is its use of calling conventions and method names _similar_ to The Eclipse Foundation's [Paho.Mqtt.Python](https://github.com/eclipse/paho.mqtt.python/).
## Install CircuitPython
Some CircuitPython compatible boards come with CircuitPython installed. Others are _CircuitPython-ready_, but need to have it installed. As well, you may want to update the version of CircuitPython already installed on your board. The steps are the same for installing and updating.
- To **install (or update) your CircuitPython board**, [follow this page and come back here when you've successfully installed (or updated) CircuitPython.](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython)
## CircuitPython Library Installation
To interface your AirLift breakout/board with and the internet - you'll need to install a few CircuitPython libraries on your board.
First make sure you are running the [latest version of Adafruit CircuitPython](https://github.com/adafruit/circuitpython/releases) for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle) matching your version of CircuitPython.
CircuitPython hardware shows up on your computer operating system as a flash drive when connected via usb. The flash drive is called **CIRCUITPY** and contains a number of files. You will need to add additional files to enable the features of this project.
First, create a folder on the drive named lib if it is not already there.
Ensure your board's **lib** folder has the following files and folders ** ** copied over. The version of the files must be the same major version as your version of CircuitPython (i.e. 4.x for 4.x, 5.x for 5.x, etc.)
- **adafruit\_minimqtt**
# MQTT in CircuitPython
## Connecting to the Adafruit IO MQTT Broker
If you do not want to host your own MQTT broker, using [Adafruit IO](https://io.adafruit.com)'s MQTT broker is a great way to get started connecting your CircuitPython project to the internet. Best of all - _it's free to use!_
You're going to build an Adafruit IO Dashboard which can visualize incoming data from your CircuitPython board, and send data to it.
## Obtain Adafruit IO Username and Key
If you have not already, [sign up for an Adafruit IO account by clicking this link](http://io.adafruit.com/welcome).
Next, you're going to need your Adafruit IO username and secret API key.
**[Navigate to your profile](https://io.adafruit.com/) and click the View AIO Key button** to retrieve them. Write them down in a safe place, you'll need them later.
## Create Adafruit IO Feeds
Adafruit IO uses a special type of MQTT Topic named a Feed to store data along with metadata (information about the data). You'll be publishing data to one feed, and subscribing to another.
**Create two new Adafruit IO Feeds** named _onoff_ and _photocell_.
- **_photocell_ ** - This feed will store light data published _from_ your device to Adafruit IO
- **onoff** - This feed will act as an on/off switch, publishing data _to_ your device from Adafruit IO
**If you have not created an Adafruit IO Feed before** , [follow this page and come back once you've the created two feeds above](https://learn.adafruit.com/adafruit-io-basics-feeds/creating-a-feed).
## Create an Adafruit IO Dashboard
[**Adafruit IO Dashboards**](https://learn.adafruit.com/adafruit-io-basics-dashboards) are a way to interact with feeds. You can link _blocks_ on dashboards to your feeds. The blocks can either display information about the feed (such as the current temperature) or allow you to interact with a feed by setting it to different values.
**Start by creating a new dashboard**. Name it whatever you'd like!
- I **f you do not know how to create a dashboard** , [head over to this page and come back here when you've successfully created a dashboard.](https://learn.adafruit.com/adafruit-io-basics-dashboards/creating-a-dashboard)
## Create a Gauge Block
After creating a dashboard, **create a Gauge Block ** to display the value of the Photocell feed.
- **Choose** the _photocell _feed
- **Change the block title** **to** _Photocell_
- **Set the Gauge Minimum Value** **to** _0_
- **Set the Gauge Maximum Value** **to** _1024_
**If you do not know how to add blocks to a dashboard** , [head to over this page and come back when you've added a gauge block to your dashboard.](https://learn.adafruit.com/adafruit-io-basics-dashboards/adding-blocks)
## Create a Toggle Switch Block
To send values to the _onoff _feed you created - create a toggle switch block.
- **Choose the** _onoff_ **feed**
- **Set the block title to** _On/Off_
- **Set the Button On Text to** _ON_
- **Set the Button Off Text to** _OFF_
Your dashboard should look like the following:
# MQTT in CircuitPython
## Create Your settings.toml File
CircuitPython works with WiFi-capable boards to enable you to make projects that have network connectivity. This means working with various passwords and API keys. As of [CircuitPython 8](https://circuitpython.org/downloads), there is support for a **settings.toml** file. This is a file that is stored on your **CIRCUITPY** drive, that contains all of your secret network information, such as your SSID, SSID password and any API keys for IoT services. It is designed to separate your sensitive information from your **code.py** file so you are able to share your code without sharing your credentials.
CircuitPython previously used a **secrets.py** file for this purpose. The **settings.toml** file is quite similar.
Warning: Your **settings.toml** file should be stored in the main directory of your **CIRCUITPY** drive. It should not be in a folder.
## CircuitPython **settings.toml** File
This section will provide a couple of examples of what your **settings.toml** file should look like, specifically for CircuitPython WiFi projects in general.
The most minimal **settings.toml** file must contain your WiFi SSID and password, as that is the minimum required to connect to WiFi. Copy this example, paste it into your **settings.toml** , and update:
- `your_wifi_ssid`
- `your_wifi_password`
```auto
CIRCUITPY_WIFI_SSID = "your_wifi_ssid"
CIRCUITPY_WIFI_PASSWORD = "your_wifi_password"
```
Many CircuitPython network-connected projects on the Adafruit Learn System involve using Adafruit IO. For these projects, you must _also_ include your Adafruit IO username and key. Copy the following example, paste it into your settings.toml file, and update:
- `your_wifi_ssid`
- `your_wifi_password`
- `your_aio_username`
- `your_aio_key`
```auto
CIRCUITPY_WIFI_SSID = "your_wifi_ssid"
CIRCUITPY_WIFI_PASSWORD = "your_wifi_password"
ADAFRUIT_AIO_USERNAME = "your_aio_username"
ADAFRUIT_AIO_KEY = "your_aio_key"
```
Some projects use different variable names for the entries in the **settings.toml** file. For example, a project might use `ADAFRUIT_AIO_ID` in the place of `ADAFRUIT_AIO_USERNAME`. **If you run into connectivity issues, one of the first things to check is that the names in the settings.toml file match the names in the code.**
Warning: Not every project uses the same variable name for each entry in the **settings.toml** file! Always verify it matches the code.
## **settings.toml** File Tips
Here is an example **settings.toml** file.
```auto
# Comments are supported
CIRCUITPY_WIFI_SSID = "guest wifi"
CIRCUITPY_WIFI_PASSWORD = "guessable"
CIRCUITPY_WEB_API_PORT = 80
CIRCUITPY_WEB_API_PASSWORD = "passw0rd"
test_variable = "this is a test"
thumbs_up = "\U0001f44d"
```
In a **settings.toml** file, it's important to keep these factors in mind:
- Strings are wrapped in double quotes; ex: `"your-string-here"`
- Integers are _ **not** _ quoted and may be written in decimal with optional sign (`+1`, `-1`, `1000`) or hexadecimal (`0xabcd`).
- Floats (decimal numbers), octal (`0o567`) and binary (`0b11011`) are not supported.
- Use `\u` escapes for weird characters, `\x` and `\ooo` escapes are not available in **.toml** files
- Example: `\U0001f44d` for 👍 (thumbs up emoji) and `\u20ac` for € (EUR sign)
- Unicode emoji, and non-ASCII characters, stand for themselves as long as you're careful to save in "UTF-8 without BOM" format
When your **settings.toml ** file is ready, you can save it in your text editor with the **.toml** extension.
## Accessing Your **settings.toml** Information in **code.py**
In your **code.py** file, you'll need to `import` the `os` library to access the **settings.toml** file. Your settings are accessed with the `os.getenv()` function. You'll pass your settings entry to the function to import it into the **code.py** file.
```python
import os
print(os.getenv("test_variable"))
```
In the upcoming CircuitPython WiFi examples, you'll see how the **settings.toml ** file is used for connecting to your SSID and accessing your API keys.
# MQTT in CircuitPython
## CircuitPython WiFi Usage
## Internet Connect!
Once you have CircuitPython setup and libraries installed, you can get your project connected to the Internet over WiFi.
To do this, you'll be editing CircuitPython code and will need an editor. We suggest using **Mu** , a lightweight text editor with support for CircuitPython built-in.
**Click the button below to get instructions on how to install the Mu Editor.**
[Install Mu Editor](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor)
**If you have not yet connected your CircuitPython WiFi board to the Internet, follow one of the guides below** and come back when you've successfully connected to the internet:
- **If you have an ESP32-S2 board (such as the MagTag), **[follow this page to connect to the internet](https://learn.adafruit.com/adafruit-metro-esp32-s2/circuitpython-internet-test).
- **If you have an AirLift All-in-One board (such as the PyPortal),** [follow this page to connect to the internet](https://learn.adafruit.com/adafruit-pyportal/internet-connect).
- **If you have an externally connected AirLift (such as the AirLift FeatherWing or AirLift breakout)**, [follow this page to connect to the internet](https://learn.adafruit.com/adafruit-airlift-breakout/internet-connect).
Warning:
## 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](https://learn.adafruit.com/mqtt-in-circuitpython/create-your-settings-toml-file) 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**.
```auto
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 **.**
## Code Usage
### ESP32-S2 Code
CircuitPython boards using the ESP32- **S2 ** such as the [MagTag](https://www.adafruit.com/product/4800) or [Metro ESP32-S2](https://www.adafruit.com/product/4775) have internet connectivity built into the CircuitPython firmware.
Copy the following code to your **code.py** file on your microcontroller:
Warning:
https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/blob/main/examples/native_networking/minimqtt_adafruitio_native_networking.py
### ESP32 AirLift Code
CircuitPython boards using an **ESP32**"AirLift" Co-Processor such as the [PyPortal](https://www.adafruit.com/product/4116) require a helper library to connect to the internet.
Copy the following code to your **code.py** file on your microcontroller:
https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/blob/main/examples/esp32spi/minimqtt_adafruitio_esp32spi.py
#### (Optional) Change ESP32 AirLift Pinouts
If you are using a board with a built-in ESP32 (like the PyPortal), you do not need to make changes to the code. It's already setup for usage with those boards. However, **if you are using an externally connected ESP32 (like the AirLift Breakout), you'll need to define the ESP32's pinouts**.
Make sure to **change the ESP32 pin definitions in the code to match your wiring**. You can do this by uncommenting and editing the following lines in your code to match your wiring.
```
esp32_cs = DigitalInOut(board.D9)
esp32_ready = DigitalInOut(board.D10)
esp32_reset = DigitalInOut(board.D5)
```
## Feed Publishing Example
Directly after saving the **code.py** file, open a serial monitor/REPL to see the output. It should look something like the following:
```python
code.py output:
Connecting to Adafruit IO...
Connected to Adafruit IO! Listening for topic changes on brubell/feeds/onoff
Sending photocell value: 0...
Sent!
Sending photocell value: 1...
Sent!
Sending photocell value: 2...
Sent!
Sending photocell value: 3...
Sent!
```
**Navigate to the dashboard** you created earlier. **You should see the photocell gauge increasing its value** as your CircuitPython device publishes the increasing photocell value to Adafruit IO.
If you **navigate to the page for the photocell feed** , you'll see the values increasing there along with metadata about when the data was received by the Adafruit IO broker.
## Feed Subscription Example
While we're publishing the increasing _photocell_ value _to_ Adafruit IO - our code also _subscribes_ to changes on the _onoff_ feed.
The example _code.py_ subscribes to the _onoff_ feed when the client successfully connects to Adafruit IO. You don't need to make any changes to your code!
With the code still running on your CircuitPython device - **click the toggle switch ** to send a value to the _onoff_ feed. You should see the value appear on your serial monitor/REPL.
If you _really_ want to see the speed of MQTT - remove the one second delay in the `while True` loop.
**Change the following code** (within `while True`) **from:**
`print('Sent!')`
`photocell_val += 1`
**`time.sleep(1)`**
**to**
`print('Sent!')`
`photocell_val += 1`
**`time.sleep(0.5)`**
**Be warned** - if you do this you will not be able to run the code for very long. This is because Adafruit IO's MQTT server imposes a rate limit to prevent excessive load on the service.
The current Adafruit IO Data Rate is at most 1 request per second (or 60 requests within 60 seconds), without an Adafruit IO+ Boost applied to your account.
## Going Further - the Adafruit IO CircuitPython Module
While you _can_ use this code to communicate with Adafruit IO, the recommend method of using CircuitPython with Adafruit IO is with [the Adafruit IO CircuitPython module](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/).
This module has methods to simplify using the Adafruit IO MQTT API. It also includes helper features to make your experience using Adafruit IO better.
If you want to use Adafruit IO and CircuitPython, check out [Adafruit IO CircuitPython](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/releases) and its [code examples](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/tree/master/examples/mqtt) on GitHub!
# MQTT in CircuitPython
## CircuitPython Ethernet Usage
## Ethernet Setup
This page assumes you've set up and connected your CircuitPython board to an Ethernet connection.
- If you have not connected to the internet using Ethernet yet, [please follow this guide and come back to this page when you've successfully connected to the internet](https://learn.adafruit.com/ethernet-for-circuitpython/usage)
## Connect Ethernet Cable
Make sure you have your Ethernet FeatherWing or Ethernet Shield firmly plugged into your hardware, and an Ethernet cable connected to your router or switch.
## Code Usage
Copy the following code to a file on your computer. Name the file **code.py**. With your operating system file explorer/finder, copy this file to the **CIRCUITPY** drive which appears when your microcontroller board is plugged in via USB.
https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/blob/main/examples/ethernet/minimqtt_adafruitio_eth.py
## Feed Publishing Example
Directly after saving the **code.py** file, open a serial monitor/REPL to see the output. It should look something like the following:
```python
code.py output:
Connecting to Adafruit IO...
Connected to Adafruit IO! Listening for topic changes on brubell/feeds/onoff
Sending photocell value: 0...
Sent!
Sending photocell value: 1...
Sent!
Sending photocell value: 2...
Sent!
Sending photocell value: 3...
Sent!
```
**Navigate to the dashboard** you created earlier. **You should see the photocell gauge increasing its value** as your CircuitPython device publishes the increasing photocell value to Adafruit IO.
If you **navigate to the page for the photocell feed** , you'll see the values increasing there along with metadata about when the data was received by the Adafruit IO broker.
## Feed Subscription Example
While we're publishing the increasing _photocell_ value _to_ Adafruit IO - our code also _subscribes_ to changes on the _onoff_ feed.
The example **code.py** subscribes to the _onoff_ feed when the client successfully connects to Adafruit IO. You don't need to make any changes to your code!
With the code still running on your CircuitPython device - **click the toggle switch ** to send a value to the _onoff_ feed. You should see the value appear on your serial monitor/REPL.
If you _really_ want to see the speed of MQTT - remove the one second delay in the `while True` loop.
**Change the following code** (within `while True`) **from:**
`print('Sent!')`
`photocell_val += 1`
**`time.sleep(1)`**
**to**
`print('Sent!')`
`photocell_val += 1`
**`time.sleep(0.5)`**
**Be warned** - if you do this you will not be able to run the code for very long. This is because Adafruit IO's MQTT server imposes a rate limit to prevent excessive load on the service.
The current Adafruit IO Data Rate is at most 1 request per second (or 60 requests within 60 seconds), without an Adafruit IO+ Boost applied to your account.
## Going Further - the Adafruit IO CircuitPython Module
While you _can_ use this code to communicate with Adafruit IO, the recommended method of using CircuitPython with Adafruit IO is with [the Adafruit IO CircuitPython module](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/).
This module has methods to simplify using the Adafruit IO MQTT API. It also includes helper features to make your experience using Adafruit IO better.
If you want to use Adafruit IO and CircuitPython, check out [Adafruit IO CircuitPython](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/releases) and [the code example for Ethernet ](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/blob/master/examples/adafruit_io_mqtt/adafruit_io_simpletest_eth.py)on GitHub!
# MQTT in CircuitPython
## CircuitPython Cellular Usage
## Cellular Data Setup
This page assumes you've set up and connected your CircuitPython board to a cellular data connection.
- If you have not connected to the internet using cellular data yet, [please follow this guide and come back when you've successfully connected.](https://learn.adafruit.com/cellular-data-for-circuitpython-with-fona)
## Connect FONA
Make sure you have attached a LiPoly battery, GSM antenna, GPS antenna to your FONA.
You must also have a SIM card inserted in the FONA to use the module with cellular data.
- If you haven't done this yet, [navigate to this page and come back when you've set up the FONA](https://learn.adafruit.com/adafruit-fona-808-cellular-plus-gps-breakout/assembly-1#attaching-antenna-and-battery-4-7).
## Code Usage
Copy the following code to a file on your computer. Name the file **code.py**. With your operating system file explorer/finder, copy this file to the **CIRCUITPY** drive which appears when your microcontroller board is plugged in via USB.
https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/blob/main/examples/cellular/minimqtt_adafruitio_cellular.py
## Feed Publishing Example
Directly after saving the **code.py** file, open a serial monitor/REPL to see the output. It should look something like the following:
```python
Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.
code.py output:
Attaching to network...
Attached to network!
Connecting to network...
Connected to network!
Connecting to Adafruit IO...
Connected to Adafruit IO! Listening for topic changes on brubell/feeds/onoff
Sending photocell value: 0...
Sent!
Sending photocell value: 1...
Sent!
Sending photocell value: 2...
Sent!
Sending photocell value: 3...
Sent!
```
**Navigate to the dashboard** you created earlier. **You should see the photocell gauge increasing its value** as your CircuitPython device publishes the increasing photocell value to Adafruit IO.
If you **navigate to the page for the photocell feed** , you'll see the values increasing there along with metadata about when the data was received by the Adafruit IO broker.
## Feed Subscription Example
While we're publishing the increasing _photocell_ value _to_ Adafruit IO - our code also _subscribes_ to changes on the _onoff_ feed.
The example **code.py** subscribes to the _onoff_ feed when the client successfully connects to Adafruit IO. You don't need to make any changes to your code!
With the code still running on your CircuitPython device - **click the toggle switch ** to send a value to the _onoff_ feed. You should see the value appear on your serial monitor/REPL.
If you _really_ want to see the speed of MQTT - remove the one second delay in the `while True` loop.
**Change the following code** (within `while True`) **from:**
`print('Sent!')`
`photocell_val += 1`
**`time.sleep(1)`**
**to**
`print('Sent!')`
`photocell_val += 1`
**`time.sleep(0.5)`**
**Be warned** - if you do this you will not be able to run the code for very long. This is because Adafruit IO's MQTT server imposes a rate limit to prevent excessive load on the service.
The current Adafruit IO Data Rate is at most 1 request per second (or 60 requests within 60 seconds), without an Adafruit IO+ Boost applied to your account.
## Going Further - the Adafruit IO CircuitPython Module
While you _can_ use this code to communicate with Adafruit IO, the recommended method of using CircuitPython with Adafruit IO is with [the Adafruit IO CircuitPython module](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/).
This module has methods to simplify using the Adafruit IO MQTT API. It also includes helper features to make your experience using Adafruit IO better.
If you want to use Adafruit IO and CircuitPython, check out [Adafruit IO CircuitPython](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/releases) and [the code example for Ethernet](https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/blob/master/examples/mqtt/adafruit_io_simpletest_eth.py) on GitHub!
# MQTT in CircuitPython
## Connecting to a MQTT Broker
**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](https://mosquitto.org/) - 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](https://learn.adafruit.com/mqtt-in-circuitpython/create-your-settings-toml-file) 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**.
```auto
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 **.**
## Code
Copy the following code to your **code.py** file on your microcontroller:
https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/blob/main/examples/minimqtt_simpletest.py
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](https://learn.adafruit.com/alltheiot-protocols/mqtt-topics).
## **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.**
```python
# 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](https://circuitpython.readthedocs.io/projects/adafruit-circuitpython-minimqtt/en/latest/api.html#adafruit_minimqtt.MQTT.subscribe)).
- [For more about the MQTT quality of service level - check out this page](https://learn.adafruit.com/alltheiot-protocols/mqtt-qos)
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.
# MQTT in CircuitPython
## Code Walkthrough
The code first connects the ESP32 to the wireless network you specified in the **settings.toml** file on your **CIRCUITPY** drive.
```auto
print("Connecting to AP...")
while not esp.is_connected:
try:
esp.connect_AP(
os.getenv("CIRCUITPY_WIFI_SSID"), os.getenv("CIRCUITPY_WIFI_PASSWORD")
)
except RuntimeError as e:
print("could not connect to AP, retrying: ", e)
continue
print("Connected to", str(esp.ssid, "utf-8"), "\tRSSI:", esp.rssi)
```
Then, it initializes a MQTT object using the network interface (esp, ethernet) you are using:
```python
# Initialize MQTT interface with the esp interface
MQTT.set_socket(socket, esp)
```
Once a WiFi network connection has been established, the code sets up a new MiniMQTT client instance
```python
client = MQTT.MQTT(
broker="io.adafruit.com",
username=aio_username,
password=aio_key,
)
```
Then, the code attaches callback handler methods to the client.
```
# Connect callback handlers to client
client.on_connect = connect
client.on_disconnect = disconnect
client.on_subscribe = subscribe
client.on_unsubscribe = unsubscribe
client.on_publish = publish
```
## MiniMQTT Callback Methods
We're going to stop here to explain the utility and operation of the callback methods which are an important part of building programs with MiniMQTT.
Further up in the code, there are methods named `connect()`, `publish()`, `subscribe()`, `unsubscribe()` and `disconnect()`.
```
def connect(client, userdata, flags, rc):
# This function will be called when the client is connected
# successfully to the broker.
print('Connected to MQTT Broker!')
print('Flags: {0}\n RC: {1}'.format(flags, rc))
def disconnect(client, userdata, rc):
# This method is called when the client disconnects
# from the broker.
print('Disconnected from MQTT Broker!')
def subscribe(client, userdata, topic, granted_qos):
# This method is called when the client subscribes to a new feed.
print('Subscribed to {0} with QOS level {1}'.format(topic, granted_qos))
def unsubscribe(client, userdata, topic, pid):
# This method is called when the client unsubscribes from a feed.
print('Unsubscribed from {0} with PID {1}'.format(topic, pid))
def publish(client, userdata, topic, pid):
# This method is called when the client publishes data to a feed.
print('Published to {0} with PID {1}'.format(topic, pid))
```
Each of these methods is executed when a **callback** is successfully read back from a MQTT control packet sent by the client.
- **If you do not know what a MQTT Client or a MQTT Broker is** , [check out this page](https://learn.adafruit.com/alltheiot-protocols/brokers-clients).
This means that whenever **MiniMQTT sends a CONNECT command to the MQTT broker** , the broker should respond that it received it and send another packet back to MiniMQTT (called a _CONNACK_ packet).
**If MiniMQTT receives this CONNACK packet, it will execute the client's on\_connect method**. It'll raise an error if it did not connect successfully.
As an example, we'll set up a connect callback method named `connect`. This method will print the string, _Connected to MQTT Broker_, if it successfully connects to your MQTT broker.
```
def connect(client, userdata, flags, rc):
print('Connected to MQTT Broker!')
```
Then, we'll _ **set** _the client's **`on_connect`** property to the `connect` method.
`client.on_connect = connect`
To connect the MiniMQTT client to the broker, we'll run the following line:
`client.connect()`
**When the client's `connect()` method runs, it sends a CONNECT command to the MQTT broker** with information including the broker's address and waits for the **CONNACK**.
**Once the CONNACK is received, MiniMQTT calls `on_connect`** from "behind the scenes". Since `connect` is attached to `on_connect`, **connect will execute and print** out the following message:
```
Connected to MQTT Broker!
```
Ok - we now understand how the _connect_ method callback works. The rest of the example calls more functions which also execute similar callback methods.
First, the code attempts to connect to the MQTT broker you specified.
```
print('Attempting to connect to %s'%client.broker)
client.connect()
```
If the CircuitPython board connects successfully, it'll run the `connect` method.
The code will next attempt to subscribe to a `mqtt_topic` you defined earlier in the code.
```
print('Subscribing to %s'%mqtt_topic)
client.subscribe(mqtt_topic)
```
If the client successfully subscribes to the `mqtt_topic`, the `subscribe` method will execute.
Once the client successfully subscribes - it'll publish to the `mqtt_topic`.
```
print('Publishing to %s'%mqtt_topic)
client.publish(mqtt_topic, 'Hello Broker!')
```
After publishing, your broker should display that it received a value from the client. In addition, the `publish` method should run.
Next, the client unsubscribes from the `mqtt_topic` and disconnects from the broker.
```
print('Unsubscribing from %s'%mqtt_topic)
client.unsubscribe(mqtt_topic)
print('Disconnecting from %s'%client.broker)
client.disconnect()
```
These two methods should call the `unsubscribe` and `disconnect` methods.
That's it! The next page will go over some of the more advanced features of this library.
# MQTT in CircuitPython
## Advanced MiniMQTT Usage
# MiniMQTT Loop
You should **always use a loop when writing CircuitPython code which uses the MiniMQTT module**. The loop method checks incoming and processes outgoing MQTT messages along with keeping the network connection between your board and the MQTT broker alive.
## loop
Calling `loop` creates a **non-blocking** network loop. You can create new code below the call to `loop`, and it'll be executed. This type of loop should be run frequently to avoid disconnecting from the MQTT server. The `loop` method also **does not handle network hardware (WiFi) or MQTT broker disconnection**. You'll need to handle that yourself.
Here's an example of using a non-blocking loop.
https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/blob/main/examples/esp32spi/minimqtt_pub_sub_nonblocking_esp32spi.py
Here's an example of using a loop with a network interface. In this example, we use the loop to reset the network interface (`wifi.reset`) and reconnect the socket to the MQTT broker (`mqtt_client.reconnect`)
https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/blob/main/examples/esp32spi/minimqtt_pub_sub_blocking_esp32spi.py
# MiniMQTT Client Identifier
By default, MiniMQTT will generate a unique, randomly generated client identifier based off the CircuitPython device's microcontroller's UUID and a random number. The broker will see a client named something like _cpy-3123_
If you'd like to set a custom `client_id` (what the broker sees the CircuitPython device as), you can provide a string. Do make sure the `client_id`'s you create are unique, or your broker will disconnect them.
```auto
client = MQTT.MQTT(
broker="io.adafruit.com",
username=aio_username,
password=aio_key,
client_id='brentspyportal'
)
```
# MiniMQTT Logging
MiniMQTT uses [the CircuitPython logger module](https://learn.adafruit.com/a-logger-for-circuitpython) for printing different types of errors, depending on the priority the logger was set to.
To attach a logger to a MiniMQTT client, simply:
```auto
client = MQTT.MQTT(
broker="io.adafruit.com",
username=aio_username,
password=aio_key,
)
client.enable_logger(adafruit_logging);
```
Then, you will need to add another line setting the logger's level. While the logger is initialized to the INFO level by default, you may want to see more information about your current MQTT session.
**To set the logger to a higher priority logging level** , like DEBUG, **add the following line** _after_ the MQTT client has been initialized:
`client.set_logger_level(DEBUG)`
# MiniMQTT Last Will and Testament
MiniMQTT supports setting publishing a message to a specific topic when your MQTT client disconnects.
- **For more information about MQTT's Last Will** - [check this guide](https://learn.adafruit.com/alltheiot-protocols/mqtt-extras#last-will-15-5).
To use the last will - specify the **`topic`** you'd like to publish to and provide it with a **`message`** to publish when the client disconnects.
`client.will_set('device/status/','Goodbye!')`
**This method must be called before the connect method**. The **last will and testament also must be allowed by your MQTT Broker** - Adafruit IO does _not_ support this feature.
## Featured Products
### Adafruit AirLift – ESP32 WiFi Co-Processor Breakout Board
[Adafruit AirLift – ESP32 WiFi Co-Processor Breakout Board](https://www.adafruit.com/product/4201)
Give your plain ol' microcontroller project a _lift_ with the Adafruit AirLift - a breakout board that lets you use the powerful ESP32 as a WiFi co-processor. You probably have your favorite microcontroller (like the ATmega328 or ATSAMD51), awesome peripherals and lots of libraries....
In Stock
[Buy Now](https://www.adafruit.com/product/4201)
[Related Guides to the Product](https://learn.adafruit.com/products/4201/guides)
### Adafruit PyPortal - CircuitPython Powered Internet Display
[Adafruit PyPortal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4116)
**PyPortal** , our easy-to-use IoT device that allows you to create all the things for the “Internet of Things” in minutes. Make custom touch screen interface GUIs, all open-source, and Python-powered using tinyJSON / APIs to get news, stock, weather, cat photos,...
In Stock
[Buy Now](https://www.adafruit.com/product/4116)
[Related Guides to the Product](https://learn.adafruit.com/products/4116/guides)
### Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor
[Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor](https://www.adafruit.com/product/4264)
Give your Feather project a _lift_ with the Adafruit AirLift FeatherWing - a FeatherWing that lets you use the powerful ESP32 as a WiFi co-processor. You probably have your favorite Feather ([like the Feather M4](https://www.adafruit.com/product/3857)) that comes with its own...
In Stock
[Buy Now](https://www.adafruit.com/product/4264)
[Related Guides to the Product](https://learn.adafruit.com/products/4264/guides)
### Adafruit Metro M4 Express AirLift (WiFi) - Lite
[Adafruit Metro M4 Express AirLift (WiFi) - Lite](https://www.adafruit.com/product/4000)
Give your next project a lift with _AirLift_ - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the **Adafruit Metro M4** featuring the **Microchip ATSAMD51** , with it's 120MHz Cortex M4 with...
In Stock
[Buy Now](https://www.adafruit.com/product/4000)
[Related Guides to the Product](https://learn.adafruit.com/products/4000/guides)
### Adafruit AirLift Shield - ESP32 WiFi Co-Processor
[Adafruit AirLift Shield - ESP32 WiFi Co-Processor](https://www.adafruit.com/product/4285)
Give your Arduino project a _lift_ with the Adafruit AirLift Shield - a shield that lets you use the powerful ESP32 as a WiFi co-processor. You probably have your favorite Arduino-compatible ([like the Metro M4](https://www.adafruit.com/product/3382) or the classic
In Stock
[Buy Now](https://www.adafruit.com/product/4285)
[Related Guides to the Product](https://learn.adafruit.com/products/4285/guides)
### Adafruit Ethernet FeatherWing
[Adafruit Ethernet FeatherWing](https://www.adafruit.com/product/3201)
Wireless is wonderful, but sometimes you want the strong reliability of a wire. If your Feather board is going to be part of a permanent installation, this **Ethernet FeatherWing** will let you add quick and easy wired Internet. Just plug in a standard
In Stock
[Buy Now](https://www.adafruit.com/product/3201)
[Related Guides to the Product](https://learn.adafruit.com/products/3201/guides)
### Ethernet Shield for Arduino - W5500 Chipset
[Ethernet Shield for Arduino - W5500 Chipset](https://www.adafruit.com/product/2971)
The W5500 Ethernet Shield for Arduino from Seeed Studio is a great way to set up your projects with internet connectivity with just a single chip. Similar to the[Arduino Ethernet Shield](https://www.adafruit.com/product/201), but with a newer chipset, this ethernet shield...
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2971)
[Related Guides to the Product](https://learn.adafruit.com/products/2971/guides)
### Pink and Purple Braided USB A to Micro B Cable - 2 meter long
[Pink and Purple Braided USB A to Micro B Cable - 2 meter long](https://www.adafruit.com/product/4148)
This cable is super-fashionable with a woven pink and purple Blinka-like pattern!
First let's talk about the cover and over-molding. We got these in custom colors, and if you _have_ to have visible cables, then you might as well have the nicest fabric-bound...
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/4148)
[Related Guides to the Product](https://learn.adafruit.com/products/4148/guides)
## Related Guides
- [Adafruit Ethernet FeatherWing](https://learn.adafruit.com/adafruit-wiz5500-wiznet-ethernet-featherwing.md)
- [Adafruit PyPortal - IoT for CircuitPython](https://learn.adafruit.com/adafruit-pyportal.md)
- [Adafruit AirLift - ESP32 WiFi Co-Processor Breakout](https://learn.adafruit.com/adafruit-airlift-breakout.md)
- [Adafruit Metro M4 Express AirLift (WiFi)](https://learn.adafruit.com/adafruit-metro-m4-express-airlift-wifi.md)
- [Adafruit AirLift FeatherWing - ESP32 WiFi Co-Processor](https://learn.adafruit.com/adafruit-airlift-featherwing-esp32-wifi-co-processor-featherwing.md)
- [Adafruit AirLift Shield - ESP32 WiFi Co-Processor](https://learn.adafruit.com/adafruit-airlift-shield-esp32-wifi-co-processor.md)
- [PyPortal YouTube Views and Subscribers Display](https://learn.adafruit.com/pyportal-youtube-views-and-subscribers-display.md)
- [A CLI in CircuitPython](https://learn.adafruit.com/a-cli-in-circuitpython.md)
- [PyPortal Weather Station](https://learn.adafruit.com/pyportal-weather-station.md)
- [PyPortal Weekly Countdown Clock](https://learn.adafruit.com/pyportal-countdown-clock.md)
- [PyPaint Drawing Program In CircuitPython](https://learn.adafruit.com/pypaint.md)
- [ePaper Maze Maker](https://learn.adafruit.com/epaper-maze-maker.md)
- [Using Python on Windows 10](https://learn.adafruit.com/using-python-on-windows-10.md)
- [Use circup to easily keep your CircuitPython libraries up to date](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup.md)
- [Program CircuitPython USB Devices with iPhone & iPad](https://learn.adafruit.com/use-circuitpython-devices-with-iphone-ipad.md)
- [PyPortal Email Display with Zapier and Adafruit IO](https://learn.adafruit.com/pyportal-email-display.md)
- [CircuitPython Minesweeper Game](https://learn.adafruit.com/circuitpython-pyportal-minesweeper-game.md)
- [Halloween Countdown Display Matrix](https://learn.adafruit.com/halloween-countdown-display-matrix.md)
- [PyPortal Wake-Up Light Alarm Clock](https://learn.adafruit.com/pyportal-wake-up-light.md)
- [Quickstart: Adafruit IO WipperSnapper ](https://learn.adafruit.com/quickstart-adafruit-io-wippersnapper.md)
- [A Floppy Thumb Drive with a Color File Icon Display](https://learn.adafruit.com/a-floppy-thumb-drive-with-a-color-file-icon-display.md)