MQTT client

MQTT client library #

Load the library:

local mqtt = require('mosquitto')

Library functions #

new(client_id, clean_session) #

Creates new instance of MQTT client connection

  • client_id (string, optional, default = empty) - client identification string
  • clean_session (Boolean, optional, default = true) - set to true to instruct the broker to clean all messages and subscriptions on disconnect, false to instruct it to keep them

Instance functions #

login_set(username, password) #

Configures username and password for a given instance, must be called before connect

  • username (string, optional) - the username to send as a string, or nil to disable authentication
  • password (string, optional) - the password to send as a string, set to nil when username is valid in order to send just a username

version_set(version) #

Sets protocol version to use, must be called before connect

  • version (integer) - MQTT version, use one of library constants: PROTOCOL_V31, PROTOCOL_V311, PROTOCOL_V5

connect(host, port, keepalive) #

Connects to an MQTT broker

  • host (string, optional, default = "localhost") - hostname or IP address of the broker
  • port (integer, optional, default = 1883) - network port of the broker
  • keepalive (integer, optional, default = 60) - a number of seconds after which the broker should send a PING message to the client if no other messages have been exchanged in that time

reconnect() #

Reconnects to a broker, provides an easy way of reconnecting to a broker after a connection has been lost, must be called after connect

disconnect() #

Disconnects from the broker

publish(topic, payload, qos, retain, props) #

Publishes a message on a given topic

  • topic (string) - topic name to publish to
  • payload (string, optional) - payload data
  • qos (integer) - value 0, 1 or 2 indicating the Quality of Service to be used for the message
  • retain (Boolean) - set to true to make the message retained
  • props (nil or table, optional) - list of MQTT 5 properties

subscribe(topic, qos, options, props) #

Subscribes to a topic

  • topic (string) - topic name / subscription pattern
  • qos (integer, optional, default = 0) - requested Quality of Service for this subscription
  • options (integer, optional, default = 0) - options to apply to this subscription (logically OR'ed), only for MQTT 5
  • props (nil or table, optional) - list of MQTT 5 properties

Options:

  • SUB_OPT_NO_LOCAL - if this client publishes to a topic to which it is subscribed, the broker will not publish the message back to the client
  • SUB_OPT_RETAIN_AS_PUBLISHED - messages published for this subscription will keep the retain flag as was set by the publishing client, the default behavior without this option set has the retain flag indicating whether a message is fresh/stale
  • SUB_OPT_SEND_RETAIN_ALWAYS - pre-existing retained messages are sent as soon as the subscription is made, even if the subscription already exists, this is the default behavior, so it is not necessary to set this option
  • SUB_OPT_SEND_RETAIN_NEW - pre-existing retained messages for this subscription will be sent when the subscription is made, but only if the subscription does not already exist
  • SUB_OPT_SEND_RETAIN_NEVER - pre-existing retained messages will never be sent for this subscription

unsubscribe(topic, props) #

Unsubscribes from a topic

  • topic (string) - topic name / subscription pattern
  • props (nil or table, optional) - list of MQTT 5 properties

tls_insecure_set(mode) #

Skips broker certificate validation if set to true, must be called before connect

  • mode (Boolean) - certificate validation mode

tls_set(cafile, capath, certfile, keyfile) #

Configures the client for certificate based SSL/TLS support, must be called before connect

  • cafile (string, optional) - path to a file containing the PEM encoded trusted CA certificate files, either cafile or capath must be present
  • capath (string, optional) - path to a directory containing the PEM encoded trusted CA certificate files, either cafile or capath must be present
  • certfile (string, optional) - path to a file containing the PEM encoded certificate file for this client, if not set then keyfile must not be set and no client certificate will be used
  • keyfile (string, optional) - path to a file containing the PEM encoded private key for this client, if not set then certfile must not be set and no client certificate will be used

tls_psk_set(psk, identity, ciphers) #

Configure the client for pre-shared-key based TLS support, must be called before connect, cannot be used in conjunction with tls_set

  • psk (string) - the pre-shared-key in hex format with no leading 0x
  • identity (string) - the identity of this client
  • ciphers (string, optional) - a string describing the PSK ciphers available for use

will_set(topic, payload, qos, retain, props) #

Configures will information for a given instance, must be called before connect

  • topic (string) - topic name to publish to
  • payload (string, optional) - payload data
  • qos (integer) - value 0, 1 or 2 indicating the Quality of Service to be used for the message
  • retain (Boolean) - set to true to make the message retained
  • props (nil or table, optional) - list of MQTT 5 properties

will_clear() #

Remove a previously configured will, must be called before connect

loop(timeout) #

Runs the main network loop for the client, must be called frequently to keep communications between the client and broker working

  • timeout (integer, optional, default = 1000ms) - maximum number of milliseconds to wait for network activity

socket() #

Returns file descriptor number of client socket or false when socket has not yet been created

getfd() #

Alias of socket()

loop_read() #

Carries out network read operations

loop_write() #

Carries out network write operations

loop_misc() #

Carries out miscellaneous operations required as part of the network loop

want_write() #

Returns true if there is data ready to be written on the socket

callback_set(type, cb) #

Sets callback function for a given type

  • type (string) - callback type, see below
  • cb (function) - callback function

Callbacks #

ON_CONNECT(success, rc, stat, flags, props)

  • success (Boolean) - connection status
  • rc (integer) - reason code
  • stat (string) - status message
  • flags (integer) - connection flags
  • props (nil or table) - list of MQTT 5 properties

ON_DISCONNECT(success, rc, stat, props)

  • success (Boolean) - connection status
  • rc (integer) - reason code
  • stat (string) - status message
  • props (nil or table) - list of MQTT 5 properties

ON_PUBLISH(mid, rc, stat, props)

  • mid (integer) - message id
  • rc (integer) - reason code
  • stat (string) - status message
  • props (nil or table) - list of MQTT 5 properties

ON_MESSAGE(mid, topic, payload, qos, retain, props)

  • mid (integer) - message id
  • topic (string) - topic name
  • payload (string) - payload data
  • qos (integer) - QoS level
  • retain (Boolean) - retain flag
  • props (nil or table) - list of MQTT 5 properties

ON_SUBSCRIBE(mid, granted_qos, props)

  • mid (integer) - message id
  • granted_qos (table) - an array of integers indicating the granted QoS for each of the subscriptions
  • props (nil or table) - list of MQTT 5 properties

ON_UNSUBSCRIBE(mid, props)

  • mid (integer) - message id
  • props (nil or table) - list of MQTT 5 properties

ON_LOG(level, str)

  • level (integer) - log level
  • str (string) - message string

ON_ERROR(err)

Executed when any other callback function has been executed with an error

  • err (string) - error message from any other callback function

MQTT v5 properties #

payload-format-indicator (byte, available during: PUBLISH, Will Properties) 0 = unspecified format, 1 = UTF-8 data

message-expiry-interval (4 byte integer, available during: PUBLISH) Lifetime of the application message in seconds, no expiration if absent or 0 Will Properties Lifetime of the will message in seconds

content-type (UTF-8 string, available during: PUBLISH, Will Properties) Value is defined by the sending and receiving application

response-topic (UTF-8 string, available during: PUBLISH, Will Properties) Topic name for a response message

correlation-data (binary Data, available during: PUBLISH, Will Properties) Identifies which request the response is for

subscription-identifier (variable byte integer, available during: PUBLISH, SUBSCRIBE) Identifier of the subscription

session-expiry-interval (4 byte integer, available during: CONNECT, CONNACK, DISCONNECT) Session expiry interval in seconds

assigned-client-identifier (UTF-8 string, available during: CONNACK) The client identifier which was assigned by the server because a zero length client identifier was set

server-keep-alive (2 byte integer, available during: CONNACK) Keep alive time assigned by the server

authentication-method (UTF-8 string, available during: CONNECT, CONNACK, AUTH) Name of the authentication method

authentication-data (binary Data, available during: CONNECT, CONNACK, AUTH) Contents of this data are defined by the authentication method and the state of already exchanged authentication data

request-problem-information (byte, available during: CONNECT) Indicates whether the reason string or user properties are sent in the case of failures

will-delay-interval (4 byte int, available during: Will properties) Will delay interval in seconds

request-response-information (byte, available during: CONNECT) The client uses this value to request the server to return response information in the CONNACK

response-information (UTF-8 string, available during: CONNACK) Used as the basis for creating a response topic

server-reference (UTF-8 string, available during: CONNACK, DISCONNECT) Identifies another server to use

reason-string (UTF-8 string, available during: All except Will properties) Represents the reason associated with this response

receive-maximum (2 byte integer, available during: CONNECT, CONNACK) Limits the number of QoS 1 and QoS 2 publications that the client is willing to process concurrently

topic-alias-maximum (2 byte integer, available during: CONNECT, CONNACK) Indicates the highest value that the client will accept as a topic alias sent by the server

topic-alias (2 byte integer, available during: PUBLISH) Identifies the topic instead of using the topic name to reduce the size of the PUBLISH packet

maximum-qos (byte, available during: CONNACK) If a server does not support QoS 1 or QoS 2 PUBLISH packets it sends a value specifying the highest QoS it supports

retain-available (byte, available during: CONNACK) Declares whether the server supports retained messages

user-property-* (UTF-8 string pair, available during: All) * is a custom property name, provides additional information to the client including diagnostic information, can appear multiple times to represent multiple name, value pairs

maximum-packet-size (4 byte integer, available during: CONNECT, CONNACK) The maximum packet size the server is willing to accept

wildcard-sub-available (byte, available during: CONNACK) Declares whether the server supports wildcard subscriptions

subscription-id-available (byte, available during: CONNACK) Declares whether the server supports subscription identifiers