Contribution from Benjamin to make Paho Lua client Koneki-friendly
Closes #399019
diff --git a/.buildpath b/.buildpath
new file mode 100644
index 0000000..986b443
--- /dev/null
+++ b/.buildpath
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<buildpath>
+ <buildpathentry kind="src" path="lua"/>
+ <buildpathentry kind="con" path="org.eclipse.koneki.ldt.ExecutionEnvironmentContainer/lua/5.1"/>
+</buildpath>
diff --git a/.project b/.project
new file mode 100644
index 0000000..05ffabf
--- /dev/null
+++ b/.project
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>org.eclipse.paho.mqtt.lua</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ <buildCommand>
+ <name>org.eclipse.dltk.core.scriptbuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ </buildSpec>
+ <natures>
+ <nature>org.eclipse.koneki.ldt.nature</nature>
+ </natures>
+</projectDescription>
diff --git a/lua/example/example_00.lua b/lua/example/example_00.lua
index 3c2286c..1c7445b 100755
--- a/lua/example/example_00.lua
+++ b/lua/example/example_00.lua
@@ -61,7 +61,7 @@
local MQTT = require("mqtt_library")
-mqtt_client = MQTT.client.create(args.host, args.port, callback)
+local mqtt_client = MQTT.client.create(args.host, args.port, callback)
mqtt_client:connect(args.id)
diff --git a/lua/example/example_01.lua b/lua/example/example_01.lua
index 9b8bfdd..d949f34 100755
--- a/lua/example/example_01.lua
+++ b/lua/example/example_01.lua
@@ -57,8 +57,8 @@
local MQTT = require("mqtt_library")
-mqtt_client1 = MQTT.client.create(args.host_s, args.port_s, callback)
-mqtt_client2 = MQTT.client.create(args.host_p, args.port_p)
+local mqtt_client1 = MQTT.client.create(args.host_s, args.port_s, callback)
+local mqtt_client2 = MQTT.client.create(args.host_p, args.port_p)
mqtt_client1:connect(args.id .. "a")
mqtt_client2:connect(args.id .. "b")
diff --git a/lua/mqtt_library.lua b/lua/mqtt_library.lua
index 1f53c2e..718bbe7 100644
--- a/lua/mqtt_library.lua
+++ b/lua/mqtt_library.lua
@@ -1,4 +1,5 @@
--- mqtt_library.lua
+---
+-- @module mqtt_library
-- ~~~~~~~~~~~~~~~~
-- Version: 0.2 2012-06-01
-- -------------------------------------------------------------------------- --
@@ -80,23 +81,56 @@
local MQTT = {}
+---
+-- @field [parent = #mqtt_library] utility#utility Utility
+--
MQTT.Utility = require("utility")
+---
+-- @field [parent = #mqtt_library] #number VERSION
+--
MQTT.VERSION = 0x03
+---
+-- @field [parent = #mqtt_library] #boolean ERROR_TERMINATE
+--
MQTT.ERROR_TERMINATE = false -- Message handler errors terminate process ?
-MQTT.DEFAULT_BROKER_HOSTNAME = "localhost"
+---
+-- @field [parent = #mqtt_library] #string DEFAULT_BROKER_HOSTNAME
+--
+MQTT.DEFAULT_BROKER_HOSTNAME = "test.mosquitto.org"
+---
+-- An MQTT client
+-- @type client
+
+---
+-- @field [parent = #mqtt_library] #client client
+--
MQTT.client = {}
MQTT.client.__index = MQTT.client
+---
+-- @field [parent = #client] #number DEFAULT_PORT
+--
MQTT.client.DEFAULT_PORT = 1883
-MQTT.client.KEEP_ALIVE_TIME = 60 -- seconds (maximum is 65535)
+
+---
+-- @field [parent = #client] #number KEEP_ALIVE_TIME
+--
+MQTT.client.KEEP_ALIVE_TIME = 60 -- seconds (maximum is 65535)
+
+---
+-- @field [parent = #client] #number MAX_PAYLOAD_LENGTH
+--
MQTT.client.MAX_PAYLOAD_LENGTH = 268435455 -- bytes
-- MQTT 3.1 Specification: Section 2.1: Fixed header, Message type
+---
+-- @field [parent = #mqtt_library] message
+--
MQTT.message = {}
MQTT.message.TYPE_RESERVED = 0x00
MQTT.message.TYPE_CONNECT = 0x01
@@ -132,6 +166,14 @@
-- Create an MQTT client instance
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---
+-- Create an MQTT client instance.
+-- @param #string hostname Host name or address of the MQTT broker
+-- @param #number port Port number of the MQTT broker (default: 1883)
+-- @param #function callback Invoked when subscribed topic messages received
+-- @function [parent = #client] create
+-- @return #client created client
+--
function MQTT.client.create( -- Public API
hostname, -- string: Host name or address of the MQTT broker
port, -- integer: Port number of the MQTT broker (default: 1883)
@@ -156,11 +198,17 @@
return(mqtt_client)
end
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
--- Transmit MQTT Client request a connection to an MQTT broker (server)
--- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
+-- Transmit MQTT Client request a connection to an MQTT broker (server).
-- MQTT 3.1 Specification: Section 3.1: CONNECT
-
+-- @param self
+-- @param #string identifier MQTT client identifier (maximum 23 characters)
+-- @param #string will_topic Last will and testament topic
+-- @param #string will_qos Last will and testament Quality Of Service
+-- @param #string will_retain Last will and testament retention status
+-- @param #string will_message Last will and testament message
+-- @function [parent = #client] connect
+--
function MQTT.client:connect( -- Public API
identifier, -- string: MQTT client identifier (maximum 23 characters)
will_topic, -- string: Last will and testament topic
@@ -231,10 +279,11 @@
return(self:message_write(MQTT.message.TYPE_CONNECT, payload))
end
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
--- Destroy an MQTT client instance
--- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
+-- Destroy an MQTT client instance.
+-- @param self
+-- @function [parent = #client] destroy
+--
function MQTT.client:destroy() -- Public API
MQTT.Utility.debug("MQTT.client:destroy()")
@@ -248,13 +297,13 @@
end
end
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
--- Transmit MQTT Disconnect message
--- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
+-- Transmit MQTT Disconnect message.
-- MQTT 3.1 Specification: Section 3.14: Disconnect notification
---
-- bytes 1,2: Fixed message header, see MQTT.client:message_write()
-
+-- @param self
+-- @function [parent = #client] disconnect
+--
function MQTT.client:disconnect() -- Public API
MQTT.Utility.debug("MQTT.client:disconnect()")
@@ -287,13 +336,14 @@
return(output)
end
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
--- Handle received messages and maintain keep-alive PING messages
--- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
+-- Handle received messages and maintain keep-alive PING messages.
-- This function must be invoked periodically (more often than the
--- MQTT.client.KEEP_ALIVE_TIME) which maintains the connection and
--- services the incoming subscribed topic messages.
-
+-- `MQTT.client.KEEP_ALIVE_TIME`) which maintains the connection and
+-- services the incoming subscribed topic messages
+-- @param self
+-- @function [parent = #client] handler
+--
function MQTT.client:handler() -- Public API
if (self.connected == false) then
error("MQTT.client:handler(): Not connected")
@@ -679,16 +729,19 @@
self:message_write(MQTT.message.TYPE_PINGRESP, nil)
end
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
--- Transmit MQTT Publish message
--- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
+-- Transmit MQTT Publish message.
-- MQTT 3.1 Specification: Section 3.3: Publish message
--
--- bytes 1,2: Fixed message header, see MQTT.client:message_write()
--- Variable header ..
--- bytes 3- : Topic name and optional Message Identifier (if QOS > 0)
--- bytes m- : Payload
-
+-- * bytes 1,2: Fixed message header, see MQTT.client:message_write()
+-- Variable header ..
+-- * bytes 3- : Topic name and optional Message Identifier (if QOS > 0)
+-- * bytes m- : Payload
+-- @param self
+-- @param #string topic
+-- @param #string payload
+-- @function [parent = #client] publish
+--
function MQTT.client:publish( -- Public API
topic, -- string
payload) -- string
@@ -704,16 +757,18 @@
self:message_write(MQTT.message.TYPE_PUBLISH, message)
end
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
--- Transmit MQTT Subscribe message
--- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
+-- Transmit MQTT Subscribe message.
-- MQTT 3.1 Specification: Section 3.8: Subscribe to named topics
--
--- bytes 1,2: Fixed message header, see MQTT.client:message_write()
--- Variable header ..
--- bytes 3,4: Message Identifier
--- bytes 5- : List of topic names and their QOS level
-
+-- * bytes 1,2: Fixed message header, see MQTT.client:message_write()
+-- Variable header ..
+-- * bytes 3,4: Message Identifier
+-- * bytes 5- : List of topic names and their QOS level
+-- @param self
+-- @param #string topics table of strings
+-- @function [parent = #client] subscribe
+--
function MQTT.client:subscribe( -- Public API
topics) -- table of strings
@@ -738,17 +793,18 @@
self.outstanding[self.message_id] = { "subscribe", topics }
end
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
+--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
-- Transmit MQTT Unsubscribe message
--- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- MQTT 3.1 Specification: Section 3.10: Unsubscribe from named topics
--
--- bytes 1,2: Fixed message header, see MQTT.client:message_write()
--- Variable header ..
--- bytes 3,4: Message Identifier
--- bytes 5- : List of topic names
-
-
+-- * bytes 1,2: Fixed message header, see MQTT.client:message_write()
+-- Variable header ..
+-- * bytes 3,4: Message Identifier
+-- * bytes 5- : List of topic names
+-- @param self
+-- @param #string topics table of strings
+-- @function [parent = #client] unsubscribe
+--
function MQTT.client:unsubscribe( -- Public API
topics) -- table of strings
diff --git a/lua/utility.lua b/lua/utility.lua
index 385cb5a..b2f11af 100644
--- a/lua/utility.lua
+++ b/lua/utility.lua
@@ -1,4 +1,5 @@
--- utility.lua
+---
+-- @module Utility
-- ~~~~~~~~~~~
-- Version: 0.2 2012-06-01
-- -------------------------------------------------------------------------- --
@@ -150,17 +151,87 @@
local Utility = {}
+---
+-- @function [parent = #utility] isPsp
+--
Utility.isPsp = isPsp
+
+---
+-- @param #boolean flag
+-- @function [parent = #utility] set_debug
+--
Utility.set_debug = set_debug
+
+---
+-- @param #string message
+-- @function [parent = #utility] debug
+--
Utility.debug = debug
+
+---
+-- @param #string value
+-- @function [parent = #utility] dump_string
+--
+
Utility.dump_string = dump_string
+
+---
+-- @function [parent = #utility] get_time
+-- @return #number
+--
Utility.get_time = get_time
+
+---
+-- @param #number last_time
+-- @param #number duration
+-- @param #string type
+-- @function [parent = #utility] expired
+-- @return #number
+--
Utility.expired = expired
+
+---
+-- @param #number value
+-- @param #number shift
+-- @function [parent = #utility] shift_left
+-- @return #number
+--
Utility.shift_left = shift_left
+
+---
+-- @param #number value
+-- @param #number shift
+-- @function [parent = #utility] shift_left
+-- @return #number
+--
Utility.shift_right = shift_right
+
+---
+-- @param socket_client
+-- @function [parent = #utility] socket_ready
+-- @return #boolean
+--
Utility.socket_ready = socket_ready
+
+---
+-- @param socket_client
+-- @param #number byte_count
+-- @function [parent = #utility] socket_receive
+-- @return #string,#string
+--
Utility.socket_receive = socket_receive
+
+---
+-- @param socket_client
+-- @function [parent = #utility] socket_wait_connected
+--
Utility.socket_wait_connected = socket_wait_connected
+
+---
+-- @param #table table
+-- @function [parent = #utility] table_to_string
+-- @return #string
+--
Utility.table_to_string = table_to_string
-- For ... Utility = require("utility")
