This project is part of the Aiko Platform
- Introduction
- Protocol implementation and restrictions
- Download
- Feedback and issues
- Installation
- Usage
- Example code
- Library API
- Known problems
MQTT stands for "Message Queue Telemetry Transport", a protocol authored by Dr. Andy Stanford-Clark and Arlen Nipper. The protocol is a message-based, publish/subscribe transport layer, which is optimized for simple telemetry applications running on small micro-controllers, such as an Arduino, over low-bandwidth connections. MQTT libraries exist for most popular programming languages, so you can utilize MQTT on whatever server or device that you require.
The Lua MQTT client library implements the client-side subset of the MQTT protocol specification 3.1.
A good use-case for this library is running on constrained systems, such as OpenWRT, and acting as a gateway between non-MQTT clients and MQTT servers. The Aiko Platform uses this approach for aggregating non-TCP/IP devices and forwarding messages onto TCP/IP networks. An advantage of using Lua is that only a text editor is required for rapid development of simple MQTT client applications on platforms such as OpenWRT. In constrast, working with the C programming language would comparatively require more effort, due to requiring a cross-platform development environment.
The Lua MQTT client library also runs (unmodified) on a Sony PlayStation Portable using the Lua Player HM (which requires your PSP to be able to run unsigned executables).
You can also install the Lua MQTT client library as part of the Aiko Platform run-time environment
Prerequisites ...
- Install Mosquitto MQTT server or any other MQTT server
- Install Lua programming language
- Install LuaRocks package manager
- Install LuaSocket
- Install PenLight
On Linux, Lua and LuaRocks can be installed via your Linux distribution package manager. On Mac OS X, Lua and LuaRocks can be installed viarDarwin ports. After that, LuaSocket and PenLight can be installed via LuaRocks.
Lua MQTT client library as a LuaRock ...
- luarocks --from=server install mqtt
Lua MQTT client library (source code) from GitHub ...
- TODO
This command periodically publishes a message on topic "test/1" and subscribes to the topic "test/2". The command exits when the message "quit" is published on topic "test/2".
cd $(LUA_MQTT_LIB) // where Lua MQTT library is installed
example/mqtt_test -d localhost // Assume MQTT server is on "localhost"
-d,--debug Verbose console logging
-i,--id (default MQTT test) MQTT client identifier
-p,--port (default 1883) MQTT server port number
<host> (default localhost) MQTT server hostname
This command publishes a single message and then exits.
example/mqtt_publish -d -t test/1 -m "Test message"
Only the --topic and --message parameters are required.
-d,--debug Verbose console logging
-H,--host (default localhost) MQTT server hostname
-i,--id (default MQTT client) MQTT client identifier
-m,--message (string) Message to be published
-p,--port (default 1883) MQTT server port number
-t,--topic (string) Topic on which to publish
-w,--will_message Last will and testament message
-w,--will_qos (default 0) Last will and testament QOS
-w,--will_retain (default 0) Last will and testament retention
-w,--will_topic Last will and testament topic
This command subscribes to a topic and listens indefinitely for messages. Use ^C (or similar) to stop execution.
example/mqtt_subscribe -d -t test/1
Only the --topic parameter is required.
-d,--debug Verbose console logging
-H,--host (default localhost) MQTT server hostname
-i,--id (default MQTT client) MQTT client identifier
-k,--keepalive (default 60) Send MQTT PING period (seconds)
-p,--port (default 1883) MQTT server port number
-t,--topic (string) Subscription topic
-w,--will_message Last will and testament message
-w,--will_qos (default 0) Last will and testament QOS
-w,--will_retain (default 0) Last will and testament retention
-w,--will_topic Last will and testament topic
-- Define a function which is called by mqtt_client:handler(),
-- whenever messages are received on the subscribed topics
function callback(topic, message)
print("Received: " .. topic .. ": " .. message)
if (message == "quit") then running = false end
end
-- Create an MQTT client instance, connect to the MQTT server and
-- subscribe to the topic called "test/2"
MQTT = require("mqtt_library")
MQTT.Utility.set_debug(true)
mqtt_client = MQTT.client.create("localhost", nil, callback)
mqtt_client:connect("lua mqtt client"))
mqtt_client:subscribe({"test/2"})
-- Continously invoke mqtt_client:handler() to process the MQTT protocol and
-- handle any received messages. Also, publish a message on topic "test/1"
running = true
while (running) do
mqtt_client:handler()
mqtt_client:publish("test/1", "test message")
socket.sleep(1.0) -- seconds
end
-- Clean-up by unsubscribing from the topic and closing the MQTT connection
mqtt_client:unsubscribe({"test/2"})
mqtt_client:destroy()
There are also a number of Lua MQTT client examples in the example/ directory. They can be run from the lua/ parent directory, as follow ...
cd mqtt_client/lua
example/example_00.lua
Use the Lua require statement to load the MQTT client library ...
MQTT = require("mqtt_library")
The following statement enables debug console logging for diagnosis.
MQTT.Utility.set_debug(true)
Create an MQTT client that will be connected to the specified host.
mqtt_client = MQTT.client.create(hostname, port, callback)
The hostname must be provided, but both the port and callback function parameters are optional. This function returns an MQTT client instance that must be used for all subsequent MQTT operations for that server connection.
hostname string: Host name or address of the MQTT broker
port integer: Port number of the MQTT broker (default: 1883)
callback function: Invoked when subscribed topic messages received
The callback function is defined as follows ...
function callback(topic, payload)
-- application specific code
end
topic -- string: Topic for the received message
payload -- string: Message data
When finished with a server connection, this statement cleans-up all resources allocated by the client.
mqtt_client:destroy()
Before messages can be transmitted, the MQTT client must connect to the server.
mqtt_client:connect(identifier)
Each individual client connection must use a unique identifier. Only the identifier parameter is required, the remaining parameters are optional.
mqtt_client:connect(identifier, will_topic, will_qos, will_retain, will_message)
MQTT also provides a "last will and testament" for clients, which is a message automatically sent by the server on behalf of the client, should the connection fail.
identifier -- string: MQTT client identifier (maximum 23 characters)
will_topic -- string: Last will and testament topic
will_qos -- byte: Last will and testament Quality Of Service
will_retain -- byte: Last will and testament retention status
will_message -- string: Last will and testament message
Transmit an MQTT disconnect message to the server.
mqtt_client:disconnect()
Transmit a message on a specified topic.
mqtt_client:publish(topic, payload)
topic -- string: Topic for the published message
payload -- string: Message data
Subscribe to one or more topics. Whenever a message is published to one of those topics, the callback function (defined above) will be invoked.
mqtt_client:subscribe(topics)
topics -- table of strings, e.g. { "topic1", "topic2" }
The handler() function must be called periodically to service incoming messages and to ensure that keep-alive messages (PING) are being sent when required.
The default KEEP_ALIVE_TIME is 60 seconds, therefore handler() must be invoked more often than once per minute.
Should any messages be received on the subscribed topics, then handler() will invoke the callback function (defined above).
mqtt_client:handler()
Unsubscribe from one or more topics, so that messages published to those topics are no longer received.
topics -- table of strings, e.g. { "topic1", "topic2" }
- Not really a problem, but if you find that the MQTT socket connection is being closed for no apparent reason, particularly for subscribers ... then check that all MQTT clients are using a unique client identifier.