MQTTClient constructor
Overview
Constructor for MQTTClient objects. After MQTTClient objects connect to an MQTT broker, they can then subscribe and publish to that broker.
For information about using the MQTT standard, see MQTT.org or the MQTT 3.1.1 Specification.
Added in version 2.1.13
Format
var mqttClient = new MQTTClient(options);
| Parameter | Description | Type | Required |
|---|---|---|---|
| options | An options object with properties used for configuration of this MQTTClient object. Properties are listed below. | Object | Required |
Options object properties
| Value | Description | Type | Required |
Notes |
|---|---|---|---|---|
| broker | A URI with the broker connection information. | String | Required |
Must start with one of the following: mqtt:// mqtts:// ws:// wss:// tcp:// May contain the username, password, and port, for example: |
| clean | Flag used to create a clean session with the broker. Use false to request that the server persists undelivered messages with QoS 1 or 2. | Boolean | Optional | If not specifed the default is true. |
| clientID | A client identifier used with connecting to the broker. | String | Optional | The client identifier defaults to a generated GUID specific to this object if not specified here. |
| username | The username used when connecting with the broker. | String | Optional | Overrides the username if specified in the broker property. |
| password | The password used when connecting with the broker. | String | Optional | Overrides the password if specified in the broker property. Only used if username property is also specified. |
| timeout | A timeout value (in seconds) for MQTT communications. | Integer | Optional | If not specified, the default is 10 seconds. |
| onMessage | A callback function that is called when a message is received. | Function | Optional | When called, the first parameter is a Message object as described below. |
| onDisconnect | A callback function that is called when the session is disconnected. | Function | Optional | When called, the first parameter is a Disconnect object as described below. |
| subscribeTo | An array of filters that are automatically subscribed to on connect. | Array | Optional | The array may contain filter strings and Subscription objects. Filter strings use the default QoS of 0. Subscription objects are described below. |
Message object properties
| Value | Description | Type |
Notes |
|---|---|---|---|
| topic | The topic for the message. | String | |
| payload | An ArrayBuffer containing the payload for the message. | ArrayBuffer | |
| qos | The quality of service (QoS) for the message. | Integer |
Will use the lowest of either the subscription QoS level or the sent message QoS level. Possible values: 0 – at most once, where messages are delivered according to the best efforts of the operating environment. Message loss can occur. 1 – at least once, where messages are assured to arrive but duplicates can occur. 2 – exactly once, where messages are assured to arrive exactly once. |
| retain | A flag indicating if this message is a retained message. | Boolean | |
| payloadAsString | The payload bytes decoded as a UTF-8 string. | String |
Disconnect object properties
| Parameter | Description | Type |
|---|---|---|
| reason | A description for the disconnect reason. | String |
Subscription object properties
| Parameter | Description | Type | Required |
Notes |
|---|---|---|---|---|
| filter | The topic filter. | String | Required | May contain + symbol to represent a single intermediate level wildcard. May end with the # symbol indicating a match with any further levels. |
| qos | The quality of service (QoS) for the filter. | Integer | Optional |
Possible values: 0 – at most once, where messages are delivered according to the best efforts of the operating environment. Message loss can occur. 1 – at least once, where messages are assured to arrive but duplicates can occur. 2 – exactly once, where messages are assured to arrive exactly once. |
| callback | A callback function that is called when a message matching this filter is received. | Function | Optional |
The onMessage callback for the MQTTClient is always called first if it exists, followed by any matching filter subscriptions specified here. The first parameter message is described above. |
Example 1
/* Displays a toast when a message is received on the "velocity/toast" topic.
* Sounds a beep when a message is received on "velocity/beep" with a payload including frequency and duration.
* Attempts to reconnect if disconnected.
*/
mqttClient = new MQTTClient({
broker: "mqtt://mymqtt.example.com",
clientId: Device.getVelocityId(),
onDisconnect: function(event) {
Logger.info("lost MQTT connection: " + event.reason);
// try to reconnect after 5 second timeout
setTimeout(function() { mqttClient.connect(); }, 5000);
},
subscribeTo: [
{
filter: "velocity/toast",
qos: 0,
callback: function(message) {
View.toast(message.payloadAsString, true);
}
},
{
filter: "velocity/beep",
qos: 0,
callback: function (message) {
var values = message.payloadAsString.split(',');
var frequency = values[0] || 2000;
var duration = values[1] || 500;
Device.beep(frequency, duration, 50);
}
}
]
});
mqttClient.connect();
Example 2
/* Publishes the last scan to a topic named "scan/" followed by the device's
* serial number or the Velocity ID if the serial number cannot be acquired.
* Uses a secure (TLS) connection.
* Uses the username and password specified.
* Uses a timeout of 30 seconds.
* Attempts to reconnect if disconnected.
*/
mqttClient = new MQTTClient({
broker: "mqtts://mysecuremqtt.example.com",
username: "user1",
password: "secret1",
timeout: 30,
onDisconnect: function(event) {
Logger.info("lost MQTT connection: " + event.reason);
// try to reconnect after 5 second timeout
setTimeout(function() { mqttClient.connect(); }, 5000);
}
});
mqttClient.connect();
WLEvent.on("Scan", function(event) {
if(mqttClient.connected) {
mqttClient.publish({
topic: "scan/" + (Device.getDeviceSerial() || Device.getVelocityId()),
qos: 0,
payload: event.data
});
}
});