合宙Air724UG LuatOS-Air script lib API--mqtt

Table of Contents
mqtt
mqtt.client(clientId, keepAlive, username, password, cleanSession, will, version)
mqttc:connect(host, port, transport, cert, timeout)
mqttc:subscribe(topic, qos)
mqttc:unsubscribe(topic)
mqttc:publish(topic, payload, qos, retain)
mqttc:receive(timeout, msg)
mqttc:disconnect()
mqtt
模块功能：MQTT客户端

mqtt.client(clientId, keepAlive, username, password, cleanSession, will, version)
创建一个mqtt client实例

参数
名称 传入值类型 释义
clientId string 确保设备唯一性
keepAlive number 可选参数，默认为300 心跳间隔(单位为秒)，默认300秒
username string 可选参数，默认为"" 用户名，用户名为空配置为"“或者nil
password string 可选参数，默认为”" 密码，密码为空配置为"“或者nil
cleanSession number 可选参数，默认为1 1/0
will table 可选参数，默认为nil 遗嘱参数，格式为{qos=,retain=,topic=,payload=}
version string 可选参数，默认为"3.1.1” MQTT版本号，仅支持"3.1"和"3.1.1"
返回值
table mqttc client实例

例子
mqttc = mqtt.client(“clientid-123”)
mqttc = mqtt.client(“clientid-123”,200)
mqttc = mqtt.client(“clientid-123”,nil,“user”,“password”)
mqttc = mqtt.client(“clientid-123”,nil,“user”,“password”,nil,{qos=0,retain=0,topic=“willTopic”,payload=“willTopic”},“3.1”)
详细指南和示例参考：指南 示例

mqttc:connect(host, port, transport, cert, timeout)
连接mqtt服务器

参数
名称 传入值类型 释义
host string 服务器地址
port param string或者number类型，服务器端口
transport string 可选参数，默认为"tcp" “tcp"或者"tcp_ssl”
cert table 可选参数，默认为nil table或者nil类型，ssl证书，当transport为"tcp_ssl"时，此参数才有意义。cert格式如下：
{
caCert = “ca.crt”, --CA证书文件(Base64编码 X.509格式)，如果存在此参数，则表示客户端会对服务器的证书进行校验；不存在则不校验
clientCert = “client.crt”, --客户端证书文件(Base64编码 X.509格式)，服务器对客户端的证书进行校验时会用到此参数
clientKey = “client.key”, --客户端私钥文件(Base64编码 X.509格式)
clientPassword = “123456”, --客户端证书文件密码[可选]
}
timeout number 可选参数，默认为120 可选参数，socket连接超时时间，单位秒
返回值
result true表示成功，false或者nil表示失败

例子
mqttc = mqtt.client(“clientid-123”, nil, nil, false); mqttc:connect(“mqttserver.com”, 1883, “tcp”, 5)
详细指南和示例参考：指南 示例

mqttc:subscribe(topic, qos)
订阅主题

参数
名称 传入值类型 释义
topic param string或者table类型，一个主题时为string类型，多个主题时为table类型，主题内容为UTF8编码
qos param 可选参数，默认为0 number或者nil，topic为一个主题时，qos为number类型(0/1/2，默认0)；topic为多个主题时，qos为nil
返回值
bool true表示成功，false或者nil表示失败

例子
mqttc:subscribe(“/abc”, 0) – subscribe topic “/abc” with qos = 0
mqttc:subscribe({[“/topic1”] = 0, [“/topic2”] = 1, [“/topic3”] = 2}) – subscribe multi topic
详细指南和示例参考：指南 示例

mqttc:unsubscribe(topic)
取消订阅主题

参数
名称 传入值类型 释义
topic param string或者table类型，一个主题时为string类型，多个主题时为table类型，主题内容为UTF8编码
返回值
bool true表示成功，false或者nil表示失败

例子
mqttc:unsubscribe(“/abc”) – unsubscribe topic “/abc”
mqttc:unsubscribe({“/topic1”, “/topic2”, “/topic3”}) – unsubscribe multi topic
详细指南和示例参考：指南 示例

mqttc:publish(topic, payload, qos, retain)
发布一条消息

参数
名称 传入值类型 释义
topic string UTF8编码的字符串
payload string 用户自己控制payload的编码，mqtt.lua不会对payload做任何编码转换
qos 0/1/2, default number 可选参数，默认为0 0
retain number 可选参数，默认为0 0或者1
返回值
bool 发布成功返回true，失败返回false

例子
mqttc = mqtt.client(“clientid-123”, nil, nil, false)
mqttc:connect(“mqttserver.com”, 1883, “tcp”)
mqttc:publish(“/topic”, “publish from luat mqtt client”, 0)
详细指南和示例参考：指南 示例

mqttc:receive(timeout, msg)
接收消息

参数
名称 传入值类型 释义
timeout number 接收超时时间，单位毫秒
msg string 可选参数，默认为nil 可选参数，控制socket所在的线程退出recv阻塞状态
返回值
result 数据接收结果，true表示成功，false表示失败
data
如果result为true，表示服务器发过来的mqtt包

如果result为false，超时失败,data为"timeout"
如果result为false，msg控制退出，data为msg的字符串
如果result为false，socket连接被动断开控制退出，data为"CLOSED"
如果result为false，PDP断开连接控制退出，data为"IP_ERROR_IND"

如果result为false，mqtt不处于连接状态，data为nil
如果result为false，收到了PUBLISH报文，发送PUBACK或者PUBREC报文失败，data为nil
如果result为false，收到了PUBREC报文，发送PUBREL报文失败，data为nil
如果result为false，收到了PUBREL报文，发送PUBCOMP报文失败，data为nil
如果result为false，发送PINGREQ报文失败，data为nil
param 如果是msg控制退出，param的值是msg的参数；其余情况无意义，为nil

例子
true, packet = mqttc:receive(2000)
false, error_message = mqttc:receive(2000)
false, msg, para = mqttc:receive(2000,“APP_SEND_DATA”)
详细指南和示例参考：指南 示例

mqttc:disconnect()
断开与服务器的连接

参数
无

返回值
nil

例子
mqttc = mqtt.client(“clientid-123”, nil, nil, false)
mqttc:connect(“mqttserver.com”, 1883, “tcp”)
process data
mqttc:disconnect()
详细指南和示例参考：指南 示例