Tarantool Mqtt Save
Tarantool MQTT client
Tarantool MQTT client
Key features:
- non-blocking communication with MQTT brokers;
- TLS support;
- pretty low overheads, code based on
libmosquitto.
Content
Prerequisites
Before reading any further, make sure you have an MQTT broker installed or use static build by passing STATIC_BUILD flags to cmake.
Building from source
Clone the repository with submodules and build the client:
$ git clone https://github.com/tarantool/mqtt.git
$ cd mqtt
$ git submodule update --init --recursive
$ mkdir build && cd build
$ cmake ..
$ make -j
API
Lua API documentation.
new
Create a new mosquitto client instance.
Parameters:
client_id - String. If NULL, a random client id will be generated
and the clean_session parameter must be set to true.
clean_session - Boolean. Set to true to instruct the broker to clean all
messages and subscriptions on disconnect; false to instruct
it to keep them. See the man page mqtt(7) for more details.
Must be set to true if the id parameter is NULL.
Note that a client will never discard its own outgoing messages on disconnect. Calling connect or reconnect will resend the messages.
Returns:
mqtt object (see mqtt_mt) or raises error
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
connect
Connect to an MQTT broker.
Parameters:
opts.host - Hostname or IP address of the broker to connect to.
opts.port - Network port to connect to. Usually 1883.
opts.keepalive - The number of seconds the broker waits since the last
message before sending a PING message to the client.
opts.log_mask - LOG_NONE, LOG_INFO, LOG_NOTICE, LOG_WARNING,
LOG_ERROR[default], LOG_DEBUG, LOG_ALL.
opts.auto_reconect - [true|false] - auto reconnect on (default) or off.
Returns:
true or false, emsg
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
instance:connect({
host='127.0.0.1',
port=1883,
keepalive=60,
log_mask=mqtt.LOG_NONE
})
reconnect
Reconnect to broker.
This function provides an easy way of reconnecting to the broker after connection loss. It uses the values provided in the connect call and must not be called prior.
Note: After the reconnection you must call subscribe to subscribe to topics.
See the connect opts.auto_reconect parameter.
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
instance:connect({host='127.0.0.1', port=1883, auto_reconect=false})
ok, emsg_or_mid = instance:subscribe('topic')
if not ok and not mqtt.connect then
print('subscribe - failed, reconnecting ...')
ok, _ = instance:reconnect()
end
subscribe
Subscribe to a topic.
Parameters:
sub - Subscription pattern.
qos - Requested Quality of Service for this subscription.
Returns:
true or false, integer mid or error message
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err_or_mid = instance:subscribe('my/topic/#', 1)
if ok then
print(ok, err_or_mid)
end
unsubscribe
Unsubscribe from a topic.
Parameters:
topic - Unsubscription pattern.
Returns:
true or false, integer mid or error message
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err = instance:unsubscribe('my/topic/#')
if ok then
print(ok, err)
end
destroy
Destroy an mqtt object.
Note: Call this function manually as the module does not use the Lua's GC.
Parameters:
None
Returns:
true or false, error message
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err = instance:destroy()
if ok then
print(ok, err)
end
lib_destroy
Cleanup everything.
Note: The module does not use the Lua's GC, the latter has to be called
manually. To call it manually, first call destroy on each mqtt object.
Parameters:
None
Returns:
None
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
mqtt.lib_destroy()
publish
Publish a message on a given topic.
Parameters:
topic - Null-terminated string of the topic to publish to.
payload - Pointer to the data to send.
qos - Integer value 0, 1 or 2 indicating the Quality of Service to be
used for the message. When you call the library with "mqtt = require('mqtt')",
you can use mqtt.QOS_0, mqtt.QOS_1 and mqtt.QOS_2 as a replacement
for some strange digital variable.
retain - Set to true to make the message retained. You can also use the values
mqtt.RETAIN and mqtt.NON_RETAIN to replace the unmarked variable.
Returns:
true or false, emsg, message id (i.e. MID) is referenced in the publish callback
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err = instance:publish('my/topic/#', 'Some payload as string', mqtt.QOS_0, mqtt.RETAIN)
if ok then
print(ok, err)
end
will_set
Configure the will information for a mosquitto instance. By default, clients do
not have a will. Must be called before calling connect.
Parameters:
topic - Topic for which to publish the will.
payload - Pointer to the data to send.
qos - Integer value 0, 1 or 2 indicating the Quality of Service to be
used for the will.
retain - Set to true to make the will a retained message.
Returns:
true or false, emsg
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err = instance:will_set('my/topic/#', 'Some payload as string', 0, true)
if ok then
print(ok, err)
end
will_clear
Remove a previously configured will. Must be called before calling
connect.
Returns:
true or false, emsg
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err = instance:will_clear()
if ok then
print(ok, err)
end
login_set
Configure a username and password for the mosquitto instance. Supported only by
the brokers that implement the MQTT spec v3.1. By default, no username
or password will be sent. If the username is NULL, the password argument is ignored.
Must be called before calling connect.
Parameters:
username - Username to send as a string or NULL to disable
authentication.
password - Password to send as a string. Set to NULL to send
just a valid username.
Returns:
true or false, emsg
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err = instance:login_set('user', 'password')
if ok then
print(ok, err)
end
tls_insecure_set
If set to true, do not check if the hostname in the server's certificate
matches the hostname of the server to connect to.
If the check is disabled, connection encryption is pointless and it is impossible to guarantee that the host you are connecting to is not impersonating the server. This can be useful during the initial server testing but makes it possible for a malicious third party to impersonate the server through, e.g., DNS spoofing.
Do not use this function in a production environment.
Must be called before connect.
Parameters:
value - If set to false (default), certificate hostname is checked.
If set to true, no checking is performed and connection is insecure.
Returns:
true or false, emsg
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err = instance:tls_insecure_set(true)
if ok then
print(ok, err)
end
tls_set
Configure a client for certificate-based SSL/TLS support. Must be called before connect.
Define certificates signed by a Certificate Authority (CA) as trusted
(i.e. the server certificate must be signed by it) using cafile.
If the server to connect to requires clients to provide a certificate,
set the certfile and keyfile paths to your client certificate
and private key files. If the private key is encrypted, provide a password
callback function or enter the password via the command line.
Parameters:
cafile - Path to a file containing PEM-encoded trusted CA
certificate. Either the cafile or capath must not be NULL.
capath - Path to a directory containing the PEM-encoded trusted CA
certificate files. See mosquitto.conf for more details on
configuring this directory. Either the cafile or capath must
not be NULL.
certfile - Path to a file containing a PEM-encoded certificate
for this client. If NULL, the keyfile must also be NULL and no
client certificate will be used.
keyfile - Path to a file containing a PEM-encoded private key for
this client. If NULL, the certfile must also be NULL and no
client certificate will be used.
pw_callback - TODO: implement me.
Returns:
true or false, emsg
See also: tls_insecure_set.
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err = instance:tls_set('my.pem', '/home/user/pems', 'my.ca', 'my.key')
if ok then
print(ok, err)
end
on_message
Set a message callback. Called when a message from the broker is received.
Parameters:
F - a callback function with the following form:
function F(integer_mid, string_topic, string_payload, integer_gos, integer_retain)
Returns:
true or false, emsg
Example:
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
-- Cut, see the connect function
ok, err = instance:on_message(
function(message_id, topic, payload, gos, retain)
print('Recv. new message',
message_id, topic, payload, gos, retain)
end)
if ok then
print(ok, err)
end
Subscribe to events
Warning: Use the following functions with caution as incorrect calls can break asynchronous I/O loops!
Non-mandatory functions:
-
on_connect
-
on_disconnect
-
on_publish
-
on_subscribe
-
on_unsubscribe
See the detailed documentation of these functions in the mqtt.init.lua file.
Performance tuning
TODO: describe me.
Examples
The examples/connect.lua file shows how to connect to an MQTT broker.
The examples/producer_consumer_queue.lua file shows how Tarantool produces, passes, and consumes data to and from an MQTT broker via the MQTT connector in a non-blocking way.
Copyright & License
See also
Please report bugs at https://github.com/tarantool/mqtt/issues.
We also warmly welcome your feedback in the discussion mailing list: [email protected].
Open Source Agenda Badge
