MQTT Client

The MqttClient class is a wrapper for connecting to an MQTT broker. It simplifies the process of connecting, publishing, subscribing, and handling messages, and automatically manages features like keep-alives and reconnections.

You must first create an instance and then connect it to a broker.

create

Creates a new, unconnected MQTT client instance.

Example

# (No arguments needed)

connect

Connects the client to a specified MQTT broker using a URL and various options.

Parameters

url: The broker URL, including the protocol (e.g., mqtt://broker.hivemq.com, wss://test.mosquitto.org:8081).
options: An object for connection configuration.
- clientId: A unique ID for this client. If not provided, a random one is generated.
- username: The username for authentication, if required.
- password: The password for authentication, if required.
- keepalive: The interval in seconds for keep-alive pings. Defaults to 60.
- connectTimeout: Timeout in milliseconds for the connection attempt. Defaults to 30000.
- will: A "Last Will and Testament" object to be published by the broker if this client disconnects ungracefully.
  - topic: The topic for the will message.
  - payload: The will message payload.
  - qos: The QoS level for the will.
  - retain: The retain flag for the will.

Example: Connect with username and a last will

# url
mqtt://broker.hivemq.com
# options
username: my-device-user
password: my-secret-password
will: {
  topic: 'devices/my-device/status',
  payload: 'offline',
  qos: 1,
  retain: true
}

Output

Returns true on a successful connection.

disconnect

Closes the connection to the broker.

Parameters

force: If true, the client closes immediately without waiting for in-flight messages to be acknowledged. Defaults to false.

Output

Returns true on success.

isConnected

Checks if the client is currently connected to the broker.

Output

Returns true if connected, false otherwise.

publishString

Publishes a string message to a specific topic.

Parameters

topic: The topic to publish to.
message: The string message to publish.
options: An optional object for publish settings.
- qos: The Quality of Service level (0, 1, or 2). Defaults to 0.
- retain: If true, the message is stored by the broker as the "last known good" value for that topic. Defaults to false.

Example

# topic
devices/my-device/log
# message
Device starting up...
# options
qos: 1

publishJson

Publishes a JSON object to a specific topic. The object is automatically stringified.

Parameters

topic: The topic to publish to.
message: The JSON object to publish.
options: An optional configuration object (see publishString for details).

Example

# topic
devices/my-device/data
# message
temperature: 21.5
humidity: 45.2

Subscribes to one or more topics to receive messages. Supports MQTT wildcards (+ for single level, # for multi-level).

Parameters

topic: A string, an array of strings, or an object representing the topic(s) to subscribe to.
options: Optional settings, primarily for setting the qos level of the subscription.

Example

# topic
sensors/+/temperature
# options
qos: 1

onStringMessage

Attaches a listener that is triggered for incoming messages, providing the payload as a string. This is a convenient way to subscribe and handle messages in one step.

Parameters

listener: The callback function that will receive the message.
topic: An optional topic or array of topics to subscribe to. If omitted, the listener will receive messages from all topics the client is already subscribed to.

Example

# listener
<callback>
# topic
devices/my-device/commands

onJsonMessage

Attaches a listener for incoming messages and automatically parses the payload as JSON. If parsing fails, the message is ignored.

Parameters

listener: The callback function that will receive the parsed JSON object.
topic: An optional topic or array of topics to subscribe to.

Example

# listener
<callback>
# topic
devices/my-device/config

unsubscribe

Unsubscribes from a topic or topics, stopping the flow of messages from them.

Parameters

topic: A string or an array of strings representing the topic(s) to unsubscribe from.

isReconnecting

Checks if the client is in the process of reconnecting after a disconnect.

Output

Returns true if the client is currently trying to reconnect.

getLastMessageId

Gets the message ID of the last message sent by this client.

Output

The last message ID number.

Last updated 17 hours ago