mqtt-packet

What is mqtt-packet?

The mqtt-packet npm package is a utility for encoding and decoding packets used in MQTT (Message Queuing Telemetry Transport), which is a lightweight messaging protocol for small sensors and mobile devices. It is designed for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium.

What are mqtt-packet's main functionalities?

Parsing MQTT Packets

This feature allows you to parse MQTT packets from a buffer. The code sample demonstrates how to create a parser instance, listen for 'packet' events, and parse a buffer containing an MQTT packet.

const mqttPacket = require('mqtt-packet');
const parser = mqttPacket.parser();
parser.on('packet', function(packet) {
  console.log(packet);
});
parser.parse(Buffer.from([0x30, 0x02, 0x00, 0x00]));

Generating MQTT Packets

This feature allows you to generate MQTT packets. The code sample shows how to create an MQTT packet object and then generate a buffer that can be sent over a network.

const mqttPacket = require('mqtt-packet');
const packet = {
  cmd: 'publish',
  messageId: 42,
  topic: 'test/topic',
  payload: 'test payload',
  qos: 0,
  retain: false
};
const buffer = mqttPacket.generate(packet);
console.log(buffer);

Other packages similar to mqtt-packet

mqtt

The 'mqtt' package is a client library for the MQTT protocol. It provides an API for connecting to an MQTT broker, publishing messages, and subscribing to topics. It is more feature-rich than mqtt-packet as it includes the full client functionality, not just packet encoding and decoding.

mqtt-connection

The 'mqtt-connection' package is a barebone connection package for MQTT that can be used when implementing an MQTT client or server. It provides a simple stream interface for sending and receiving MQTT packets over a network. It is similar to mqtt-packet but includes stream handling capabilities.

aedes-packet

The 'aedes-packet' package is a fork of mqtt-packet, which is used by the Aedes MQTT broker. It has similar functionalities to mqtt-packet but is tailored to work seamlessly with the Aedes broker ecosystem.

README

mqtt-packet   

Encode and Decode MQTT packets the node way.

• Installation
• Examples
• Packets
• API
• Licence & copyright

Acknowledgements

This library has been extracted and refactored from MQTT.js. Thanks Adam Rudd for the great module.

Installation

npm install mqtt-packet --save

Examples

Generating

var mqtt    = require('mqtt-packet')
  , object  = {
        cmd: 'publish'
      , retain: false
      , qos: 0
      , dup: false
      , length: 10
      , topic: 'test'
      , payload: 'test'
    }

console.log(mqtt.generate(object))
// prints
// <Buffer 30 0a 00 04 74 65 73 74 74 65 73 74>
//
// the same as
//
// new Buffer([
//   48, 10, // Header
//   0, 4, // Topic length
//   116, 101, 115, 116, // Topic (test)
//   116, 101, 115, 116 // Payload (test)
// ])

Parsing

var mqtt      = require('mqtt-packet')
  , parser    = mqtt.parser()

// synchronously emits all the parsed packets
parser.on('packet', function(packet) {
  console.log(packet)
  // prints:
  //
  // {
  //     cmd: 'publish'
  //   , retain: false
  //   , qos: 0
  //   , dup: false
  //   , length: 10
  //   , topic: 'test'
  //   , payload: 'test'
  // }
})

parser.parse(new Buffer([
  48, 10, // Header
  0, 4, // Topic length
  116, 101, 115, 116, // Topic (test)
  116, 101, 115, 116 // Payload (test)
])
// returns the number of bytes left in the parser

API

• mqtt#generate()
• mqtt#parser()

### mqtt.generate(object)

Generates a Buffer containing an MQTT packet. The object must be one of the ones specified by the packets section. Throws an Error if a packet cannot be generated.

### mqtt.parser(opts)

Returns a new Parser object. Parser inherits from EventEmitter and will emit:

• packet, when a new packet is parsed, according to packets
• error, if an error happens

The only allowed option is { encoding: 'binary' } which will block the automatic parsing of all the strings in the package. Instead, the strings will remain 'raw', i.e. a Buffer.

#### Parser.parse(buffer)

Parse a given Buffer and emits synchronously all the MQTT packets that are included. Returns the number of bytes left to parse.

Packets

This section describes the format of all packets emitted by the Parser and that you can input to generate.

Connect

{
    cmd: 'connect'
  , protocolId: 'MQTT' // or 'MQIsdp' in MQTT 3.1.1
  , protocolVersion: 4 // or 3 in MQTT 3.1
  , clean: true // or false
  , clientId: 'my-device'
  , keepalive: 0 // seconds, 0 is the default, can be any positive number
  , username: 'matteo'
  , password: 'collina'
  , will: {
        topic: 'mydevice/status'
      , payload: 'dead'
    }
}

The only mandatory argument is clientId, as generate will throw if missing.

Connack

{
    cmd: 'connack'
  , returnCode: 0 // or whatever else you see fit
}

The only mandatory argument is returnCode, as generate will throw if missing.

Subscribe

{
    cmd: 'subscribe'
  , messageId: 42
  , subscriptions: [{
        topic: 'test'
      , qos: 0
    }]
}

All properties are mandatory.

Suback

{
    cmd: 'suback'
  , messageId: 42
  , granted: [0, 1, 2, 128]
}

All the granted qos must be < 256, as they are encoded as UInt8. All properties are mandatory.

Unsubscribe

{
    cmd: 'unsubscribe'
  , messageId: 42
  , unsubscriptions: [
        'test'
      , 'a/topic'
    ]
}

All properties are mandatory.

Unsuback

{
    cmd: 'unsuback'
  , messageId: 42
}

All properties are mandatory.

Publish

{
    cmd: 'publish'
  , messageId: 42
  , qos: 2
  , dup: false
  , topic: 'test'
  , payload: 'test'
  , retain: false
}

Only the topic and properties are mandatory Both topic and payload can be Buffer objects instead of strings. messageId is mandatory for qos > 0.

Puback

{
    cmd: 'puback'
  , messageId: 42
}

The only mandatory argument is messageId, as generate will throw if missing.

Pubrec

{
    cmd: 'pubcomp'
  , messageId: 42
}

The only mandatory argument is messageId, as generate will throw if missing.

Pubrel

{
    cmd: 'pubrel'
  , messageId: 42
}

The only mandatory argument is messageId, as generate will throw if missing.

Pubcomp

{
    cmd: 'pubcomp'
  , messageId: 42
}

The only mandatory argument is messageId, as generate will throw if missing.

Pingreq

{
  cmd: 'pingreq'
}

Pingresp

{
  cmd: 'pingresp'
}

Disconnect

{
  cmd: 'pingresp'
}

License

MIT