node-mqtt-smarthome-connect

Node module for MQTT-Smarthome

This Module is a wrapper around MQTT.js adding extra functionality to ease the handling of topics and payloads following the mqtt-smarthome architecture proposal.

Usage

$ npm install mqtt-smarthome-connect --save

const mqsh = new MqttSmarthome('mqtt://localhost', {
    will: {topic: 'foo/maintenance/online', payload: 'false', retain: true}
});

mqsh.on('connect', () => {
    mqsh.publish('foo/maintenance/online', true, {retain: true});
});
mqsh.connect();

mqsh.subscribe('foo/+/bar', (topic, message, wildcardMatch, rawPacket) => {
    console.log('received', wildcardMatch[0], message)
});

mqsh.publish('foo/boolean/bar', true);
mqsh.publish('foo/intNumber/bar', 42);
mqsh.publish('foo/floatNumber/bar', 3.1415);
mqsh.publish('foo/string/bar', 'A string.');
mqsh.publish('foo/array/bar', [1, 2, 3]);
mqsh.publish('foo/object/bar', {val: 42, ts: Date.now()});

See examples for more.

API

Classes

MqttSmarthome

Typedefs

messageCallback : function

MqttSmarthome

Kind: global class

• MqttSmarthome
  • new MqttSmarthome([mqttUrl], [options])
  • .sub : MqttSmarthome.subscribe
  • .pub : MqttSmarthome.publish
  • .connect()
  • .end([force], [callback])
  • .reconnect()
  • .subscribe(topic, [callback]) ⇒ idSubscription
  • .unregisterCallback(id) ⇒ number
  • .unsubscribe(topic, [callback])
  • .publish(topic, payload, [options], [callback])
  • "connect"
  • "close"
  • "error"
  • "offline"
  • "reconnect"
  • "message" (topic, payload, packet,)

new MqttSmarthome([mqttUrl], [options])

Params

• [mqttUrl] string = "mqtt://localhost"
• [options] object - see all available options in the MQTT.js docs
  • [.logger] object
  • [.globalOptions] object - that'll overwrite options given in publish(topic, payload, options, callback)
  • [.clientId] string = "mqttsmarthome-<random>"

mqttSmarthome.sub : MqttSmarthome.subscribe

Just a convenience alias to subscribe

Kind: instance property of MqttSmarthome

mqttSmarthome.pub : MqttSmarthome.publish

Just a convenience alias to publish

Kind: instance property of MqttSmarthome

mqttSmarthome.connect()

Kind: instance method of MqttSmarthome

mqttSmarthome.end([force], [callback])

Disconnect from the MQTT broker.

Kind: instance method of MqttSmarthome
Params

• [force] boolean = false - passing it to true will close the client right away, without waiting for the in-flight messages to be acked.
• [callback] function - will be called when the client is closed.

mqttSmarthome.reconnect()

Reconnect to the MQTT broker.

Kind: instance method of MqttSmarthome

mqttSmarthome.subscribe(topic, [callback]) ⇒ idSubscription

Kind: instance method of MqttSmarthome
Returns: idSubscription - id
Params

• topic string
• [callback] messageCallback =

mqttSmarthome.unregisterCallback(id) ⇒ number

Unregister a callback. If no registered callback on the corresponding topic is left a MQTT unsubscribe will be done.

Kind: instance method of MqttSmarthome
Returns: number - remaining number of subscription on that topic
Params

• id idSubscription - an id that was returned by the subscribe() method.

mqttSmarthome.unsubscribe(topic, [callback])

Unsubscribe a whole topic with all its callbacks.

Kind: instance method of MqttSmarthome
Params

• topic string
• [callback] function

mqttSmarthome.publish(topic, payload, [options], [callback])

Publish a MQTT message. Payloads that are neither of type string nor an instance of Buffer will be JSON stringified.

Kind: instance method of MqttSmarthome
Params

• topic string
• payload *
• [options] object
  • [.qos] number = 0 - QoS level
  • [.retain] boolean = false - Retain Flag
  • [.dup] boolean = false - Mark as duplicate flag
• [callback] function - Fired when the QoS handling completes, or at the next tick if QoS 0. An error occurs if client is disconnecting.

"connect"

Kind: event emitted by MqttSmarthome

"close"

Kind: event emitted by MqttSmarthome

"error"

Kind: event emitted by MqttSmarthome

"offline"

Kind: event emitted by MqttSmarthome

"reconnect"

Kind: event emitted by MqttSmarthome

"message" (topic, payload, packet,)

Kind: event emitted by MqttSmarthome
Params

• topic string
• payload string
• packet, Mqtt.packet - see https://github.com/mqttjs/mqtt-packet#publish

messageCallback : function

Kind: global typedef
Params

• topic string
• payload string | number | boolean | object
• [wildcardMatch] array - If subscription was example/+/foo/bar this array contains the "+" in topic string
• packet Mqtt.packet

License

MIT © Simon Christmann, Sebastian Raff and Contributors