You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
321 lines
9.1 KiB
321 lines
9.1 KiB
5 years ago
|
mqtt-connection [![Build Status](https://travis-ci.org/mqttjs/mqtt-connection.png)](https://travis-ci.org/mqttjs/mqtt-connection)
|
||
|
===============
|
||
|
|
||
|
Barebone Connection object for MQTT.
|
||
|
Works over any kind of binary Streams, TCP, TLS, WebSocket, ...
|
||
|
|
||
|
It uses [mqtt-packet](http://npm.im/mqtt-packet) for generating and
|
||
|
parsing MQTT packets. See it for the full documentations on the
|
||
|
packet types.
|
||
|
|
||
|
* <a href="#install">Install</a>
|
||
|
* <a href="#usage">Usage</a>
|
||
|
* <a href="#api">API</a>
|
||
|
* <a href="#contributing">Contributing</a>
|
||
|
* <a href="#license">Licence & copyright</a>
|
||
|
|
||
|
This library works with node v0.10 and node v0.8, but it requires at
|
||
|
least NPM 1.4. To upgrade on node v0.8, run `npm install
|
||
|
npm@v1.4-latest -g`.
|
||
|
|
||
|
Install
|
||
|
-------
|
||
|
|
||
|
```sh
|
||
|
npm install mqtt-connection --save
|
||
|
```
|
||
|
|
||
|
Usage
|
||
|
-----
|
||
|
|
||
|
As a client:
|
||
|
|
||
|
```js
|
||
|
var net = require('net')
|
||
|
, mqttCon = require('mqtt-connection')
|
||
|
, stream = net.createConnection(1883, 'localhost')
|
||
|
, conn = mqttCon(stream);
|
||
|
|
||
|
// conn is your MQTT connection!
|
||
|
|
||
|
```
|
||
|
|
||
|
As a server:
|
||
|
```js
|
||
|
var net = require('net')
|
||
|
, mqttCon = require('mqtt-connection')
|
||
|
, server = new net.Server();
|
||
|
|
||
|
server.on('connection', function(stream) {
|
||
|
var conn = mqttCon(stream);
|
||
|
|
||
|
// conn is your MQTT connection!
|
||
|
});
|
||
|
```
|
||
|
|
||
|
As a websocket server:
|
||
|
|
||
|
```js
|
||
|
var websocket = require('websocket-stream')
|
||
|
, WebSocketServer = require('ws').Server
|
||
|
, Connection = require('mqtt-connection')
|
||
|
, server = http.createServer()
|
||
|
|
||
|
function attachWebsocketServer(server, handler) {
|
||
|
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)
|
||
|
|
||
|
server.emit("client", connection)
|
||
|
})
|
||
|
|
||
|
return server
|
||
|
}
|
||
|
|
||
|
attachWebsocketServer(server)
|
||
|
```
|
||
|
|
||
|
API
|
||
|
---
|
||
|
|
||
|
* <a href="#connection"><code>mqtt.<b>Connection()</b></code></a>
|
||
|
* <a href="#parseStream"><code>mqtt.<b>parseStream()</b></code></a>
|
||
|
* <a href="#generateStream"><code>mqtt.<b>parseStream()</b></code></a>
|
||
|
|
||
|
---------------------------------
|
||
|
|
||
|
<a name="connection"></a>
|
||
|
### 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 the `Connection` to another stream to
|
||
|
consume the packets. If this option is passed `true` the object will
|
||
|
emit no packet-related events.
|
||
|
|
||
|
#### Connection#connect(options, [callback])
|
||
|
|
||
|
Send an MQTT connect packet.
|
||
|
|
||
|
`options` supports the following properties:
|
||
|
|
||
|
* `protocolId`: Protocol ID, usually `MQIsdp`. `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`
|
||
|
* `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 an MQTT connack packet.
|
||
|
|
||
|
`options` supports the following properties:
|
||
|
|
||
|
* `returnCode`: the return code of the connack, success is
|
||
|
indicated by `0`. `number`
|
||
|
|
||
|
#### Connection#publish(options, [callback])
|
||
|
Send an 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` or `buffer`
|
||
|
* `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`
|
||
|
|
||
|
#### Connection#puback #pubrec #pubcomp #unsuback(options, [callback])
|
||
|
Send an MQTT `[puback, pubrec, pubcomp, unsuback]` packet.
|
||
|
|
||
|
`options` supports the following properties:
|
||
|
|
||
|
* `messageId`: the ID of the packet
|
||
|
|
||
|
#### Connection#pubrel(options, [callback])
|
||
|
Send an MQTT pubrel packet.
|
||
|
|
||
|
`options` supports the following properties:
|
||
|
|
||
|
* `dup`: duplicate message flag
|
||
|
* `messageId`: the ID of the packet
|
||
|
|
||
|
#### Connection#subscribe(options, [callback])
|
||
|
Send an MQTT subscribe packet.
|
||
|
|
||
|
`options` supports the following properties:
|
||
|
|
||
|
* `dup`: duplicate message flag
|
||
|
* `messageId`: the ID of the packet
|
||
|
* `subscriptions`: a list of subscriptions of the form
|
||
|
`[{topic: a, qos: 0}, {topic: b, qos: 1}]`
|
||
|
|
||
|
#### Connection#suback(options, [callback])
|
||
|
Send an 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 packet
|
||
|
|
||
|
#### Connection#unsubscribe(options, [callback])
|
||
|
Send an MQTT unsubscribe packet.
|
||
|
|
||
|
`options` supports the following properties:
|
||
|
|
||
|
* `messageId`: the ID of the packet
|
||
|
* `dup`: duplicate message flag
|
||
|
* `unsubscriptions`: a list of topics to unsubscribe from,
|
||
|
of the form `["topic1", "topic2"]`
|
||
|
|
||
|
#### Connection#pingreq #pingresp #disconnect(options, [callback])
|
||
|
Send an MQTT `[pingreq, pingresp, disconnect]` packet.
|
||
|
|
||
|
#### Event: 'connect'
|
||
|
`function(packet) {}`
|
||
|
|
||
|
Emitted when an MQTT connect packet is received by the client.
|
||
|
|
||
|
`packet` is an object that may have the following properties:
|
||
|
|
||
|
* `version`: the protocol version string
|
||
|
* `versionNum`: the protocol version number
|
||
|
* `keepalive`: the client's keepalive period
|
||
|
* `clientId`: the client's ID
|
||
|
* `will`: an object with the following keys:
|
||
|
* `topic`: the client's will topic
|
||
|
* `payload`: the will message
|
||
|
* `retain`: will retain flag
|
||
|
* `qos`: will qos level
|
||
|
* `clean`: clean start flag
|
||
|
* `username`: v3.1 username
|
||
|
* `password`: v3.1 password
|
||
|
|
||
|
#### Event: 'connack'
|
||
|
`function(packet) {}`
|
||
|
|
||
|
Emitted when an 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 packet
|
||
|
|
||
|
#### Event: 'publish'
|
||
|
`function(packet) {}`
|
||
|
|
||
|
Emitted when an 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 on
|
||
|
* `payload`: the payload of the message
|
||
|
* `messageId`: the ID of the packet
|
||
|
* `qos`: the QoS level to publish at
|
||
|
|
||
|
#### Events: \<'puback', 'pubrec', 'pubrel', 'pubcomp', 'unsuback'\>
|
||
|
`function(packet) {}`
|
||
|
|
||
|
Emitted when an 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 packet
|
||
|
|
||
|
#### Event: 'subscribe'
|
||
|
`function(packet) {}`
|
||
|
|
||
|
Emitted when an MQTT subscribe packet is received.
|
||
|
|
||
|
`packet` is an object that may contain the properties:
|
||
|
|
||
|
* `messageId`: the ID of the packet
|
||
|
* `subscriptions`: an array of objects
|
||
|
representing the subscribed topics, containing the following keys
|
||
|
* `topic`: the topic subscribed to
|
||
|
* `qos`: the qos level of the subscription
|
||
|
|
||
|
|
||
|
#### Event: 'suback'
|
||
|
`function(packet) {}`
|
||
|
|
||
|
Emitted when an MQTT suback packet is received.
|
||
|
|
||
|
`packet` is an object that may contain the properties:
|
||
|
|
||
|
* `messageId`: the ID of the packet
|
||
|
* `granted`: a vector of granted QoS levels
|
||
|
|
||
|
#### Event: 'unsubscribe'
|
||
|
`function(packet) {}`
|
||
|
|
||
|
Emitted when an MQTT unsubscribe packet is received.
|
||
|
|
||
|
`packet` is an object that may contain the properties:
|
||
|
|
||
|
* `messageId`: the ID of the packet
|
||
|
* `unsubscriptions`: a list of topics the client is
|
||
|
unsubscribing from, of the form `[topic1, topic2, ...]`
|
||
|
|
||
|
#### Events: \<'pingreq', 'pingresp', 'disconnect'\>
|
||
|
`function(packet){}`
|
||
|
|
||
|
Emitted when an MQTT `[pingreq, pingresp, disconnect]` packet is received.
|
||
|
|
||
|
`packet` only includes static header information and can be ignored.
|
||
|
|
||
|
-------------------------------------
|
||
|
|
||
|
<a name="generateStream">
|
||
|
### mqtt.generateStream()
|
||
|
|
||
|
Returns a `Transform` stream that calls [`generate()`](https://github.com/mqttjs/mqtt-packet#generate).
|
||
|
The stream is configured into object mode.
|
||
|
|
||
|
<a name="parseStream">
|
||
|
### mqtt.parseStream(opts)
|
||
|
|
||
|
Returns a `Transform` stream that embeds a [`Parser`](https://github.com/mqttjs/mqtt-packet#mqttparser) and calls [`Parser.parse()`](https://github.com/mqttjs/mqtt-packet#parserparsebuffer) for each new `Buffer`. The stream is configured into object mode. It accepts the same options of [`parser(opts)`](#parser).
|
||
|
|
||
|
<a name="contributing"></a>
|
||
|
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](https://github.com/mqttjs/mqtt-connection/blob/master/CONTRIBUTING.md) file for more details.
|
||
|
|
||
|
### Contributors
|
||
|
|
||
|
mqtt-packet is only possible due to the excellent work of the following contributors:
|
||
|
|
||
|
<table><tbody>
|
||
|
<tr><th align="left">Matteo Collina</th><td><a href="https://github.com/mcollina">GitHub/mcollina</a></td><td><a href="http://twitter.com/matteocollina">Twitter/@matteocollina</a></td></tr>
|
||
|
<tr><th align="left">Adam Rudd</th><td><a href="https://github.com/adamvr">GitHub/adamvr</a></td><td><a href="http://twitter.com/adam_vr">Twitter/@adam_vr</a></td></tr>
|
||
|
</tbody></table>
|
||
|
|
||
|
License
|
||
|
-------
|
||
|
|
||
|
MIT
|