Module eco.mqtt

MQTT 3.1.1 client.

This module implements a small MQTT client that integrates with lua-eco's coroutine scheduler.

Create a client with new, register event handlers with client:on, then call client:run to connect and start processing packets.

Events are delivered via callbacks registered by client:on. A handler is called as handler(data, client).

Known events:

  • conack: CONNACK received. data = { rc = integer, reason = string, session_present = boolean }
  • suback: SUBACK received. data = { rc = integer, topic = string }
  • unsuback: UNSUBACK received. data = topic (string)
  • publish: PUBLISH received. data = { topic = string, payload = string, qos = integer, dup = boolean, retain = boolean }
  • error: network/protocol errors and timeouts. data = err (string)

Functions

new ([opts]) Create a new MQTT client.

Fields

QOS0 QoS 0: at most once.
QOS1 QoS 1: at least once.
QOS2 QoS 2: exactly once.
SUBACK_FAILURE SUBACK failure return code.
CONNACK_ACCEPTED CONNACK return code: connection accepted.
CONNACK_REFUSED_PROTOCOL_VERSION CONNACK return code: unacceptable protocol version.
CONNACK_REFUSED_IDENTIFIER_REJECTED CONNACK return code: identifier rejected.
CONNACK_REFUSED_SERVER_UNAVAILABLE CONNACK return code: server unavailable.
CONNACK_REFUSED_BAD_USER_NAME_OR_PASSWORD CONNACK return code: bad username or password.
CONNACK_REFUSED_NOT_AUTHORIZED CONNACK return code: not authorized.

Class client

methods:publish (topic, payload[, qos=mqtt.QOS0[, retain]]) Publish a message.
methods:subscribe (topic[, qos=mqtt.QOS0]) Subscribe to a topic.
methods:unsubscribe (topic) Unsubscribe from a topic.
methods:disconnect () Send DISCONNECT.
methods:close () Close the underlying network socket.
methods:on (event, handler, handlers) Register event handler(s).
methods:set (name, value) Set one option on the client.
methods:run () Connect and start handling packets.


Functions

new ([opts])
Create a new MQTT client.

Parameters:

  • opts Options table.
    • ipaddr string Broker address. (default '127.0.0.1')
    • port int Broker port. (Default 1883 (plain) or 8883 (TLS) depending on ssl) (optional)
    • ssl boolean Enable MQTT over TLS. (default false)
    • ca string CA certificate path for TLS. (optional)
    • cert string Client certificate path for TLS. (optional)
    • key string Client private key path for TLS. (optional)
    • insecure boolean Disable TLS certificate verification. (default false)
    • mark int Set SO_MARK on the socket. (optional)
    • device string Set SO_BINDTODEVICE on the socket. (optional)
    • id string Client id. Randomly generated if absent. (optional)
    • keepalive int keepalive seconds. (default 30)
    • clean_session boolean Clean session flag. (default false)
    • will table Last will message: topic (string) message (string) qos (int) (optional)
    • username string (optional)
    • password string (optional)

Returns:

    client

Fields

QOS0
QoS 0: at most once.
QOS1
QoS 1: at least once.
QOS2
QoS 2: exactly once.
SUBACK_FAILURE
SUBACK failure return code.
CONNACK_ACCEPTED
CONNACK return code: connection accepted.
CONNACK_REFUSED_PROTOCOL_VERSION
CONNACK return code: unacceptable protocol version.
CONNACK_REFUSED_IDENTIFIER_REJECTED
CONNACK return code: identifier rejected.
CONNACK_REFUSED_SERVER_UNAVAILABLE
CONNACK return code: server unavailable.
CONNACK_REFUSED_BAD_USER_NAME_OR_PASSWORD
CONNACK return code: bad username or password.
CONNACK_REFUSED_NOT_AUTHORIZED
CONNACK return code: not authorized.

Class client

MQTT client object.

A client instance is created by calling mqtt.new.

methods:publish (topic, payload[, qos=mqtt.QOS0[, retain]])
Publish a message.

For QoS 1 and 2, the client will keep the packet for retransmission until an acknowledgement is received.

Parameters:

Returns:

    boolean true On success

Or

  1. nil On failure.
  2. string Error message.
methods:subscribe (topic[, qos=mqtt.QOS0])
Subscribe to a topic.

This sends a SUBSCRIBE packet and later triggers the suback event.

Parameters:

  • topic string Topic filter.
  • qos integer Requested QoS. (default mqtt.QOS0)

Returns:

    boolean true On success

Or

  1. nil On failure.
  2. string Error message.
methods:unsubscribe (topic)
Unsubscribe from a topic.

This sends an UNSUBSCRIBE packet and later triggers the unsuback event.

Parameters:

Returns:

    boolean true On success

Or

  1. nil On failure.
  2. string Error message.
methods:disconnect ()
Send DISCONNECT.

This only sends the packet; the underlying socket is not closed here.

Returns:

    boolean true On success

Or

  1. nil On failure.
  2. string Error message.
methods:close ()
Close the underlying network socket.
methods:on (event, handler, handlers)
Register event handler(s).

This function supports two calling forms:

  • client:on(event, handler)
  • client:on({ event1 = handler1, event2 = handler2 })

The handler is called as handler(data, client).

Parameters:

  • event string Event name (when using the 2-argument form).
  • handler function Callback (when using the 2-argument form).
  • handlers table A table of { event = handler } pairs (when using the 1-argument form).
methods:set (name, value)
Set one option on the client.

This is equivalent to providing the field in new's opts.

Parameters:

  • name string Option name.
  • value any Option value.
methods:run ()
Connect and start handling packets.

This call returns when the network connection is closed or an error occurs. Any termination reason is reported through the error event.

generated by LDoc 1.5.0 Last updated 2026-04-09 14:48:22