HiveMQ Logo
Paho JavaScript - MQTT Client Library Encyclopedia

Paho JavaScript - MQTT Client Library Encyclopedia

author portrait

Written by James Sutton

Category: MQTT MQTT Client MQTT Client Library

Published: November 16, 2015


Short info

Paho JavaScript
Language JavaScript
License Eclipse Public Licence
Website eclipse.org/paho/
API Style Asynchronous

Description

The Eclipse Paho project provides a number of open-source clients of the MQTT and MQTT-SN messaging protocols. The Paho JavaScript client is a browser based library that takes advantage of WebSockets to connect to an MQTT Broker. The Library was originally authored by Andrew Banks at IBM and was donated to Eclipse by IBM in 2013.

The library is considered to be very stable and is used in many MQTT based web applications. It’s also available to use via a GUI on the Eclipse Paho website as well as HiveMQ’s very own Websocket-Client. By using WebSockets, the JavaScript library allows developers to take advantage of MQTT without having to worry about port 1883 being blocked, they can simply point it at a WebSocket enabled MQTT Broker on port 80 and they are ready to go.

Features

Feature
MQTT 3.1 ok
MQTT 3.1.1 ok
LWT ok
SSL/TLS ok
Automatic Reconnect nok
Feature
QoS 0 ok
QoS 1 ok
QoS 2 ok
Authentication ok
Throttling nok

Usage

Installation

The JavaScript Paho library is available as a download from the project page and is all that is required to use it in your project. Once downloaded, simply include it in your HTML file using the script tags:

<script src="mqttws31.js">
</script>

Connect

Connecting to a broker is relatively simple with the JavaScript client, a basic example is shown below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// Create a client instance: Broker, Port, Websocket Path, Client ID
client = new Paho.MQTT.Client("iot.eclipse.org", Number(80), "/ws", "clientId");

// set callback handlers
client.onConnectionLost = function (responseObject) {
    console.log("Connection Lost: "+responseObject.errorMessage);
}

client.onMessageArrived = function (message) {
  console.log("Message Arrived: "+message.payloadString);
}

// Called when the connection is made
function onConnect(){
	console.log(“Connected!”);
}

// Connect the client, providing an onConnect callback
client.connect({
	onSuccess: onConnect
});

Connect with MQTT 3.1 or MQTT 3.1.1

By default, the standard action is to connect using MQTT 3.1.1, however if that fails, you could fall back and try to connect as MQTT 3.1. This is managed from the connectOptions object.

3 - MQTT 3.1 4 – MQTT 3.1.1

1
2
3
4
5

// Connect the client, using MQTT 3.1
client.connect({
	onSuccess: onConnect, 
	mqttVersion: 3
});

Connect with LWT

In order to use the really handy Last-Will-and-Testament feature of MQTT, we can use the same options object as in previous examples.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Connect the client, with a Last-Will-and-Testament
var lwt = new Paho.MQTT.Message(“payload”);
lwt.destinationName = “topic”;
lwt.qos = 0;
lwt.retained = false;

client.connect({
	onSuccess: onConnect, 
	willMessage = lwt
});

Connect with Username / Password

The JavaScript client can also authenticate using a Username and Password.

1
2
3
4
5
6

// Connect the client, with a Username and Password
client.connect({
	onSuccess: onConnect, 
	userName : “Username”,
	password : “password”
});

Publish

Once you are connected to the MQTT broker, you are able to publish a message. This is fairly straight forward and can be done as such:

1
2
3
4
5
6

// Publish a Message
var message = new Paho.MQTT.Message(“Message Payload”);
message.destinationName = “topic”;
message.qos = 0;

client.send(message);

Although destinationName is required, qos is optional. If not supplied, qos will default to 0

Publish a retained message

Publishing a retained message is very simple too, just set retained to true.

1
2
3
4

// Publish a Message
var message = new Paho.MQTT.Message(“Message Payload”);
message.destinationName = “topic”;
message.retained = true;

Subscribe

Subscribing to a topic can be done with this one liner:

1

client.subscribe(“topic”);

When a message arrives, the onMessageArrived Callback will be called with a MQTT Message object. You can use it like this:

1
2
3
4
5
6
7
8

client.onMessageArrived = function (message) {
  console.log("Message Arrived: " + message.payloadString);
  console.log(“Topic:     “ + message.destinationName);
  console.log(“QoS:       “ + message.qos);
  console.log(“Retained:  “ + message.retained);
  // Read Only, set if message might be a duplicate sent from broker
  console.log(“Duplicate: “ + message.duplicate);
}

You can also set more advanced options when subscribing:

1
2
3
4
5
6
7
8

var subscribeOptions = {
	qos: 0,  // QoS
	invocationContext: {foo: true},  // Passed to success / failure callback
	onSuccess: onSuccessCallback,
	onFailure: onFailureCallback,
	timeout: 10
};
client.subscribe(“topic”, subscribeOptions);

Unsubscribe

Unsubscribing is equally as simple as subscribing:

client.unsubscribe(“topic”);

You can also set more advanced options when unsubscribing:

1
2
3
4
5
6
7

var unsubscribeOptions = {
	invocationContext: {foo: true},  // Passed to success / failure callback
	onSuccess: onSuccessCallback,
	onFailure: onFailureCallback,
	timeout: 10
};
client.unsubscribe (“topic”, unsubscribeOptions);

Disconnect

Disconnecting is done like this:

client.disconnect();

Using SSL / TLS

Connecting to your broker using TLS is also very straight forward. Make sure that you’ve set the port to your Brokers TLS / WebSocket port, then set the useSSL setting in the connectOptions:

1
2
3
4
5

// Connect the client, with a Username and Password
client.connect({
	onSuccess: onConnect, 
	useSSL: true
});

Keep in mind that as the browser manages external connections, you may receive an error in the console if the Certificate is not trusted.

Example application

Below is a very simple JavaScript application that will subscribe to the topic /World, the publish the Message 'Hello' to it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// Create a client instance
client = new Paho.MQTT.Client(location.hostname, Number(location.port), "clientId");

// set callback handlers
client.onConnectionLost = onConnectionLost;
client.onMessageArrived = onMessageArrived;

// connect the client
client.connect({onSuccess:onConnect});

// called when the client connects
function onConnect() {
  // Once a connection has been made, make a subscription and send a message.
  console.log("onConnect");
  client.subscribe("/World");
  message = new Paho.MQTT.Message("Hello");
  message.destinationName = "/World";
  client.send(message); 
}

// called when the client loses its connection
function onConnectionLost(responseObject) {
  if (responseObject.errorCode !== 0) {
    console.log("onConnectionLost:"+responseObject.errorMessage);
  }
}

// called when a message arrives
function onMessageArrived(message) {
  console.log("onMessageArrived:"+message.payloadString);
}

Thanks for this guest blog post by James Sutton | IBM

About James Sutton

I work for IBM in the Internet of Things Foundation team. I’m a contributor on the Eclipse Paho Project, mainly working on the Java, Android and JavaScript Clients
newer posts Paho Android Service - MQTT Client Library Encyclopedia
Paho Go - MQTT Client Library Encyclopedia older posts