外观
system.mqttmessage
约 473 字大约 2 分钟
2026-07-15
用于小米内部 MQTT 消息结构的 protobuf 校验、编码与解码，不负责建立 MQTT 连接。
import mqttmessage from '@system.mqttmessage'消息结构
| 字段 | 类型 | protobuf 编号 |
|---|---|---|
ts | Integer/Number | 1 |
id | String | 2 |
carId | String | 3 |
packageName | String | 4 |
action | String | 5 |
data | Uint8Array/ArrayBuffer | 6 |
ts 在 protobuf 中是整数语义，但 JS 运行时只有 Number。若协议要求毫秒时间戳，当前日期仍处于安全整数范围；不要传 BigInt，固件类型校验不接受它。
方法
| 方法 | 返回值 | 说明 |
|---|---|---|
verify(object) | Boolean | 检查对象及字段类型，不检查业务含义 |
encode(object) | Uint8Array | 校验并编码 protobuf；对象为空或校验失败时失败 |
decode(buffer) | Object | 解码 typed buffer；空参数、普通数组或损坏数据会失败 |
const msg = {
ts: Date.now(),
id: '1',
carId: '',
packageName: 'com.example.demo',
action: 'ping',
data: new Uint8Array([1, 2, 3])
}
if (mqttmessage.verify(msg)) {
const wire = mqttmessage.encode(msg)
const decoded = mqttmessage.decode(wire)
console.log(decoded.action, decoded.data)
}安全封装
export function encodeMqttMessage(message) {
if (!message || !mqttmessage.verify(message)) {
throw new TypeError('invalid mqtt message')
}
const result = mqttmessage.encode(message)
if (!result) throw new Error('mqtt message encode failed')
return result
}
export function decodeMqttMessage(buffer) {
if (!(buffer instanceof Uint8Array) && !(buffer instanceof ArrayBuffer)) {
throw new TypeError('typed buffer required')
}
const result = mqttmessage.decode(buffer)
if (!result) throw new Error('mqtt message decode failed')
return result
}字段解释与边界
id：业务消息 ID，模块不会替你生成或去重；carId：协议保留的车辆标识，不属于设备蓝牙 ID；packageName：消息来源/目标业务包名，不会自动从当前应用填充；action：业务动作名，允许值由上层协议决定；data：原始二进制负载，不会自动 JSON 编解码。
该模块不建立连接、不选择 broker、不发布消息，也不验证 packageName 是否等于当前应用。verify() 通过只能说明类型可编码。
机型可用性
| Xiaomi Smart Band 10 Pro | Xiaomi Watch S4 41mm |
|---|---|
| ✅ | ✅ |