{"id":13792539,"url":"https://github.com/tarantool/mqtt","last_synced_at":"2025-09-06T14:49:25.549Z","repository":{"id":44777672,"uuid":"63227584","full_name":"tarantool/mqtt","owner":"tarantool","description":"Tarantool MQTT client","archived":false,"fork":false,"pushed_at":"2022-01-28T14:08:48.000Z","size":105,"stargazers_count":39,"open_issues_count":5,"forks_count":10,"subscribers_count":38,"default_branch":"master","last_synced_at":"2025-05-31T20:48:26.281Z","etag":null,"topics":["c","lua","mqtt-bridge","mqtt-client","persistent-queue","rabbitmq-client"],"latest_commit_sha":null,"homepage":"tarantool.org","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarantool.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-13T08:12:52.000Z","updated_at":"2025-04-29T10:57:34.000Z","dependencies_parsed_at":"2022-07-20T17:18:46.868Z","dependency_job_id":null,"html_url":"https://github.com/tarantool/mqtt","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/tarantool/mqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarantool","download_url":"https://codeload.github.com/tarantool/mqtt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmqtt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273919914,"owners_count":25191207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","lua","mqtt-bridge","mqtt-client","persistent-queue","rabbitmq-client"],"created_at":"2024-08-03T22:01:13.416Z","updated_at":"2025-09-06T14:49:20.535Z","avatar_url":"https://github.com/tarantool.png","language":"Lua","readme":"\u003ca href=\"https://travis-ci.org/tarantool/mqtt\"\u003e\n  \u003cimg src=\"https://travis-ci.org/tarantool/mqtt.png?branch=master\"\u003e\n\u003c/a\u003e\n\n# Tarantool MQTT client\n---------------------------------\n\nKey features:\n\n* non-blocking communication with MQTT brokers;\n* TLS support;\n* pretty low overheads, code based on `libmosquitto`.\n\n## Content\n----------\n* [Prerequisites](#prerequisites)\n* [Building from source](#building-from-source)\n* [API](#api)\n  * [lib_destroy](#lib_destroy)\n  * [new](#new)\n  * [connect](#connect)\n  * [reconnect](#reconnect)\n  * [subscribe](#subscribe)\n  * [unsubscribe](#unsubscribe)\n  * [destroy](#destroy)\n  * [publish](#publish)\n  * [will_set](#will_set)\n  * [will_clear](#will_clear)\n  * [login_set](#login_set)\n  * [tls_insecure_set](#tls_insecure_set)\n  * [tls_set](#tls_set)\n  * [on_message](#on_message)\n  * [Subscribe to events](#subscribe-to-events)\n* [Performance tuning](#performance-tuning)\n* [Examples](#examples)\n* [Copyright \u0026 License](#copyright--license)\n* [See also](#see-also)\n\n## Prerequisites\n-------------------------------\n\n  Before reading any further, make sure you have an MQTT broker installed or use static build by passing **STATIC_BUILD** flags to cmake.\n\n### Building from source\n\nClone the repository with submodules and build the client:\n\n```bash\n$ git clone https://github.com/tarantool/mqtt.git\n$ cd mqtt\n$ git submodule update --init --recursive\n$ mkdir build \u0026\u0026 cd build\n$ cmake ..\n$ make -j\n```\n\n[Back to content](#content)\n\n## API\n------\n\nLua API documentation.\n\n### new\n-------\n\n  Create a new `mosquitto` client instance.\n\n  Parameters:\n\n    client_id       - String. If NULL, a random client id will be generated \n                      and the clean_session parameter must be set to true.\n    clean_session   - Boolean. Set to true to instruct the broker to clean all \n                      messages and subscriptions on disconnect; false to instruct \n                      it to keep them. See the man page mqtt(7) for more details.\n                      Must be set to true if the id parameter is NULL.\n\nNote that a client will never discard its own outgoing messages on disconnect. \nCalling [connect](#connect) or [reconnect](#reconnect) will resend the messages.\n\n  Returns:\n\n     mqtt object (see mqtt_mt) or raises error\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n```\n\n[Back to content](#content)\n\n### connect\n-----------\n\n  Connect to an MQTT broker.\n\n  Parameters:\n\n    opts.host          - Hostname or IP address of the broker to connect to.\n    opts.port          - Network port to connect to. Usually 1883.\n    opts.keepalive     - The number of seconds the broker waits since the last \n                         message before sending a PING message to the client.\n    opts.log_mask      - LOG_NONE, LOG_INFO, LOG_NOTICE, LOG_WARNING,\n                         LOG_ERROR[default], LOG_DEBUG, LOG_ALL.\n    opts.auto_reconect - [true|false] - auto reconnect on (default) or off.\n\n  Returns:\n\n    true or false, emsg\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  instance:connect({\n    host='127.0.0.1',\n    port=1883,\n    keepalive=60,\n    log_mask=mqtt.LOG_NONE\n  })\n```\n\n[Back to content](#content)\n\n### reconnect\n-------------\n\n  Reconnect to broker.\n\n  This function provides an easy way of reconnecting to the broker after\n  connection loss. It uses the values provided in the [connect](#connect) \n  call and must not be called prior.\n\n  Note: After the reconnection you must call [subscribe](#subscribe) to \n  subscribe to topics.\n\n  See the [connect](#connect) `opts.auto_reconect` parameter.\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  instance:connect({host='127.0.0.1', port=1883, auto_reconect=false})\n  ok, emsg_or_mid = instance:subscribe('topic')\n  if not ok and not mqtt.connect then\n    print('subscribe - failed, reconnecting ...')\n    ok, _ = instance:reconnect()\n  end\n```\n\n[Back to content](#content)\n\n### subscribe\n-------------\n\n  Subscribe to a topic.\n\n  Parameters:\n\n    sub -  Subscription pattern.\n    qos -  Requested Quality of Service for this subscription.\n\n  Returns:\n\n    true or false, integer mid or error message\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err_or_mid = instance:subscribe('my/topic/#', 1)\n  if ok then\n    print(ok, err_or_mid)\n  end\n```\n\n[Back to content](#content)\n\n### unsubscribe\n---------------\n\n  Unsubscribe from a topic.\n\n  Parameters:\n\n    topic - Unsubscription pattern.\n\n  Returns:\n\n    true or false, integer mid or error message\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err = instance:unsubscribe('my/topic/#')\n  if ok then\n    print(ok, err)\n  end\n```\n\n[Back to content](#content)\n\n### destroy\n-----------\n\n  Destroy an `mqtt` object.\n\n  Note: Call this function manually as the module does not use the Lua's GC.\n\n  Parameters:\n\n    None\n\n  Returns:\n\n    true or false, error message\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err = instance:destroy()\n  if ok then\n    print(ok, err)\n  end\n```\n\n[Back to content](#content)\n\n### lib_destroy\n---------------\n\n  Cleanup everything.\n\n  Note: The module does not use the Lua's GC, the latter has to be called \n  manually. To call it manually, first call `destroy` on each `mqtt` object.\n\n  Parameters:\n\n    None\n\n  Returns:\n\n    None\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  mqtt.lib_destroy()\n```\n\n[Back to content](#content)\n\n### publish\n-----------\n\n  Publish a message on a given topic.\n\n  Parameters:\n\n    topic      - Null-terminated string of the topic to publish to.\n    payload    - Pointer to the data to send.\n    qos        - Integer value 0, 1 or 2 indicating the Quality of Service to be\n                 used for the message. When you call the library with \"mqtt = require('mqtt')\",\n                 you can use mqtt.QOS_0, mqtt.QOS_1 and mqtt.QOS_2 as a replacement \n                 for some strange digital variable.\n    retain     - Set to true to make the message retained. You can also use the values\n                 mqtt.RETAIN and mqtt.NON_RETAIN to replace the unmarked variable.\n\n  Returns:\n\n    true or false, emsg, message id (i.e. MID) is referenced in the publish callback\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err = instance:publish('my/topic/#', 'Some payload as string', mqtt.QOS_0, mqtt.RETAIN)\n  if ok then\n    print(ok, err)\n  end\n```\n\n[Back to content](#content)\n\n### will_set\n------------\n\n  Configure the `will` information for a `mosquitto` instance. By default, clients do\n  not have a `will`. Must be called before calling [connect](#connect).\n\n  Parameters:\n\n    topic      - Topic for which to publish the will.\n    payload    - Pointer to the data to send.\n    qos        - Integer value 0, 1 or 2 indicating the Quality of Service to be\n                 used for the will.\n    retain     - Set to true to make the will a retained message.\n\n  Returns:\n\n    true or false, emsg\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err = instance:will_set('my/topic/#', 'Some payload as string', 0, true)\n  if ok then\n    print(ok, err)\n  end\n```\n\n[Back to content](#content)\n\n### will_clear\n--------------\n\n  Remove a previously configured `will`. Must be called before calling\n  [connect](#connect).\n\n  Returns:\n\n    true or false, emsg\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err = instance:will_clear()\n  if ok then\n    print(ok, err)\n  end\n```\n\n[Back to content](#content)\n\n### login_set\n-------------\n\n  Configure a username and password for the `mosquitto` instance. Supported only by \n  the brokers that implement the MQTT spec v3.1. By default, no username \n  or password will be sent. If the username is NULL, the password argument is ignored.\n\n  Must be called before calling [connect](#connect).\n\n  Parameters:\n\n    username - Username to send as a string or NULL to disable\n               authentication.\n    password - Password to send as a string. Set to NULL to send \n               just a valid username.\n\n  Returns:\n\n    true or false, emsg\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err = instance:login_set('user', 'password')\n  if ok then\n    print(ok, err)\n  end\n```\n\n[Back to content](#content)\n\n### tls_insecure_set\n--------------------\n\n  If set to `true`, do not check if the hostname in the server's certificate \n  matches the hostname of the server to connect to.\n\n  If the check is disabled, connection encryption is pointless and \n  it is impossible to guarantee that the host you are connecting to is not \n  impersonating the server. This can be useful during the initial server \n  testing but makes it possible for a malicious third party to impersonate \n  the server through, e.g., DNS spoofing.\n\n  Do not use this function in a production environment. \n\n  Must be called before [connect](#connect).\n\n  Parameters:\n\n    value - If set to false (default), certificate hostname is checked. \n            If set to true, no checking is performed and connection is insecure.\n\n  Returns:\n\n    true or false, emsg\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err = instance:tls_insecure_set(true)\n  if ok then\n    print(ok, err)\n  end\n```\n\n[Back to content](#content)\n\n### tls_set\n-----------\n\n  Configure a client for certificate-based SSL/TLS support. Must be called\n  before [connect](#connect).\n\n  Define certificates signed by a Certificate Authority (CA) as trusted \n  (i.e. the server certificate must be signed by it) using `cafile`.\n\n  If the server to connect to requires clients to provide a certificate, \n  set the `certfile` and `keyfile` paths to your client certificate \n  and private key files. If the private key is encrypted, provide a password \n  callback function or enter the password via the command line.\n\n  Parameters:\n\n    cafile      - Path to a file containing PEM-encoded trusted CA\n                  certificate. Either the cafile or capath must not be NULL.\n    capath      - Path to a directory containing the PEM-encoded trusted CA\n                  certificate files. See mosquitto.conf for more details on\n                  configuring this directory. Either the cafile or capath must \n                  not be NULL.\n    certfile    - Path to a file containing a PEM-encoded certificate\n                  for this client. If NULL, the keyfile must also be NULL and no\n                  client certificate will be used.\n    keyfile     - Path to a file containing a PEM-encoded private key for\n                  this client. If NULL, the certfile must also be NULL and no\n                  client certificate will be used.\n    pw_callback - TODO: implement me.\n\n  Returns:\n\n    true or false, emsg\n\n  See also: [tls_insecure_set](#tls_insecure_set).\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err = instance:tls_set('my.pem', '/home/user/pems', 'my.ca', 'my.key')\n  if ok then\n    print(ok, err)\n  end\n```\n\n[Back to content](#content)\n\n### on_message\n\n  Set a message callback. Called when a message from the broker \n  is received.\n\n  Parameters:\n\n    F - a callback function with the following form:\n        function F(integer_mid, string_topic, string_payload, integer_gos, integer_retain)\n\n  Returns:\n\n    true or false, emsg\n\n  Example:\n\n```lua\n  mqtt = require('mqtt')\n  instance = mqtt.new(\"client_id\", true)\n  -- Cut, see the connect function\n  ok, err = instance:on_message(\n    function(message_id, topic, payload, gos, retain)\n      print('Recv. new message',\n        message_id, topic, payload, gos, retain)\n    end)\n  if ok then\n    print(ok, err)\n  end\n```\n\n[Back to content](#content)\n\n### Subscribe to events\n-----------------------\n\n  Warning: Use the following functions with caution as \n  incorrect calls can break asynchronous I/O loops!\n\n  Non-mandatory functions:\n\n  * on_connect\n\n  * on_disconnect\n\n  * on_publish\n\n  * on_subscribe\n\n  * on_unsubscribe\n\n  See the detailed documentation of these functions in the [mqtt.init.lua](mqtt/init.lua) file.\n\n[Back to content](#content)\n\n## Performance tuning\n---------------------\n\nTODO: describe me.\n\n[Back to content](#content)\n\n## Examples\n-----------\n\n  The [examples/connect.lua](examples/connect.lua) file shows how to connect \n  to an MQTT broker.\n\n  The [examples/producer_consumer_queue.lua](examples/producer_consumer_queue.lua) file shows how \n  Tarantool produces, passes, and consumes data to and from an MQTT broker \n  via the MQTT connector in a non-blocking way.\n\n[Back to content](#content)\n\n## Copyright \u0026 License\n----------------------\n[LICENSE](https://github.com/tarantool/mqtt/blob/master/LICENSE)\n\n[Back to content](#content)\n\n## See also\n----------\n* [Tarantool](https://www.tarantool.io) homepage.\n* MQTT brokers:\n  * [Mosquitto](https://mosquitto.org) homepage.\n  * [RabbitMQ](https://www.rabbitmq.com) homepage.\n\n[Back to content](#content)\n\n---\n\nPlease report bugs at https://github.com/tarantool/mqtt/issues.\n\nWe also warmly welcome your feedback in the discussion mailing list: tarantool@googlegroups.com.\n","funding_links":[],"categories":["Packages"],"sub_categories":["Clients"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fmqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarantool%2Fmqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fmqtt/lists"}