Parse and generate MQTT packets like a breeze
npm install mqtt-packetmqtt-packet
===========
Encode and Decode MQTT 3.1.1, 5.0 packets the node way.

* 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
--------
`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)
// ])
`
`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()
Generates a Buffer containing an MQTT packet.Error
The object must be one of the ones specified by the packets
section. Throws an if a packet cannot be generated.
Writes the mqtt packet defined by object to the given stream.Error
The object must be one of the ones specified by the packets
section. Emits an on the stream if a packet cannot be generated.cork()
On node >= 0.12, this function automatically calls on your stream,uncork()
and then it calls on the next tick.mqtt.writeToStream.cacheNumbers = false
By default cache for number buffers is enabled.
It creates a list of buffers for faster write. To disable cache set .writeToStream
Should be set before any calls.
Returns a new Parser object. Parser inherits from EventEmitter and
will emit:
* packet, when a new packet is parsed, according toerror
packets
* , 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 eventsparse()
will be emitted after that. Calling again clears the error andParser
previous buffer, as if you created a new .
Packets
-------
This section describes the format of all packets emitted by the Parsergenerate
and that you can input to .
`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 willBuffer
automatically be converted into a .
`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: 1,
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.
`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.
`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.
`js`
{
cmd: 'unsubscribe',
messageId: 42,
properties: { // MQTT 5.0 properties
userProperties: {
'test': 'test'
}
}
unsubscriptions: [
'test',
'a/topic'
]
}
All properties are mandatory.
`js`
{
cmd: 'unsuback',
messageId: 42,
properties: { // MQTT 5.0 properties
reasonString: 'test',
userProperties: {
'test': 'test'
}
}
}
All properties are mandatory.
`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.topic
Both and payload can be Buffer objects instead of strings.messageId is mandatory for qos > 0.
`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.
`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.
`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.
`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.
`js`
{
cmd: 'pingreq'
}
`js`
{
cmd: 'pingresp'
}
`js`
{
cmd: 'disconnect',
reasonCode: 0, // MQTT 5.0 code
properties: { // properties MQTT 5.0
sessionExpiryInterval: 145,
reasonString: 'test',
userProperties: {
'test': 'test'
},
serverReference: 'test'
}
}
`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 file for more details.
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