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.