mqtt-packet =========== Encode and Decode MQTT 3.1.1, 5.0 packets the node way. [![JavaScript Style Guide](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard) * Installation * Examples * Packets * API * Contributing * License & copyright 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 ------------ ```bash npm install mqtt-packet --save ``` Examples -------- ### Generating ```js 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: // // // // 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 ```js 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: // } }) 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() * mqtt#writeToStream() * mqtt#parser() ### mqtt.generate(object, [opts]) Generates a `Buffer` containing an MQTT packet. The object must be one of the ones specified by the [packets](#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](#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](#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 ```js { 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 ```js { 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 ```js { 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 ```js { 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 ```js { cmd: 'unsubscribe', messageId: 42, properties: { // MQTT 5.0 properties userProperties: { 'test': 'test' } } unsubscriptions: [ 'test', 'a/topic' ] } ``` All properties are mandatory. ### Unsuback ```js { cmd: 'unsuback', messageId: 42, properties: { // MQTT 5.0 properties reasonString: 'test', userProperties: { 'test': 'test' } } } ``` All properties are mandatory. ### Publish ```js { 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 ```js { 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 ```js { 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 ```js { 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 ```js { 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 ```js { cmd: 'pingreq' } ``` ### Pingresp ```js { cmd: 'pingresp' } ``` ### Disconnect ```js { cmd: 'disconnect', reasonCode: 0, // MQTT 5.0 code properties: { // properties MQTT 5.0 sessionExpiryInterval: 145, reasonString: 'test', userProperties: { 'test': 'test' }, serverReference: 'test' } } ``` ### Auth ```js { 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](https://github.com/mqttjs/mqtt-packet/blob/master/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
Siarhei BuntsevichGitHub/scarry1992
License ------- MIT