lua-mosquitto

Contents

• Library functions
• Instance functions
• Module Constants

Modules

• mosquitto

Module mosquitto

Lua bindings to libmosquitto

This documentation is partial, and doesn't cover all functionality yet.

Library functions

version ()	Return mosquitto library version.
topic_matches_sub (subscription, topic)	Does a topic match a subscription string?
init ()
cleanup ()	Cleanup mosquitto library.
new ([client=nil[, clean_session=true]])	Create a new mosquitto instance

Instance functions

destroy ()	Destroy context This is called automatically by garbage collection, you shouldn't normally have to call this.
reinitialise ([client=nil[, clean=true]])	Reinitialise
will_set (topic, payload[, qos=0[, retain=false]])	Set a Will
will_clear ()	Clear a will
login_set ([username=nil[, password=nil]])	Set login details
tls_set ([cafile=nil[, capath=nil[, certfile=nil[, keyfile=nil]]]])	Set TLS details This doesn't currently support callbacks for passphrase prompting!
tls_insecure_set (value)	Set TLS insecure flags
tls_psk_set (psk, identity[, ciphers])	Set TLS PSK options
tls_opts_set (cert[, tls_version=nil[, ciphers=nil]])	Set TLS options, must be called before connect.
threaded_set (value)	Set/clear threaded flag
option (option, value)	Set client options, normally required before connect.
connect ([host=localhost[, port=1883[, keepalive=60]]])	Connect to a broker
connect_async ([host=localhost[, port=1883[, keepalive=60]]])	connect (async)
reconnect ()
disconnect ()
publish (topic, payload[, qos=0[, retain=nil]])	Publish a message
subscribe (topic[, qos=0])	Subscribe to a topic
unsubscribe (topic)	Unsubscribe from a topic
loop ([timeout=-1[, max_packets=1]])	run the loop manually
loop_forever ([timeout=-1[, max_packets=1]])	run the loop forever, blocking
loop_start ()	Start a loop thread
loop_stop ()	Stop an existing loop thread
socket ()	Get the underlying socket
loop_read ([max_packets=1])	Handle loop read events manually
loop_write ([max_packets=1])	Handle loop write events manually
loop_misc ()	Handle loop misc events manually
want_write ()	Does the library want to write?

Module Constants

callback_ids	Callback ids
log_types	Log types
option_types	Option types
option_values	Option Values

Library functions

version ()

Return mosquitto library version.

Returns:

string version string "major.minor.revision"

See also:

mosquitto_lib_version

topic_matches_sub (subscription, topic)

Does a topic match a subscription string?

Parameters:

• subscription string eg, blah/+/wop/#
• topic string to test

Returns:

boolean result

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_topic_matches_sub

init ()

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_lib_init

cleanup ()

Cleanup mosquitto library. This is called automatically by garbage collection, you shouldn't normally have to call this.

Returns:

true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_lib_cleanup

new ([client=nil[, clean_session=true]])

Create a new mosquitto instance

Parameters:

• client string id, optional. nil to allow library to generate (default nil)
• clean_session boolean (default true)

Returns:

a mosquitto instance

Raises:

For some out of memory or illegal states, or both nil id and clean session true

See also:

mosquitto_new

Instance functions

destroy ()

Destroy context This is called automatically by garbage collection, you shouldn't normally have to call this.

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_destroy

reinitialise ([client=nil[, clean=true]])

Reinitialise

Parameters:

• client string id, nil to allow the library to determine (default nil)
• clean boolean session. (default true)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

• mosquitto_reinitialise
• new

will_set (topic, payload[, qos=0[, retain=false]])

Set a Will

Parameters:

• topic string as per mosquitto_will_set
• payload string as per mosquitto_will_set (but a proper lua string)
• qos number 0, 1 or 2 (default 0)
• retain boolean (default false)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_will_set

will_clear ()

Clear a will

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_will_clear

login_set ([username=nil[, password=nil]])

Set login details

Parameters:

• username string may be nil (default nil)
• password string may be nil (default nil)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_username_pw_set

tls_set ([cafile=nil[, capath=nil[, certfile=nil[, keyfile=nil]]]])

Set TLS details This doesn't currently support callbacks for passphrase prompting!

Parameters:

• cafile string may be nil (default nil)
• capath string may be nil (default nil)
• certfile string may be nil (default nil)
• keyfile string may be nil (default nil)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_tls_set

tls_insecure_set (value)

Set TLS insecure flags

Parameters:

• value boolean true or false

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_tls_insecure_set

tls_psk_set (psk, identity[, ciphers])

Set TLS PSK options

Parameters:

• psk string
• identity string
• ciphers string (optional)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_tls_psk_set

tls_opts_set (cert[, tls_version=nil[, ciphers=nil]])

Set TLS options, must be called before connect.

Parameters:

• cert bool true for SSL_VERIFY_PEER, false for SSL_VERIFY_NONE
• tls_version string nil to use default (default nil)
• ciphers string nil to use the default set (default nil)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_tls_opts_set

threaded_set (value)

Set/clear threaded flag

Parameters:

• value boolean true or false

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_threaded_set

option (option, value)

Set client options, normally required before connect. This will call _string_option or _int_option automatically based on the parameters provided.

Parameters:

• option number code, eg M.OPT_TLS_ALPN or M.OPT_PROTOCOL_VERSION
• value string_or_number the value of the option to set

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For illegal arguments

See also:

• mosquitto_string_option
• mosquitto_int_option
• option_types

connect ([host=localhost[, port=1883[, keepalive=60]]])

Connect to a broker

Parameters:

• host string (default localhost)
• port number (default 1883)
• keepalive number in seconds (default 60)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_connect

connect_async ([host=localhost[, port=1883[, keepalive=60]]])

connect (async)

Parameters:

• host string (default localhost)
• port number (default 1883)
• keepalive number in seconds (default 60)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_connect_async

reconnect ()

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_reconnect

disconnect ()

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_disconnect

publish (topic, payload[, qos=0[, retain=nil]])

Publish a message

Parameters:

• topic string
• payload string (may be nil)
• qos number 0, 1 or 2 (default 0)
• retain boolean flag (default nil)

Returns:

Or

number MID can be used for correlation with callbacks

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_publish

subscribe (topic[, qos=0])

Subscribe to a topic

Parameters:

• topic string eg "blah/+/json/#"
• qos number 0, 1 or 2 (default 0)

Returns:

number MID can be used for correlation with callbacks

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_subscribe

unsubscribe (topic)

Unsubscribe from a topic

Parameters:

• topic string to unsubscribe from

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_unsubscribe

loop ([timeout=-1[, max_packets=1]])

run the loop manually

Parameters:

• timeout number how long in ms to wait for traffic (-1 for library default) (default -1)
• max_packets number (default 1)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_loop

loop_forever ([timeout=-1[, max_packets=1]])

run the loop forever, blocking

Parameters:

• timeout number how long in ms to wait for traffic (-1 for library default) (default -1)
• max_packets number (default 1)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_loop_forever

loop_start ()

Start a loop thread

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_loop_start

loop_stop ()

Stop an existing loop thread

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_loop_stop

socket ()

Get the underlying socket

Returns:

number the socket number

Or

boolean false if the socket was uninitialized

See also:

mosquitto_socket

loop_read ([max_packets=1])

Handle loop read events manually

Parameters:

• max_packets number (default 1)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_loop_read

loop_write ([max_packets=1])

Handle loop write events manually

Parameters:

• max_packets number (default 1)

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_loop_write

loop_misc ()

Handle loop misc events manually

Returns:

boolean true

Or

1. nil
2. number error code
3. string error description.

Raises:

For some out of memory or illegal states

See also:

mosquitto_loop_misc

want_write ()

Does the library want to write?

Returns:

boolean result

See also:

mosquitto_want_write

Module Constants

callback_ids

Callback ids

Fields:

• ON_CONNECT
• ON_DISCONNECT
• ON_PUBLISH
• ON_MESSAGE
• ON_SUBSCRIBE
• ON_UNSUBSCRIBE
• ON_LOG

log_types

Log types

Fields:

• LOG_NONE
• LOG_INFO
• LOG_NOTICE
• LOG_WARNING
• LOG_ERROR
• LOG_DEBUG
• LOG_ALL

option_types

Option types

Fields:

• OPT_PROTOCOL_VERSION
• OPT_SSL_CTX
• OPT_SSL_CTX_WITH_DEFAULTS
• OPT_RECEIVE_MAXIMUM
• OPT_SEND_MAXIMUM
• OPT_TLS_KEYFORM
• OPT_TLS_ENGINE
• OPT_TLS_ENGINE_KPASS_SHA1
• OPT_TLS_OCSP_REQUIRED
• OPT_TLS_ALPN

See also:

option

option_values

Option Values

Fields:

• MQTT_PROTOCOL_V31
• MQTT_PROTOCOL_V311
• MQTT_PROTOCOL_V5

See also:

option