Updates to Support Jetty & G3Firmware

.gitignore

@@ -4,3 +4,9 @@
 dist/*
 build/*
 MANIFEST
+*.svn
+virtualenv
+htmlcov
+build
+dist
+pys3g.egg-info

SConstruct

@@ -1,14 +1,27 @@
+# vim:ai:et:ff=unix:fileencoding=utf-8:sw=4:syntax=python:ts=4:
 #
 # Top-level SConstruct file for s3g.
 #
 
+import os,sys
+
 AddOption('--test', action='store_true', dest='test')
 run_test = GetOption('test')
 
-env = Environment()
+env = Environment(ENV = os.environ)
+
+if 'win32' == sys.platform:
+	vcmd=env.Command('virtualenv', 'setup.bat', 'setup.bat')
+else:
+	vcmd=env.Command('virtualenv', 'setup.sh', './setup.sh')
 
-#disabled until setup.py works
-#env.Command('build', 'setup.py', 'python setup.py')
+env.Clean(vcmd,'virtualenv')
 
 if run_test:
-    env.Command('test', 'unit_tests.py', 'python unit_tests.py')
+    if 'win32' == sys.platform:
+        env.Command('test', 'test.bat', 'test.bat')
+    else: 
+        env.Command('test', 'test.sh', 'test.sh')
+
+#if run_test:
+#    env.Command('test', 'unit_tests.py', 'python unit_tests.py')

doc/CheckResponseCode.dot

@@ -35,4 +35,12 @@ digraph
   "RESPONSE=CANCEL_BUILD?" [shape=diamond];
   "RESPONSE=CANCEL_BUILD?" -> "RAISE BUILD_CANCELLED_ERROR" [label="yes"];
   "RESPONSE=CANCEL_BUILD?" -> "RAISE PROTOCOL_ERROR" [label="no", weight=10];
+
+  "RESPONSE=ACTIVE_LOCAL_BUILD?" [shape=diamond];
+  "RESPONSE=ACTIVE_LOCAL_BUILD?" -> "RAISE ACTIVE_BUILD_ERROR" [label="yes"];
+  "RESPONSE=ACTIVE_LOCAL_BUILD?" -> "RAISE PROTOCOL_ERROR" [label="no", weight=10];
+
+  "RESPONSE=BOT_OVERHEAT?" [shape=diamond];
+  "RESPONSE=BOT_OVERHEAT?" -> "RAISE BOT_OVERHEAT_ERROR" [label="yes"];
+  "RESPONSE=BOT_OVERHEAT?" -> "RAISE PROTOCOL_ERROR" [label="no", weight=10];
 }

doc/bot_notifier.markdown

@@ -0,0 +1,61 @@
+#Machine Detector
+The Machine Detector is a python object used to discover different types of bots.
+
+##Purpose
+The Machine Detector is a utility that is meant to be run in the background of another service with the sole purpose of reporting the current machines plugged in, and any machines that have been added or removed from the host computer.
+
+##Instructions
+The Machine Detector can be initialized with:
+
+    mb = s3g.MachineDetector()
+
+To begin scanning for just one type of machine, put one machine name in a python list and pass it into the begin_scanning function:
+
+    mb.begin_scanning(['ReplicatorDual'])
+
+To begin scanning for multiple types of machines, put two machine names in a python list and pass it into the begin_scanning function:
+
+    mb.begin_scanning(['ReplicatorDual', 'Thing-O-Matic'])
+
+##Information Storage
+The Machine Detector stores all information in an internal python dictionary called 'ports'.  To access this dictionary:
+
+    myports = mb.ports
+
+Each type of machine being scanned for is a separate key.  That key is defined by an additional dict, which stores three specific values:
+
+* 'current_ports'
+* 'added_ports'
+* 'removed_ports'
+
+For instance, if we wanted to scan for a 'ReplicatorDual' and a 'Thing-O-Matic', the architecture of the ports dict would be:
+
+    {
+    "ReplicatorDual"  :   {
+          "current_ports" : [],
+          "added_ports"   : [],
+          "removed_ports" : [],
+          },
+    "Thing-O-Matic"   :   {
+          "current_ports" : [],
+          "added_ports"   : [],
+          "removed_ports" : [],
+          }
+    }
+
+##Scanning by VID/PID
+It is possible to scan for a specific VID/PID.  To do this:
+
+    md = s3g.MachineDetector()
+    current_ports = []
+    vid = <some_vid>
+    pid = <some_pid>
+    current_ports, added_ports, removed_ports = md.scan_serial_ports(current_ports, vid, pid)
+
+scan_serial_ports requires a python list of currently connected ports as its first parameter.  The function checks the newly ascertained ports against the parametized port list to find added and removed ports.
+
+##Find VID/PID of a machine
+To find the VID/PID information from a specific machine that has a fully defined machine profile:
+
+    md = s3g.MachineDetector()
+    vid, pid = md.get_vid_pid('ReplicatorDual')

doc/firmware_update.markdown

@@ -0,0 +1,44 @@
+#Firmware Update
+The s3g driver has the capability of uploading firmware to a machine via AVRDude, an external firmware uploading utility.  No AVRDude utility is packaged with this driver, so it is up to the user to satisfy this requirement.
+
+To download AVRDude, goto: www.nongnu.org/avrdude
+
+##Definitions
+<table>
+<tr>
+  <th>Name</th>
+  <th>Definition</th>
+</tr>
+<tr>
+  <td>Machine Board Profile</td>
+  <td>A .json file that contains information about a specific machine's board.</td>
+</tr>
+</table>
+
+##Uploading
+To upload firmware, an uploader object must first be created:
+
+    uploader = s3g.Firmware.Uploader()
+
+To actually upload firmware, call
+
+    uploader.upload(<port>, <machine name>, <version>)
+
+This will create the command line arguments and invoke AVRDude with the correct .hex file relative to the passed version. 
+
+##AVRDude Parameters
+S3G's uploader has access to several machine board profiles, each with a set of predefined defaults that are passed to AVRDude.  The machine board profile also has a dictionary of all firmware versions and their associated .hex files.
+
+##File exploring
+The uploader can explore and report back different bits of information related to the boards it knows about.  To get a list of boards the uploader and talk to:
+
+    uploader.list_machines()
+
+To get a list of possible firmware versions the uploader can upload to:
+
+    uploader.list_versions(<machine name>)
+
+##Overriding Default avrdude.conf file
+The Uploader has default avrdude.conf file specified.  To override, issue the following before invoking uploader.upload:
+
+    uploader.conf_path = <path to new avrdude.conf file>