add troubleshooting section

[challenge-bot] / guide / hausner / overview.org

diff --git a/guide/hausner/overview.org b/guide/hausner/overview.org
index 8a50e2ac76cf7fc591704b81a32f08ae634a4240..b73f7283dd07ac04ccab11da4e3638e5362606f3 100644 (file)
--- a/guide/hausner/overview.org
+++ b/guide/hausner/overview.org
@@ -1,32 +1,75 @@
+#+TITLE:hausner challenge-bot overview
 * challenge-bot robot overview
 ** videos for assembling the hardware
-** content
-*** software
-    software is available as nice neat installable packages for
-    Mac OS X, GNU+Linux, and MS Windows.
-
-    it's also available in source code form, so you can compile it for
-    other platforms.
-
-    all software used in this robot is available for you to use for any
-    purpose, improve, and, share those improvements (if you want).
-**** arduino
-***** summary
-      control how the robot gets information from sensors, and moves
-      its motors.
-***** download
-      https://www.arduino.cc/en/Main/Software
-**** openscad
-***** summary
-      create robot parts!
-
-      use this program to view parts inside the "3d-printables"
-      directory.  write code to modify the parts and create completely
-      new ones.
-***** download
-      http://www.openscad.org/downloads.html
-**** fritzing
-***** summary
-      wire up components!
-***** download
-      http://fritzing.org/download/?donation=0
+** software
+   software is available as nice neat installable packages for
+   Mac OS X, GNU+Linux, and MS Windows.
+
+   it's also available in source code form, so you can compile it for
+   other platforms.
+
+   all software used in this robot is available for you to use for any
+   purpose, improve, and, share those improvements (if you want).
+*** arduino
+**** summary
+     control how the robot gets information from sensors, and moves
+     its motors.
+**** download
+     https://www.arduino.cc/en/Main/Software
+*** openscad
+**** summary
+     create robot parts!
+
+     use this program to view parts inside the "3d-printables"
+     directory.  write code to modify the parts and create completely
+     new ones.
+**** download
+     http://www.openscad.org/downloads.html
+*** fritzing
+**** summary
+     wire up components!
+**** download
+     http://fritzing.org/download/?donation=0
+*** 7-zip
+**** summary
+     extract the contents of .tgz files, like the content of this class.
+
+     this is needed on MS Windows(tm) only.
+
+     if you are on Mac OS X, or GNU (on cygwin or linux), then you do
+     not need this.  your software will be able to extract the
+     class content
+**** download
+     http://7-zip.org/
+** class content
+   all the source code for the class is available here:
+
+   http://challenge-bot.com/repos/?p=challenge-bot;a=snapshot;h=232ff7a14f9d8be27362c268c6cdd1b67f59a24a;sf=tgz
+
+   what follows is a high level description of the contents of the most
+   important top level directories in the class content.
+*** 3d-printables
+    the parts of the robot that are 3d-printed are in this directory.
+    use openscad to open the parts in this directory.
+*** build-stages
+    all the wiring diagrams and arduino code live in this directory.
+
+    under this directory, there is one subdirectory for each
+    build stage.
+    each build stage is prefixed with a letter to make it appear in
+    order.
+    for example, =a_serial= contains the first build stage.
+** troubleshooting
+    to troubleshoot a misbehaving robot, go through these stages
+    in order until you find a stage that does not work correctly.
+
+    first, in =a_serial=, you'll check whether the arduino can
+    communicate over the serial connection with the computer.
+
+    in each stage, make sure the wires shown in the fritzing
+    diagram are correctly connected on your robot.
+    then load the corresponding arduino sketch to your robot
+    and either check the serial monitor, or turn on the motor battery.
+
+    this will help you pinpoint exactly where the problem lies on your
+    robot.