Module mqtt.client
MQTT client module
| client_mt:__init (args) |
Create and initialize MQTT client instance |
| client_mt:on (...) |
Add functions as handlers of given events |
| client_mt:off (event, func) |
Remove given function handler for specified event |
| client_mt:subscribe (args) |
Subscribe to specified topic. |
| client_mt:unsubscribe (args) |
Unsubscribe from specified topic, and calls optional callback when subscription will be removed on broker |
| client_mt:publish (args) |
Publish message to broker |
| client_mt:acknowledge (msg[, rc=0[, properties[, user_properties]]]) |
Acknowledge given received message |
| client_mt:disconnect ([rc=0[, properties[, user_properties]]]) |
Send DISCONNECT packet to the broker and close the connection |
| client_mt:auth ([rc=0[, properties[, user_properties]]]) |
Send AUTH packet to authenticate client on broker, in MQTT v5.0 protocol |
| client_mt:close_connection ([reason]) |
Immediately close established network connection, without graceful session finishing with DISCONNECT packet |
| client_mt:start_connecting () |
Start connecting to broker |
| create (...) |
Create, initialize and return new MQTT client instance |
MQTT client instance metatable
-
client_mt:__init (args)
-
Create and initialize MQTT client instance
Parameters:
- args MQTT client creation arguments table
- uri
string
MQTT broker uri to connect.
Expecting "host:port" or "host" format, in second case the port will be selected automatically:
1883 port for plain or 8883 for secure network connections
- clean
string
clean session start flag
- version
number
MQTT protocol version to use, either 4 (for MQTT v3.1.1) or 5 (for MQTT v5.0).
Also you may use special values mqtt.v311 or mqtt.v50 for this field.
(default 4)
- id
string
MQTT client ID, will be generated by luamqtt library if absent
(optional)
- username
string
username for authorization on MQTT broker
(optional)
- password
string
password for authorization on MQTT broker; not acceptable in absence of username
(optional)
- secure
boolean,table
use secure network connection, provided by luasec lua module;
set to true to select default params: { mode="client", protocol="tlsv1_2", verify="none", options="all" }
or set to luasec-compatible table, for example with cafile="...", certificate="...", key="..."
(default false)
- will
table
will message table with required fields { topic="...", payload="..." }
and optional fields { qos=1...3, retain=true/false }
(optional)
- keep_alive
number
time interval for client to send PINGREQ packets to the server when network connection is inactive
(default 60)
- reconnect
boolean
force created MQTT client to reconnect on connection close.
Set to number value to provide reconnect timeout in seconds
It's not recommended to use values < 3
(default false)
- connector
table
connector table to open and send/receive packets over network connection.
default is require("mqtt.luasocket"), or require("mqtt.luasocket_ssl") if secure argument is set
(optional)
- ssl_module
string
module name for the luasec-compatible ssl module, default is "ssl"
may be used in some non-standard lua environments with own luasec-compatible ssl module
(default "ssl")
Returns:
client_mt
MQTT client instance table
-
client_mt:on (...)
-
Add functions as handlers of given events
Parameters:
- ...
(event_name, function) or { event1 = func1, event2 = func2 } table
-
client_mt:off (event, func)
-
Remove given function handler for specified event
Parameters:
- event
string
event name to remove handler
- func
function
handler function to remove
-
client_mt:subscribe (args)
-
Subscribe to specified topic. Returns the SUBSCRIBE packet id and calls optional callback when subscription will be created on broker
Parameters:
- args subscription arguments
- topic
string
topic to subscribe
- qos
number
QoS level for subscription
(default 0)
- no_local
boolean
for MQTT v5.0 only: no_local flag for subscription
- retain_as_published
boolean
for MQTT v5.0 only: retain_as_published flag for subscription
- retain_handling
boolean
for MQTT v5.0 only: retain_handling flag for subscription
- properties
table
for MQTT v5.0 only: properties for subscribe operation
(optional)
- user_properties
table
for MQTT v5.0 only: user properties for subscribe operation
(optional)
- callback
function
callback function to be called when subscription will be created
(optional)
Returns:
packet id on success or false and error message on failure
-
client_mt:unsubscribe (args)
-
Unsubscribe from specified topic, and calls optional callback when subscription will be removed on broker
Parameters:
- args subscription arguments
- topic
string
topic to unsubscribe
- properties
table
properties for unsubscribe operation
(optional)
- user_properties
table
user properties for unsubscribe operation
(optional)
- callback
function
callback function to be called when subscription will be removed on broker
(optional)
Returns:
packet id on success or false and error message on failure
-
client_mt:publish (args)
-
Publish message to broker
Parameters:
- args publish operation arguments table
- topic
string
topic to publish message
- payload
string
publish message payload
(optional)
- qos
number
QoS level for message publication
(default 0)
- retain
boolean
retain message publication flag
(default false)
- dup
boolean
dup message publication flag
(default false)
- properties
table
properties for publishing message
(optional)
- user_properties
table
user properties for publishing message
(optional)
- callback
function
callback to call when published message will be acknowledged
(optional)
Returns:
true or packet id on success or false and error message on failure
-
client_mt:acknowledge (msg[, rc=0[, properties[, user_properties]]])
-
Acknowledge given received message
Parameters:
- msg
packet_mt
PUBLISH message to acknowledge
- rc
number
The reason code field of PUBACK packet in MQTT v5.0 protocol
(default 0)
- properties
table
properties for PUBACK/PUBREC packets
(optional)
- user_properties
table
user properties for PUBACK/PUBREC packets
(optional)
Returns:
true on success or false and error message on failure
-
client_mt:disconnect ([rc=0[, properties[, user_properties]]])
-
Send DISCONNECT packet to the broker and close the connection
Parameters:
- rc
number
The Disconnect Reason Code value from MQTT v5.0 protocol
(default 0)
- properties
table
properties for PUBACK/PUBREC packets
(optional)
- user_properties
table
user properties for PUBACK/PUBREC packets
(optional)
Returns:
true on success or false and error message on failure
-
client_mt:auth ([rc=0[, properties[, user_properties]]])
-
Send AUTH packet to authenticate client on broker, in MQTT v5.0 protocol
Parameters:
- rc
number
Authenticate Reason Code
(default 0)
- properties
table
properties for PUBACK/PUBREC packets
(optional)
- user_properties
table
user properties for PUBACK/PUBREC packets
(optional)
Returns:
true on success or false and error message on failure
-
client_mt:close_connection ([reason])
-
Immediately close established network connection, without graceful session finishing with DISCONNECT packet
Parameters:
- reason
string
the reasong string of connection close
(optional)
-
client_mt:start_connecting ()
-
Start connecting to broker
Returns:
true on success or false and error message on failure
-
client_mt:send_pingreq ()
-
Send PINGREQ packet
Returns:
true on success or false and error message on failure
-
client_mt:open_connection ()
-
Open network connection to the broker
Returns:
true on success or false and error message on failure
-
client_mt:send_connect ()
-
Send CONNECT packet into opened network connection
Returns:
true on success or false and error message on failure
-
create (...)
-
Create, initialize and return new MQTT client instance
Parameters:
- ...
see arguments of client_mt:__init(args)
Returns:
client_mt
MQTT client instance
See also: