WolkAbout WolkSocket library

Node.js/Web client library for using WolkAbout MQTT Broker API.

Getting Started

Installation

This library is distributed on npm. In order to add it as a dependency, run the following command:

$ npm install @wolkabout/wolk-socket

Usage

Connecting

Create a new instance of the WolkSocket with your url, port and apiBaseUrl.

const socket = new WolkSocket({
  url: 'https://websockets-demo.wolkabout.com',
  port: 9002,
  apiBaseUrl: 'https://api-demo.wolkabout.com',
  backgroundTask: true,
  worker: new Worker(),
  maxReconnectAttempts: 7,
  path: '/mqtt',
  logRawMessages: true,
  logSubscribedMessages: true,
  useSSL: true
});

socket
  .connect({
    token: 'YOUR_TOKEN',
    userId: 'YOUR_USER_ID'
  })
  .then(() => {
    socket.subscribeToFeeds(feedIds, message => {
      console.log(message);
    });
  });

• url: WolkAbout MQTT Broker API URL
• port: WolkAbout MQTT Broker API port
• apiBaseUrl: WolkAbout REST API URL
• backgroundTask: If set to true, MQTT client is created inside a Web Worker instance, so it's run in a separate thread, improving performance significantly.
• token: OAUTH2 access token, obtained by authenticating with WolkAbout REST API
• userId: ID of the currently logged in user, obtained by authenticating with WolkAbout REST API
• worker: Web worker instance, needs to be instantiated with 0.worker.js script (found inside dist directory)
• maxReconnectAttempts: [Optional] Number of times to retry connecting. Defaults to 7.
• path: [Optional] Path to MQTT Broker API. Defaults to /mqtt.
• logRawMessages: [Optional] If set to true, logs all messages received from the MQTT Broker to browser's console
• logSubscribedMessages: [Optional] If set to true, logs all raw messages which have a subscription, once for every callback
• useSSL: [Optional] Signals whether to use SSL for MQTT connections. Defaults to true

Subscribing to topics

Following topics are available: FEED, MESSAGE, ACTUATOR, ALARM, POINT. In order to subscribe to a topic, invoke one of the following methods:

• subscribeToFeeds
• subscribeToActuators
• subscribeToMessages
• subscribeToPoints
• subscribeToAlarms

Each method except subscribeToMessages, accepts two paramters: ids and callback. subscribeToMessages accepts only one parameter: callback. For example, if you wish to subscribe to FEED topic, you would invoke subscribeToFeeds like this:

socket.subscribeToFeeds(feedIds, message => {
  // do something when new FEED message is received
});

ids parameter specifies on which messages should the callback be invoked. Messages with id not in ids parameter will be dropped. callback callback to invoke after a message is received

Subscribe methods are synchronous. (No Promise is returned)

Unsubscribing from topics

In order to unsubscribe from a topic, invoke one of the following methods:

• unsubscribeFromFeeds
• unsubscribeFromActuators
• unsubscribeFromMessages
• unsubscribeFromPoints
• unsubscribeFromAlarms

After that, no messages from unsubscribed topic will be sent to WolkSocket. Unsubscribe methods are synchronous. (No Promise is returned)

Disconnecting

WolkSocket is disconnected by invoking the disconnect method, like this:

socket.disconnect();

disconnect method returns a Promise.

Access token refreshing

Every time the access token is refreshed, refreshToken method must be invoked, like this:

socket.refreshToken(newAccessToken);

refreshToken method returns a Promise. After the token is refreshed, WolkSocket will disconnect and then connect to the MQTT Broker API.

Angular

If you wish to use this library inside an Angular project, do the following:

1. Install worker-loader webpack plugin: npm install worker-loader
2. Add a new script called custom.d.ts with following content:

declare module 'worker-loader!*' {
  class WebpackWorker extends Worker {
    constructor();
  }

  export = WebpackWorker;
}

This will allow you to use webpack worker-loader.

3. Import worker script inside the script where you plan on using the WolkSocket library:

import Worker = require('worker-loader!../../node_modules/@wolkabout/wolk-socket/dist/0.worker');

../../node_modules/@wolkabout/wolk-socket/dist/0.worker is an example path to 0.worker.js script. In your app, the path may vary.

4. Create a new instance of Worker class and pass it as a parameter to the WolkSocket constructor:

const worker = new Worker();

const socket = new WolkSocket({
  url: 'https://websockets-demo.wolkabout.com',
  port: 9002,
  apiBaseUrl: 'https://api-demo.wolkabout.com',
  backgroundTask: true,
  worker
});

React

1. Install worker-loader webpack plugin: npm install worker-loader
2. Import worker script inside the script where you plan on using the WolkSocket library:

// eslint-disable-next-line
import Worker from 'worker-loader!../../node_modules/@wolkabout/wolk-socket/dist/0.worker';

../../node_modules/@wolkabout/wolk-socket/dist/0.worker is an example path to 0.worker.js script. In your app, the path may vary. // eslint-disable-next-line is important if you are using react-scripts to start/build your React application, since it does not allow inline webpack configuration. By adding this comment, you override that behavior.

3. Create a new instance of Worker class and pass it as a parameter to the WolkSocket constructor:

const worker = new Worker();

const socket = new WolkSocket({
  url: 'https://websockets-demo.wolkabout.com',
  port: 9002,
  apiBaseUrl: 'https://api-demo.wolkabout.com',
  backgroundTask: true,
  worker
});

IMPORTANT Due to current WebPack limitations, Web Workers cannot be used if Hot Module Replacement feature is enabled.

Contributing

Contributions are always welcome! Please read the contribution guidelines first.

• Contributing guide
• Code of Conduct

License

This library is licensed under Apache 2.0.