洛汐文档库

外观

system.mqtt

约 509 字大约 2 分钟

2026-07-15

原生 MQTT 客户端 Feature。它与只负责 protobuf 编解码的 system.mqttmessage 不同：system.mqtt 建立网络连接、订阅主题并发布消息。

import mqtt from '@system.mqtt'

mqtt.createConnection(options)

interface MqttConnectOptions {
  brokerUrl: string
  clientId?: string
  username?: string
  password?: string
  clean?: boolean
  keepalive?: number
  reconnectPeriod?: number
  connectTimeout?: number
  userProperties?: object
}

createConnection(options: MqttConnectOptions): MqttClient
字段必需说明
brokerUrl是Broker URL；格式不合法或缺失会直接报错
clientId否客户端 ID；未传时固件可生成以 mqtt_ 开头的 ID
username、password否Broker 凭据
clean否是否使用 clean session
keepalive否MQTT keepalive 周期
reconnectPeriod否自动重连间隔
connectTimeout否建连超时
userProperties否MQTT 用户属性；预装汽车应用用于携带业务元数据
const client = mqtt.createConnection({
  brokerUrl: 'ssl://broker.example.invalid:8883',
  clientId: 'watch-client-id',
  username: 'user',
  password: 'short-lived-token',
  clean: true,
  keepalive: 60,
  reconnectPeriod: 3000,
  connectTimeout: 10000,
  userProperties: { channel: 'watch' }
})

协议 scheme、TLS 证书和端口是否可用由厂商 MQTT 后端决定。示例域名不可直接使用。

客户端事件

client.onconnect = () => {}
client.ondisconnect = reason => {}
client.onreconnect = () => {}
client.onerror = error => {}
client.onmessage = (topic, payload) => {}

固件确认 onconnect、ondisconnect、onreconnect、onmessage；预装应用还设置 onerror。payload 可能是 String 或 ArrayBuffer，应按协议判断后再解码。

订阅与发布

client.addTopic(options: {
  topic: string
  success?: Function
  fail?: Function
  complete?: Function
}): void

client.removeTopic(options: { topic: string } | string): void

client.publish(options: {
  topic: string
  payload: string | ArrayBuffer
  retain?: boolean
  success?: Function
  fail?: Function
  complete?: Function
}): void

addTopic 对应订阅，原生实现强制要求 topic。publish 强制要求 topic，并只接受 String 或 ArrayBuffer 的 payload。固件还保留 addTopicListener、removeTopicListener 内部入口；业务应用使用 onmessage 接收消息即可。

client.onconnect = () => {
  client.addTopic({
    topic: 'ToWatch/device-id/#',
    fail(data, code) { console.error('subscribe', code) }
  })
}

client.onmessage = (topic, payload) => {
  console.log('message topic', topic)
}

client.publish({
  topic: 'FromWatch/device-id/result',
  payload: new Uint8Array([1, 2, 3]).buffer,
  retain: false
})

断开连接

预装应用在 onHide/onDestroy 调用客户端的 disconnect()。应先移除不再使用的主题，再断开连接；不要让后台重连器在页面销毁后继续运行。

机型可用性

Xiaomi Smart Band 10 ProXiaomi Watch S4 41mm
❌△

获取源代码