Home

Awesome

node-meshblu-socket.io

Build Status Code Climate Test Coverage Slack Status

NPM

A client side library for using the Meshblu Socket.IO API in Node.js

NOTICE: Major Version Release

Version 2.0.0 of this library introduces some major API changes that make it incompatible with many of the code samples external to this README. Notably, the library is now instantiated as a class instead of using a createConnection function, and the connect method must be called to establish a connection. If the old functionality is required, the latest version of the previous API was 1.34.1. It is highly recommended that you update to 2.0.0, as 1.x.x will not be supported in the future.

Table of Contents

Getting Started

Install

The Meshblu client-side library is best obtained through NPM:

npm install --save meshblu

Quick Start

The client side library establishes a secure socket.io connection to Meshblu at https://meshblu-socket-io.octoblu.com by default.

var MeshbluSocketIO = require('meshblu');
var meshblu = new MeshbluSocketIO({
  resolveSrv: true,
  uuid: '78159106-41ca-4022-95e8-2511695ce64c',
  token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574'
})
meshblu.on('ready', function(){
  console.log('Ready to rock');
});
meshblu.connect();

Events

Event: "config"

The config event is emitted whenever a device is updated. Use the meshblu.subscribe API to subscribe to config events. In order to receive config events from a device, your connection must be authenticated as a device that is in the target device's configure.sent whitelist. See the Meshblu whitelist documentation for more information.

Example
meshblu.on('config', function(device){
  console.log('on config');
  console.log(JSON.stringify(device, null, 2));
  // on config
  // {
  //   "meshblu": {
  //     "version": "2.0.0",
  //     "whitelists": {},
  //     "hash": "9OAPxo5Yq1oTYNi1szGVBBlg4xuIVni47k8JhHYlXFk="
  //     }
  //   },
  //   "uuid": "78159106-41ca-4022-95e8-2511695ce64c",
  //   "foo": "bar"
  // }
});

otherConn.update({uuid: '78159106-41ca-4022-95e8-2511695ce64c', foo: 'bar'});

Event: "message"

The message event is emitted whenever a device sends or receives a message. Use the meshblu.subscribe API to subscribe to message events for a device. In order to receive broadcast from a device, your connection must be authenticated as a device that is in the target device's broadcast.sent whitelist. To receive message sent by a device, your connection must be in the target's message.sent whitelist. To receive messages from other devices, they must be in the authorized device's message.from whitelist. See the Meshblu whitelist documentation for more information.

Example
meshblu.on('message', function(message){
  console.log('on message');
  console.log(JSON.stringify(message, null, 2));
  // on message
  // {
  //   "devices": [
  //     "*"
  //   ],
  //   "foo": "bar",
  //   "fromUuid": "1f6d9e7b-059b-4c1a-b699-708948ad8e10"
  // }
});

otherConn.message({devices: ['*'], foo: 'bar'});

Event: "notReady"

The notReady event is emitted when certain things go wrong. These include emitting invalid authentication information in response to the identify challenge.

Example

When an incorrect identity event is rejected by Meshblu

meshblu.on('notReady', function(response){
  console.error('notReady');
  console.error(JSON.stringify(response, null, 2));
  // notReady
  // {
  //   "uuid": "i-made-this-uuid-up",
  //   "token": "i-made-this-token-up",
  //   "api": "connect",
  //   "status": 401
  // }
});

Event: "ready"

The ready event is emitted whenever the connection emits an identity and Meshblu accepts the credentials.

Note

The "ready" event is emitted every time the connection is re-established. In normal network conditions, it is not uncommon the connection to occasionally drop and reestablish itself. In those cases, the library will re-authenticate and the brief outage will not be noticeable. Two things to note:

Example

When a valid identity is accepted by Meshblu:

meshblu.on('ready', function(response){
  console.log('ready');
  console.log(JSON.stringify(response, null, 2));
  // ready
  // {
  //   "uuid": "78159106-41ca-4022-95e8-2511695ce64c",
  //   "token": "d5265dbc4576a88f8654a8fc2c4d46a6d7b85574",
  //   "api": "connect",
  //   "status": 201
  // }
});

Methods

constructor(options)

Establishes a socket.io connection to meshblu and returns the connection object.

Arguments
Note

If the uuid and token options are omitted, Meshblu will create a new device when the connection is established and emit a ready event with the device's credentials. This will be the only time that device's token is available as plain text. This auto device creation feature exists for backwards compatibility, its use in new projects is strongly discouraged.

Example
var MeshbluSocketIO = require('meshblu');
var conn = new MeshbluSocketIO({
  resolveSrv: true,
  uuid: '78159106-41ca-4022-95e8-2511695ce64c',
  token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574'
})

meshblu.connect(callback)

Establish a socket.io connection to Meshblu.

Arguments
Note

The callback is called once the socket.io connection is connected, but not yet authorized. All calls should wait until after the ready event has occurred.

Example
meshblu.connect(function(error){
  console.log('connect');
  console.log(error);
  // connect
  // undefined
});

meshblu.device(query, callback)

Retrieve a device from the Meshblu device registry by its uuid. In order to retrieve a target device, your connection must be authenticated as a device that is in the target device's discover.view whitelist. See the Meshblu whitelist documentation for more information.

Arguments
Note

In Meshblu, it is not possible to distinguish between a device not existing and not having permission to view a device. In most of the Meshblu API calls, the error in both cases yields the protocol-specific equivalent of an HTTP 404: Not Found. The Socket.IO API, however, returns the error Forbidden. This is for backwards compatibility and will likely change with the next major version release of the Socket.IO API.

Example

When requesting a valid device that the authorized device may view:

meshblu.device({uuid: '78159106-41ca-4022-95e8-2511695ce64c'}, function(result){
  console.log('device');
  console.log(JSON.stringify(result, null, 2));
  // device
  // {
  //   "device": {
  //     "meshblu": {
  //       "version": "2.0.0",
  //       "whitelists": {},
  //       "createdAt": "2016-05-19T23:28:08+00:00",
  //       "hash": "4ez1I/uziZVk7INf6n1un+op/oNsIDoFVs/MW/KGWMQ=",
  //       "updatedAt": "2016-05-20T16:07:57+00:00"
  //     },
  //     "uuid": "78159106-41ca-4022-95e8-2511695ce64c",
  //     "online": true
  //   }
  // }
});

When requesting a non-existing device, or a device the authenticated device may not view:

meshblu.device({uuid: 'i-made-this-uuid-up'}, function(result){
  console.log('device');
  console.log(JSON.stringify(result, null, 2));
  // device
  // {
  //   "error": "Forbidden"
  // }
});

meshblu.devices(query, callback)

Retrieve devices from the Meshblu device registry. In order to retrieve a target device, your connection must be authenticated as a device that is in the target device's discover.view whitelist. See the Meshblu whitelist documentation for more information.

Arguments
Example

When requesting valid devices that the authorized device may view:

meshblu.devices({color: 'blue'}, function(result){
  console.log('devices');
  console.log(JSON.stringify(result, null, 2));
  // devices
  // {
  //   "devices": [
  //     {
  //       "color": "blue",
  //       "discoverWhitelist": [ "*" ],
  //       "uuid": "c30a7506-7a45-4fe1-ab51-c57afad7f41a"
  //     },
  //     {
  //       "color": "blue",
  //       "discoverWhitelist": [ "*" ],
  //       "uuid": "7a9475ea-a595-42a4-8928-0aeb677c4990"
  //     }
  //   ]
  // }
});

When requesting a non-existing devices, or devices the authenticated device may not view:

meshblu.devices({color: 'i-made-this-color-up'}, function(result){
  console.log('devices');
  console.log(JSON.stringify(result, null, 2));
  // device
  // {
  //   "devices": []
  // }
});

meshblu.generateAndStoreToken(query, callback)

Generate a session token for a device in the Meshblu device registry. In order to generate a token, your connection must be authenticated as a device that is in the target device's configure.update whitelist. See the Meshblu whitelist documentation for more information.

Arguments
Note

In Meshblu, it is not possible to distinguish between a device not existing and not having permission to view a device. In most of the Meshblu API calls, the error in both cases yields the protocol-specific equivalent of an HTTP 404: Not Found. The Socket.IO API, however, returns the error Forbidden. This is for backwards compatibility and will likely change with the next major version release of the Socket.IO API.

Example

When generateAndStoreToken is called for a valid device that the authorized device may update:

meshblu.generateAndStoreToken({uuid: '78159106-41ca-4022-95e8-2511695ce64c'}, function(result){
  console.log('generateAndStoreToken');
  console.log(JSON.stringify(result, null, 2));
  // generateAndStoreToken
  // {
  //   "uuid": "78159106-41ca-4022-95e8-2511695ce64c",
  //   "createdAt": "2016-05-20T18:25:13.587Z",
  //   "token": "8234f58b65ff042da60d84af4230d3692778ca5b"
  // }
});

When generateAndStoreToken is called for a non-existing devices, or devices the authenticated device may not update:

meshblu.generateAndStoreToken({uuid: 'i-made-this-uuid-up'}, function(result){
  console.log('generateAndStoreToken');
  console.log(JSON.stringify(result, null, 2));
  // generateAndStoreToken
  // {
  //   "error": "Forbidden"
  // }
});

meshblu.message(message)

Send a message to one or more Meshblu devices. In order to send a device a message, the connection must be authenticated as a device that is in the recipient's message.from whitelist. See the Meshblu whitelist documentation for more information.

Arguments
Note

Meshblu does not currently provide any receipt confirmation natively. If a message is sent to an offline recipient that has no message forwarding or device subscriptions, the message will be dropped. If it is important to know when the recipient received a message, it is recommended to have the recipient send some form of acknowledgement message back.

Example

To send a direct message.

meshblu.message({
  devices: ['78159106-41ca-4022-95e8-2511695ce64c'],
  topic: 'greeting',
  data: {
    howdy: 'partner'
  }
});

To send a broadcast message.

meshblu.message({
  devices: ['*'],
  topic: 'exclamation',
  data: {
    feeling: 'good'
  }
});

To send a message that is simultaneously broadcast and sent directly to a device.

meshblu.message({
  devices: ['*', '78159106-41ca-4022-95e8-2511695ce64c'],
  topic: 'recommendation',
  data: {
    guys: '78159106-41ca-4022-95e8-2511695ce64c is a pretty awesome dude!'
  }
});

meshblu.register(params, callback)

Register a new device with the Meshblu registry.

Arguments
Note

The Socket.io implementation of Meshblu creates open devices using the old (deprecated) whitelists by default. This is to preserve backwards compatibility. It is strongly recommended to register devices with explicitly locked down version 2.0.0 whitelists instead by creating a v2.0.0 device (see the second example).

Example

To register a new (open) device

meshblu.register({color: 'black'}, function(device){
  console.log('register');
  console.log(JSON.stringify(device, null, 2))
  // {
  //   "color": "black",
  //   "discoverWhitelist": [
  //     "*"
  //   ],
  //   "configureWhitelist": [
  //     "*"
  //   ],
  //   "sendWhitelist": [
  //     "*"
  //   ],
  //   "receiveWhitelist": [
  //     "*"
  //   ],
  //   "uuid": "5c7392dc-a4ba-4b5a-8c84-5934a3b3678b",
  //   "online": false,
  //   "token": "9e78f644a866e1b5b71d0a2dde912e8662477abf",
  //   "meshblu": {
  //     "createdAt": "2016-05-20T22:10:23+00:00",
  //     "hash": "kt8lmSb5r6ruHG41jqZZHp1CEQvzM1iMJ/kAUppryZo="
  //   }
  // }
});

To register a new closed device.

meshblu.register({color: 'black', version: '2.0.0'}, function(device){
  console.log('register');
  console.log(JSON.stringify(device, null, 2))
  // {
  //   "color": "black",
  //   "uuid": "5c7392dc-a4ba-4b5a-8c84-5934a3b3678b",
  //   "online": false,
  //   "token": "9e78f644a866e1b5b71d0a2dde912e8662477abf",
  //   "meshblu": {
  //     "version": "2.0.0",
  //     "createdAt": "2016-05-20T22:10:23+00:00",
  //     "hash": "kt8lmSb5r6ruHG41jqZZHp1CEQvzM1iMJ/kAUppryZo="
  //   }
  // }
});

meshblu.resetToken(query, callback)

Reset the root token of a device. This will revoke the existing root token, generate a new one, and yield the generated token in the callback.

Arguments
Example

To reset a token for a device:

meshblu.resetToken({uuid: '5c7392dc-a4ba-4b5a-8c84-5934a3b3678b'}, function(response){
  console.log('resetToken');
  console.log(JSON.stringify(device, null, 2));
  // resetToken
  // {
  //   "device": {
  //     "uuid": "2f9556ff-1084-4d4c-b131-5d3de42eff68",
  //     "token": "cc2f1fba8ffd7a46f4f414daf1011c2053e9a466"
  //   }
  // }
});

meshblu.revokeToken(auth, callback)

Revoke a session token for a device

Arguments
Example

To revoke a token for a device:

meshblu.revokeToken({uuid: '5c7392dc-a4ba-4b5a-8c84-5934a3b3678b', token: '9e78f644a866e1b5b71d0a2dde912e8662477abf'}, function(){
  console.log('revokeToken');
});

meshblu.subscribe(params)

Create a subscription to a device's messages. Subscribe tries to subscribe the connection to every message type. To limit subscriptions, use the types attribute.

Arguments
Example

To subscribe to everything allowed for a device:

meshblu.subscribe({uuid: '5c7392dc-a4ba-4b5a-8c84-5934a3b3678b'});

To subscribe to only broadcasts:

meshblu.subscribe({uuid: '5c7392dc-a4ba-4b5a-8c84-5934a3b3678b', type: ['broadcast']});

meshblu.unregister(query, callback)

Remove a device from the Meshblu device registry. In order to unregister a target device, your connection must be authenticated as a device that is in the target device's configure.update whitelist. See the Meshblu whitelist documentation for more information.

Arguments
Note

In Meshblu, it is not possible to distinguish between a device not existing and not having permission to view a device. In most of the Meshblu API calls, the error in both cases yields the protocol-specific equivalent of an HTTP 404: Not Found. The Socket.IO API, however, returns the error Forbidden. This is for backwards compatibility and will likely change with the next major version release of the Socket.IO API.

Example

When unregister is called for a device the authenticated device may modify:

meshblu.unregister({uuid: 'f52d8b52-ef04-44d3-ae45-59dfec2f7663'}, function(result){
  console.log('unregister');
  console.log(JSON.stringify(result, null, 2));
  // unregister
  // {
  //   "uuid": "f52d8b52-ef04-44d3-ae45-59dfec2f7663"
  // }
});

When unregister is called for a non-existing device, or device the authenticated device may modify:

meshblu.unregister({uuid: 'i-made-this-uuid-up'}, function(result){
  console.log('unregister');
  console.log(JSON.stringify(result, null, 2));
  // unregister
  // {
  //   "error": "Forbidden"
  // }
});

meshblu.unsubscribe(params)

Remove a subscription to a device's messages. Unsubscribe tries to unsubscribe the connection from every message type. To limit what is unsubscribed, use the types attribute.

Arguments
Example

To unsubscribe from everything allowed for a device:

meshblu.subscribe({uuid: '5c7392dc-a4ba-4b5a-8c84-5934a3b3678b'});

To unsubscribe from only broadcasts:

meshblu.subscribe({uuid: '5c7392dc-a4ba-4b5a-8c84-5934a3b3678b', type: ['broadcast']});

meshblu.update(query/update, callback)

Update a device in the Meshblu device registry. In order to update a target device, your connection must be authenticated as a device that is in the target device's configure.update whitelist. See the Meshblu whitelist documentation for more information.

Arguments
Example

Updating a device:

meshblu.update({uuid: 'c30a7506-7a45-4fe1-ab51-c57afad7f41a', color: 'blue'}, function(result){
  console.log('update');
  console.log(JSON.stringify(result, null, 2));
  // update
  // {
  //   "uuid": "78159106-41ca-4022-95e8-2511695ce64c",
  //   "status": 200
  // }
});

When updating a non-existing devices, or a device the authenticated connection may not update:

meshblu.update({uuid: 'i-made-this-uuid-up', color: 'blue'}, function(result){
  console.log('update');
  console.log(JSON.stringify(result, null, 2));
  // update
  // {
  //   "uuid": "i-made-this-uuid-up",
  //   "status": 200
  // }
});

meshblu.whoami(callback)

Retrieve the device the connection is currently authenticated as from the Meshblu device registery.

Arguments
Example

Calling whoami: When whoami is called:

meshblu.whoami(function(device){
  console.log('whoami');
  console.log(JSON.stringify(device, null, 2));
  // whoami
  // {
  //   "meshblu": {
  //     "version": "2.0.0",
  //     "whitelists": {},
  //     "createdAt": "2016-05-19T23:28:08+00:00",
  //     "hash": "4ez1I/uziZVk7INf6n1un+op/oNsIDoFVs/MW/KGWMQ=",
  //     "updatedAt": "2016-05-20T16:07:57+00:00"
  //   },
  //   "uuid": "78159106-41ca-4022-95e8-2511695ce64c",
  //   "online": true
  // }
});