mqtt ==== .. _mqtt-1: mqtt ---- 模块功能：MQTT客户端 mqtt.client(clientId, keepAlive, username, password, cleanSession, will, version) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 创建一个mqtt client实例 - 参数 +------------+--------------------------------------------------------+ | 传入值类型 | 释义 | +============+========================================================+ | string | clientId | +------------+--------------------------------------------------------+ | number | **可选参数，默认为\ ``300``**\ ，keepAlive | | | 心跳间隔(单位为秒)，默认300秒 | +------------+--------------------------------------------------------+ | string | **可选参数，默认为\ ``""``**\ ，username | | | 用户名，用户名为空配置为""或者nil | +------------+--------------------------------------------------------+ | string | **可选参数，默认为\ ``""``**\ ，password | | | 密码，密码为空配置为""或者nil | +------------+--------------------------------------------------------+ | number | **可选参数，默认为\ ``1``**\ ，cleanSession 1/0 | +------------+--------------------------------------------------------+ | table | **可选参数，默认为\ ``nil``**\ ，will | | | 遗嘱参数，格式为{qos=, retain=, topic=, payload=} | +------------+--------------------------------------------------------+ | string | **可选参数，默认为\ ``"3.1.1"``**\ ，version | | | MQTT版本号 | +------------+--------------------------------------------------------+ - 返回值 table mqttc client实例 - 例子 .. code:: lua 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,nil,"3.1") -------------- mqttc:connect(host, port, transport, cert, timeout) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 连接mqtt服务器 - 参数 +-----------------------------------+-----------------------------------+ | 传入值类型 | 释义 | +===================================+===================================+ | string | host 服务器地址 | +-----------------------------------+-----------------------------------+ | param | port | | | string或者number类型，服务器端口 | +-----------------------------------+-----------------------------------+ | string | **可选参数， | | | 默认为\ ``"tcp"``**\ ，transport | | | “tcp”或者“tcp_ssl” | +-----------------------------------+-----------------------------------+ | table | **可选参数，默认为\ ``nil``**\ | | | ，cert，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”, | | | –客户端证书文件密码[可选]} | +-----------------------------------+-----------------------------------+ | number | timeout | | | 可选参数 | | | ，连接超时时间，单位秒，默认120秒 | +-----------------------------------+-----------------------------------+ - 返回值 result true表示成功，false或者nil表示失败 - 例子 .. code:: lua mqttc = mqtt.client("clientid-123", nil, nil, false); mqttc:connect("mqttserver.com", 1883, "tcp", 5) -------------- mqttc:subscribe(topic, qos) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 订阅主题 - 参数 +-----------------------------------+-----------------------------------+ | 传入值类型 | 释义 | +===================================+===================================+ | param | topic，string或者table类型， | | | 一个主题时为string类型，多个主题 | | | 时为table类型，主题内容为UTF8编码 | +-----------------------------------+-----------------------------------+ | param | **可选参数，默认为\ ``0``**\ | | | ，qos，number或者nil，topic为一个 | | | 主题时，qos为number类型(0/1/2，默 | | | 认0)；topic为多个主题时，qos为nil | +-----------------------------------+-----------------------------------+ - 返回值 bool true表示成功，false或者nil表示失败 - 例子 .. code:: lua mqttc:subscribe("/abc", 0) -- subscribe topic "/abc" with qos = 0 mqttc:subscribe({["/topic1"] = 0, ["/topic2"] = 1, ["/topic3"] = 2}) -- subscribe multi topic -------------- mqttc:unsubscribe(topic) ~~~~~~~~~~~~~~~~~~~~~~~~ 取消订阅主题 - 参数 +------------+--------------------------------------------------------+ | 传入值类型 | 释义 | +============+========================================================+ | param | topic，string或者table类型，一个主题时为 | | | string类型，多个主题时为table类型，主题内容为UTF8编码 | +------------+--------------------------------------------------------+ - 返回值 bool true表示成功，false或者nil表示失败 - 例子 .. code:: lua mqttc:unsubscribe("/abc") -- unsubscribe topic "/abc" mqttc:unsubscribe({"/topic1", "/topic2", "/topic3"}) -- unsubscribe multi topic -------------- mqttc:publish(topic, payload, qos, retain) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 发布一条消息 - 参数 +------------+--------------------------------------------------------+ | 传入值类型 | 释义 | +============+========================================================+ | string | topic UTF8编码的字符串 | +------------+--------------------------------------------------------+ | string | payload | | | 用户自己 | | | 控制payload的编码，mqtt.lua不会对payload做任何编码转换 | +------------+--------------------------------------------------------+ | number | **可选参数，默认为\ ``0``**\ ，qos 0/1/2, default 0 | +------------+--------------------------------------------------------+ | number | **可选参数，默认为\ ``0``**\ ，retain 0或者1 | +------------+--------------------------------------------------------+ - 返回值 bool 发布成功返回true，失败返回false - 例子 .. code:: lua 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) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 接收消息 - 参数 +------------+--------------------------------------------------------+ | 传入值类型 | 释义 | +============+========================================================+ | number | timeout 接收超时时间，单位毫秒 | +------------+--------------------------------------------------------+ | string | **可选参数，默认为\ ``nil``**\ ，msg | | | 可选参数，控制socket所在的线程退出recv阻塞状态 | +------------+--------------------------------------------------------+ - 返回值 result 数据接收结果，true表示成功，false表示失败 data 如果result为true，表示服务器发过来的包；如果result为false，表示错误信息，超时失败时为“timeout” param msg控制退出时，返回msg的字符串 - 例子 .. code:: lua true, packet = mqttc:receive(2000) false, error_message = mqttc:receive(2000) false, msg, para = mqttc:receive(2000) -------------- mqttc:disconnect() ~~~~~~~~~~~~~~~~~~ 断开与服务器的连接 - 参数 无 - 返回值 nil - 例子 .. code:: lua mqttc = mqtt.client("clientid-123", nil, nil, false) mqttc:connect("mqttserver.com", 1883, "tcp") process data mqttc:disconnect() --------------