MQTT

MQTT is a lightweight publish and subscribe network protocol. It's commonly used for Internet-of-Things (IoT) devices due to its low resource requirements.

MQTT can be used to send messages between two IoTy devices, or between IoTy devices and a phone / computer. IoTy provides an MQTT App Builder (...find it under "App -> MQTT App Builder") that you can use to build an interactive webapp that can communicate with your IoTy device.

Brokers

To use MQTT, you need to have an MQTT broker. If you have a server, you can install your own broker (eg. Mosquitto). Alternatively, you can use a cloud based broker (eg. HiveMQ Cloud, the Free Serverless plan will do fine).

Publish and Subscribe

In MQTT, each client can subscribe to one or more topic. Topic names can be any string, and need not be created in advanced. After subscription, the client will receive any messages that are published to that topic.

You must run Check for message or in Python, check_msg(), frequently. You will not receive any messages if you do not run this.

A client can also publish to a topic. Published messages will be sent to all subscriber clients. By default, a message for publishing should be a bytes object, but IoTy also provide Blocks that automatically convert strings to a bytes object.

If you need to send complex data (eg. list) via MQTT, you can use the json dump string block or in Python, json.dumps(). This will convert your data (eg. list, dictionary) to a string format that you can send via MQTT. The recepient will need to use json load string or in Python, json.loads(), to convert it back.

MQTT App Builder

In IoTy, click on "App -> MQTT App Builder" to open the app builder page.

Connect to an MQTT broker by clicking "3 dots menu -> Connect". Fill in the host name (...make sure it ends with "/mqtt"), username, and password.

If you don't have a broker, you can obtain a free one from HiveMQ. Follow the instructions here.

Add a Switch and a Display. Set their topics. Click the "Run" button.

Code

Blocks

Create the following program. Make sure to put in your actual WiFi SSID and password. You also need to put in your actual MQTT broker URL, username, and password.

Python

import ioty.wifi
from umqtt.robust import MQTTClient
import machine
import ubinascii
import time
from ioty import pin

ioty.wifi.connect('SSID', 'password') # Put in actual WiFi SSID/Password

# MQTT callback
def ioty_mqtt_cb(topic, msg):
    if topic == b'topic1':
        print(msg.decode()) # decode converts bytes to string

client_id = ubinascii.hexlify(machine.unique_id()) # Creates a client ID from machine ID.
# Alternatively, you can just use any string as client_id, as long as it is unique.

# Connect to MQTT server. Put in the actual URL, username, and password
ioty_mqtt = MQTTClient(
    client_id,
    'something.s1.eu.hivemq.cloud',
    port=8883,
    user='user',
    password='password',
    keepalive=60,
    ssl=True, # Exclude this line and the next if not using SSL
    ssl_params={'server_hostname':'something.s1.eu.hivemq.cloud'}
)
ioty_mqtt.set_callback(ioty_mqtt_cb)
ioty_mqtt.connect()
ioty_mqtt.subscribe(b'topic1')

while True:
    if pin.digital_read(0) == 0:
        ioty_mqtt.publish(b'topic2', bytes('hello', 'utf-8')) # bytes converts string to bytes
        time.sleep(1)
    ioty_mqtt.check_msg() # Run this frequently or you will not receive messages

Results

In the MQTT App Builder, click the Switch Widget. You should see the message "on" or "off" printed in the IoTy monitor.

Press the boot button on your ESP32. You should see the message "hello" appear in the Display Widget on the MQTT App Builder.