mqtt-packet
    TypeScript icon, indicating that this package has built-in type declarations

    7.1.1 • Public • Published

    mqtt-packet

    Encode and Decode MQTT 3.1.1, 5.0 packets the node way.

    JavaScript Style Guide

    This library is tested with node v6, v8, v10, v12 and v14. The last version to support older versions of node was mqtt-packet@4.1.2.

    Installation

    npm install mqtt-packet --save

    Examples

    Generating

    const mqtt = require('mqtt-packet');
    const object = {
      cmd: 'publish',
      retain: false,
      qos: 0,
      dup: false,
      length: 10,
      topic: 'test',
      payload: 'test' // Can also be a Buffer
    };
    const opts = { protocolVersion: 4 }; // default is 4. Usually, opts is a connect packet
    
    console.log(mqtt.generate(object))
    // Prints:
    //
    // <Buffer 30 0a 00 04 74 65 73 74 74 65 73 74>
    //
    // Which is the same as:
    //
    // Buffer.from([
    //   48, 10, // Header (publish)
    //   0, 4, // Topic length
    //   116, 101, 115, 116, // Topic (test)
    //   116, 101, 115, 116 // Payload (test)
    // ])

    Parsing

    const mqtt = require('mqtt-packet');
    const opts = { protocolVersion: 4 }; // default is 4. Usually, opts is a connect packet
    const parser = mqtt.parser(opts);
    
    // Synchronously emits all the parsed packets
    parser.on('packet', 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(Buffer.from([
      48, 10, // Header (publish)
      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, [opts])

    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, [opts])

    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 >= 0.12, this function automatically calls cork() on your stream, and then it calls uncork() on the next tick. By default cache for number buffers is enabled. It creates a list of buffers for faster write. To disable cache set mqtt.writeToStream.cacheNumbers = false. Should be set before any writeToStream calls.

    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

    Parser.parse(buffer)

    Parses 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 and 5.0
      protocolVersion: 4, // Or 3 in MQTT 3.1, or 5 in MQTT 5.0
      clean: true, // Can also be false
      clientId: 'my-device',
      keepalive: 0, // Seconds which can be any positive number, with 0 as the default setting
      username: 'matteo',
      password: Buffer.from('collina'), // Passwords are buffers
      will: {
        topic: 'mydevice/status',
        payload: Buffer.from('dead'), // Payloads are buffers
        properties: { // MQTT 5.0
          willDelayInterval: 1234,
          payloadFormatIndicator: false,
          messageExpiryInterval: 4321,
          contentType: 'test',
          responseTopic: 'topic',
          correlationData: Buffer.from([1, 2, 3, 4]),
          userProperties: {
            'test': 'test'
          }
        }
      },
      properties: { // MQTT 5.0 properties
          sessionExpiryInterval: 1234,
          receiveMaximum: 432,
          maximumPacketSize: 100,
          topicAliasMaximum: 456,
          requestResponseInformation: true,
          requestProblemInformation: true,
          userProperties: {
            'test': 'test'
          },
          authenticationMethod: 'test',
          authenticationData: Buffer.from([1, 2, 3, 4])
      }
    }

    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 MQTT < 5.0
      sessionPresent: false, // Can also be true.
      reasonCode: 0, // reason code MQTT 5.0
      properties: { // MQTT 5.0 properties
          sessionExpiryInterval: 1234,
          receiveMaximum: 432,
          maximumQoS: 2,
          retainAvailable: true,
          maximumPacketSize: 100,
          assignedClientIdentifier: 'test',
          topicAliasMaximum: 456,
          reasonString: 'test',
          userProperties: {
            'test': 'test'
          },
          wildcardSubscriptionAvailable: true,
          subscriptionIdentifiersAvailable: true,
          sharedSubscriptionAvailable: false,
          serverKeepAlive: 1234,
          responseInformation: 'test',
          serverReference: 'test',
          authenticationMethod: 'test',
          authenticationData: Buffer.from([1, 2, 3, 4])
      }
    }

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

    Subscribe

    {
      cmd: 'subscribe',
      messageId: 42,
      properties: { // MQTT 5.0 properties
        subscriptionIdentifier: 145,
        userProperties: {
          test: 'test'
        }
      }
      subscriptions: [{
        topic: 'test',
        qos: 0,
        nl: false, // no Local MQTT 5.0 flag
        rap: true, // Retain as Published MQTT 5.0 flag
        rh: 1 // Retain Handling MQTT 5.0
      }]
    }

    All properties are mandatory.

    Suback

    {
      cmd: 'suback',
      messageId: 42,
      properties: { // MQTT 5.0 properties
        reasonString: 'test',
        userProperties: {
          'test': 'test'
        }
      }
      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,
      properties: { // MQTT 5.0 properties
        userProperties: {
          'test': 'test'
        }
      }
      unsubscriptions: [
        'test',
        'a/topic'
      ]
    }

    All properties are mandatory.

    Unsuback

    {
      cmd: 'unsuback',
      messageId: 42,
      properties: { // MQTT 5.0 properties
        reasonString: 'test',
        userProperties: {
          'test': 'test'
        }
      }
    }

    All properties are mandatory.

    Publish

    {
      cmd: 'publish',
      messageId: 42,
      qos: 2,
      dup: false,
      topic: 'test',
      payload: Buffer.from('test'),
      retain: false,
      properties: { // optional properties MQTT 5.0
          payloadFormatIndicator: true,
          messageExpiryInterval: 4321,
          topicAlias: 100,
          responseTopic: 'topic',
          correlationData: Buffer.from([1, 2, 3, 4]),
          userProperties: {
            'test': 'test'
          },
          subscriptionIdentifier: 120, // can be an Array in message from broker, if message included in few another subscriptions
          contentType: 'test'
       }
    }

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

    Puback

    {
      cmd: 'puback',
      messageId: 42,
      reasonCode: 16, // only for MQTT 5.0
      properties: { // MQTT 5.0 properties
          reasonString: 'test',
          userProperties: {
            'test': 'test'
          }
      }
    }

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

    Pubrec

    {
      cmd: 'pubrec',
      messageId: 42,
      reasonCode: 16, // only for MQTT 5.0
      properties: { // properties MQTT 5.0
        reasonString: 'test',
        userProperties: {
          'test': 'test'
        }
      }
    }

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

    Pubrel

    {
      cmd: 'pubrel',
      messageId: 42,
      reasonCode: 16, // only for MQTT 5.0
      properties: { // properties MQTT 5.0
         reasonString: 'test',
         userProperties: {
           'test': 'test'
         }
      }
    }

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

    Pubcomp

    {
      cmd: 'pubcomp',
      messageId: 42,
      reasonCode: 16, // only for MQTT 5.0
      properties: { // properties MQTT 5.0
        reasonString: 'test',
        userProperties: {
           'test': 'test'
        }
      }
    }

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

    Pingreq

    {
      cmd: 'pingreq'
    }

    Pingresp

    {
      cmd: 'pingresp'
    }

    Disconnect

    {
      cmd: 'disconnect',
      reasonCode: 0, // MQTT 5.0 code
      properties: { // properties MQTT 5.0
         sessionExpiryInterval: 145,
         reasonString: 'test',
         userProperties: {
           'test': 'test'
         },
         serverReference: 'test'
      }
    }

    Auth

    {
      cmd: 'auth',
      reasonCode: 0, // MQTT 5.0 code
      properties: { // properties MQTT 5.0
         authenticationMethod: 'test',
         authenticationData: Buffer.from([0, 1, 2, 3]),
         reasonString: 'test',
         userProperties: {
           'test': 'test'
         }
      }
    }

    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 Collina GitHub/mcollina Twitter/@matteocollina
    Adam Rudd GitHub/adamvr Twitter/@adam_vr
    Peter Sorowka GitHub/psorowka Twitter/@psorowka
    Siarhei Buntsevich GitHub/scarry1992

    License

    MIT

    Install

    npm i mqtt-packet

    DownloadsWeekly Downloads

    422,983

    Version

    7.1.1

    License

    MIT

    Unpacked Size

    172 kB

    Total Files

    19

    Last publish

    Collaborators

    • matteo.collina
    • wuhkuh