From a3ccf23a7e146d62a1f2f15389afc1cd24f35554 Mon Sep 17 00:00:00 2001
From: Mark Slee <mcslee@Mark-Slees-MacBook-Pro.local>
Date: Thu, 22 Aug 2013 01:19:39 -0700
Subject: [PATCH] Documentation on mapping functionality

---
 _Mappings.pde    | 13 ++++++++++++-
 _PandaDriver.pde | 40 +++++++++++++++++++++++++++++++++++++---
 2 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/_Mappings.pde b/_Mappings.pde
index 91bd543..01aaa2a 100644
--- a/_Mappings.pde
+++ b/_Mappings.pde
@@ -22,8 +22,10 @@ public Model buildModel() {
   final Cube.Wiring WRL = Cube.Wiring.REAR_LEFT;
   final Cube.Wiring WRR = Cube.Wiring.REAR_RIGHT;
   
+  // Utility value if you need the height of a cube shorthand
   final float CH = Cube.EDGE_HEIGHT;
   
+  // Positions for the bass box
   final float BBY = BassBox.EDGE_HEIGHT + BoothFloor.PLEXI_WIDTH;
   final float BBX = 56;
   final float BBZ = 2;
@@ -78,10 +80,15 @@ public Model buildModel() {
 
   // The speakers!
   List<Speaker> speakers = Arrays.asList(new Speaker[] {
+    // each speaker parameter is x, y, z, rotation, the left speaker comes first
     new Speaker(-12, 6, 0, 15),
     new Speaker(TRAILER_WIDTH - Speaker.EDGE_WIDTH + 8, 6, 3, -15)
   });
 
+  //////////////////////////////////////////////////////////////////////
+  //      BENEATH HERE SHOULD NOT REQUIRE ANY MODIFICATION!!!!        //
+  //////////////////////////////////////////////////////////////////////
+
   // These guts just convert the shorthand mappings into usable objects
   ArrayList<Tower> towerList = new ArrayList<Tower>();
   ArrayList<Cube> tower;
@@ -106,6 +113,10 @@ public Model buildModel() {
   return new Model(towerList, cubes, bassBox, speakers);
 }
 
+/**
+ * This function maps the panda boards. We have an array of them, each has
+ * an IP address and a list of channels.
+ */
 public PandaMapping[] buildPandaList() {
   final int LEFT_SPEAKER = 0;
   final int RIGHT_SPEAKER = 1;
@@ -119,7 +130,7 @@ public PandaMapping[] buildPandaList() {
         new ChannelMapping(),
         new ChannelMapping(),
         new ChannelMapping(),
-        new ChannelMapping(),        
+        new ChannelMapping(),
         new ChannelMapping(ChannelMapping.MODE_BASS),
         new ChannelMapping(ChannelMapping.MODE_STRUTS_AND_FLOOR),
         new ChannelMapping(ChannelMapping.MODE_SPEAKER, LEFT_SPEAKER),
diff --git a/_PandaDriver.pde b/_PandaDriver.pde
index d6cd995..d2998a7 100644
--- a/_PandaDriver.pde
+++ b/_PandaDriver.pde
@@ -53,6 +53,40 @@ public static class PandaDriver {
   private final static int FORWARD = -1;
   private final static int BACKWARD = -2;
 
+  ////////////////////////////////////////////////////////////////
+  //
+  // READ THIS RIGHT NOW BEFORE YOU MODIFY THE BELOW!!!!!!!!!!!!!
+  // READ THIS RIGHT NOW BEFORE YOU MODIFY THE BELOW!!!!!!!!!!!!!
+  // READ THIS RIGHT NOW BEFORE YOU MODIFY THE BELOW!!!!!!!!!!!!!
+  //
+  // The mappings below indicate the physical order of strips
+  // connected to a pandaboard channel. The strip numbers are a
+  // reflection of how the model is built.
+  //
+  // For ANYTHING in the model which is a rectangular prism,
+  // which means Cubes, the BassBox, and each Speaker, the
+  // strips are numbered incrementally by face. The first
+  // face is always the FRONT, which you are looking at.
+  // The next face is the RIGHT, then the BACK, then the LEFT.
+  //
+  // For every face, the strips are ordered numerically moving
+  // clockwise from the the TOP LEFT.
+  //
+  // So, for a cube:
+  //
+  //  Strip 0: front face, top strip, left to right
+  //  Strip 1: front face, right strip, top to bottom
+  //  Strip 2: front face, bottom strip, right to left
+  //  Strip 3: front face, left strip, bottom to top
+  //
+  //  Strip 4: right face, top strip, left to right
+  //  ... and so on
+  //  Strip 14: left face, bottom strip, right to left
+  //  Strip 15: left face, left strip, bottom to top
+  //
+  ////////////////////////////////////////////////////////////////
+  
+
   /**
    * These constant arrays indicate the order in which the strips of a cube
    * are wired. There are four different options, depending on which bottom
@@ -67,8 +101,8 @@ public static class PandaDriver {
   
   private final static int[][] BASS_STRIP_ORDERING = {
     // front face, counterclockwise from bottom front left
-    {2, BACKWARD }, 
-    {1, BACKWARD },
+    {2, BACKWARD /* if this strip has extra pixels, you can add them here */ /*, 4 */ }, 
+    {1, BACKWARD /* if this strip is short some pixels, substract them here */ /*, -3 */ },
     {0, BACKWARD },
     {3, BACKWARD },
     
@@ -98,7 +132,7 @@ public static class PandaDriver {
     {3, FORWARD},
     {2, BACKWARD},
     {1, FORWARD},
-    {0, BACKWARD, /* dummy pixels at the end of string, remove when strip is fixed  */ 4},
+    {0, BACKWARD},
     {7, FORWARD},    
   };
   
-- 
2.34.1