nodemcu-firmware/docs/en/modules/mqtt.md

MQTT Module

The client adheres to version 3.1.1 of the MQTT protocol. Make sure that your broker supports and is correctly configured for version 3.1.1. The client is backwards incompatible with brokers running MQTT 3.1.

mqtt.Client()

Creates a MQTT client.

Syntax

mqtt.Client(clientid, keepalive, username, password, [cleansession])

Parameters

• clientid client ID
• keepalive keepalive seconds
• username user name
• password user password
• cleansession 0/1 for false/true

Returns

MQTT client

Example

-- init mqtt client with keepalive timer 120sec
m = mqtt.Client("clientid", 120, "user", "password")

-- setup Last Will and Testament (optional)
-- Broker will publish a message with qos = 0, retain = 0, data = "offline" 
-- to topic "/lwt" if client don't send keepalive packet
m:lwt("/lwt", "offline", 0, 0)

m:on("connect", function(client) print ("connected") end)
m:on("offline", function(client) print ("offline") end)

-- on publish message receive event
m:on("message", function(client, topic, data) 
  print(topic .. ":" ) 
  if data ~= nil then
    print(data)
  end
end)

-- for TLS: m:connect("192.168.11.118", secure-port, 1)
m:connect("192.168.11.118", 1880, 0, function(client) print("connected") end)

-- Calling subscribe/publish only makes sense once the connection
-- was successfully established. In a real-world application you want
-- move those into the 'connect' callback or make otherwise sure the 
-- connection was established.

-- subscribe topic with qos = 0
m:subscribe("/topic",0, function(client) print("subscribe success") end)
-- publish a message with data = hello, QoS = 0, retain = 0
m:publish("/topic","hello",0,0, function(client) print("sent") end)

m:close();
-- you can call m:connect again

MQTT Client

mqtt.client:close()

Closes connection to the broker.

Syntax

mqtt:close()

Parameters

none

Returns

nil

mqtt.client:connect()

Connects to the broker specified by the given host, port, and secure options.

Syntax

mqtt:connect(host, port, secure, function(client))

Parameters

• host host, domain or IP (string)
• port broker port (number)
• secure 0/1 for false/true, default 0. As per #539 secure connections use TLS 1.2.
• function(client) call back function for when the connection was established

Returns

nil

mqtt.client:lwt()

Setup Last Will and Testament (optional). A broker will publish a message with qos = 0, retain = 0, data = "offline" to topic "/lwt" if client does not send keepalive packet.

Syntax

mqtt:lwt(topic, message, qos, retain)

Parameters

• topic the topic to publish to (string)
• message the message to publish, (buffer or string)
• qos QoS level, default 0
• retain retain flag, default 0

Returns

nil

mqtt.client:on()

Registers a callback function for an event.

Syntax

mqtt:on(event, function(client, [topic], [message]))

Parameters

• event can be "connect", "message" or "offline"
• function(client, [topic], [message]) callback function. The first parameter is the client. If event is "message", the 2nd and 3rd param are received topic and message (strings).

Returns

nil

mqtt.client:publish()

Publishes a message.

Syntax

mqtt:publish(topic, payload, qos, retain, function(client))

Parameters

• topic the topic to publish to (topic string)
• message the message to publish, (buffer or string)
• qos QoS level, default 0
• retain retain flag, default 0
• function(client) callback fired when PUBACK received

Returns

nil

mqtt.client:subscribe()

Subscribes to one or several topics.

Syntax

mqtt:subscribe(topic, qos, function(client, topic, message))

Parameters

• topic a topic string
• qos QoS subscription level, default 0
• function(client, topic, message) callback fired when message received

Returns

nil