luamqtt

To use luamqtt, you must first install its required dependencies via LuaRocks. Note that some dependencies are optional depending on your Lua version and whether you require SSL/TLS.

Required Dependencies

• luasocket: Required for TCP connections. (Note: If you provide your own connector, this is optional).
• luabitop: Required only if you are using Lua 5.1. If you are using Lua 5.3 or above, you do not need this.

Optional Dependencies

• luasec: Required only if you need to establish secure (SSL/TLS) connections to an MQTT broker.

Installation Steps

1. Install dependencies:

luarocks install luasocket
luarocks install luabitop  # Only for Lua 5.1
luarocks install luasec    # Only for SSL/TLS

2. Install the library:

luarocks install luamqtt

For development, you can install the development branch or build from a cloned repository:

# Install development branch
luarocks install luamqtt --dev

# Build from cloned repo
luarocks make

The examples/simple.lua script demonstrates the fundamental lifecycle of an MQTT client using luamqtt. It covers the following sequence of operations:

1. Connecting: Establishing a connection to an MQTT broker.
2. Subscribing: Subscribing to a specific topic.
3. Publishing: Sending a message to a topic after the subscription is created.
4. Receiving: Handling the incoming message (in this case, the self-published message).
5. Disconnecting: Gracefully closing the connection to the broker.

Expected console output follows this pattern:

created MQTT client     mqtt.client{id="luamqtt-v2-0-0-5807dc7"}
running ioloop for it
connected:      CONNACK{rc=0, sp=false, type=2}
subscribed:     SUBACK{rc={1}, packet_id=1, type=9}
publishing test message "hello" to "luamqtt/simpletest" topic...
received:       PUBLISH{payload="hello", topic="luamqtt/simpletest", dup=false, retain=false, qos=1, packet_id=1, type=3}
disconnecting...
done, ioloop is stopped

-- Refer to examples/simple.lua for the full implementation

You can create an MQTT client using mqtt.client and define event handlers using the :on method. Common events include connect (triggered when the connection is established) and message (triggered when a message is received on a subscribed topic).

To keep the client running and processing events, you must call mqtt.run_ioloop(client).

Example: Connect, Subscribe, and Publish

local mqtt = require("mqtt")

-- Create client
local client = mqtt.client{
    uri = "mqtt.flespi.io", 
    username = os.getenv("FLESPI_TOKEN"), 
    clean = true
}

-- Assign event handlers
client:on{
    connect = function(connack)
        if connack.rc ~= 0 then
            print("connection to broker failed:", connack:reason_string(), connack)
            return
        end

        -- Subscribe to a topic upon connection
        assert(client:subscribe{
            topic="luamqtt/#", 
            qos=1, 
            callback=function()
                assert(client:publish{ topic = "luamqtt/simpletest", payload = "hello" })
            end
        })
    end,

    message = function(msg)
        assert(client:acknowledge(msg))
        print("received message", msg)
        client:disconnect()
    end,
}

-- Start the event loop
mqtt.run_ioloop(client)

The Last Will & Testament (LWT) feature allows a client to specify a message that the broker will automatically publish to a specific topic if the client's connection is lost unexpectedly (e.g., without sending a DISCONNECT packet).

To simulate this behavior:

1. Configure the LWT: When initializing the client connection, specify the LWT topic and payload.
2. Trigger a connection loss: Instead of calling a graceful disconnect method, terminate the network connection abruptly (simulating a crash or network failure).
3. Verify delivery: A second client subscribed to the LWT topic will receive the message published by the broker on behalf of the disconnected client.

-- Conceptual workflow based on the example
-- Client 1: Connects with LWT configured, then loses connection abruptly
-- Client 2: Subscribes to the LWT topic and waits for the broker to deliver the message

When initializing the client, you can provide the following keys in the args table: