mqtt5 - Reference

---

Constructor

mqtt5 ( {params} )

The constructor of MQTT client requires a table with the following fields:

• socket: an object supplying the methods close, read & write (a subset of the cqueues.socket API)
• logger: an optional object supplying the methods debug & error (a subset of the LuaLogging API)
• on_connect: an optional callback function
• on_message: an optional callback function
• on_disconnect: an optional callback function
• on_error: an optional callback function

Instance methods

connect ( [{options} [, { prop_id1, prop_value1, ... }]] )

Send a CONNECT packet with an optional set of Properties, or throws an error when invalid parameter.

The optional table options may contains the following fields:

• clean: a boolean Clean Start
• keep_alive: an integer Keep Alive, the default value is 0
• id: a string Client Identifier, could be auto-generated
• will: a table (see below)
• username: a string User Name
• password: a string Password

The array part of the table will contains the Will Topic and the Will Payload, the hash part may contains the following fields:

• qos: an value in the set 0, 1 and 2, the default value is 0
• retain: a boolean
• props: a set of Will Properties

reconnect (socket)

Replays the call to connect with a new socket.

This method is typically called by the callback on_error.

publish ( topic, payload [, {options} [, { prop_id1, prop_value1, ... }]] )

Send a PUBLISH packet with a Topic Name, a Payload, and an optional set of Properties, or throws an error when invalid parameter.

The optional table options may contains the following fields:

• qos with an value in the set 0, 1 and 2, the default value is 0
• retain with a boolean meaning

subscribe ( { filter1, options1, ... } [, { prop_id1, prop_value1, ... }] )

Send a SUBSCRIBE packet with a non empty set of pair of Topic Filters and Subscription Options, and an optional set of Properties, or throws an error when invalid parameter.

unsubscribe ( { filter1, ... } [, { prop_id1, prop_value1, ... }] )

Send a UNSUBSCRIBE packet with a non empty list of Topic Filters, and an optional set of Properties, or throws an error when invalid parameter.

ping ()

Send a PINGREQ packet.

disconnect ( [reason_code [, { prop_id1, prop_value1, ... }]] )

Send a DISCONNECT packet with a Reason Code, and an optional set of Properties, the default Reason Code is 0, or throws an error when invalid parameter.

auth ( reason_code [, { prop_id1, prop_value1, ... }] )

Send an AUTH packet with a Reason Code, and an optional set of Properties, or throws an error when invalid parameter.

read ()

Waits and handles a packet from the server. Returns a table describing this packet or nil and a message describing the reason of a disconnection or an unsuccessful reconnection.

The table contains at least the field type with a string value.

The callback on_connect (reason_code, session_present, props) is called on CONNACK packet received. If the connection is successful, this callback does typically some subscriptions. This callback is not intended to return something.

The callback on_message (topic, payload, props) is called on each PUBLISH packet received. This callback is not intended to return something.

The callback on_disconnect (reason_code, props) is called on DISCONNECT packet received. This callback is not intended to return something.

The callback on_error () is called when the connection is broken. When everything is going well, this callback open a new connection, calls the method reconnect with it and finally return a true value. In bad case, this callback returns a false value, optionally followed by a message.

Class functions & members

match (name, filter)

Checks if a Topic Name matches a Topic Filter. Returns a boolean or throws an error when invalid parameter.

PORT

Gives the IANA registered port 1883 as a string.

PORT_TLS

Gives the IANA registered port 8883 as a string.

PROP

Gives a table with all Property Identifier.