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, [CA file, persistence, persistence path])

Creates a new MQTT client instance.

Arguments:

• clientid: client identifier.
• host: broker domain name or ip.
• port: broker port (typically 1883).
• secure: true for secure communication, false for non-secure communication.
• CA file (optional): path to CA file, used only if secure argument it's true.
• persistence (optional): if true use persistence, if false don't use persistence.
• persistence path (optional): the path to a file system's folder where persistence data will be stored. If the folder doesn't exists it is created the first time.

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. To use mqtt.QOS1, or mqtt.QOS2 you must enable the persistence when calling to the mqtt.client function.

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.

  The topic name can contain wildcard characters:

  • A '#' character represents a complete sub-tree of the hierarchy and thus must be the last character in a subscription topic string, such as SENSOR/#. This will match any topic starting with SENSOR/, such as SENSOR/1/TEMP and SENSOR/2/HUMIDITY.

  • A '+' character represents a single level of the hierarchy and is used between delimiters. For example, SENSOR/+/TEMP will match SENSOR/1/TEMP and SENSOR/2/TEMP.

• 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)