Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/emitter-io/javascript

Nodejs MQTT client for emitter.io.
https://github.com/emitter-io/javascript

emitter mqtt-client sdk

Last synced: about 2 months ago
JSON representation

Nodejs MQTT client for emitter.io.

Awesome Lists containing this project

README 

        
[![NPM](https://nodei.co/npm/emitter-io.png)](https://nodei.co/npm/emitter-io/)

[![NPM](https://nodei.co/npm-dl/emitter-io.png)](https://nodei.co/npm/emitter-io/)



This repository contains JavaScript client for both NodeJS and the Browser for [Emitter](https://emitter.io) (see also on [Emitter GitHub](https://github.com/emitter-io/emitter)). Emitter is an **open-source** real-time communication service for connecting online devices. At its core, emitter.io is a distributed, scalable and fault-tolerant publish-subscribe messaging platform based on MQTT protocol and featuring message storage.



* [Installation](#install)

* [Example](#example)

* [API](#api)

* [License](#license)





## Installation



Emitter for NodeJS:

```

npm install emitter-io --save

```



Emitter for the Browser:

* [http://cdn.emitter.io/js/emitter.js](http://cdn.emitter.io/js/emitter.js)

* [http://cdn.emitter.io/js/emitter.min.js](http://cdn.emitter.io/js/emitter.min.js)





## Example



```

// connect to emitter.io and get the client

var client = emitter.connect(); // or: require('emitter-io') on NodeJS 



// once we're connected, subscribe to the 'chat' channel

client.subscribe({

	key: "",

	channel: "chat"

});

    

// on every message, print it out

client.on('message', function(msg){

	console.log( msg.asString() );

});



// publish a message to the chat channel

client.publish({

	key: "",

	channel: "chat/my_name",

	message: "hello, emitter!"

});

```



## API

  * connect()

  * Emitter()

  * Emitter#disconnect()

  * Emitter#publish()

  * Emitter#subscribe()

  * Emitter#unsubscribe()

  * Emitter#keygen()

  * Emitter#link()

  * Emitter#me()

  * Emitter#presence()

  * EmitterMessage()

  * EmitterMessage#asString()

  * EmitterMessage#asBinary()

  * EmitterMessage#asObject()



-------------------------------------------------------



### connect(host: string, port: number)



Connects to the emitter api broker specified by the given url and options and returns an [Emitter](#emitter) instance. The URL can be on the following protocols: 'mqtt', 'mqtts', 'tcp', 'tls', 'ws', 'wss'. The URL can also be an object as returned by [`URL.parse()`](http://nodejs.org/api/url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost), in that case the two objects are merged, i.e. you can pass a single object with both the URL and the connect options.



-------------------------------------------------------



### Emitter()



The `Emitter` class wraps a client connection to an emitter.io MQTT broker over an arbitrary transport method (TCP, TLS, WebSocket, ecc). It automatically handles the following by with help of MQTT.js client:

* Regular server pings

* QoS flow

* Automatic reconnections

* Start publishing before being connected



#### Event `'connect'`



`function(connack) {}`



Emitted on successful (re)connection (i.e. connack rc=0). 

* `connack` received connack packet. When `clean` connection option is `false` and server has a previous session 

for `clientId` connection option, then `connack.sessionPresent` flag is `true`. When that is the case, 

you may rely on stored session and prefer not to send subscribe commands for the client.



#### Event `'disconnect'`



`function() {}`



Emitted after a disconnection.



#### Event `'offline'`



`function() {}`



Emitted when the client goes offline.



#### Event `'error'`



`function(error) {}`



Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs.



#### Event `'keygen'`



`function(keyJson) {}`



Emitted when the client generate a key to a channel using Emitter#keygen() function.



### Event `'message'`



`function(message) {}`



Emitted when the client receives a message packet. The message object will be of [EmitterMessage](#message) class, encapsulating the channel and the payload.



-------------------------------------------------------



### Emitter#disconnect()



Disconnects from the remote broker



-------------------------------------------------------



### Emitter#link({ key: string; channel: string; name: string; private: boolean; message: any; ttl?: number; me?: boolean; })



Creates a 2-character link to a channel. The channel may be private. For more information about this feature, see [Emitter: Simplify Client/Server and IoT Apps with Links and Private Links (on YouTube)](https://youtu.be/_FgKiUlEb_s) and the [Emitter Pull Request (on GitHub)](https://github.com/emitter-io/emitter/pull/183).



* `key` is security key to use for the operation, `String`

* `channel` is the channel string to publish to, `String`

* `name` is the 2-character name of the link, `String`

* `private` requests the creation of a private channel, `Boolean`

* `message` is the message to publish, `Buffer` or `String`

* `ttl` is the time to live of the messages that will be sent through the link, `Number`.

* `me` tells whether the messages sent through the link should be also sent to the publisher, `Boolean`. By default it is set to `true`.



See also `publishWithLink()`.



-------------------------------------------------------



### Emitter#publish({ key: string; channel: string; message: any; ttl?: number; me?: boolean; })



Publishes a message to a channel

* `key` is security key to use for the operation, `String`

* `channel` is the channel string to publish to, `String`

* `message` is the message to publish, `Buffer` or `String`

* `ttl` is the time to live of the message, `Number`

* `me` tells whether the messages should be also sent to the publisher, `Boolean`. By default it is set to `true`.



-------------------------------------------------------



### Emitter#publishWithLink({ link: string; message: any;  })



Publishes a message to a link.

* `link` is the name of the link, `String`

* `message` is the message to publish, `Buffer` or `String`



See also `link()`.



-------------------------------------------------------



### Emitter#subscribe({ key: string; channel: string;  })



Subscribes to a channel

* `key` is security key to use for the operation, `String`

* `channel` is the channel string to subscribe to, `String`



-------------------------------------------------------



### Emitter#unsubscribe({ key: string; channel: string;  })



Unsubscribes from a channel

* `key` is security key to use for the operation, `String`

* `channel` is the channel string to unsubscribe from, `String`



-------------------------------------------------------



### Emitter#keygen({ key: string; channel: string; type: string; ttl: number; })



Sends a key generation request to the server.

* `key` is **master/secret key** to use for the operation, `String`

* `channel` is the channel string to generate a key for, `String`

* `type` the type of the key to generate. Possible options include `r` for read-only, `w` for write-only, `p` for presence only and `rw` for read-write keys (In addition to `rw`, you can use any combination of `r`, `w` and `p` for key generation), `String`

* `ttl` is the time-to-live of the key, in seconds.



-------------------------------------------------------



### Emitter#me()



Retrieves information about the underlying client connection. Information includes the client ID and the links created by the client.



-------------------------------------------------------



### Emitter#presence({ key: string; channel: string; status: boolean; changes: boolean; })



Requests the presence for a particular channel.

* `key` is **master/secret key** to use for the operation, `String`

* `channel` is the channel string to generate a key for, `String`

* `status` whether the current state should be retrieved or not

* `changes` whether the future changes should be received or not



-------------------------------------------------------



### EmitterMessage()



The `EmitterMessage` class wraps a message received from the broker. It contains several properties:

* `channel` is channel the message was published to, `String`

* `binary` is the buffer associated with the payload, `Buffer`



-------------------------------------------------------



### EmitterMessage#asString()



Returns the payload as a utf-8 `String`.



-------------------------------------------------------



### EmitterMessage#asBinary()



Returns the payload as the `Buffer`.



-------------------------------------------------------



### EmitterMessage#asObject()



Returns the payload as JSON-deserialized `Object`.





## License



The MIT License (MIT)

Copyright (c) 2016 Misakai Ltd.