Key features

• allowing to create communication with MQTT broker in non-blocking way
• TLS supported
• pretty low overheads, code based on libmosquitto

• v0.1 - beta

• Compilation and install
• API
  • new
  • connect
  • reconnect
  • subscribe
  • unsubscribe
  • publish
  • will_set
  • will_clear
  • login_set
  • tls_insecure_set
  • tls_set
  • on_message
  • Subscribe on events
• Performance tuning
• Examples
• Copyright & License
• See also

Before reading any further, make sure, you have installed MQTT broker

$ git clone https://github.com/tarantool/mqtt.git
$ cd mqtt
$ git submodule update --init --recursive
$ cmake .
$ make

Back to content

Lua API documentation

Create a new mosquitto client instance.

Parameters: id - String to use as the client id. If NULL, a random client id will be generated. If id is NULL, clean_session must be true. clean_session - 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. Note that a client will never discard its own outgoing messages on disconnect. Calling (connect)[#connect] or (reconnect)[#reconnect] will cause the messages to be resent. Use reinitialise to reset a client to its original state. Must be set to true if the id parameter is NULL.

Returns: mqtt object(see mqtt_mt) or raise error

  mqtt = require('mqtt')
  instance = mqtt.new(1, true)

Back to content

Connect to an MQTT broker.

Parameters: opts.host - the hostname or ip address of the broker to connect to. opts.port - the network port to connect to. Usually 1883. opts.keepalive - the 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. opts.log_mask - LOG_NONE, LOG_INFO, LOG_NOTICE, LOG_WARNING, LOG_ERROR[default], LOG_DEBUG, LOG_ALL opts.auto_reconect - true[default], false - auto reconnect on, off

Returns: true or false, emsg

  mqtt = require('mqtt')
  instance = mqtt.new(1, true)
  instance:connect({
    host='127.0.0.1',
    port=1883,
    keepalive=60,
    log_mask=mqtt.LOG_NONE
  })

Back to content

Reconnect to a broker.

This function provides an easy way of reconnecting to a broker after a
connection has been lost. It uses the values that were provided in the
[connect](#connect) call. It must not be called before
[connect](#connect).

NOTE After reconnecting you must call subscribe for subscribing to a topics.

See connect <opts.auto_reconect>

  mqtt = require('mqtt')
  instance = mqtt.new(1, 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

Back to content

Subscribe to a topic.

Parameters: sub - the subscription pattern. qos - the requested Quality of Service for this subscription.

Returns: true or false, integer mid or error message

  mqtt = require('mqtt')
  -- Cut, see [new](#new) and [connect](#connect)
  ok, err_or_mid = mqtt:subscribe('my/topic/#', 1)
  if ok then
    print(ok, err_or_mid)
  end

Back to content

Unsubscribe from a topic.

Parameters: topic - the unsubscription pattern.

Returns: true or false, integer mid or error message

  mqtt = require('mqtt')
  -- Cut, see [new](#new) and [connect](#connect)
  ok, err = mqtt:unsubscribe('my/topic/#')
  if ok then
    print(ok, err)
  end

Back to content

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. retain - set to true to make the message retained.

Returns: true or false, emsg, message id(e.g. MID) is referenced in the publish callback

  mqtt = require('mqtt')
  -- Cut, see [new](#new) and [connect](#connect)
  ok, err = mqtt:publish('my/topic/#', 'Some payload as string', 0, true)
  if ok then
    print(ok, err)
  end

Back to content

Configure will information for a mosquitto instance. By default, clients do not have a will. This must be called before calling connect.

Parameters: topic - the topic on 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

  mqtt = require('mqtt')
  -- Cut, see [new](#new) and [connect](#connect)
  ok, err = mqtt:will_set('my/topic/#', 'Some payload as string', 0, true)
  if ok then
    print(ok, err)
  end

Back to content

Remove a previously configured will. This must be called before calling connect.

Returns: true or false, emsg

  mqtt = require('mqtt')
  -- Cut, see [new](#new) and [connect](#connect)
  ok, err = mqtt:will_clear()
  if ok then
    print(ok, err)
  end

Back to content

Configure username and password for a mosquitton instance. This is only supported by brokers that implement the MQTT spec v3.1. By default, no username or password will be sent. If username is NULL, the password argument is ignored. This must be called before calling connect.

This is must be called before calling connect.

Parameters: username - the username to send as a string, or NULL to disable authentication. password - the password to send as a string. Set to NULL when username is valid in order to send just a username.

Returns: true or false, emsg

  mqtt = require('mqtt')
  -- Cut, see [new](#new) and [connect](#connect)
  ok, err = mqtt:login_set('user', 'password')
  if ok then
    print(ok, err)
  end

Back to content

Configure verification of the server hostname in the server certificate. If value is set to true, it is impossible to guarantee that the host you are connecting to is not impersonating your server. This can be useful in initial server testing, but makes it possible for a malicious third party to impersonate your server through DNS spoofing, for example. Do not use this function in a real system. Setting value to true makes the connection encryption pointless. Must be called before connect.

Parameters: value - if set to false, the default, certificate hostname checking is performed. If set to true, no hostname checking is performed and the connection is insecure.

Returns: true or false, emsg

  mqtt = require('mqtt')
  -- Cut, see [new](#new) and [connect](#connect)
  ok, err = mqtt:tls_insecure_set(true)
  if ok then
    print(ok, err)
  end

Back to content

Configure the client for certificate based SSL/TLS support. Must be called before connect.

Define the Certificate Authority certificates to be trusted (ie. the server certificate must be signed with one of these certificates) using cafile.

If the server you are connecting to requires clients to provide a certificate, define certfile and keyfile with your client certificate and private key. If your private key is encrypted, provide a password callback function or you will have to enter the password at the command line.

Parameters: cafile - path to a file containing the PEM encoded trusted CA certificate files. Either 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 cafile or capath must not be NULL. certfile - path to a file containing the PEM encoded certificate file for this client. If NULL, keyfile must also be NULL and no client certificate will be used. keyfile - path to a file containing the PEM encoded private key for this client. If NULL, 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

  mqtt = require('mqtt')
  -- Cut, see [new](#new) and [connect](#connect)
  ok, err = mqtt:tls_set('my.pem', '/home/user/pems', 'my.ca', 'my.key')
  if ok then
    print(ok, err)
  end

Back to content

Set the message callback. This is called when a message is received from the broker.

Parameters: F - a callback function in the following form: function F(integer_mid, string_topic, string_payload, integer_gos, integer_retain)

Returns: true or false, emsg

  mqtt = require('mqtt')
  -- Cut, see [new](#new) and [connect](#connect)
  ok, err = mqtt: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

Back to content

NOTE Basically, you don't need this functions, so use them with caution. Wrong uncorrect of following funtions might break async I/O loop! * on_connect * on_disconnect * on_publish * on_subscribe * on_unsubscribe * on_disconnect Detailed documentation of functions described above can be found in the file: mqtt/init.lua

Back to content

Back to content

Connecting to the MQTT broker * examples/connect.lua

Tarantool produces data then passes it to MQTT broker via MQTT connector in non-blocking way. Also, Tarantool consumes data from the MQTT broker via MQTT connector in non-blocking way. * examples/producer_consumer_queue.lua

Back to content

LICENSE

Back to content

• Tarantool homepage.
• MQTT brokers
  • Mosquitto homepage.
  • RabbitMQ homepage.

Back to content

================ Please report bugs at https://github.com/tarantool/mqtt/issues.

We also warmly welcome your feedback in the discussion mailing list, tarantool@googlegroups.com.