mqtt - mqtt Client

Adapted Air780E/Air700E Air780EP Air601 Air101/Air103 Air105 ESP32C3 ESP32S3

Note

This page document is automatically generated by this file. If there is any error, please submit issue or help modify pr, thank you！

Tip

This library has its own demo,click this link to view the demo example of mqtt

Example

-- Please see the specific usage demo
-- mqtt 3.1.1 is supported by this library. other versions such as 3.1 or 5 are not supported.
-- Only pure MQTT/MQTTS communication is supported. mqtt over websocket

-- several major premises:
-- This library is based on TCP links and supports encrypted TCP and non-encrypted TCP
-- Any communication failure will disconnect. If automatic reconnect is turned on, automatic reconnect will start after an interval of N seconds.
-- Uplink data are all one-time, there is no cache mechanism, and there is no uplink retry/retransmission mechanism.
-- How to know that the sending was successful: trigger the event = = "sent" event in mqttc:on

-- Regarding the explanation of QOS value at publish, the behavior of the special module ascending to the cloud/server side:
-- QOS0, Push the underlying TCP send stack as a success
-- QOS1, Receive server response PUBACK, considered successful
-- QOS2, After receiving the server response PUBREC, the uplink PUBCOMP is immediately pushed into the TCP send queue and regarded as successful.

-- The important thing is said three times: no retransmission mechanism, no retransmission mechanism, no retransmission mechanism
-- 1. MQTT A retransmission mechanism is specified in the protocol, but that is a mechanism that will only be implemented on the cloud/server side, not on the module side.
-- 2. The only possibility of uplink failure is that there is a problem with the TCP link, and the solution to the problem with the TCP link is reconnection.
-- 3. The module side will not save any uplink data, and retransmission cannot be realized after reconnection.

-- The business needs to determine whether the uplink is successful and how to solve it.:
-- First recommend use QOS1, then monitor/judge sent events, and select a timeout period to meet 99.9 percent of the demand.
-- With QOS2, there is a theoretical possibility that the server side does not broadcast data due to PUBCOMP uplink failure.
-- demo There is a code that demonstrates waiting for the sent event, similar to sys.waitUntil("mqtt_sent", 3000) to search for mqtt_sent keywords.

Constant

constant	type	explanation
mqtt.STATE_DISCONNECT	number	mqtt Disconnect
mqtt.STATE_SCONNECT	number	mqtt socket In connection
mqtt.STATE_MQTT	number	mqtt socket Connected mqtt connection in process
mqtt.STATE_READY	number	mqtt mqtt Connected

mqttc:subscribe(topic, qos)

Subscribe to Topic

Parameters

Incoming Value Type	Explanation
string/table	Theme
int	topic 0/1/2 Default 0

Return Value

return value type	explanation
int	Message id, valid when qos is 1/2, if the bottom layer fails to return, it will return nil

Examples

-- Subscribe to a single topic, and qos=0
mqttc:subscribe("/luatos/123456", 0)
-- Subscribe to a single topic, and qos=1
mqttc:subscribe("/luatos/12345678", 1)
-- subscribe to multiple topics and use different qos
mqttc:subscribe({["/luatos/1234567"]=1,["/luatos/12345678"]=2})

---

mqttc:unsubscribe(topic)

Unsubscribe from a topic

Parameters

Incoming Value Type	Explanation
string/table	Theme

Return Value

None

Examples

mqttc:unsubscribe("/luatos/123456")
mqttc:unsubscribe({"/luatos/1234567","/luatos/12345678"})

---

mqttc:debug(onoff)

Configure whether to open debug information

Parameters

Incoming Value Type	Explanation
boolean	Whether to turn on debug switch

Return Value

return value type	explanation
nil	No return value

Examples

None

---

mqtt.create(adapter,host,port,ssl,isipv6)

mqtt Client Creation

Parameters

Incoming Value Type	Explanation
int	The adapter serial number can only be socket.ETH0, socket.STA, socket.AP. If it is not filled in, the platform’s own method will be selected, and then the last registered adapter will be selected.
string	Server address, which can be a domain name or ip
int	Port number
bool/table	Whether it is an ssl encrypted connection or not, default is no encryption, true is the simplest encryption without certificate, table is encryption with certificate server_cert server ca certificate data client_cert client certificate data client_key client private key encrypted data client_password client private key password data verify mandatory verification 0 no verification/1 optional verification/2 mandatory verification default 2
bool	ipv6 default is not

Return Value

return value type	explanation
userdata	if successful, the mqtt client instance is returned. otherwise, the mqtt client instance is returned.nil

Examples

-- Common TCP Link
mqttc = mqtt.create(nil,"120.55.137.106", 1884)
-- Encrypt TCP link without validating server certificate
mqttc = mqtt.create(nil,"120.55.137.106", 8883, true)
-- Encrypted TCPTCP link, single server certificate validation
mqttc = mqtt.create(nil,"120.55.137.106", 8883, {server_cert=io.readFile("/luadb/ca.crt")})
-- Encrypted TCPTCP link, single server certificate validation, but optional authentication
mqttc = mqtt.create(nil,"120.55.137.106", 8883, {server_cert=io.readFile("/luadb/ca.crt"), verify=1})
-- Encrypted TCPTCP link, two-way certificate verification
mqttc = mqtt.create(nil,"120.55.137.106", 8883, {
                    server_cert=io.readFile("/luadb/ca.crt"),
                    client_cert=io.readFile("/luadb/client.pem"),
                    client_key="123456",
                    client_password="123456",
                    })

---

mqttc:auth(client_id,username,password,cleanSession)

mqtt Triple configuration and cleanSession

Parameters

Incoming Value Type	Explanation
string	the device id must be unique for the same mqtt server. the same client_id will be kicked off each other.
string	Account Number Optional
string	Password optional
bool	Clear session, default true, optional

Return Value

return value type	explanation
nil	No return value

Examples

-- Login without account password, only clientId
mqttc:auth("123456789")
-- Login with account password
mqttc:auth("123456789","username","password")
-- Additional configuration cleanSession, do not clear
mqttc:auth("123456789","username","password", false)
-- no clientId mode, the server randomly generates an id, the cleanSession is not configurable
mqttc:auth()

---

mqttc:keepalive(time)

mqtt Heartbeat Settings

Parameters

Incoming Value Type	Explanation
int	Optional unit s defaults to 240s. first 15, highest 600

Return Value

return value type	explanation
nil	No return value

Examples

mqttc:keepalive(30)

---

mqttc:on(cb)

register mqtt callback

Parameters

Incoming Value Type	Explanation
function	cb mqtt callback, parameters include mqtt_client, event, data, payload

Return Value

return value type	explanation
nil	No return value

Examples

mqttc:on(function(mqtt_client, event, data, payload, metas)
    -- User-defined code
    log.info("mqtt", "event", event, mqtt_client, data, payload)
end)
--[[
event The possible values are
  conack -- the server authentication is completed, the mqtt connection has been established, and data can be subscribed and published without additional data.
  recv   -- The received data is delivered by the server, data is the topic value (string), payload is the business data (string), metas is metadata (table), generally not processed. .
             -- metas Contains the following
             -- qos Value range 0,1,2
             -- retain Value range 0,1
             -- dup Value range 0,1
  sent   -- After the sending is completed, qos0 will notify immediately, qos1/qos2 will call back in the server response, and data is a message.id
  disconnect -- The server is disconnected, network problems or the server kicks the client, such as duplicate clientId, timeout not reporting business data
]]

---

mqttc:connect()

Connection Server

Parameters

None

Return Value

return value type	explanation
boolean	Returns true if the launch is successful, otherwise false

Examples

-- Start establishing a connection
mqttc:connect()
-- this function only indicates that the mqtt is successfully initiated. you need to determine whether the mqtt connection is normal according to the ready function.

---

mqttc:disconnect()

Disconnect the server (resources are not released)

Parameters

None

Return Value

return value type	explanation
boolean	Returns true if the launch is successful, otherwise false

Examples

-- Disconnect
mqttc:disconnect()

---

mqttc:autoreconn(reconnect, reconnect_time)

Automatic reconnect

Parameters

Incoming Value Type	Explanation
bool	Auto reconnect
int	Auto reconnect cycle unit ms default 3000ms

Return Value

None

Examples

mqttc:autoreconn(true)

---

mqttc:publish(topic, data, qos, retain)

Publish message

Parameters

Incoming Value Type	Explanation
string	Subject, required
string	Message, required, but length can be 0
int	Message Level 0/1 Default 0
int	Archive, 0/1, default 0

Return Value

return value type	explanation
int	the id of the message, which is valid when qos is 1 or 2. if no is returned from the bottom layer, the value is returned.nil

Examples

mqttc:publish("/luatos/123456", "123")

---

mqttc:close()

mqtt Client shutdown (resources released after shutdown can no longer be used)

Parameters

None

Return Value

None

Examples

mqttc:close()

---

mqttc:ready()

mqtt Whether the client is ready

Parameters

None

Return Value

return value type	explanation
bool	Whether the client is ready

Examples

local error = mqttc:ready()

---

mqttc:state()

mqtt Client Status

Parameters

None

Return Value

return value type	explanation
number	Client Status

Examples

local state = mqttc:state()
-- Known Status:
-- 0: MQTT_STATE_DISCONNECT
-- 1: MQTT_STATE_CONNECTING
-- 2: MQTT_STATE_CONNECTED
-- 3: MQTT_STATE_READY
-- 4: MQTT_STATE_ERROR

---

mqttc:will(topic, payload, qos, retain)

Set Will Message

Parameters

Incoming Value Type	Explanation
string	The message of the will topic
string	The message of the will payload
string	Qos of will message, default 0, can not fill in
string	Retain of will message, default 0, can not fill in

Return Value

return value type	explanation
bool	Returns true on success, otherwise false

Examples

-- To call before connect
mqttc:will("/xxx/xxx", "xxxxxx")

---