node-mqtt-client

MQTT Client

A Node.js MQTT client for managing secure MQTT connections with certificate-based authentication.

Features

• Connect to MQTT brokers securely using TLS/SSL.
• Manage certificates with a built-in certificate manager.
• Easily configure and handle MQTT connections, subscriptions, and messages.

Installation

Install the package via npm:

npm install node-mqtt-client

Libraries Used

This project makes use of the following libraries:

• fs: File system module to handle reading and writing of files.
• mqtt: MQTT.js library to handle MQTT connections and communication.
• node-forge: Library for creating and managing X.509 certificates.

Usage

Here's an example of how to use the MQTT client:

const { MQTTClient } = require('node-mqtt-client');

const mqttClient = new MQTTClient();
mqttClient.host = 'broker.fabris.io';
mqttClient.port = 8883;
mqttClient.hostProtocol = MQTTClient.Protocol.MQTTS;
mqttClient.certificateManager.loadCertificates(
  'authority.pem',
  'certificate.pem',
  'key.pem'
);
mqttClient.connect();

Configuration Parameters

Parameter	Type	Description	Default
host	string	The MQTT broker's host address.	'your-mqtt-broker-host'
port	number	The port to connect to on the MQTT broker.	8883
hostProtocol	string	The protocol to use (mqtt, mqtts, ws, wss).	mqtts

Public Methods

MQTTClient Methods

connect()

Connects to the MQTT broker using the loaded certificates.

Returns:
MQTTClient - The instance of MQTTClient.

subscribe(topic, options, callback)

Subscribes to a topic or topics on the MQTT broker.

• topic (string|string[]|Object): The topic(s) to subscribe to. Can be a single topic, an array of topics, or an object with topics as keys and QoS levels as values.
• options (Object): Optional parameters for the subscription.
  • qos (number): QoS level for the subscription (0, 1, or 2). Default is 0.
  • nl (boolean): No Local flag for MQTT 5.0. Default is false.
  • rap (boolean): Retain as Published flag for MQTT 5.0. Default is false.
  • rh (number): Retain Handling option for MQTT 5.0. Default is 0.
  • properties (Object): MQTT 5.0 properties object.
• callback (Function): The callback function to handle the subscription response.

Returns:
MQTTClient - The instance of MQTTClient.

unsubscribe(topic, options, callback)

Unsubscribes from a topic or topics on the MQTT broker.

• topic (string|string[]): The topic(s) to unsubscribe from. Can be a single topic (string) or an array of topics (string[]).
• options (Object): Optional parameters for the unsubscription.
  • nosuffix (boolean): If set to true, does not prepend the common name to the topic.
• callback (Function): The callback function to handle the unsubscription response. Called with (err, topic) parameters.

Returns:
MQTTClient - The instance of MQTTClient.

publish(topic, message, options, callback)

Publishes a message to a topic on the MQTT broker.

• topic (string): The topic to publish to.
• message (string|Buffer): The message to publish.
• options (Object): Optional parameters for publishing.
  • qos (number): QoS level (0, 1, or 2). Default is 0.
  • retain (boolean): Retain flag. Default is false.
  • dup (boolean): Mark as duplicate flag. Default is false.
  • properties (Object): MQTT 5.0 properties object.
• callback (Function): Callback called when QoS handling completes or an error occurs.

Returns:
MQTTClient - The instance of MQTTClient.

onMessage(callback)

Registers a callback for incoming messages.

• callback (Function): The callback function to handle incoming messages.

Returns:
MQTTClient - The instance of MQTTClient.

CertificateManager Methods

loadCertificates(ca, certificate, key)

Loads certificates from the specified paths.

• ca (string): Path to the CA certificate.
• certificate (string): Path to the client certificate.
• key (string): Path to the private key.

Returns:
CertificateManager - The instance of CertificateManager.

getCertificates()

Returns the loaded certificates.

Returns:
{ cert: Buffer, key: Buffer, ca: Buffer } - The loaded certificates.

Example

1. Subscribing to a Topic

Subscribe to a topic to receive messages:

mqttClient.subscribe('your/topic', { qos: 1 }, (err, granted) => {
    if (err) console.error('Subscription error:', err);
    // Anything you want
});

2. Publishing a Message

Publish a message to a specific topic:

mqttClient.publish('your/topic', 'Hello MQTT!', { qos: 1, retain: true }, (err) => {
    if (err) console.error('Error publishing message:', err);
    // Anything you want
});

3. Handling Incoming Messages

Register a callback to handle incoming messages:

mqttClient.onMessage((topic, message) => {
    console.log(`Received message on topic ${topic}: ${message.toString()}`);
    // Anything you want
});

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Paolo Fabris - Initial work - ubyte.it

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License. See the LICENSE file for details.