MQTT module

About this

This module contains functions for send and receive information through MQTT.

Lua RTOS support for MQTT is build over Eclipse Paho MQTT.

What do you need?

For use MQTT you need an internet connection, and credentials to connect to a MQTT broker. You can configure an internet connection in Lua RTOS through Net module.

Key concepts

MQTT (Message Queue Telemetry Transport) is an ISO standard (ISO/IEC PRF 20922) publish-subscribe-based "lightweight" messaging protocol for use on top of the TCP/IP protocol. It is designed for connections with remote locations where a "small code footprint" is required or the network bandwidth is limited.

The publish-subscribe messaging pattern requires a message broker. The broker is responsible for distributing messages to interested clients based on the topic of a message.

To use this module you must take into consideration the following:

1. Create a MQTT client instance, and store the instance into a variable.

 client = mqtt.client("100", "xxxx.xx", 1883, false)

2. Connect to the broker:

   client:connect("","")

3. Publish to a topic, or subscribe to a topic using client:publish or client:subcribe functions.

4. Disconnect from the broker:

   client:disconnect()

Setup functions

client = mqtt.client(clientid, host, port, secure)

Creates a new MQTT client instance.

Arguments:

• clientid: client identifier
• host: broker domain name or ip
• port: broker port (tipically 1883)
• secure: true for secure communicacition (not tested), false for non-secure comunication

Returns: a client instance, or an exception. You must store this instance into a variable for further operations with it.

-- Creates an mqtt instance. Broker domain is xxxx.xx, at port 1883
client = mqtt.client("100", "xxxx.xx", 1883, false)

Operation functions

instance:connect(username,password)

Connects the client instance to the broker.

Arguments:

• username: user name
• password: password
• Returns: nothing

Returns: nothing, or an exception.

-- Creates an mqtt instance. Broker domain is xxxx.xx, at port 1883
client = mqtt.client("100", "xxxx.xx", 1883, false)

-- Connect
client:connect("","")

instance:disconnect()

Disconnects the client instance from the broker.

Arguments: nothing Returns: nothing, or an exception.

-- Creates an mqtt instance. Broker domain is xxxx.xx, at port 1883
client = mqtt.client("100", "xxxx.xx", 1883, false)

-- Connect
client:connect("","")

...
...

-- Disconnect
client:disconnect()

client:publish(topic, payload, qos)

Publish a message to a topic.

Arguments:

• topic: topic name.
• payload: payload, a string with the information to publish packed on it.
• qos: quality of service, according to MQTT specs, can be either mqtt.QOS0, mqtt.QOS1, or mqtt.QOS2

Returns: nothing or an exception

-- Creates an mqtt instance. Broker domain is xxxx.xx, at port 1883
client = mqtt.client("100", "xxxx.xx", 1883, false)

-- Connect
client:connect("","")

-- Publish to topic
client:publish("/100", "hello", mqtt.QOS0)

client:subscribe(topic, qos, callback)

Subscribe to a topic.

Arguments:

• topic: topic name.
• qos: quality of service, according to MQTT specs, can be either mqtt.QOS0, mqtt.QOS1, or mqtt.QOS2
• function: callback function that will be executed when a message is received on topic. This function takes 2 arguments: the message length, and the message.

Returns: nothing or an exception

-- Creates an mqtt instance. Broker domain is xxxx.xx, at port 1883
client = mqtt.client("100", "xxxx.xx", 1883, false)

-- Connect
client:connect("","")

-- Subscribe to topic
client:subscribe("/100", mqtt.QOS0, function(len, message)
  print("new message received")
  print("message length: "..len)
  print("message: "..message)
end)