more robust serial conn establishment

Instead of trying to establish the serial connection in the Board constructor,
delegate this to a separate `setup()`. (**API change**!)
This allows the user to add listeners to the Board’s `error` event, which
signifies that the connection could not be established. (This was already
intended, but wasn't possible, as far as I can tell.)
Also displays a more intuitive error message.

Author: tjanson

lib/board.js

@@ -1,4 +1,3 @@
-
 var events = require('events'),
     child  = require('child_process'),
     util   = require('util'),
@@ -7,24 +6,37 @@ var events = require('events'),
 
 /*
  * The main Arduino constructor
- * Connect to the serial port and bind
+ *
+ * [NEW] Does *not* open a serial connection. Add a `setup()` call to do so.
+ *
+ * This allows the user to add a listener for error events that occur
+ * during the serial connection attempts.
  */
 var Board = function (options) {
   this.log('info', 'initializing');
-  this.debug = options && options.debug || false;
-  this.device = options && options.device || 'usb|ttyACM*|ttyS0';
+  this.debug    = options && options.debug    || false;
+  this.devregex = options && options.devregex || 'usb|ttyACM*|ttyS0';
   this.baudrate = options && options.baudrate || 115200;
   this.writeBuffer = [];
+}
+
+/*
+ * EventEmitter, I choose you!
+ */
+util.inherits(Board, events.EventEmitter);
 
+/*
+ * Establish the serial connection
+ *
+ * Tries to open a serial connection with `connectSerial()`.
+ * If successful, the connection is initialized ("clearing bytes", debug mode).
+ * If unsuccessful, error event is emitted; if no listeners: error is thrown.
+ */
+Board.prototype.setup = function() {
   var self = this;
-  this.detect(function (err, serial) {
-    if (err) {
-      if(self.listeners('error').length)
-        self.emit('error', err);
-      else
-        throw new Error(err);
-    }else{
-      self.serial = serial;
+  this.connectSerial(function(found) {
+    if (found) {
+      self.serial = found;
       self.emit('connected');
 
       self.log('info', 'binding serial events');
@@ -56,52 +68,69 @@ var Board = function (options) {
 
         self.emit('ready');      
       }, 500);
+    } else {
+      msg = "Could not establish Serial connection to Arduino.";
+      if (self.listeners('error').length > 0) {
+        self.emit('error', msg);
+      } else {
+        throw new Error(msg);
+      }
     }
   });
 }
 
 /*
- * EventEmitter, I choose you!
+ * (Tries to) Open serial connection with Arduino (formerly named `detect()`)
+ *
+ * Loops through devices matching `devregex` and naively tries to open a serial
+ * connection with each until one succeeds.
+ * This should really message the device and wait for a correct response to
+ * ensure that we're actually connected to an Arduino running `duino`. FIXME
+ *
+ * Returns false if no serial connection could be established.
  */
-util.inherits(Board, events.EventEmitter);
-
-/*
- * Detect an Arduino board
- * Loop through all USB devices and try to connect
- * This should really message the device and wait for a correct response
- */
-Board.prototype.detect = function (callback) {
+Board.prototype.connectSerial = function (callback) {
   this.log('info', 'attempting to find Arduino board');
   var self = this;
-  child.exec('ls /dev | grep -E "'+ self.device +'"', function(err, stdout, stderr){
-    var usb = stdout.slice(0, -1).split('\n'),
-        found = false,
-        err = null,
-        possible, temp;
-
-    while ( usb.length ) {
-      possible = usb.pop();
-
-      if (possible.slice(0, 2) !== 'cu') {
-        try {
-          temp = new serial.SerialPort('/dev/' + possible, {
-            baudrate: self.baudrate,
-            parser: serial.parsers.readline('\n')
-          });
-        } catch (e) {
-          err = e;
-        }
-        if (!err) {
-          found = temp;
-          self.log('info', 'found board at ' + temp.port);
-          break;
-        } else {
-          err = new Error('Could not find Arduino');
-        }
-      }
+  child.exec('ls /dev | grep -E "'+ self.devregex +'"', function(err, stdout, stderr){
+
+    function skipUnwanted(e) {
+      return (e !== '') && (e.slice(0, 2) !== 'cu');
     }
 
-    callback(err, found);
+    var devices = stdout.slice(0, -1).split('\n').filter(skipUnwanted),
+        device,
+        candidate;
+
+    // loop over list of possible Arduinos
+    // do not stop (even/especially on error, that's the point!) until
+    //  - we run out of options, or
+    //  - a serial connection is established
+    var success = devices.some(function(device) {
+      try {
+        self.log('debug', 'attempting to open serial conn.: ' + device);
+        candidate = new serial.SerialPort('/dev/' + device, {
+          baudrate: self.baudrate,
+          parser: serial.parsers.readline('\n')
+        });
+
+        // connection succeeded, though we don't test whether it's an Arduino
+        self.log('info', 'found board at /dev/' + device);
+        return true;
+
+      } catch (e) {
+        // ignore error and cont.
+        self.log('warning', 'error while establishing serial connection with'
+                            + '/dev/' + device + '; trying next');
+        return false;
+      }
+    });
+
+    if (success) {
+      callback(candidate);
+    } else {
+      callback(false);
+    }
   });
 }
 
@@ -137,18 +166,17 @@ Board.prototype.write = function (m) {
   }
 }
 
-/*
- * Add a 0 to the front of a single-digit pin number
- */
+// Add a 0 to the front of a single-digit pin number
 Board.prototype.normalizePin = function (pin) {
   return this.lpad( 2, '0', pin );
 }
 
+// Left-pad values with 0s so it has three digits.
 Board.prototype.normalizeVal = function(val) {
-	return this.lpad( 3, '0', val );
+  return this.lpad( 3, '0', val );
 }
 
-//
+// Left-pad `str` with `chr` and return the last `len` digits
 Board.prototype.lpad = function(len, chr, str) {
   return (Array(len + 1).join(chr || ' ') + str).substr(-len);
 };

package.json

@@ -16,7 +16,7 @@
   ],
   "name": "duino",
   "description": "Arduino framework for mad scientists",
-  "version": "0.0.11",
+  "version": "0.1.0",
   "keywords": [
     "arduino",
     "serial",