JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1259961
  • Score
    100M100P100Q195517F
  • License MIT

Parse and generate MQTT packets like a breeze

Package Exports

  • mqtt-packet

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (mqtt-packet) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

mqtt-packet   Build Status

Encode and Decode MQTT 3.1.1 packets the node way.

This library is tested with node v4 and v6. The last version to support older versions of node was mqtt-packet@4.1.2.

Install

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' // can also be a Buffer
    }

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: <Buffer 74 65 73 74>
  // }
})

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(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.writeToStream(object, stream)

Writes the mqtt packet defined by object to the given stream. The object must be one of the ones specified by the packets section. Emits an Error on the stream if a packet cannot be generated. On node >= 12, this function automatically calls cork() on your stream, and then it calls uncork() on the next tick.

### mqtt.parser()

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

 #### 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.

If an error happens, an error event will be emitted, but no packet events will be emitted after that. Calling parse() again clears the error and previous buffer as if you created a new Parser.

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: new Buffer('collina') // passwords are buffers
  , will: {
        topic: 'mydevice/status'
      , payload: new Buffer('dead') // payloads are buffers
    }
}

If protocolVersion is 3, clientId is mandatory and generate will throw if missing.

If password or will.payload are passed as strings, they will automatically be converted into a Buffer.

Connack

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

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: new Buffer('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.

If payload is passed to generate(packet) as a string, it will be automatically converted into a Buffer.

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'
}

Contributing

mqtt-packet is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the CONTRIBUTING.md file for more details.

Contributors

mqtt-packet is only possible due to the excellent work of the following contributors:

Matteo CollinaGitHub/mcollinaTwitter/@matteocollina
Adam RuddGitHub/adamvrTwitter/@adam_vr
Peter SorowkaGitHub/psorowkaTwitter/@psorowka

License

MIT