zettajs/zetta-scout

A Scout class for Zetta.

zetta-scout

Installation

$ npm install zetta-scout --save

Reference and Usage

Class: Zetta.Scout

This is a class you inherit from when writing custom device drivers. Scouts are used to search for devices with external node modules, or protocols. It's used by require('zetta-scout'); or require('zetta').Scout;. You must inherit from the Scout class when building custom Zetta modules.

var util = require('util');
var Scout = require('zetta-scout');

function MyScout(){
  Scout.call(this);
}
util.inherits(MyScout, Scout);

Method: Scout#init(func)

• func Function

This method should be implemented by you. This allows you to initialize any resources like bluetooth access, serial ports, or vendor modules needed to look for devices. The argument func is provided, and must be called after scouting has started.

MyScout.prototype.init = function(next) {
  var connection = Serial.connect(function(){
  });

  connection.on('start', function(){
    next();
  });
};

Method: Scout#discover(constructor, [arguments])

• constructor Subclass of Device
• arguments List of Objects

This method is called by you when you've found your device. The constructor argument should be a subclass of Device, and the second argument is a list of objects to be used by the constructor.

MyScout.prototype.init = function(next) {
  this.discover(MyDevice, foo, bar, 'baz');
};

Method: Scout#provision(deviceObject, constructor)

• deviceObject Object
• constructor Subclass of Device

Zetta will persist device data to an internal registry. Using an object retrieved from this registry you can initialize a device that Zetta already knows about. The first argument deviceObject is just data on the object from Zetta. The constructor argument is what will be created by Zetta.

MyScout.prototype.init = function(next) {
  var deviceObject = {
    name:'testObject',
    id: '123',
    foo: 'bar'
  };
  this.provision(deviceObject, MyDevice);
};

Property: Scout#server

This gives access to the zetta runtime. Here you can issue queries and lookup devices that Zetta already knows about.

MyScout.prototype.init = function(next) {
  var self = this;

  // query registry for any device that has type led and an id that we know of.
  var query = this.server.where({ type: 'lcd', id: 'some-id' });
  this.server.find(query, function(err, results) {
    if (results.length > 0) {
      // found in registry, tell zetta it came online
      self.provision(results[0], MyDevice, foo, bar, 'baz');
    } else {
      // does not exist in registry, discover a new one.
      self.discover(MyDevice, foo, bar, 'baz');
    }
  });
};

zetta-scout's Issues

Provision Should Return Existing Device

The "good" path for Scout.prototype.provision returns the device instance. However, if the instance already exists, the result is null.

Is there a good reason for that? Feels weird to assume "success" if result is null or a returned device instance.

  // if already initiated on runtime do not create a second instnace
  if(this.server._jsDevices[deviceObject.id]) {
    return null;
  }

I'm asking because I'm in a situation where it looks like I have a false result (don't know for sure if null though) and so reach into _jsDevices for the device instance, and that is also falsey.

dev = self.provision(serverQueryResult, device, parameters);
if(!dev) {
  dev = self.server._jsDevices[result.id];
}
...
if(dev) {
 // success
} else {
  // CODE REACHES HERE
}

Provisioned name takes precedence over init name()

cf: zettajs/zetta#93