TTL_TechMeetup/august7_mqtt/README.md

# MQTT for Fun

In this workshop, we will learn how to use MQTT for connected devices.

* Install Mosquitto Broker and Client
* Adjust ports/firewalls

On the hardware side, we will learn to install and use an MQTT client on diverse devices.

* Install MicroPython client on RP2040
* Install GDScript client on Godot Game Engine

## Software Required

* Git (for downloading project repo)
* Thonny (python code editor with RP2040 support)

### Optional
* Raspberry Pi running Raspbian
* Godot Game Engine

## Intro

What is MQTT? MQTT is a very lightweight protocol for sending messages around a network. It is simple and easy to work with, involving the use of a "broker" that centralizes the messages, and "clients" that can receive and send the messages.

Because MQTT is so lightweight, it works well on devices with limited resources, such as microcontrollers. It has become one of the most popular protocols for internet-of-things and edge devices.

# The MQTT Broker

While there are many software packages for installing an MQTT broker, probably the most popular is Mosquitto. It is available for most operating systems, and comes with both broker and client software.

Installation on Linux (debian):

```sudo apt install mosquitto mosquitto-clients```

Once you have installed the broker, it will automatically start as a service that will run in the background, and clients can connect to it.

In Mosquitto version 2+ extra security was implemented requiring clients to connect with authentication. This is overkill for many purposes, so we will allow clients to connect anonymously by editing the configuration file.

On Ubuntu:

Locate `/etc/mosquitto/mosquitto.conf`

Open the file for editing:

`sudo nano mosquitto.conf`

Add the following line:

`allow_anonymous    true`

However, there may be other factors in your OS setup that can affect the clients from connecting - most importantly your firewall settings.

In Ubuntu Linux, the most common firewall software is UFW. This comes by default with that distribution. The firewall can be configured to allow or disallow traffic on specific ports.

The port used by default for the Mosquitto broker is 1883. We must ensure that this is available for clients to connect to.

The command to see if UFW is running and what ports it is monitoring looks like this:

`sudo ufw status`

To allow connections through the firewall on port 1883 (the MQTT port) you can write a rule for UFW

`sudo ufw allow 1883/tcp`

Note that you can get a lot more specific with UFW rules, including limiting access to certain applications or IP addresses.

# Using the MQTT Client

Once the broker is up and running, and the firewall is configured to allow connections, clients can connect. This is very easy to test on the local machine, because the Mosquitto installation come with a client you can use from the command line.

MQTT organizes messaging by topics that clients can both publish to and subscribe to for updates. The topics can include anything.

On the machine where we installed the broker we can test by subscribing and publishing to the "godot" topic.

`mosquitto_sub -v -h 127.0.0.1 -t "godot/#"`

This subscribes the mosquitto client to hear updates from the broker running on 127.0.0.1 (the local machine) for any message in the "godot" topic.

In a new window, lets test publishing a message.

`mosquitto_pub -h 127.0.0.1 -t "godot/abcd" -m "Bingo!"`

In the first window, you'll see the message appear.

From this you can see that devices can be either publishers, subscribers, or both. Any devices on the same network can use their client to communicate back and forth with this messaging.

### What you can do with this:

MQTT clients are pretty ubiquitous since they are just based on TCP, a very common protocol.

If the client can be made to run on something like a microcontroller, messaging can be used to do things such boards are great at - controlling hardware.

In the next section, we will get an MQTT client working on the Raspberry Pi Pico W, a popular microcontroller built on the RP2040 chip.

To achieve this, we will need to:

* Flash the board with the language of choice (we are using MicroPython)
* Install an MQTT client written in that language
* Write code that connects to the network and uses the client code to connect to the broker
* Interpret the MQTT messaging into control of hardware

# MQTT on MicroPython

Let's begin by prepping the board for programming

In the 'resources' folder you will find specific instructions, along with the UF2 file that is needed to flash the board with MicroPython. Once that is done you'll need to have a code editor that has support for connecting to the board.

Thonny is the code editor commonly used for this.

If you do not have Thonny installed, you can follow these instructions.

Ubuntu:

`sudo apt install Thonny`

Raspbian:

If you are using a Raspberry Pi, Thonny should already be installed. (You will be limited to Python 3.9 but this should not cause any problems)

Once completed you should be able to connect to the RP2040 with Thonny.

In the bottom-right corner of the software you will see the currently configured Python interpreter. Click on that to edit it.

You will be taken to options, where you can find "MicroPython for Rpi Pico". When you select this option, the code your write in Thonny will be executed on the Pico board rather than locally. You're programming the board!

In the "rp2040_client" folder you will find a folder "lib". Inside of that you will find the folder "mqtt", and a python file called `simple.py`

The lib folder is important. It is where the pico will look for any libraries you have installed on the board. You will need to move the lib folder onto the Pico using Thonny. The easiest way to do this save-as. Create a new file, and save it into "lib/mqtt" as `simple.py`. You can then just copy the code into that file.

You are now ready to write the code that will use the MQTT client. Take a look in the `main.py` for an example.

The example uses the MQTT client to subscribe to the "godot" topic. Note that you will need to edit the code to fill in the details about your wifi network.

## The Godot Example

Once you have the MQTT client subscribed on the Pico board, you could consider another interesting use of MQTT.

In the `godot_client` folder you will find a Godot project you can import into the game engine to test your MQTT connection.

Like the project we put on the Pico board, there is a lightweight client that connects when you run the application.

If both the Godot client and the Pico client are connected to the same broker on the same network, you should be able to send messages between them.

This opens up a whole world of possibilities!

# Suggested Projects

**simple**

Send a message from Godot to the Pico that causes the pico to toggle an LED light.

**intermediate**

Collect sensor data from the Pico and provide this in messages to Godot. Create a visualisation for the data using Godot's animation capability.

## Resources

* Mosquitto man pages https://mosquitto.org/man/
* Godot MQTT client https://github.com/goatchurchprime/godot-mqtt
* Install broker/client on Linux http://www.steves-internet-guide.com/install-mosquitto-linux/
* Install broker/client on RPI https://randomnerdtutorials.com/how-to-install-mosquitto-broker-on-raspberry-pi/
* Core Electronics RP2040 guide https://core-electronics.com.au/guides/getting-started-with-mqtt-on-raspberry-pi-pico-w-connect-to-the-internet-of-things/
* RP2040 client https://github.com/micropython/micropython-lib/tree/master/micropython/umqtt.simple