mqtt-connection-fix
v4.0.2
Published
Stream-based Connection object for MQTT, extracted from MQTT.js
Downloads
13
Readme
mqtt-connection
Barebone Connection object for MQTT. Works over any kind of binary Streams, TCP, TLS, WebSocket, ...
It uses mqtt-packet for generating and parsing MQTT packets. See it for the full documentations on the packet types.
- Installation
- Usage
- API
- Contributing
- License & copyright
This library is tested with node v4, v6 and v7. The last version to support older versions of node was [email protected].
Installation
npm install mqtt-connection --save
Usage
As a client:
var net = require('net')
var mqttCon = require('mqtt-connection')
var stream = net.createConnection(1883, 'localhost')
var conn = mqttCon(stream)
// conn is your MQTT connection!
As a server:
var net = require('net')
var mqttCon = require('mqtt-connection')
var server = new net.Server()
server.on('connection', function (stream) {
var client = mqttCon(stream)
// client connected
client.on('connect', function (packet) {
// acknowledge the connect packet
client.connack({ returnCode: 0 });
})
// client published
client.on('publish', function (packet) {
// send a puback with messageId (for QoS > 0)
client.puback({ messageId: packet.messageId })
})
// client pinged
client.on('pingreq', function () {
// send a pingresp
client.pingresp()
});
// client subscribed
client.on('subscribe', function (packet) {
// send a suback with messageId and granted QoS level
client.suback({ granted: [packet.qos], messageId: packet.messageId })
})
// timeout idle streams after 5 minutes
stream.setTimeout(1000 * 60 * 5)
// connection error handling
client.on('close', function () { client.destroy() })
client.on('error', function () { client.destroy() })
client.on('disconnect', function () { client.destroy() })
// stream timeout
stream.on('timeout', function () { client.destroy(); })
})
// listen on port 1883
server.listen(1883)
As a websocket server:
var websocket = require('websocket-stream')
var WebSocketServer = require('ws').Server
var Connection = require('mqtt-connection')
var server = http.createServer()
var wss = new WebSocketServer({server: server})
if (handler) {
server.on('client', handler)
}
wss.on('connection', function (ws) {
var stream = websocket(ws)
var connection = new Connection(stream)
handle(connection)
})
function handle (conn) {
// handle the MQTT connection like
// the net example
}
API
- mqtt.Connection()
- mqtt.parseStream()
- mqtt.generateStream()
new mqtt.Connection([options])
Creates a new MQTT Connection
.
Options:
notData
: do not listen to the'data'
event, so that it can respect backpressure. Pipe theConnection
to another stream to consume the packets. If this option is passedtrue
the object will emit no packet-related events.
Connection#connect(options, [callback])
Send a MQTT connect packet.
options
supports the following properties:
protocolId
: Protocol ID, usuallyMQIsdp
.string
protocolVersion
: Protocol version, usually 3.number
keepalive
: keepalive period in seconds.number
clientId
: client ID.string
will
: the client's will message options.object
that supports the following properties:topic
: the will topic.string
payload
: the will payload.string
qos
: will qos level.number
retain
: will retain flag.boolean
properties
: properties of will by MQTT 5.0:willDelayInterval
: representing the Will Delay Interval in secondsnumber
,payloadFormatIndicator
: Will Message is UTF-8 Encoded Character Data or notboolean
,messageExpiryInterval
: value is the lifetime of the Will Message in seconds and is sent as the Publication Expiry Interval when the Server publishes the Will Messagenumber
,contentType
: describing the content of the Will Messagestring
,responseTopic
: String which is used as the Topic Name for a response messagestring
,correlationData
: The Correlation Data is used by the sender of the Request Message to identify which request the Response Message is for when it is receivedbinary
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
properties
: properties MQTT 5.0.object
that supports the following properties:sessionExpiryInterval
: representing the Session Expiry Interval in secondsnumber
,receiveMaximum
: representing the Receive Maximum valuenumber
,maximumPacketSize
: representing the Maximum Packet Size the Client is willing to acceptnumber
,topicAliasMaximum
: representing the Topic Alias Maximum value indicates the highest value that the Client will accept as a Topic Alias sent by the Servernumber
,requestResponseInformation
: The Client uses this value to request the Server to return Response Information in the CONNACKboolean
,requestProblemInformation
: The Client uses this value to indicate whether the Reason String or User Properties are sent in the case of failuresboolean
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
,authenticationMethod
: the name of the authentication method used for extended authenticationstring
,authenticationData
: Binary Data containing authentication databinary
clean
: the 'clean start' flag.boolean
username
: username for protocol v3.1.string
password
: password for protocol v3.1.string
Connection#connack(options, [callback])
Send a MQTT connack packet.
options
supports the following properties:
returnCode
: the return code of the connack, success is for MQTT < 5.0reasonCode
: suback Reason Codenumber
MQTT 5.0properties
: properties MQTT 5.0.object
that supports the following properties:sessionExpiryInterval
: representing the Session Expiry Interval in secondsnumber
,receiveMaximum
: representing the Receive Maximum valuenumber
,maximumQoS
: maximum qos supported by servernumber
,retainAvailable
: declares whether the Server supports retained messagesboolean
,maximumPacketSize
: Maximum Packet Size the Server is willing to acceptnumber
,assignedClientIdentifier
: Assigned Client Identifierstring
,topicAliasMaximum
: representing the Topic Alias Maximum value indicates the highest value that the Client will accept as a Topic Alias sent by the Servernumber
,reasonString
: representing the reason associated with this responsestring
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
,wildcardSubscriptionAvailable
: this byte declares whether the Server supports Wildcard Subscriptionsboolean
subscriptionIdentifiersAvailable
: declares whether the Server supports Subscription Identifiersboolean
,sharedSubscriptionAvailable
: declares whether the Server supports Shared Subscriptionsboolean
,serverKeepAlive
: Keep Alive time assigned by the Servernumber
,responseInformation
: String which is used as the basis for creating a Response Topicstring
,serverReference
: String which can be used by the Client to identify another Server to usestring
,authenticationMethod
: the name of the authentication method used for extended authenticationstring
,authenticationData
: Binary Data containing authentication databinary
Connection#publish(options, [callback])
Send a MQTT publish packet.
options
supports the following properties:
topic
: the topic to publish to.string
payload
: the payload to publish, defaults to an empty buffer.string
orbuffer
qos
: the quality of service level to publish on.number
messageId
: the message ID of the packet, required if qos > 0.number
retain
: retain flag.boolean
properties
:object
payloadFormatIndicator
: Payload is UTF-8 Encoded Character Data or notboolean
,messageExpiryInterval
: the lifetime of the Application Message in secondsnumber
,topicAlias
: value that is used to identify the Topic instead of using the Topic Namenumber
,responseTopic
: String which is used as the Topic Name for a response messagestring
,correlationData
: used by the sender of the Request Message to identify which request the Response Message is for when it is receivedbinary
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
,subscriptionIdentifier
: representing the identifier of the subscriptionnumber
,contentType
: String describing the content of the Application Messagestring
Connection#puback #pubrec #pubcomp #unsuback(options, [callback])
Send a MQTT [puback, pubrec, pubcomp, unsuback]
packet.
options
supports the following properties:
messageId
: the ID of the packetreasonCode
: Reason Code by packetnumber
properties
:object
reasonString
: representing the reason associated with this responsestring
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
Connection#pubrel(options, [callback])
Send a MQTT pubrel packet.
options
supports the following properties:
dup
: duplicate message flagreasonCode
: pubrel Reason Codenumber
messageId
: the ID of the packetproperties
:object
reasonString
: representing the reason associated with this responsestring
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
Connection#subscribe(options, [callback])
Send a MQTT subscribe packet.
options
supports the following properties:
dup
: duplicate message flagmessageId
: the ID of the packetproperties
:object
subscriptionIdentifier
: representing the identifier of the subscriptionnumber
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
subscriptions
: a list of subscriptions of the form[{topic: a, qos: 0}, {topic: b, qos: 1}]
[{topic: a, qos: 0, nl: false, rap: true, rh: 15 }, {topic: b, qos: 1, nl: false, rap: false, rh: 100 }]
MQTT 5.0 Example
Connection#suback(options, [callback])
Send a MQTT suback packet.
options
supports the following properties:
granted
: a vector of granted QoS levels, of the form[0, 1, 2]
messageId
: the ID of the packetreasonCode
: suback Reason Codenumber
properties
:object
reasonString
: representing the reason associated with this responsestring
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
Connection#unsubscribe(options, [callback])
Send a MQTT unsubscribe packet.
options
supports the following properties:
messageId
: the ID of the packetreasonCode
: unsubscribe Reason Code MQTT 5.0number
dup
: duplicate message flagproperties
:object
userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
unsubscriptions
: a list of topics to unsubscribe from, of the form["topic1", "topic2"]
Connection#pingreq #pingresp #disconnect(options, [callback])
Send a MQTT [pingreq, pingresp]
packet.
Connection#disconnect(options, [callback])
Send a MQTT disconnect
packet.
options
supports the following properties only MQTT 5.0:
reasonCode
: Disconnect Reason Codenumber
properties
:object
sessionExpiryInterval
: representing the Session Expiry Interval in secondsnumber
,reasonString
: representing the reason for the disconnectstring
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
,serverReference
: String which can be used by the Client to identify another Server to usestring
Connection#auth(options, [callback])
Send a MQTT auth
packet. Only MQTT 5.0
options
supports the following properties only MQTT 5.0:
reasonCode
: Auth Reason Codenumber
properties
:object
authenticationMethod
: the name of the authentication method used for extended authenticationstring
,authenticationData
: Binary Data containing authentication databinary
,reasonString
: representing the reason for the disconnectstring
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairsobject
Event: 'connect'
function(packet) {}
Emitted when a MQTT connect packet is received by the client.
packet
is an object that may have the following properties:
version
: the protocol version stringversionNum
: the protocol version numberkeepalive
: the client's keepalive periodclientId
: the client's IDwill
: an object with the following keys:topic
: the client's will topicpayload
: the will messageretain
: will retain flagqos
: will qos levelproperties
: properties of will
properties
: properties of packetclean
: clean start flagusername
: v3.1 usernamepassword
: v3.1 password
Event: 'connack'
function(packet) {}
Emitted when a MQTT connack packet is received by the client.
packet
is an object that may have the following properties:
returnCode
: the return code of the connack packetproperties
: properties of packet
Event: 'publish'
function(packet) {}
Emitted when a MQTT publish packet is received by the client.
packet
is an object that may have the following properties:
topic
: the topic the message is published onpayload
: the payload of the messagemessageId
: the ID of the packetproperties
: properties of packetqos
: the QoS level to publish at
Events: <'puback', 'pubrec', 'pubrel', 'pubcomp', 'unsuback'>
function(packet) {}
Emitted when a MQTT [puback, pubrec, pubrel, pubcomp, unsuback]
packet is received by the client.
packet
is an object that may contain the property:
messageId
: the ID of the packetproperties
: properties of packet
Event: 'subscribe'
function(packet) {}
Emitted when a MQTT subscribe packet is received.
packet
is an object that may contain the properties:
messageId
: the ID of the packetproperties
: properties of packetsubscriptions
: an array of objects representing the subscribed topics, containing the following keystopic
: the topic subscribed toqos
: the qos level of the subscription
Event: 'suback'
function(packet) {}
Emitted when a MQTT suback packet is received.
packet
is an object that may contain the properties:
messageId
: the ID of the packetproperties
: properties of packetgranted
: a vector of granted QoS levels
Event: 'unsubscribe'
function(packet) {}
Emitted when a MQTT unsubscribe packet is received.
packet
is an object that may contain the properties:
messageId
: the ID of the packetproperties
: properties of packetunsubscriptions
: a list of topics the client is unsubscribing from, of the form[topic1, topic2, ...]
Events: <'pingreq', 'pingresp'>
function(packet){}
Emitted when a MQTT [pingreq, pingresp, disconnect]
packet is received.
packet
only includes static header information and can be ignored.
Event: 'disconnect'
function(packet) {}
Emitted when a MQTT disconnect packet is received.
packet
only includes static header information and can be ignored for MQTT < 5.0.
packet
is an object that may contain the properties for MQTT 5.0:
reasonCode
: disconnect Reason Codeproperties
: properties of packet
Event: 'auth'
function(packet) {}
Emitted when a MQTT auth packet is received.
packet
is an object that may contain the properties:
reasonCode
: Auth Reason Codeproperties
: properties of packet
mqtt.generateStream()
Returns a Transform
stream that calls generate()
.
The stream is configured into object mode.
mqtt.parseStream(opts)
Returns a Transform
stream that embeds a Parser
and calls Parser.parse()
for each new Buffer
. The stream is configured into object mode. It accepts the same options of parser(opts)
.
Contributing
mqtt-connection 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-connection is only possible due to the excellent work of the following contributors:
License
MIT