# MQTT应用基础类

***

## MQTT 连接应用（上送数据）封装模块

> ***API\_VER: 5***

本模块封装了MQTT上送数据的基础逻辑。帮助用户快速开发通过MQTT协议上送设备数据到云服务的应用。

应用示例:

* [阿里云接入](https://github.com/freeioe/freeioe_example_apps/blob/master/aliyun/app.lua)
* [百度云接入](https://github.com/freeioe/freeioe_example_apps/blob/master/baidu_cloud/app.lua)
* [广州联通云平台接入](https://github.com/freeioe/freeioe_example_apps/blob/master/telit/app.lua)

### initialize

构造 (同应用构造函数)

```lua
function initialize(name, sys, conf)
end
```

#### MQTT 配置

配置信息 conf 可以通过包含以下信息，来配置MQTT连接认证相关的信息。

* client\_id MQTT 客户端 ID
* username MQTT 连接认证用户名
* password MQTT 连接认证密码
* server MQTT 连接服务器地址（可以是域名和 IP)
* port MQTT 连接服务器端口
* clean\_session MQTT 连接的 clean\_session 标识
* enable\_tls 是否启用 TLS 安全认证
* tls\_cert TLS 服务器证书文件路径（应用目录内的相对路径)
* tls\_insecure 是否启用非安全证书认证模式
* tls\_ca\_path TLS 服务器证书目录路径（应用目录内的相对路径)
* client\_cert TLS 客户端证书文件路径（应用目录内的相对路径)
* client\_key TLS 客户端密钥文件路径（应用目录内的相对路径)

#### 其他配置

**period**

周期上送的周期时间(秒)，缺省是60秒。 小于1则不开启周期上送功能

**ttl**

变化传输的强制上传周期(秒)，数据不变，但是经过ttl的时间数据必须上传一次, 默认300秒

**float\_threshold**

变化传输判断浮点数据变化的精度 (默认0.0000001)

**data\_upload\_dpp**

数据上传单包数据点数量上限。缺省是1024

**data\_upload\_buffer**

周期上送最多缓存数据点数量。缺省为10240

**enable\_data\_cache**

是否开启断线缓存。为1的时候开启断线缓存功能

**cache\_per\_file**

断线缓存单文件数据点数量。缺省为4096，范围是1024 \~ 4096

**data\_cache\_limit**

断线缓存文件数量上限。缺省为128，取值范围:1 \~ 256

**data\_cache\_fire\_gap**

断线缓存上送数据间隔时间。单位毫秒, 缺省为1000，取值范围: 不小于1000

### 回调函数

模块派生应用需要提供以下回调函数处理数据

#### 必选回调函数

**on\_publish\_data**

当未开启周期上送时，此接口会被调用，用以上传单点数据。

```lua
function app:on_publish_data(key, value, timestamp, quality)
end
```

**on\_publish\_data\_list**

开启周期上送后，此接口用以上传多个数据（数据数组）

```lua
function app:on_publish_data_list(val_list)
end
```

**pack\_key**

创建数据点唯一标识。

* 用以创建数据点唯一标识，默认本模块会以 `<sn>/<input>/<prop>` 进行编码，如有需要则重载此函数。
* 其次函数返回空(nil)表示该点数据需要忽略。可以用作忽略某种数据，或忽略某些设备的数据

```lua
function app:pack_key(app_src, device_sn, input, prop)
end
```

**on\_publish\_data\_em**

当设备有紧急数据需要上送时调用此接口（同一紧急数据也会抄送至普通数据处理接口)

```lua
function app:on_publish_data_em(key, value, timestamp, quality)
end
```

**on\_publish\_devices**

当网关采集的设备信息有变动时此接口被调用（或MQTT刚连接成功时，此接口会被调用一次)。用以上送当前采集的设备信息（如设备描述等等）

```lua
function app:on_publish_devices(devices)
end
```

**on\_comm**

通过此接口处理设备通讯报文

```lua
function app:on_comm(app_src, device_sn, dir, timestmap, ...)
end
```

**on\_event**

通过此接口可以监听当前网关(FreeIOE)内部的设备事件

```lua
function app:on_event(app_src, device_sn, event_level, event_data, event_timestamp)
end
```

**on\_stat**

通过此接口可以监听统计数据（详情参考统计接口的文档获取更详细信息）

```lua
function app:on_stat(app_src, device_sn, stat, prop, value, timestamp)
end
```

**on\_publish\_cached\_data\_list**

当开启MQTT模块的断线缓存功能时，此接口用以处理缓存数据。

```lua
function app:on_publish_cached_data_list(val_list)
end
```

**mqtt\_auth**

此接口用以实现复杂的MQTT认证，需要返回以下信息

```lua
function app:mqtt_auth()
end
```

```lua
return {
	client_id = client_id,
	username = username,
	password = password,
	clean_session = true,
	host = host,
	port = port,
	enable_tls = enable_tls,
	tls_cert = "root_cert.crt",
}
```

**mqtt\_will**

实现此接口会让模块在连接MQTT服务器成功时发送on will 消息，用以发布离线通知

```lua
function app:mqtt_will()
	return will_topic, will_data, will_qos, will_retained
end
```

**on\_mqtt\_connect\_ok**

此接口会在连接成功时被调用，可用以发送上线通知以及订阅主题等操作

```lua
function app:on_mqtt_connect_ok()
end
```

**on\_mqtt\_message**

处理MQTT下行数据

```lua
function app:on_mqtt_message(msg_id, topic, payload, qos, retained)
end
```

**on\_mqtt\_publish**

本模块已经处理了qos为1的信息处理，此接口用以进行额外处理（如qos 2的信息处理等等)

```lua
function app:on_mqtt_publish(msg_id)
end
```

### connected

返回是否已经连接成功

```lua
function app:connected()
```

### connect

开启连接（仅用以调用disconnect()后再次发起连接，本模块启动后会自动开启连接)

```lua
function app:connect()
```

### disconnect

断开与MQTT服务器的连接

```lua
function app:disconnect()
```

### subscribe

订阅主题

```lua
function app:subscribe(topic, qos)
```

### unsubscribe

取消订阅主题

```lua
function app:unsubscribe(topic)
```

### publish

发布MQTT信息数据

```lua
function app:publish(topic, msg, qos, retained)
```

### compress

压缩数据（string类型), 返回压缩好的数据(string类型)。压缩算法为zip压缩

```lua
function app:compress(data)
```

### decompress

解压数据(string类型)

```lua
function app:decompress(data)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://freeioe.gitbook.io/doc/reference/app/base/mqtt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.