mqtt-client

mqtt-client is a kickass library which provide client and service to manage mqtt topics.

Pre-requisites

• node >= 6.0.0

Installation

npm install @telecomsante/mqtt-client

Client

A client can subscribe and publish to many topics.

Example

• Create, subscribe and listen to messages:

const MQTTClient = require('@telecomsante/mqtt-client').client;

const options = {
  url: 'mqtt://mosquitto',
  username: 'admin',
  password: 'admin'
};

const client = new MQTTClient(options);
client.on('message', (topic, value) => console.log('message', topic, value));
client.on('error', error => console.log('error', error));
client.subscribe(['terminal/vlc/#', 'terminal/sound/volume']);

• Send a value

client.setValue('terminal/test', 4);

• Close the client

client.close().then(() => console.log('close successfully'));

API

new MQTTClient(options)

Create a MQTTClient and connect to the mqtt server. For the options, take a look at https://github.com/mqttjs/MQTT.js#client

Default options:

const defaultOpts = {
  url: 'mqtt://localhost:1883',
  keepalive: 10000,
  clean: true
}

Event 'connect' -> function()

Emit when the client is connected to the mqtt server.

Event 'error' -> function(error)

Emit when a mqtt error appears.

Event 'close' -> function()

Emit after a mqtt disconnection

Event 'message' -> function(topic, value)

Emit when a value in the subscribed topics is changed.

client.subscribe([topics]) -> Promise

The client subscribes to the given topics.

MQTT topic wildcard characters are supported (+ - for single level and # - for multi level).

client.unsubscribe([topics]) -> Promise

The client unsubscribes to the given topics

client.setValue(topic, value) -> Promise

The client publishes the value to the request topic.

Example:

client.setValue('terminal/sound/volume', 50);

Will set the value in the req/terminal/sound/volume topic.

client.close(force) -> Promise

Close the current client connection

Service

A service manages two mqtt topics:

• A read only topic(terminal/sound/volume) for the clients.
• A request topic(req/terminal/sound/volume) for the clients.

The service subscribes to the change in the request topic and updates the read only topic at his convenience.

Example

• Create and listen to messages:

const MQTTService = require('@telecomsante/mqtt-client').service;

const options = {
  url: 'mqtt://mosquitto',
  username: 'admin',
  password: 'admin'
};

const jsonschema = {
  "type": "object",
  "properties": {
    "volume": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}

const service = new MQTTService(options, 'terminal/sound/#', jsonschema);
service.on('message', (key, value) => console.log('message', key, value));
service.on('error', error => console.log('error', error));

• Send a value

service.setValue('volume', 4);

By default, when a service send a value, this value is retained by the MQTT server. It may happen that we don't want the value to be retained, so in this case :

service.setValue('volume', 4, false);

• Close the service

service.close().then(() => console.log('close successfully'));

API

new MQTTService(options, topic, jsonSchema)

Create a MQTTService and connect to the mqtt server. For the options, take a look at https://github.com/mqttjs/MQTT.js#client

Default options:

const defaultOpts = {
  url: 'mqtt://localhost:1883',
  keepalive: 10000,
  clean: true
}

The service manages the topic with the terminal or companion prefixes.

The json schema represents the structure of the tree managed by the service

Event 'connect' -> function()

Emit when the service is connected to the mqtt server.

Event 'error' -> function(error)

Emit when a mqtt error appears.

Event 'close' -> function()

Emit after a mqtt disconnection

Event 'message' -> function(key, value)

Emit when a value in the request topic is changed.

If the req/terminal/sound/volume value is changed and the managed topic is req/terminal/sound/#:

key = 'sound'
value = the new value

service.setValue(key, value) -> Promise

The service publishes the value to the managed topic.

Example:

If the managed topic is req/terminal/sound/#

service.setValue('volume', 50);

Will set the value in the /terminal/sound/volume topic.

service.close(force) -> Promise

Close the current service connection

Development

Before commit, run the tests and the linter:

• Tests

npm run test

• linter

npm run lint