Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tarantool/mqtt
Tarantool MQTT client
https://github.com/tarantool/mqtt
c lua mqtt-bridge mqtt-client persistent-queue rabbitmq-client
Last synced: 3 months ago
JSON representation
Tarantool MQTT client
- Host: GitHub
- URL: https://github.com/tarantool/mqtt
- Owner: tarantool
- License: bsd-2-clause
- Created: 2016-07-13T08:12:52.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2022-01-28T14:08:48.000Z (almost 3 years ago)
- Last Synced: 2024-04-05T21:33:02.228Z (7 months ago)
- Topics: c, lua, mqtt-bridge, mqtt-client, persistent-queue, rabbitmq-client
- Language: Lua
- Homepage: tarantool.org
- Size: 103 KB
- Stars: 39
- Watchers: 40
- Forks: 10
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-tarantool - mqtt - (Packages / Clients)
README
# Tarantool MQTT client
---------------------------------
Key features:
* non-blocking communication with MQTT brokers;
* TLS support;
* pretty low overheads, code based on `libmosquitto`.
## Content
----------
* [Prerequisites](#prerequisites)
* [Building from source](#building-from-source)
* [API](#api)
* [lib_destroy](#lib_destroy)
* [new](#new)
* [connect](#connect)
* [reconnect](#reconnect)
* [subscribe](#subscribe)
* [unsubscribe](#unsubscribe)
* [destroy](#destroy)
* [publish](#publish)
* [will_set](#will_set)
* [will_clear](#will_clear)
* [login_set](#login_set)
* [tls_insecure_set](#tls_insecure_set)
* [tls_set](#tls_set)
* [on_message](#on_message)
* [Subscribe to events](#subscribe-to-events)
* [Performance tuning](#performance-tuning)
* [Examples](#examples)
* [Copyright & License](#copyright--license)
* [See also](#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:
```bash
$ 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](#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](#connect) or [reconnect](#reconnect) will resend the messages.
Returns:
mqtt object (see mqtt_mt) or raises error
Example:
```lua
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
```
[Back to content](#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:
```lua
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](#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](#connect)
call and must not be called prior.
Note: After the reconnection you must call [subscribe](#subscribe) to
subscribe to topics.
See the [connect](#connect) `opts.auto_reconect` parameter.
Example:
```lua
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](#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:
```lua
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](#content)
### unsubscribe
---------------
Unsubscribe from a topic.
Parameters:
topic - Unsubscription pattern.
Returns:
true or false, integer mid or error message
Example:
```lua
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](#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:
```lua
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](#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:
```lua
mqtt = require('mqtt')
instance = mqtt.new("client_id", true)
mqtt.lib_destroy()
```
[Back to content](#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:
```lua
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](#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](#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:
```lua
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](#content)
### will_clear
--------------
Remove a previously configured `will`. Must be called before calling
[connect](#connect).
Returns:
true or false, emsg
Example:
```lua
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](#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](#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:
```lua
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](#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](#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:
```lua
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](#content)
### tls_set
-----------
Configure a client for certificate-based SSL/TLS support. Must be called
before [connect](#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](#tls_insecure_set).
Example:
```lua
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](#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:
```lua
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](#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](mqtt/init.lua) file.
[Back to content](#content)
## Performance tuning
---------------------
TODO: describe me.
[Back to content](#content)
## Examples
-----------
The [examples/connect.lua](examples/connect.lua) file shows how to connect
to an MQTT broker.
The [examples/producer_consumer_queue.lua](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](#content)
## Copyright & License
----------------------
[LICENSE](https://github.com/tarantool/mqtt/blob/master/LICENSE)
[Back to content](#content)
## See also
----------
* [Tarantool](https://www.tarantool.io) homepage.
* MQTT brokers:
* [Mosquitto](https://mosquitto.org) homepage.
* [RabbitMQ](https://www.rabbitmq.com) homepage.
[Back to content](#content)
---
Please report bugs at https://github.com/tarantool/mqtt/issues.
We also warmly welcome your feedback in the discussion mailing list: [email protected].