Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xHasKx/luamqtt
luamqtt - Pure-lua MQTT v3.1.1 and v5.0 client
https://github.com/xHasKx/luamqtt
internet-of-things lua lua-versions luajit luarocks luasec mqtt mqtt-client mqtt-protocol mqtt5 protocol smarthome ssl tcp-connection
Last synced: 2 months ago
JSON representation
luamqtt - Pure-lua MQTT v3.1.1 and v5.0 client
- Host: GitHub
- URL: https://github.com/xHasKx/luamqtt
- Owner: xHasKx
- License: mit
- Created: 2018-09-16T19:04:16.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-07-20T15:14:38.000Z (6 months ago)
- Last Synced: 2024-08-07T18:38:07.068Z (6 months ago)
- Topics: internet-of-things, lua, lua-versions, luajit, luarocks, luasec, mqtt, mqtt-client, mqtt-protocol, mqtt5, protocol, smarthome, ssl, tcp-connection
- Language: Lua
- Homepage: https://xhaskx.github.io/luamqtt/
- Size: 354 KB
- Stars: 152
- Watchers: 11
- Forks: 41
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# luamqtt - Pure-lua MQTT v3.1.1 and v5.0 client
[](https://github.com/xHasKx/luamqtt/blob/master/LICENSE)
[](https://github.com/xHasKx/luamqtt/actions/workflows/tests-and-coverage.yml)
[](https://coveralls.io/github/xHasKx/luamqtt?branch=master)
[](https://github.com/hobbyquaker/awesome-mqtt)
[](https://forthebadge.com)
MQTT ( [http://mqtt.org/](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.
# Features
* 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
# Documentation
See [https://xhaskx.github.io/luamqtt/](https://xhaskx.github.io/luamqtt/)
# Forum
See [flespi forum thread](https://forum.flespi.com/d/97-luamqtt-mqtt-client-written-in-pure-lua)
# Source Code
[https://github.com/xHasKx/luamqtt](https://github.com/xHasKx/luamqtt)
# Dependencies
The only main dependency is a [**luasocket**](https://luarocks.org/modules/luasocket/luasocket) to establishing TCP connection to the MQTT broker. Install it like this:
```sh
luarocks install luasocket
```
On Lua 5.1 it also depends on [**LuaBitOp**](http://bitop.luajit.org/) (**bit**) library to perform bitwise operations.
It's not listed in package dependencies, please install it manually like this:
```sh
luarocks install luabitop
```
## luasec (SSL/TLS)
To establish secure network connection (SSL/TSL) to MQTT broker
you also need [**luasec**](https://github.com/brunoos/luasec) module, please install it manually like this:
```sh
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).
# Lua versions
It's tested to work on Debian 9 GNU/Linux with Lua versions:
* Lua 5.1 ... Lua 5.4 (**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.
# Installation
As the luamqtt is almost zero-dependency you have to install required Lua libraries by yourself, before using the luamqtt library:
```sh
luarocks install luasocket # optional if you will use your own connectors (see below)
luarocks install luabitop # you don't need this for lua 5.3 and above
luarocks install luasec # you don't need this if you don't want to use SSL connections
```
Then you may install the luamqtt library itself:
```sh
luarocks install luamqtt
```
Or for development purposes;
```sh
# development branch:
luarocks install luamqtt --dev
# or from the cloned repo:
luarocks make
```
[LuaRocks page](http://luarocks.org/modules/xhaskx/luamqtt)
# Examples
Here is a short version of [`examples/simple.lua`](examples/simple.lua):
```lua
-- load mqtt library
local mqtt = require("mqtt")
-- create MQTT client, flespi tokens info: https://flespi.com/kb/tokens-access-keys-to-flespi-platform
local client = mqtt.client{ uri = "mqtt.flespi.io", username = os.getenv("FLESPI_TOKEN"), clean = true }
-- assign MQTT client event handlers
client:on{
connect = function(connack)
if connack.rc ~= 0 then
print("connection to broker failed:", connack:reason_string(), 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/`](examples/) directory. Also checkout tests in [`tests/spec/mqtt-client.lua`](tests/spec/mqtt-client.lua)
Also 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
# Connectors
Connector is a network connection layer for luamqtt. There is a three standard connectors included:
* [`luasocket`](mqtt/luasocket.lua)
* [`luasocket_ssl`](mqtt/luasocket_ssl.lua)
* [`ngxsocket`](mqtt/ngxsocket.lua) - for using in [openresty environment](examples/openresty)
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.
# Bugs & contributing
Please [file a GitHub issue](https://github.com/xHasKx/luamqtt/issues) if you found any bug.
And of course, any contribution are welcome!
# Tests
To run tests in this git repo you need [**busted**](https://luarocks.org/modules/olivine-labs/busted):
```sh
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](https://github.com/mpeterv/hererocks):
```sh
./tests/run-for-all-lua-versions.sh
```
# Code coverage
Code coverage may be collected using [luacov](https://keplerproject.github.io/luacov/).
To collect code coverage stats - install luacov using luarocks and then execute:
```sh
# 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
```
# MQTT version
Currently supported is:
* [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.
* [MQTT v5.0 protocol](http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) version.
Both protocols has full control packets support.
# LICENSE
Standard MIT License, see LICENSE file for full text
# Version bump checklist
* in file `./mqtt/const.lua`: change `_VERSION` table field
* in file `./openwrt/make-package-without-openwrt-sources.sh`: change `Version: X.Y.Z-P` in $PKG_ROOT/control
* in file `./openwrt/Makefile`: change `PKG_VERSION:=X.Y.Z` and maybe `PKG_RELEASE:=1`
* 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"`
* run `./tests/run-luacheck.sh` and check output for errors
* run `./tests/run-markdownlint.sh` and check output for errors
* run `./tests/run-for-all-lua-versions.sh` and check output for errors
* run `./openwrt/make-package-without-openwrt-sources.sh` and check output for errors
* run `git commit`, `git tag vX.Y.Z`
* run `git push`, `git push --tags`
* upload to LuaRocks; `luarocks upload ./rockspecs/luamqtt-X.Y.Z-1.rockspec --api-key=ABCDEFGH`