更新记录

0.0.1（2026-04-27）

添加基础连接、订阅、发送、心跳、断开等 mqtt 功能

平台兼容性

uni-app x(5.01)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
×	×	10.0	×	×	×

wicos-mqtt

wicos-mqtt 是一个面向 uni-app x 的 Android MQTT 原生插件，用 UTS 封装 MQTT/TCP 能力，对外提供面向 Broker 连接、主题订阅、消息发布和事件监听的统一调用方式。它主要服务于 MQTT 联调、设备上报、任务调度、心跳保活和状态回传等场景。

特性

Android-only MQTT 原生能力封装。
支持 Broker 连接、断开、订阅、取消订阅、消息发布。
支持连接状态变化、消息到达、错误事件回调。
内置基础 keepalive 心跳，避免连接长时间空闲后被 Broker 主动断开。
对非 Android 平台提供统一的 fallback 错误返回。

目录结构

uni_modules/wicos-mqtt/
├── README.md
├── package.json
├── utssdk/
│   ├── index.uts
│   ├── interface.uts
│   └── app-android/
│       ├── index.uts
│       ├── AndroidManifest.xml
│       ├── config.json
│       └── mqtt/
│           ├── listener.uts
│           └── options.uts
└── js_sdk/
    ├── errors.ts
    ├── event-emitter.ts
    ├── index.ts
    └── types.ts

文件职责

utssdk/index.uts：插件根入口，对外导出统一 API；非 Android 平台在这里返回 fallback 错误。
utssdk/app-android/index.uts：Android 平台主入口，负责 MQTT 报文收发、连接状态切换和 keepalive。
utssdk/app-android/mqtt/listener.uts：消息、状态、错误监听器注册表，以及事件对象构造。
utssdk/app-android/mqtt/options.uts：Broker URL 组装、默认 clientId、keepalive、QoS 等参数解析。
utssdk/interface.uts：连接参数、事件结构和客户端接口声明。
js_sdk/：可选的 JS/TS 门面层，当前项目页面未直接依赖。
package.json：uni_modules 插件元数据。

平台支持

当前仅支持 APP-ANDROID。
其他平台会返回 wicos-mqtt 当前仅支持 Android 宿主环境。

安装方式

通常将整个 wicos-mqtt 目录放入项目的 uni_modules 下即可。发布时请确保插件根目录下存在 utssdk/，页面侧通过下面的方式导入：

import { createNativeMqttClient } from "@/uni_modules/wicos-mqtt"

如果需要显式引用类型，可再按需引入：

import type {
  ConnectOptions,
  NativeMqttClient,
  MqttMessageEvent
} from "@/uni_modules/wicos-mqtt/utssdk/interface.uts"

调用流程

推荐按下面的顺序调用插件接口：

1. 创建客户端

先通过 createNativeMqttClient 创建客户端实例，再统一注册消息、状态和错误监听器。

const client = createNativeMqttClient()

2. 注册事件监听

连接前建议先注册：

addStateChangeListener
addMessageListener
addErrorListener

这样连接中的状态变化、Broker 推送消息和底层错误都不会漏掉。

3. 建立 Broker 连接

准备好 host / port / clientId / username / password / ssl 等参数后，调用 connect 建立连接。

await client.connect({
  host: "192.168.0.10",
  port: 1883,
  clientId: "task-broker-mobile",
  clean: true,
  keepAliveSeconds: 60,
  connectTimeoutMs: 10000,
  autoReconnect: true,
  ssl: false
})

4. 订阅目标主题

连接成功后，再调用 subscribe 订阅业务主题，例如任务下行主题、设备控制主题或广播状态主题。

5. 发布消息

当需要上报任务执行状态、设备心跳或业务响应时，调用 publish 向指定主题发送消息。

6. 处理消息与错误

Broker 推送消息通过 addMessageListener 接收；连接异常、鉴权失败、网络中断、心跳失败等都通过 addErrorListener 接收。

7. 断开与清理

页面退出或不再需要连接时，调用 disconnect，并按需移除对应监听器。

API 概览

1. `createNativeMqttClient()`

创建一个原生 MQTT 客户端实例。

无参数。
返回值：NativeMqttClient

注意事项：

当前仅在 Android 宿主环境下可正常工作。
非 Android 平台会返回 fallback 客户端，调用连接或发布能力会直接失败。

2. `connect(options)`

连接到指定 Broker。

options: ConnectOptions

参数字段：

host: string：Broker 地址。
port: number：Broker 端口。
clientId?: string | null：客户端标识。
username?: string | null：用户名。
password?: string | null：密码。
clean?: boolean | null：是否启用 clean session。
keepAliveSeconds?: number | null：keepalive 秒数。
connectTimeoutMs?: number | null：连接超时时间，单位毫秒。
reconnectIntervalMs?: number | null：重连间隔，当前仅作配置保留。
autoReconnect?: boolean | null：是否启用自动重连状态标记。
protocolVersion?: number | null：协议版本，当前默认 MQTT 3.1.1。
ssl?: boolean | null：是否使用 SSL。

返回值：

Promise<void>

注意事项：

如果 Broker 返回 CONNACK 拒绝码，错误事件里会带上对应可读说明。
如果连接失败，错误事件会带上 broker URL、SSL 开关、超时信息和底层 cause。
当前实现基于原生 MQTT/TCP，不使用 WebSocket。

3. `disconnect()`

主动断开当前 Broker 连接。

无参数。
返回值：Promise<void>

注意事项：

调用后会停止 keepalive 心跳。
断开成功后会触发状态变更到 disconnected。

4. `subscribe(topic, options?)`

订阅指定主题。

topic: string：目标主题。
options?: SubscribeOptions | null

可选字段：

qos?: number | null

返回值：

Promise<void>

注意事项：

当前默认使用 QoS 0。
调用前必须已连接到 Broker，否则会返回 MQTT client 未连接。

5. `unsubscribe(topic)`

取消订阅指定主题。

topic: string
返回值：Promise<void>

注意事项：

调用前必须已连接到 Broker。
当前实现基于 UNSUBSCRIBE 报文直接发送，不依赖额外确认回调。

6. `publish(topic, payload, options?)`

向指定主题发布消息。

topic: string
payload: string
options?: PublishOptions | null

可选字段：

qos?: number | null
retain?: boolean | null

返回值：

Promise<void>

注意事项：

当前默认 QoS 0。
如果选择 QoS 1，客户端会在收到下行 QoS 1 消息时回发 PUBACK。
payload 当前按 UTF-8 字符串编码发送。

7. `getState()`

获取当前连接状态。

无参数。
返回值：MqttConnectionState

可选状态值：

"idle"
"connecting"
"connected"
"reconnecting"
"disconnected"
"error"

8. `addMessageListener(listener)`

注册消息到达监听器。

listener: (event: MqttMessageEvent) => void
返回值：number，监听器 ID

消息事件字段：

topic: string
payload: string
qos: number
retained: boolean
duplicate: boolean
timestamp: number

9. `removeMessageListener(listenerId)`

移除消息监听器。

listenerId: number
无返回值。

10. `addStateChangeListener(listener)`

注册连接状态变化监听器。

listener: (event: MqttStateChangeEvent) => void
返回值：number

状态事件字段：

state: MqttConnectionState
reason?: string | null
timestamp: number

11. `removeStateChangeListener(listenerId)`

移除状态监听器。

listenerId: number
无返回值。

12. `addErrorListener(listener)`

注册错误监听器。

listener: (event: MqttErrorEvent) => void
返回值：number

错误事件字段：

code: string
message: string
cause?: string | null
timestamp: number

13. `removeErrorListener(listenerId)`

移除错误监听器。

listenerId: number
无返回值。

事件回调

`addMessageListener`

收到 Broker 下行消息时触发，返回结构：

{
  topic: string
  payload: string
  qos: number
  retained: boolean
  duplicate: boolean
  timestamp: number
}

`addStateChangeListener`

连接状态变化时触发：

{
  state: "idle" | "connecting" | "connected" | "reconnecting" | "disconnected" | "error"
  reason?: string | null
  timestamp: number
}

`addErrorListener`

发生连接、订阅、发布、断线或 keepalive 异常时触发：

{
  code: string
  message: string
  cause?: string | null
  timestamp: number
}

常见错误码

插件通过 MqttErrorEvent 对外返回错误信息。常见错误码如下：

错误码	含义
`CONNECT_FAILED`	Broker 建连失败
`DISCONNECT_FAILED`	主动断开失败
`SUBSCRIBE_FAILED`	主题订阅失败
`UNSUBSCRIBE_FAILED`	取消订阅失败
`PUBLISH_FAILED`	消息发布失败
`CONNECTION_LOST`	已建立连接后底层连接中断
`KEEPALIVE_FAILED`	心跳发送失败

keepalive 说明

当前实现已经内置基础 keepalive：

连接成功后，会按 keepAliveSeconds / 2 周期发送 PINGREQ
收到 PINGRESP 后静默确认
如果心跳发送失败，会抛出 KEEPALIVE_FAILED

这能避免连接空闲一段时间后被 Broker 主动断开。

实现说明

这个插件的结构已经按项目内 wicos-ble 的 UTS 插件方式对齐：

utssdk/index.uts 只保留跨平台导出和非 Android fallback。
utssdk/app-android/index.uts 负责 Android 平台 MQTT 主逻辑。
utssdk/app-android/mqtt/listener.uts 专门处理事件监听器注册表。
utssdk/app-android/mqtt/options.uts 专门处理参数与默认值解析。

这样做的目标是把平台边界和 MQTT 协议处理边界拆开，降低后续维护成本，也更贴近 uni-app x UTS 插件的推荐结构。

使用建议

只在 Android 端调用这个插件。
页面层优先依赖 @/uni_modules/wicos-mqtt，不要直接耦合 Android SDK 类。
连接前先注册状态、消息、错误监听器。
如果在手机上联调本机电脑 Broker，不要填写 127.0.0.1，要改成电脑在局域网中的实际 IP。
如果 Broker 使用 TLS，请同步打开 ssl 开关并核对端口。

常见问题

1. 连接失败

确认 host 和 port 正确。
确认手机与 Broker 所在设备在同一网络可达范围内。
确认 Broker 已启动并监听对应端口。
确认 SSL 开关和 Broker 实际端口匹配。

2. 连接一段时间后断开

确认 Broker 是否允许长连接空闲。
检查错误日志里是否出现 KEEPALIVE_FAILED。
检查移动网络切换、Wi-Fi 休眠或宿主进程被系统限制的情况。

3. 订阅成功但没有消息

确认主题名称完全一致。
确认发布端的 QoS、retain 和业务路由配置正确。
确认消息确实发到了当前客户端订阅的主题。

4. 发布失败

确认当前状态已经是 connected。
确认 Broker 没有限制当前客户端的发布权限。
检查错误事件中的 cause，区分是底层 I/O 失败还是连接已经丢失。

关联页面

项目中可直接调用这个插件的页面是：

pages/MQTT/index.uvue

该页面提供了 Broker 连接、任务主题订阅、单次发送、定时发送和日志抽屉展示的完整调试入口。

版本说明

当前版本：0.0.1
插件 ID：wicos-mqtt

MQTT- Android 版 安卓 物联网 MQTT

更新记录

0.0.1（2026-04-27）

平台兼容性

uni-app x(5.01)

wicos-mqtt

特性

目录结构

文件职责

平台支持

安装方式

调用流程

1. 创建客户端

2. 注册事件监听

3. 建立 Broker 连接

4. 订阅目标主题

5. 发布消息

6. 处理消息与错误

7. 断开与清理

API 概览

1. createNativeMqttClient()

2. connect(options)

3. disconnect()

4. subscribe(topic, options?)

5. unsubscribe(topic)

6. publish(topic, payload, options?)

7. getState()

8. addMessageListener(listener)

9. removeMessageListener(listenerId)

10. addStateChangeListener(listener)

11. removeStateChangeListener(listenerId)

12. addErrorListener(listener)

13. removeErrorListener(listenerId)

事件回调

addMessageListener

addStateChangeListener

addErrorListener

常见错误码

keepalive 说明

实现说明

使用建议

常见问题

1. 连接失败

2. 连接一段时间后断开

3. 订阅成功但没有消息

4. 发布失败

关联页面

版本说明

隐私、权限声明

1. 本插件需要申请的系统权限列表：

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

BLE 蓝牙- Android 版

MQTT- Android 版

Modal title

MQTT- Android 版安卓物联网 MQTT

1. `createNativeMqttClient()`

2. `connect(options)`

3. `disconnect()`

4. `subscribe(topic, options?)`

5. `unsubscribe(topic)`

6. `publish(topic, payload, options?)`

7. `getState()`

8. `addMessageListener(listener)`

9. `removeMessageListener(listenerId)`

10. `addStateChangeListener(listener)`

11. `removeStateChangeListener(listenerId)`

12. `addErrorListener(listener)`

13. `removeErrorListener(listenerId)`

`addMessageListener`

`addStateChangeListener`

`addErrorListener`