README.md

Tarantool MQTT client

---

Key features:

• non-blocking communication with MQTT brokers;
• TLS support;
• pretty low overheads, code based on libmosquitto.

Content

---

• Prerequisites
• Building from source
• API
  • lib_destroy
  • new
  • connect
  • reconnect
  • subscribe
  • unsubscribe
  • destroy
  • publish
  • will_set
  • will_clear
  • login_set
  • tls_insecure_set
  • tls_set
  • on_message
  • Subscribe to events
• Performance tuning
• Examples
• Copyright & License
• See also

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

Back to content

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)

Back to content

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
  })

Back to content

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

Back to content

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

Back to content

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

Back to content

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

Back to content

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()

Back to content

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

Back to content

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

Back to content

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

Back to content

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

Back to content

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

Back to content

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

Back to content

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

Back to content

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.

Back to content

Performance tuning

---

TODO: describe me.

Back to content

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.

Back to content

Copyright & License

---

LICENSE

Back to content

See also

---

• 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: [email protected].