connection

MqttConnection

Introduction

The MqttConnection class represents a raw MQTT connection, both on the server and on the client side. For client side operations, it is strongly recommended that MqttClient is used, as MqttConnection requires a great deal of additional boilerplate such as setting up error handling and ping request/responses.

If such fine grained control is required, MqttConnection can be instantiated using the mqtt.createConnection method.

MqttServerClient is an unaltered subclass of MqttConnection and can be used in exactly the same way.

Example

var mqtt = require('mqtt');
var conn = mqtt.createConnection(
    1883, 
    'localhost', 
    function(err, client) {
  if (err) throw err;

  client.connect({
    protocolId: 'MQIsdp',
    protocolVersion: 3,
    clientId: 'example',
    keepalive: 30000
  });

  client.on('connack', function(packet) {
    if (packet.returnCode !== 0) {
      throw 'Connect error'
    }
    client.publish({
      topic: 'example',
      payload: new Buffer('example', 'utf8')
    });
  });
});

MqttConnection

Invalid arguments to the methods below will cause MqttConnection to emit error events, which, if unhandled, will cause the program to terminate.

For all events below packet will also contain all of the information contained in the MQTT static header. This includes cmd, dup, qos and retain even when they do not apply to the packet. It will also contain the length of the packet.

###client.connect([options]) Send an MQTT connect packet.

options supports the following properties:

• protocolId: Protocol ID, usually MQIsdp. string
• protocolVersion: Protocol version, usually 3. number
• keepalive: keepalive period. number
• clientId: client ID. string
• will: the client's will message options. object that supports the following properties:
  • topic: the will topic. string
  • payload: the will payload. string
  • qos: will qos level. number
  • retain: will retain flag. boolean
• clean: the 'clean start' flag. boolean
• username: username for protocol v3.1. string
• password: password for protocol v3.1. string

###client.connack([options]) Send an MQTT connack packet.

options supports the following properties:

• returnCode: the return code of the connack, success is indicated by 0. number

###client.publish([options]) Send an MQTT publish packet.

options supports the following properties:

• topic: the topic to publish to. string
• payload: the payload to publish, defaults to an empty buffer. string or buffer
• qos: the quality of service level to publish on. number
• messageId: the message ID of the packet, required if qos > 0. number
• retain: retain flag. boolean

###client.['puback', 'pubrec', 'pubcomp', 'unsuback']([options]) Send an MQTT [puback, pubrec, pubcomp, unsuback] packet.

options supports the following properties:

• messageId: the ID of the packet

###client.pubrel([options]) Send an MQTT pubrel packet.

options supports the following properties:

• dup: duplicate message flag
• messageId: the ID of the packet

###client.subscribe([options]) Send an MQTT subscribe packet.

options supports the following properties:

• dup: duplicate message flag
• messageId: the ID of the packet
• subscriptions: a list of subscriptions of the form [{topic: a, qos: 0}, {topic: b, qos: 1}]

###client.suback([options]) Send an MQTT suback packet.

options supports the following properties:

• granted: a vector of granted QoS levels, of the form [0, 1, 2]
• messageId: the ID of the packet

###client.unsubscribe([options]) Send an MQTT unsubscribe packet.

options supports the following properties:

• messageId: the ID of the packet
• dup: duplicate message flag
• unsubscriptions: a list of topics to unsubscribe from, of the form ["topic1", "topic2"]

###client.['pingreq', 'pingresp', 'disconnect']() Send an MQTT [pingreq, pingresp, disconnect] packet.

###Event: 'connected' function() {}

Emitted when the socket underlying the MqttConnection is connected.

Note: only emitted by clients created using mqtt.createConnection().

###Event: 'connect' function(packet) {}

Emitted when an MQTT connect packet is received by the client.

packet is an object that may have the following properties:

• version: the protocol version string

• versionNum: the protocol version number

• keepalive: the client's keepalive period

• client: the client's ID

• will: an object of the form:

  { "topic": "topic", "payload": "payload", "retain": false, "qos": 0 }

  where topic is the client's will topic, payload is its will message, retain is whether or not to retain the will message and qos is the QoS of the will message.

• clean: clean start flag

• username: v3.1 username

• password: v3.1 password

###Event: 'connack' function(packet) {}

Emitted when an MQTT connack packet is received by the client.

packet is an object that may have the following properties:

• returnCode: the return code of the connack packet

###Event: 'publish' function(packet) {}

Emitted when an MQTT publish packet is received by the client.

packet is an object that may have the following properties:

• topic: the topic the message is published on
• payload: the payload of the message
• messageId: the ID of the packet
• qos: the QoS level to publish at

###Events: ['puback', 'pubrec', 'pubrel', 'pubcomp', 'unsuback'] function(packet) {}

Emitted when an MQTT [puback, pubrec, pubrel, pubcomp, unsuback] packet is received by the client.

packet is an object that may contain the property:

• messageId: the ID of the packet

###Event: 'subscribe' function(packet) {}

Emitted when an MQTT subscribe packet is received.

packet is an object that may contain the properties:

• messageId: the ID of the packet
• subscriptions: a list of topics and their requested QoS level, of the form [{topic: 'a', qos: 0},...]

###Event: 'suback' function(packet) {}

Emitted when an MQTT suback packet is received.

packet is an object that may contain the properties:

• messageId: the ID of the packet
• granted: a vector of granted QoS levels

###Event: 'unsubscribe' function(packet) {}

Emitted when an MQTT unsubscribe packet is received.

packet is an object that may contain the properties:

• messageId: the ID of the packet
• unsubscriptions: a list of topics the client is unsubscribing from, of the form [topic1, topic2, ...]

###Events: ['pingreq', 'pingresp', 'disconnect'] function(packet){}

Emitted when an MQTT [pingreq, pingresp, disconnect] packet is received.

packet is an empty object and can be ignored.