MQTT ( http://mqtt.org/ ) client library for Lua. MQTT is a popular network communication protocol working by "publish/subscribe" model.
This library is written in pure-lua to provide maximum portability.
- Full MQTT v3.1.1 client-side support
- Full MQTT v5.0 client-side support
- Several long-living MQTT clients in one script thanks to ioloop
See https://xhaskx.github.io/luamqtt/
https://github.com/xHasKx/luamqtt
The only main dependency is a luasocket to establishing TCP connection to the MQTT broker.
On Lua 5.1 and Lua 5.2 it also depends on LuaBitOp (bit) library to perform bitwise operations. It's not listed in package dependencies, please install it manually like this:
luarocks install luabitop
To establish secure network connection (SSL/TSL) to MQTT broker you also need luasec module, please install it manually like this:
luarocks install luasec
This 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).
It's tested to work on Debian 9 GNU/Linux with Lua versions:
- Lua 5.1 ... Lua 5.3 (i.e. any modern Lua version)
- LuaJIT 2.0.0 ... LuaJIT 2.1.0 beta3
- It may also work on other Lua versions without any guarantees
Also I've successfully run it under Windows and it was ok, but installing luarock-modules may be a non-trivial task on this OS.
luarocks install luamqtt
Here is a short version of examples/simple.lua
:
-- load mqtt library
local mqtt = require("mqtt")
-- create MQTT client
local client = mqtt.client{ uri = "test.mosquitto.org", clean = true }
-- assign MQTT client event handlers
client:on{
connect = function(connack)
if connack.rc ~= 0 then
print("connection to broker failed:", connack)
return
end
-- connection established, now subscribe to test topic and publish a message after
assert(client:subscribe{ topic="luamqtt/#", qos=1, callback=function()
assert(client:publish{ topic = "luamqtt/simpletest", payload = "hello" })
end})
end,
message = function(msg)
assert(client:acknowledge(msg))
-- receive one message and disconnect
print("received message", msg)
client:disconnect()
end,
}
-- run ioloop for client
mqtt.run_ioloop(client)
More examples placed in examples/
directory. Also checkout tests in tests/spec/mqtt-client.lua
Also you can learn MQTT protocol by reading tests/spec/protocol-make.lua
and tests/spec/protocol-parse.lua
tests
Connector is a network connection layer for luamqtt. There is a three standard connectors included:
luasocket
luasocket_ssl
ngxsocket
- for using in openresty environment
The luasocket
or luasocket_ssl
connector will be used by default, if not specified, according secure=true/false
option per MQTT client.
In simple terms, connector is a set of functions to establish a network stream (TCP connection usually) and send/receive data through it. Every MQTT client instance may have their own connector.
And it's very simple to implement your own connector to make luamqtt works in your environment.
Please file a GitHub issue if you found any bug.
And of course, any contribution are welcome!
To run tests in this git repo you need busted:
busted -e 'package.path="./?/init.lua;./?.lua;"..package.path' tests/spec/*.lua
There is a script to run all tests for all supported lua versions, using hererocks:
./tests/run-for-all-lua-versions.sh
Code coverage may be collected using luacov.
To collect code coverage stats - install luacov using luarocks and then execute:
# collect stats during tests
busted -v -e 'package.path="./?/init.lua;./?.lua;"..package.path;require("luacov.runner")(".luacov")' tests/spec/*.lua
# generate report into luacov.report.out file
luacov
Currently supported is:
- MQTT v3.1.1 protocol version.
- MQTT v5.0 protocol version.
Both protocols has full control packets support.
- more examples
- check some packet sequences are right
- coroutines and other asyncronous approaches based on some event loop
- [DONE] more permissive args for some methods
- [DONE] several clients in one process
- [DONE] MQTT 5.0
Standard MIT License, see LICENSE file for full text