p71924506
/
cylon
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #122 from hybridgroup/pure-js-comments 

Pure js comments
This commit is contained in:
Ron Evans 2014-02-27 15:18:01 -08:00
parent 9ef38a6a02 933c5d2660
commit d70785328f
9 changed files with 286 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
lib/api.js
View File

@ -12,6 +12,8 @@ var express = require('express.io');
var namespace = require('node-namespace');
namespace("Cylon", function() {
// The Cylon API Server provides an interface to communicate with master class
// and retrieve information about the robots being controlled.
this.ApiServer = (function() {
var master;
@ -40,6 +42,9 @@ namespace("Cylon", function() {
});
}
// Parses req to extract params to be used for commands.
//
// Returns an array of params
ApiServer.prototype.parseCommandParams = function(req) {
var param_container, params, v, _;
params = [];

38
lib/basestar.js
View File

@ -12,6 +12,11 @@ require('./utils');
var namespace = require('node-namespace');
var EventEmitter = require('events').EventEmitter;
// Basestar is a base class to be used when writing external Cylon adaptors and
// drivers. It provides some useful base methods and functionality
//
// It also extends EventEmitter, so child classes are capable of emitting events
// for other parts of the system to handle.
namespace("Cylon", function() {
this.Basestar = (function(klass) {
subclass(Basestar, klass);
@ -20,6 +25,14 @@ namespace("Cylon", function() {
this.self = this;
}
// Public: Proxies calls from all methods in the object to a target object
//
// methods - array of methods to proxy
// target - object to proxy methods to
// source - object to proxy methods from
// force - whether or not to overwrite existing method definitions
//
// Returns the klass where the methods have been proxied
Basestar.prototype.proxyMethods = function(methods, target, source, force) {
if (force == null) {
force = false;
@ -27,6 +40,17 @@ namespace("Cylon", function() {
return proxyFunctionsToObject(methods, target, source, force);
};
// Public: Defines an event handler that proxies events from a source object
// to a target object
//
// opts - object containing options:
// - targetEventName or eventName - event that should be emitted from the
// target
// - target - object to proxy event to
// - source - object to proxy event from
// - update - whether or not to send an 'update' event
//
// Returns the source
Basestar.prototype.defineEvent = function(opts) {
var sendUpdate, targetEventName,
_this = this;
@ -43,6 +67,13 @@ namespace("Cylon", function() {
return opts.source;
};
// Public: Creates an event handler that proxies events from an adaptor's
// 'connector' (reference to whatever module is actually talking to the hw)
// to the adaptor's associated connection.
//
// opts - hash of opts to be passed to defineEvent()
//
// Returns @connector
Basestar.prototype.defineAdaptorEvent = function(opts) {
opts['source'] = this.connector;
opts['target'] = this.connection;
@ -52,6 +83,13 @@ namespace("Cylon", function() {
return this.defineEvent(opts);
};
// Public: Creates an event handler that proxies events from an device's
// 'connector' (reference to whatever module is actually talking to the hw)
// to the device's associated connection.
//
// opts - hash of opts to be passed to defineEvent()
//
// Returns @connection
Basestar.prototype.defineDriverEvent = function(opts) {
opts['source'] = this.connection;
opts['target'] = this.device;

22
lib/config.js
View File

@ -10,6 +10,28 @@
var namespace = require('node-namespace');
// Public: Fetches a variable from the environment, returning a provided value if
// it's not set.
//
// variable - variable to fetch from the environment
// defaultValue - value to return if the ENV variable isn't set
//
// Examples
//
// process.env["CYLON_TEST"] #=> undefined
// fetch("CYLON_TEST", "not set")
// #=> "not set"
//
// process.env["CYLON_TEST"] #=> false
// fetch("CYLON_TEST", true)
// #=> false
//
// process.env["CYLON_TEST"] #=> true
// fetch("CYLON_TEST", false)
// #=> true
//
// Returns the env var or default value
var fetch = function(variable, defaultValue) {
if (defaultValue == null) {
defaultValue = false;

31
lib/connection.js
View File

@ -15,10 +15,24 @@ var namespace = require('node-namespace');
var EventEmitter = require('events').EventEmitter;
var __bind = function(fn, me){ return function(){ return fn.apply(me, arguments); }; }
// The Connection class represents the interface to
// a specific group of hardware devices. Examples would be an
// Arduino, a Sphero, or an ARDrone.
namespace("Cylon", function() {
this.Connection = (function(klass) {
subclass(Connection, klass);
// Public: Creates a new Connection
//
// opts - hash of acceptable params:
// id - string ID for the connection
// robot - Robot the Connection belongs to
// name - name for the connection
// adaptor - string module name of the adaptor to be set up
// port - string port to use for the Connection
//
// Returns the newly set-up connection
function Connection(opts) {
if (opts == null) {
opts = {};
@ -36,6 +50,9 @@ namespace("Cylon", function() {
proxyFunctionsToObject(this.adaptor.commands(), this.adaptor, this.self);
}
// Public: Exports basic data for the Connection
//
// Returns an Object containing Connection data
Connection.prototype.data = function() {
return {
name: this.name,
@ -45,6 +62,11 @@ namespace("Cylon", function() {
};
};
// Public: Connect the adaptor's connection
//
// callback - callback function to run when the adaptor is connected
//
// Returns the result of the supplied callback function
Connection.prototype.connect = function(callback) {
var msg;
msg = "Connecting to '" + this.name + "'";
@ -55,6 +77,9 @@ namespace("Cylon", function() {
return this.adaptor.connect(callback);
};
// Public: Disconnect the adaptor's connection
//
// Returns nothing
Connection.prototype.disconnect = function() {
var msg;
msg = "Disconnecting from '" + this.name + "'";
@ -65,6 +90,12 @@ namespace("Cylon", function() {
return this.adaptor.disconnect();
};
// Public: sets up adaptor with @robot
//
// opts - options for adaptor being initialized
// adaptor - name of the adaptor
//
// Returns the set-up adaptor
Connection.prototype.initAdaptor = function(opts) {
Logger.debug("Loading adaptor '" + opts.adaptor + "'");
return this.robot.initAdaptor(opts.adaptor, this.self, opts);

40
lib/device.js
View File

@ -13,11 +13,24 @@ require('./driver');
var namespace = require('node-namespace');
var EventEmitter = require('events').EventEmitter;
var __bind = function(fn, me){ return function(){ return fn.apply(me, arguments); }; }
// The Artoo::Device class represents the interface to
// a specific individual hardware devices. Examples would be a digital
// thermometer connected to an Arduino, or a Sphero's accelerometer
namespace("Cylon", function() {
this.Device = (function(klass) {
subclass(Device, klass);
// Public: Creates a new Device
//
// opts - object containing Device params
// name - string name of the device
// pin - string pin of the device
// robot - parent Robot to the device
// connection - connection to the device
// driver - string name of the module the device driver logic lives in
//
// Returns a new Device
function Device(opts) {
if (opts == null) {
opts = {};
@ -33,6 +46,11 @@ namespace("Cylon", function() {
proxyFunctionsToObject(this.driver.commands(), this.driver, this.self);
}
// Public: Starts the device driver
//
// callback - callback function to be executed by the driver start
//
// Returns result of supplied callback
Device.prototype.start = function(callback) {
var msg;
msg = "Starting device '" + this.name + "'";
@ -43,11 +61,17 @@ namespace("Cylon", function() {
return this.driver.start(callback);
};
// Public: Stops the device driver
//
// Returns result of supplied callback
Device.prototype.stop = function() {
Logger.info("Stopping device '" + this.name + "'");
return this.driver.stop();
};
// Public: Exports basic data for the Connection
//
// Returns an Object containing Connection data
Device.prototype.data = function() {
return {
name: this.name,
@ -58,12 +82,20 @@ namespace("Cylon", function() {
};
};
// Public: Retrieves the connections from the parent Robot instances
//
// c - name of the connection to fetch
//
// Returns a Connection instance
Device.prototype.determineConnection = function(c) {
if (c) {
return this.robot.connections[c];
}
};
// Public: Returns a default Connection to use
//
// Returns a Connection instance
Device.prototype.defaultConnection = function() {
var first, k, v, _ref;
first = 0;
@ -75,6 +107,12 @@ namespace("Cylon", function() {
return first;
};
// Public: sets up driver with @robot
//
// opts - object containing options when initializing driver
// driver - name of the driver to intt()
//
// Returns the set-up driver
Device.prototype.initDriver = function(opts) {
if (opts == null) {
opts = {};

10
lib/digital-pin.js
View File

@ -12,6 +12,8 @@ var FS = require('fs');
var EventEmitter = require('events').EventEmitter;
var namespace = require('node-namespace');
// DigitalPin class offers an interface with the Linux GPIO system present in
// single-board computers such as a Raspberry Pi, or a BeagleBone
namespace("Cylon.IO", function() {
this.DigitalPin = (function(klass) {
subclass(DigitalPin, klass);
@ -74,6 +76,12 @@ namespace("Cylon.IO", function() {
return value;
};
// Public: Reads the digial pin's value periodicly on a supplied interval,
// and emits the result or an error
//
// interval - time (in milliseconds) to read from the pin at
//
// Returns the defined interval
DigitalPin.prototype.digitalRead = function(interval) {
var readData,
_this = this;
@ -109,6 +117,7 @@ namespace("Cylon.IO", function() {
}
};
// Creates the GPIO file to read/write from
DigitalPin.prototype._createGPIOPin = function() {
var _this = this;
return FS.writeFile(this._exportPath(), "" + this.pinNum, function(err) {
@ -133,6 +142,7 @@ namespace("Cylon.IO", function() {
}
};
// Sets the mode for the GPIO pin by writing the correct values to the pin reference files
DigitalPin.prototype._setMode = function(mode, emitConnect) {
var _this = this;
if (emitConnect == null) {

22
lib/driver.js
View File

@ -11,10 +11,20 @@
require('./basestar');
var namespace = require('node-namespace');
// The Driver class is a base class for Driver classes in external Cylon
// modules to use. It offers basic functions for starting/stopping that
// descendant classes can.
namespace("Cylon", function() {
this.Driver = (function(klass) {
subclass(Driver, klass);
// Public: Creates a new Driver
//
// opts - hash of acceptable params
// name - name of the Driver, used when printing to console
// device - Device the driver will use to proxy commands/events
//
// Returns a new Driver
function Driver(opts) {
if (opts == null) {
opts = {};
@ -26,10 +36,19 @@ namespace("Cylon", function() {
this.commandList = [];
}
// Public: Exposes all commands the driver will respond to/proxy
//
// Returns an array of string method names
Driver.prototype.commands = function() {
return this.commandList;
};
// Public: Starts up the driver, and emits 'connect' from the @device
// when done.
//
// callback - function to run when the driver is started
//
// Returns nothing
Driver.prototype.start = function(callback) {
Logger.info("Driver " + this.name + " started");
callback(null);
@ -37,6 +56,9 @@ namespace("Cylon", function() {
return true;
};
// Public: Stops the driver
//
// Returns nothing
Driver.prototype.stop = function() {
return Logger.info("Driver " + this.name + " stopped");
};

19
lib/port.js
View File

@ -10,27 +10,42 @@
var namespace = require('node-namespace');
// The Port class represents a port and/or host to be used to connect to
// a specific hardware device
namespace("Cylon", function() {
return this.Port = (function() {
// Public: Creates a new Port based on a passed String representation
//
// data - string representation of the Port
//
// Returns a new Port
function Port(data) {
this.self = this;
this.isTcp = this.isSerial = this.isPortless = false;
this.parse(data);
}
// Public: Parses the Port's data to determine what kind of port it is
//
// data - string representation of the port to parse
//
// Returns nothing.
Port.prototype.parse = function(data) {
var match;
if (data === void 0) {
this.port = void 0;
return this.isPortless = true;
// is TCP host/port?
} else if (match = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}):(\d{1,5})/.exec(data)) {
this.port = match[2];
this.host = match[1];
return this.isTcp = true;
// is it a numeric port for localhost tcp?
} else if (/^[0-9]{1,5}$/.exec(data)) {
this.port = data;
this.host = "localhost";
return this.isTcp = true;
// must be a serial port
} else {
this.port = data;
this.host = void 0;
@ -38,6 +53,10 @@ namespace("Cylon", function() {
}
};
// Public: Returns a string representation of the port that can be used to
// connect to it.
//
// Returns a string
Port.prototype.toString = function() {
if (this.isPortless) {
return "none";

101
lib/robot.js
View File

@ -23,10 +23,35 @@ var EventEmitter = require('events').EventEmitter;
var namespace = require('node-namespace');
// A Robot is the primary interface for interacting with a collection of physical
// computing capabilities.
namespace("Cylon", function() {
this.Robot = (function(klass) {
subclass(Robot, klass);
// Public: Creates a new Robot
//
// opts - object containing Robot options
// name - optional, string name of the robot
// master - Cylon.Master class that orchestrates robots
// connection/connections - object connections to connect to
// device/devices - object devices to connect to
// work - work to be performed when the Robot is started
//
// Returns a new Robot
// Example (CoffeeScript):
// Cylon.robot
// name: "Spherobot!"
//
// connection:
// name: 'sphero', adaptor: 'sphero', port: '/dev/rfcomm0'
//
// device:
// name: 'sphero', driver: 'sphero'
//
// work: (me) ->
// every 1.second(), ->
// me.sphero.roll 60, Math.floor(Math.random() * 360//
function Robot(opts) {
var func, n, reserved;
if (opts == null) {
@ -70,10 +95,16 @@ namespace("Cylon", function() {
}
}
// Public: Generates a random name for a Robot.
//
// Returns a string name
Robot.randomName = function() {
return "Robot " + (Math.floor(Math.random() * 100000));
};
// Public: Exports basic data for the Robot
//
// Returns an Object containing Robot data
Robot.prototype.data = function() {
var connection, device, n;
return {
@ -102,6 +133,11 @@ namespace("Cylon", function() {
};
};
// Public: Initializes all connections for the robot
//
// connections - connections to initialize
//
// Returns initialized connections
Robot.prototype.initConnections = function(connections) {
var connection, _i, _len;
Logger.info("Initializing connections...");
@ -118,6 +154,11 @@ namespace("Cylon", function() {
return this.connections;
};
// Public: Initializes all devices for the robot
//
// devices - devices to initialize
//
// Returns initialized devices
Robot.prototype.initDevices = function(devices) {
var device, _i, _len, _results;
Logger.info("Initializing devices...");
@ -135,6 +176,11 @@ namespace("Cylon", function() {
return _results;
};
// Public: Starts the Robot working.
//
// Starts the connections, devices, and work.
//
// Returns the result of the work
Robot.prototype.start = function() {
var _this = this;
return this.startConnections(function() {
@ -147,6 +193,11 @@ namespace("Cylon", function() {
});
};
// Public: Starts the Robot's connections and triggers a callback
//
// callback - callback function to be triggered
//
// Returns nothing
Robot.prototype.startConnections = function(callback) {
var connection, n, starters, _ref;
Logger.info("Starting connections...");
@ -160,6 +211,11 @@ namespace("Cylon", function() {
return Async.parallel(starters, callback);
};
// Public: Starts the Robot's devices and triggers a callback
//
// callback - callback function to be triggered
//
// Returns nothing
Robot.prototype.startDevices = function(callback) {
var device, n, starters, _ref;
Logger.info("Starting devices...");
@ -173,6 +229,11 @@ namespace("Cylon", function() {
return Async.parallel(starters, callback);
};
// Public: Stops the Robot working.
//
// Stops the devices, disconnects the connections.
//
// Returns nothing
Robot.prototype.stop = function() {
var connection, device, n, _ref, _ref1, _results;
_ref = this.devices;
@ -189,6 +250,12 @@ namespace("Cylon", function() {
return _results;
};
// Public: Initialize an adaptor and adds it to @robot.adaptors
//
// adaptorName - module name of adaptor to require
// connection - the Connection that requested the adaptor be required
//
// Returns the adaptor
Robot.prototype.initAdaptor = function(adaptorName, connection, opts) {
var realAdaptor, testAdaptor;
if (opts == null) {
@ -211,6 +278,11 @@ namespace("Cylon", function() {
}
};
// Public: Requires a hardware adaptor and adds it to @robot.adaptors
//
// adaptorName - module name of adaptor to require
//
// Returns the module for the adaptor
Robot.prototype.requireAdaptor = function(adaptorName) {
if (this.robot.adaptors[adaptorName] == null) {
this.robot.registerAdaptor("cylon-" + adaptorName, adaptorName);
@ -219,12 +291,25 @@ namespace("Cylon", function() {
return this.robot.adaptors[adaptorName];
};
// Public: Registers an Adaptor with the Robot
//
// moduleName - name of the Node module to require
// adaptorName - name of the adaptor to register the moduleName under
//
// Returns the registered module name
Robot.prototype.registerAdaptor = function(moduleName, adaptorName) {
if (this.adaptors[adaptorName] == null) {
return this.adaptors[adaptorName] = require(moduleName);
}
};
// Public: Init a hardware driver
//
// driverName - driver name
// device - the Device that requested the driver be initialized
// opts - object containing options when initializing driver
//
// Returns the new driver
Robot.prototype.initDriver = function(driverName, device, opts) {
var realDriver, testDriver;
if (opts == null) {
@ -245,8 +330,13 @@ namespace("Cylon", function() {
} else {
return realDriver;
}
};
};
// Public: Requires module for a driver and adds it to @robot.drivers
//
// driverName - module name of driver to require
//
// Returns the module for driver
Robot.prototype.requireDriver = function(driverName) {
if (this.robot.drivers[driverName] == null) {
this.robot.registerDriver("cylon-" + driverName, driverName);
@ -255,12 +345,21 @@ namespace("Cylon", function() {
return this.robot.drivers[driverName];
};
// Public: Registers an Driver with the Robot
//
// moduleName - name of the Node module to require
// driverName - name of the driver to register the moduleName under
//
// Returns the registered module nam//
Robot.prototype.registerDriver = function(moduleName, driverName) {
if (this.drivers[driverName] == null) {
return this.drivers[driverName] = require(moduleName);
}
};
// Public: Returns basic info about the robot as a String
//
// Returns a String
Robot.prototype.toString = function() {
return "[Robot name='" + this.name + "']";
};