npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

web-mqtt-client

v1.3.1

Published

A better MQTT API for the browser

Downloads

43

Readme

web-mqtt-client

A better MQTT API for the browser

web-mqtt-client is a wrapper around the Eclipse Paho MQTT javascript client, and offers an improved programmatic API somewhat similar to MQTT.js in a much smaller package than the latter browserified. Further improvements will also be implemented as this library matures (see Roadmap below).

An example of this library in use is available on gh-pages, source code and resources for the example under the demo/ folder.

Installation

$ npm install web-mqtt-client
$ bower install web-mqtt-client

In addition to mqtt-client.js, you will also need to add mqttws31.js from Eclipse Paho to your html, eg.

<script src="path/to/mqttws31.js"></script>
<script src="path/to/mqtt-client.js"></script>

mqtt-client.js expects the globals from Eclipse Paho to be available when initialized, so the order of evaluation matters. When the scripts have been evaluated, web-mqtt-client is available through the MqttClient global.

Usage

An MQTT client is intialized with the call to new MqttClient with a configuration object. The configuration object is required to contain host and port, but accepts multiple other values:

| Parameter | Mandatory | Type | Default | |:--------------|:----------|:--------------|:----------| | host | required | String | | | port | required | Number | | | clientId | optional | String | generated | | timeout | optional | Number | 10 | | keepalive | optional | Number | 30 | | mqttVersion | optional | Number [3,4] | | | username | optional | String | | | password | optional | String | | | ssl | optional | boolean | | | clean | optional | boolean | | | will | optional | Object | | | reconnect | optional | Number | undefined |

reconnect is the time to wait in milliseconds before trying to connect if a client loses its connection to the broker. If not defined, automatic reconnection is disabled.

Some further details for the parameters can be found in the Paho documentation.

Example:

var client = new MqttClient({
  host : 'some.domain.tld/mqtt',
  port : 5678,
  will : {
    topic   : 'farewells',
    payload : 'So long!',
  }
});

The will object is specified as follows and has the typical MQTT message attributes

| field | Mandatory | Type | Default | |:----------|:----------|:----------------------|:----------| | topic | required | String | | | payload | required | String or ArrayBuffer | | | qos | optional | Number [0,1,2] | 0 | | retain | optional | boolean | false |

Client API

A client var client = new MqttClient(opts) initialized as above will have

Fields:

client.connected : boolean

Simplified connection state, ie. true if connected or false otherwise. If you need more detailed connection state tracking, this can be implemented by attaching callbacks to connection lifecycle events (see below).

Methods:

client.connect() ⇒ client

Connect client to the broker specified in the configuration object.

client.disconnect() ⇒ undefined

Disconnect from the currently connected broker.

client.subscribe(topic, function callback(error, granted) { }) ⇒ undefined

client.subscribe(topic, qos, function callback(error, granted) { }) ⇒ undefined

Subscribe to topic. qos and callback are optional, if two parameters are used the second one is assumed to be a callback function and the default QoS 0 is used. Note that if QoS 0 is passed, the broker does not actually acknowledge receiving the subscription message, so the callback firing essentially only means that the Paho library has processed the function call.

The callback function parameter error is the error object returned by Paho, and granted is the QoS level (0,1 or 2) granted by the broker.

client.unsubscribe(topic, function callback (error) { }) ⇒ undefined

Unsubscribe from topic. The optional callback will be fired when the broker acknowledges the request.

The callback function gets a single error parameter if something went wrong, containing the error object returned by Paho.

client.publish(topic, payload, options, callback) ⇒ undefined

Publish payload to topic, callback will be fired when the broker acknowledges the request. NB. if qos is 0 and a callback is provided functionality is identical to the subscribe callback. The callback getting triggered may also be broker-dependant, so verify the functionality before depending on a callback being fired.

options are optional and can specify the following:

{
    qos    : <optional> - default 0,
    retain : <optional> - default false,
}

The following event methods are used to attach callbacks to the events specified in the next section.

client.bind(event, callback) ⇒ client

Attaches callback to be called whenever event is triggered by the library. See Events below for possible events.

client.on(event, callback) ⇒ client

Synonym for client.bind.

client.unbind(event, callback) ⇒ client

De-register callback from being called when event is triggered. Previously registered callbacks must be named variables for this to work, otherwise the method will fail silently.

client.once(event, callback) ⇒ client

Just like bind/on, but is automatically de-registered after being called.

Messages API

The client has a utility API that compliments the client.on('message', callback) pattern.

client.messages.bind(topic, qos, callback, force) ⇒ client

Attaches callback to be called whenever a message arrives that match the MQTT topic. The topic string supports both MQTT wildcard characters, so it can be used fairly flexibly, but verify that your usecase is covered with client.convertTopic(). qos and force parameters are optional, if not supplied qos is 0. By default, a MQTT subscribe signal is not sent to the broker if there is already a callback registered with the Messages API that has the same exact string as its topic (wildcard matching is not attempted), force can be used to cirumvent this behavior f.e. when qos should change or similar.

client.messages.on(topic, qos, callback, force) ⇒ client

Synonym for client.messages.bind.

client.messages.unbind(callback) ⇒ client

De-register callback from being called when incoming messages that matches its topic arrive. Previously registered callbacks must be named variables for this to work, otherwise the method will fail silently. For correct functionality, it's also important that the topic property added to callback in subscribe is not modified elsewhere in code (it should match the string passed when the callback was attached).

Utils:

client.convertTopic(topic) ⇒ RegEx

Converts string topic to a matching regular expression that supports the MQTT topic wildcards (# and +), used internally. The implementation is not bullet-proof, see tests and verify that the functionality matches your use-case.

Events:

The client emits the following events

  • 'connecting': client has started connecting to a broker
  • 'connect': client has successfully connected to broker
  • 'disconnect': client was disconnected from broker for whatever reason
  • 'offline': client is disconnected and no automatic reconnection attempts will be made
  • 'message': client received an MQTT message

As outlined above, callbacks can be attached to these events through client.on or client.bind and removed with client.unbind.

client
  .on('connecting', function() { console.log('connecting...'); })
  .on('connect',    function() { console.log("hooraah, I'm connected"); })
  .on('disconnect', function() { console.log('oh noes!'); })
  .on('offline',    function() { console.log('stopped trying, call connect manually'); });

client.on('message', console.log.bind(console, 'MQTT message arrived: '));

The callback attached to the message event has the following signature

client.on('message', function handleMessage(topic, payload, details) {
  // ..
});
  • payload is either the UTF-8 encoded String in the message if parsed by Paho, or the payload as an ArrayBuffer
  • details is an object containing
{
    topic     : /* String */,
    qos       : /* 0 | 1 | 2 */,
    retained  : /* boolean  */,
    payload   : /* payloadBytes */,
    duplicate : /* boolean */,
}

The meaning of the fields are explained in the Paho documentation.

Colophon

The event emitter pattern that web-mqtt-client uses is based on microevent.js.

License

web-mqtt-client is ISC licensed.

Roadmap & Changelog

1.3.1

  • [x] fix for #3, throwing errors when trying to parse some string messages

1.3.0

  • [x] Messages API automatically subscribes and unsubscribes from topics
  • [x] filter subscription/unsubscription calls to broker if topic has other callbacks
  • [x] can manually force subscribe or unsubscribe calls using Messages API

1.2.1

  • [x] fix for #2 Cannot send retained messages using MqttClient's publish method

1.2.0

  • [x] separate messages event API
  • [x] MQTT topic regex support

1.1.0

  • [x] automatic reconnection interval
  • [x] extended connection lifecycle callbacks
  • [ ] ~~optional logging support~~ dropped, since it's currently easy to attach logging to callbacks if needed
  • [x] integration tests against Mosca

1.0.1

  • [x] improve test coverage
  • [x] fix publish API (call w/o payload, options, callback)
  • [x] subscribe API (document callback, callback this reference)
  • [x] unsubscribe API (document callback, callback this reference)

1.0.0

  • [x] unit test setup
  • [x] CI test configuration (travis)
  • [x] eslint configuration
  • [x] test coverage x
  • [x] lightweight API documentation
  • [x] publish demo to gh-pages

0.9.0

  • [x] randomly generated clientIds
  • [x] subscribe / unsubscribe API
  • [x] event for incoming messages
  • [x] publish API
  • [x] lwt support
  • [x] minfied build
  • [x] public release npm/bower

Future

  • [ ] ~~reconnection callback~~ abandoned, can easily be implemented with attaching a function that calls client.connect() to the offline event
  • [ ] better example in README
  • [ ] rewrite Paho Errors
  • [ ] proper linting config
  • [ ] test coverage x
  • [ ] ~~filter sub/unsub is QoS-aware~~
  • [ ] ~~automatic resubscription of topics on reconnect~~
  • [ ] optimize compression
  • [ ] provide sourcemaps

Notes

  • Paho documentation http://www.eclipse.org/paho/files/jsdoc/index.html
  • promise support for methods? or example for wrapping
  • publish callback if qos 0 is essentially nothing more than a message that message has been delivered to Paho lib...
  • piggyback on Paho error reporting or do own validation?