JSKit App 文档

# MQTT 5 客户端

JSKit App 从 1.4.0-b 版本开始增加了 MQTT 5 客户端的支持。MQTT 协议在物联网（IoT）等领域使用越来越广泛。

说明

注意，现在仅对 MqttClient 做了少量的测试，对 MQTT 5 的支持还有限，如使用中遇到问题请联系我们。

MQTT 协议是什么 (opens new window)

# MqttClient 构造方法

MqttClient 从 mqtt 默认导出。

import MqttClient from 'mqtt';// default 导出的，名字随意。

MqttClient 的构造方法参数需要符合：

interface MqttArgs {
    serverURL: string;
    clientId?: string;
}

constructor(args: string | MqttArgs);
  • args 是一个对象：
    • serverURL 必选的服务端地址。支持 tcp:// 或 ws:// 等 scheme 的 serverURL。
    • clientId 可选的 clientId 。缺省时，将交由 JSKit App 为每个扩展自动生成一个 uuid。
const mqt = new MqttClient('tcp://broker-cn.emqx.io:1883');

//或

const mqt = new MqttClient({
    serverURL: 'tcp://broker-cn.emqx.io:1883',
    clientId: 'jsk-mqt-cid-233'
});

# 连接 MQTT Broker

interface WillMessage {
    topic: string;
    payload?: string | ArrayBuffer;
    qos?: 0 | 1 | 2;
    retain?: boolean;
    willDelayInterval?: number;
}

interface ConnArgs {
    userName?: string;
    password?: string | ArrayBuffer;
    callback?: MqttActionCallback;
    automaticReconnect?: boolean;//default true
    willMessage?: WillMessage;
}

function connect(args: undefined | ConnArgs): void;

  • args 参数可以为空，表示匿名连接。

  • args 也可以提供用户名密码鉴权登录，如 ConnArgs 所示的对象：

    • userName string 类型的用户名
    • password string 的密码，将转换成 utf-8 类型的字节流；或者可以是一个 ArrayBuffer 的二进制密码
    • callback 连接的回调，可以异步的用来判断 connect 方法异步执行的结果，MqttActionCallback 类型，具体后面说明
    • automaticReconnect 是否自动连接。缺省值为 true
    • willMessage 遗嘱消息

说明

当前 mqtt 模块支持：匿名连接、用户名密码鉴权连接，如果需求需要支持其他鉴权方式请反馈给我们。

MqttActionCallback 结构为：

MqttActionCallback {
    onSuccess?: () => void;
    onFailure?: (msg: string) => void;
    finalAction?: () => void;
}
  • onSuccess 动作执行成功后回调
  • onFailure 动作执行出错后回调，错误信息会包含在 msg 中
  • finalAction 不管是执行成功还是执行失败，最后都会回调的方法

MqttClient 会异步执行，但所有回调代码都会自动在创建它的 JSKit 线程中调度。

# 自动重连和主动重连

如果 automaticReconnect 为 true ，MqttClient 会在断开后自动重连。如果为 false 可调用 reconnect() 方法主动进行重连。

# 遗嘱消息

遗嘱消息，按照协议，MQTT 允许在客户端断开连接后，由 MQTT Broker 发布一个遗嘱消息。具体可参考 MQTT 遗嘱消息（Will Message）的使用 (opens new window)。

# MQTT 回调

从 MQTT Broker 发来的消息都经过 MQTT 回调返回，设置回调方式如下：

interface MqttMessage {
    topic: string;
    payload: ArrayBuffer;
    qos: 0 | 1 | 2;
    retain: boolean;
}

interface MqttCallback {
    onConnected?: (reconnect: boolean) => void;
    onDisconnected?: () => void;
    onMessage?: (msg: MqttMessage) => void;
    onError?: (code: number, msg: string) => void;
}

function setCallback(callback: MqttCallback): void;
  • onConnected 连接时回调，reconnect 参数返回此次连接是否是自动连接。
  • onDisconnected 断开连接时回调
  • onMessage 收到消息时回调
  • onError 当发生错误时回调，code，错误码；msg 错误信息

# MQTT 主题订阅

interface SubArgs {
    topic: string;
    qos?: 0 | 1 | 2;
    callback?: MqttActionCallback;
}

function subscribe(args: string | SubArgs): void;
  • args 订阅的 string 类型的主题或者是订阅的 SubArgs 类型的对象：
    • topic 订阅的主题
    • qos 服务质量
    • callback 订阅的异步执行结果回调

# MQTT QoS（服务质量）

参见MQTT QoS（服务质量）介绍 (opens new window)

# MQTT 取消订阅

interface UnsubArgs {
    topic: string;
    callback?: MqttActionCallback;
}

function unsubscribe(args: string | UnsubArgs): void;
  • topic 要取消订阅的主题
  • callback 取消订阅的异步执行结果回调

# MQTT 主题发布

interface PubArgs {
    topic: string;
    payload?: string | ArrayBuffer;
    qos?: 0 | 1 | 2;
    retain?: boolean;
    callback?: MqttActionCallback;
}
function publish(args: string | PubArgs): void;
  • args 发布主题，如果为 string 类型，发布一个主题；或者为 PubArgs 类型的对象：
    • topic 发布的主题
    • payload string 或者是 ArrayBuffer 类型的消息负载
    • qos 发布主题的 qos 服务质量等级
    • retain 是否为保留消息，缺省值为 false 。
    • callback 主题发布的异步执行结果回调

关于 retained 消息的进一步说明可参考 MQTT 保留消息 (opens new window)

# 断开连接

function disconnect(): void;

断开与服务端的连接，主动断开连接后可调用 reconnect() 方法再次连接到 Broker。

# 重新连接

function reconnect(): void;

调用 reconnect 连接回调 MqttCallback#onConnected 的 reconnect 参数为 false 。

# 关闭 MqttClient

function close(): void;

关闭 MqttClient 客户端，调用此方法后，不能再次调用 reconnect 。

其他资源

← 多线程 Worker →