{"id":29942192,"url":"https://github.com/xhaskx/luamqtt","last_synced_at":"2026-03-17T14:20:23.806Z","repository":{"id":34263829,"uuid":"149026706","full_name":"xHasKx/luamqtt","owner":"xHasKx","description":"luamqtt - Pure-lua MQTT v3.1.1 and v5.0 client","archived":false,"fork":false,"pushed_at":"2025-06-20T19:35:00.000Z","size":303,"stargazers_count":172,"open_issues_count":8,"forks_count":45,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-08-03T02:01:58.186Z","etag":null,"topics":["internet-of-things","lua","lua-versions","luajit","luarocks","luasec","mqtt","mqtt-client","mqtt-protocol","mqtt5","protocol","smarthome","ssl","tcp-connection"],"latest_commit_sha":null,"homepage":"https://xhaskx.github.io/luamqtt/","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xHasKx.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-09-16T19:04:16.000Z","updated_at":"2025-08-02T23:55:28.000Z","dependencies_parsed_at":"2024-11-25T01:31:08.702Z","dependency_job_id":"ef635643-dd58-49c2-8414-5d4c50cbb8d3","html_url":"https://github.com/xHasKx/luamqtt","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/xHasKx/luamqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xHasKx%2Fluamqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xHasKx%2Fluamqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xHasKx%2Fluamqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xHasKx%2Fluamqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xHasKx","download_url":"https://codeload.github.com/xHasKx/luamqtt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xHasKx%2Fluamqtt/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268484362,"owners_count":24257660,"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-08-03T02:00:12.545Z","response_time":2577,"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":["internet-of-things","lua","lua-versions","luajit","luarocks","luasec","mqtt","mqtt-client","mqtt-protocol","mqtt5","protocol","smarthome","ssl","tcp-connection"],"created_at":"2025-08-03T02:01:42.344Z","updated_at":"2026-03-17T14:20:18.780Z","avatar_url":"https://github.com/xHasKx.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# luamqtt - Pure-lua MQTT v3.1.1 and v5.0 client\n\n![luamqtt logo](./logo.svg)\n\n[![License](http://img.shields.io/badge/Licence-MIT-brightgreen.svg)](https://github.com/xHasKx/luamqtt/blob/master/LICENSE)\n[![tests](https://github.com/xHasKx/luamqtt/actions/workflows/tests-and-coverage.yml/badge.svg)](https://github.com/xHasKx/luamqtt/actions/workflows/tests-and-coverage.yml)\n[![Coverage Status](https://coveralls.io/repos/github/xHasKx/luamqtt/badge.svg?branch=master)](https://coveralls.io/github/xHasKx/luamqtt?branch=master)\n[![Mentioned in Awesome MQTT](https://awesome.re/mentioned-badge.svg)](https://github.com/hobbyquaker/awesome-mqtt)\n[![forthebadge](https://forthebadge.com/images/badges/powered-by-electricity.svg)](https://forthebadge.com)\n\nMQTT ( [http://mqtt.org/](http://mqtt.org/) ) client library for Lua.\n**MQTT** is a popular network communication protocol working by **\"publish/subscribe\"** model.\n\nThis library is written in **pure-lua** to provide maximum portability.\n\n# Features\n\n* Full MQTT v3.1.1 client-side support\n* Full MQTT v5.0 client-side support\n* Several long-living MQTT clients in one script thanks to ioloop\n\n# Documentation\n\nSee [https://xhaskx.github.io/luamqtt/](https://xhaskx.github.io/luamqtt/)\n\n# Forum\n\nSee [flespi forum thread](https://forum.flespi.com/d/97-luamqtt-mqtt-client-written-in-pure-lua)\n\n# Source Code\n\n[https://github.com/xHasKx/luamqtt](https://github.com/xHasKx/luamqtt)\n\n# Dependencies\n\nThe only main dependency is a [**luasocket**](https://luarocks.org/modules/luasocket/luasocket) to establishing TCP connection to the MQTT broker. Install it like this:\n\n```sh\nluarocks install luasocket\n```\n\nOn Lua 5.1 it also depends on [**LuaBitOp**](http://bitop.luajit.org/) (**bit**) library to perform bitwise operations.\nIt's not listed in package dependencies, please install it manually like this:\n\n```sh\nluarocks install luabitop\n```\n\n## luasec (SSL/TLS)\n\nTo establish secure network connection (SSL/TSL) to MQTT broker\nyou also need [**luasec**](https://github.com/brunoos/luasec) module, please install it manually like this:\n\n```sh\nluarocks install luasec\n```\n\nThis stage is optional and may be skipped if you don't need the secure network connection (e.g. broker is located in your local network).\n\n# Lua versions\n\nIt's tested to work on Debian 9 GNU/Linux with Lua versions:\n\n* Lua 5.1 ... Lua 5.4 (**i.e. any modern Lua version**)\n* LuaJIT 2.0.0 ... LuaJIT 2.1.0 beta3\n* It may also work on other Lua versions without any guarantees\n\nAlso I've successfully run it under **Windows** and it was ok, but installing luarock-modules may be a non-trivial task on this OS.\n\n# Installation\n\nAs the luamqtt is almost zero-dependency you have to install required Lua libraries by yourself, before using the luamqtt library:\n\n```sh\nluarocks install luasocket # optional if you will use your own connectors (see below)\nluarocks install luabitop  # you don't need this for lua 5.3 and above\nluarocks install luasec    # you don't need this if you don't want to use SSL connections\n```\n\nThen you may install the luamqtt library itself:\n\n```sh\nluarocks install luamqtt\n```\n\nOr for development purposes;\n\n```sh\n# development branch:\nluarocks install luamqtt --dev\n\n# or from the cloned repo:\nluarocks make\n```\n\n[LuaRocks page](http://luarocks.org/modules/xhaskx/luamqtt)\n\n# Examples\n\nHere is a short version of [`examples/simple.lua`](examples/simple.lua):\n\n```lua\n-- load mqtt library\nlocal mqtt = require(\"mqtt\")\n\n-- create MQTT client, flespi tokens info: https://flespi.com/kb/tokens-access-keys-to-flespi-platform\nlocal client = mqtt.client{ uri = \"mqtt.flespi.io\", username = os.getenv(\"FLESPI_TOKEN\"), clean = true }\n\n-- assign MQTT client event handlers\nclient:on{\n    connect = function(connack)\n        if connack.rc ~= 0 then\n            print(\"connection to broker failed:\", connack:reason_string(), connack)\n            return\n        end\n\n        -- connection established, now subscribe to test topic and publish a message after\n        assert(client:subscribe{ topic=\"luamqtt/#\", qos=1, callback=function()\n            assert(client:publish{ topic = \"luamqtt/simpletest\", payload = \"hello\" })\n        end})\n    end,\n\n    message = function(msg)\n        assert(client:acknowledge(msg))\n\n        -- receive one message and disconnect\n        print(\"received message\", msg)\n        client:disconnect()\n    end,\n}\n\n-- run ioloop for client\nmqtt.run_ioloop(client)\n```\n\nMore examples placed in [`examples/`](examples/) directory. Also checkout tests in [`tests/spec/mqtt-client.lua`](tests/spec/mqtt-client.lua)\n\nAlso you can learn MQTT protocol by reading [`tests/spec/protocol4-make.lua`](tests/spec/protocol4-make.lua) and [`tests/spec/protocol4-parse.lua`](tests/spec/protocol4-parse.lua) tests\n\n# Connectors\n\nConnector is a network connection layer for luamqtt. There is a three standard connectors included:\n\n* [`luasocket`](mqtt/luasocket.lua)\n* [`luasocket_ssl`](mqtt/luasocket_ssl.lua)\n* [`ngxsocket`](mqtt/ngxsocket.lua) - for using in [openresty environment](examples/openresty)\n\nThe `luasocket` or `luasocket_ssl` connector will be used by default, if not specified, according `secure=true/false` option per MQTT client.\n\nIn simple terms, connector is a set of functions to establish a network stream (TCP connection usually) and send/receive data through it.\nEvery MQTT client instance may have their own connector.\n\nAnd it's very simple to implement your own connector to make luamqtt works in your environment.\n\n# Bugs \u0026 contributing\n\nPlease [file a GitHub issue](https://github.com/xHasKx/luamqtt/issues) if you found any bug.\n\nAnd of course, any contribution are welcome!\n\n# Tests\n\nTo run tests in this git repo you need [**busted**](https://luarocks.org/modules/olivine-labs/busted):\n\n```sh\nbusted -e 'package.path=\"./?/init.lua;./?.lua;\"..package.path' tests/spec/*.lua\n```\n\nThere is a script to run all tests for all supported lua versions, using [hererocks](https://github.com/mpeterv/hererocks):\n\n```sh\n./tests/run-for-all-lua-versions.sh\n```\n\n# Code coverage\n\nCode coverage may be collected using [luacov](https://keplerproject.github.io/luacov/).\n\nTo collect code coverage stats - install luacov using luarocks and then execute:\n\n```sh\n# collect stats during tests\nbusted -v -e 'package.path=\"./?/init.lua;./?.lua;\"..package.path;require(\"luacov.runner\")(\".luacov\")' tests/spec/*.lua\n\n# generate report into luacov.report.out file\nluacov\n```\n\n# MQTT version\n\nCurrently supported is:\n\n* [MQTT v3.1.1 protocol](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html) version.\n* [MQTT v5.0 protocol](http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) version.\n\nBoth protocols has full control packets support.\n\n# LICENSE\n\nStandard MIT License, see LICENSE file for full text\n\n# Version bump checklist\n\n* in file `./mqtt/const.lua`: change `_VERSION` table field\n* in file `./openwrt/make-package-without-openwrt-sources.sh`: change `Version: X.Y.Z-P` in $PKG_ROOT/control\n* in file `./openwrt/Makefile`: change `PKG_VERSION:=X.Y.Z` and maybe `PKG_RELEASE:=1`\n* copy file `./luamqtt-scm-1.rockspec` to `./rockspecs/luamqtt-X.Y.Z-1.rockspec` change `local package_version = \"scm\"`, `local package_version = \"X.Y.Z\"`\n* run `./tests/run-luacheck.sh` and check output for errors\n* run `./tests/run-markdownlint.sh` and check output for errors\n* run `./tests/run-for-all-lua-versions.sh` and check output for errors\n* run `./openwrt/make-package-without-openwrt-sources.sh` and check output for errors\n* run `git commit`, `git tag vX.Y.Z`\n* run `git push`, `git push --tags`\n* upload to LuaRocks; `luarocks upload ./rockspecs/luamqtt-X.Y.Z-1.rockspec --api-key=ABCDEFGH`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxhaskx%2Fluamqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxhaskx%2Fluamqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxhaskx%2Fluamqtt/lists"}