Reorganized docs index for more readability, added information about

Maple hardware and design files.  Other tweaks and improvements.

7 files changed, 147 insertions, 49 deletions

diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
index bf05832..93547f0 100644
--- a/docs/source/_templates/layout.html
+++ b/docs/source/_templates/layout.html
@@ -1,6 +1,5 @@
 {% extends "!layout.html" %}
 {% block rootrellink %}
-    <li><a href="http://leaflabs.com">LeafLabs</a> |</li>
-    <li><a href="index.html">Docs Home</a> |</li>
+    <li><a href="http://leaflabs.com/">LeafLabs</a> |</li>
     {{ super() }}
 {% endblock %}      
diff --git a/docs/source/errata.rst b/docs/source/errata.rst
index a3bb66a..8feb6ea 100644
--- a/docs/source/errata.rst
+++ b/docs/source/errata.rst
@@ -10,22 +10,22 @@ but are easy ways to break or damage your board permanently. For a
 list of differences between the Maple and Arduinos, see the
 :ref:`compatibility reference <compatibility>`.
 
+The errata are grouped by Maple version ("Rev").  Rev 5 is currently
+on sale.  If you are unsure which version you own, the :ref:`Maple
+hardware page <maple-hardware-identify-rev>` has pictures and
+descriptions of each version.
+
 .. contents:: Contents
    :local:
 
 Maple Rev 5
 -----------
 
-These boards went on sale in November 2010.  They have white buttons,
-and "r5" in small print near the "LeafLabs Maple" text next to the
-"infinity-leaf" logo, among other changes:
-
-.. figure:: /_static/img/maple_rev5.png
-   :align: center
-   :alt: Maple Rev 5
-
 Known issues:
 
+* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the
+    corresponding "AIN" is missing from its silkscreen.
+
 * **GPIO 39-43 not configured**: this is really more of a software
   "TODO" item.  Some of the JTAG header pins are numbered 39-43. These
   STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when the a
@@ -43,13 +43,6 @@ Potential failure modes:
 Maple Rev 3
 -----------
 
-This batch of boards went on sale beginning in May 2010. They have a
-darker red silkscreen and the "infinity-leaf" logo:
-
-.. figure:: /_static/img/maple_rev3.png
-   :align: center
-   :alt: Maple Rev 3
-
 Known issues:
 
 * **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010
@@ -106,13 +99,6 @@ Potential failure modes:
 Maple Rev 1
 -----------
 
-This batch of 100 boards shipped in later 2009. They have a red
-silkscreen and the logo is a single pixelated leaf:
-
-.. figure:: /_static/img/maple_rev1.png
-   :align: center
-   :alt: Maple Rev 1
-
 Known issues:
 
 * **ADC noise**: generally very high, in particular when the USB port
diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst
index aabf39f..8350cc5 100644
--- a/docs/source/hardware/maple.rst
+++ b/docs/source/hardware/maple.rst
@@ -1,7 +1,104 @@
+.. highlight:: sh
+
 .. _hardware-maple:
 
 Maple
 =====
 
-Stub. TODO picture, describe what things do, serial bootloader
-uploading, etc. etc.
+.. contents:: Contents
+   :local:
+
+.. _maple-hardware-identify-rev:
+
+Identifying your Rev
+--------------------
+
+We went through three versions ("Revs") of the Maple hardware: Rev 1,
+Rev 3, and Rev 5 [#frev2_4]_; Rev 5, the final design, is currently on
+sale.  The following sections will help you to help you identify your
+Rev.  Known issues are listed in the :ref:`errata <errata>`.
+
+Rev 1
+^^^^^
+
+A small number of Maple Rev 1 boards went on sale in late 2009.  They
+have a light red silkscreen and a single pixelated leaf as a logo.
+
+.. figure:: /_static/img/maple_rev1.png
+   :align: center
+   :alt: Maple Rev 1
+
+.. rubric:: Footnotes
+
+.. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal
+   testing.
+
+Rev 3
+^^^^^
+
+This batch of boards went on sale beginning in May 2010. They have a
+darker red silkscreen and the "infinity leaf" logo.  The Maple Rev 3
+was the first version which includes the built-in button, labeled BUT.
+It also includes a built-in LiPo battery charger.
+
+.. figure:: /_static/img/maple_rev3.png
+   :align: center
+   :alt: Maple Rev 3
+
+Rev 5
+^^^^^
+
+These boards went on sale in November 2010.  They have white buttons,
+and "r5" in small print near the "LeafLabs Maple" text next to the
+"infinity leaf" logo.  The Maple Rev 5 repositioned the double header
+on the right hand side to better fit 0.1 inch pitch breadboard.  This
+necessitated the removal of pins 21 and 22 from the double header;
+they are still available, but don't have any headers installed on
+them.
+
+.. figure:: /_static/img/maple_rev5.png
+   :align: center
+   :alt: Maple Rev 5
+
+Powering the Maple
+------------------
+
+The Maple's power source is determined by the header to the left of
+the "LeafLabs" label on the silkscreen.  All versions of the Maple can
+be powered from the barrel jack connector, USB, or a LiPo battery.  We
+ship the Maple with a jumper on the USB selector.  In order to power
+it off of an alternative source, unplug the Maple, then move the
+jumper to the desired selector before reconnecting power.
+
+You can also power the Maple via the pin labeled "Vin" on the lower
+header.  However, don't do this while simultaneously powering the
+Maple from another source, or you could damage the board.
+
+Using the Built-in Battery Charger
+----------------------------------
+
+Maples Rev 3 and Rev 5 also have a built-in LiPo battery charger.  In
+order to use it, put a jumper across the CHRG header on the power
+selection header and across the USB, or EXT selectors, depending on
+whether you're charging the battery via USB cable or barrel jack
+connector.  The LED labeled CHRG will light up while the battery is
+being charged.  When the battery is finished charging, the LED labeled
+DONE will also light up.
+
+Hardware Design Files
+---------------------
+
+The hardware schematics and board layout files are available in the
+`Maple github repository <https://github.com/leaflabs/maple>`_.  The
+design files for Rev 1, Rev 3, and Rev 5 are respectively in the
+``maple-r1``, ``maple-r3``, and ``maple-r5`` subdirectories.  A
+schematic for a JTAG adapter suitable for use with Maple is available
+in the ``jtagadapter`` directory.
+
+From the github repository main page, you can download the entire
+repository by clicking the "Download" button.  If you are familiar
+with `git <http://git-scm.com/>`_, you can also clone the repository
+at the command line with ::
+
+    $ git clone git://github.com/leaflabs/maple.git
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 25bda65..5c1718f 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -20,7 +20,7 @@ Have fun!
 
    Quickstart <maple-quickstart>
    IDE Installation <maple-ide-install>
-   IDE Anatomy <ide>
+   IDE Usage <ide>
    Command-Line Toolchain <unix-toolchain>
 
 .. _index-maple-programming:
@@ -30,12 +30,12 @@ Have fun!
 .. toctree::
    :maxdepth: 1
 
-   Maple Language <language>
-   Maple Libraries <libraries>
+   Language <language>
+   Libraries <libraries>
    Arduino Compatibility <compatibility>
+   libmaple <libmaple>
    External Interrupts <external-interrupts>
    Bootloader <bootloader>
-   libmaple <libmaple>
    Troubleshooting <troubleshooting>
    Known Problems <errata>
 
@@ -46,15 +46,15 @@ Have fun!
 .. toctree::
    :maxdepth: 1
 
-   i2c
-   pwm
+   adc
    gpio
-   usb
+   i2c
    jtag
-   adc
+   pwm
    spi
-   usart
    timers
+   usb
+   usart
 
 .. _index-schematics:
 
@@ -64,6 +64,12 @@ Have fun!
    :maxdepth: 1
 
    hardware/maple.rst
+
+.. TODO write/include these upon Mini and Native release
+
+.. toctree::
+   :hidden:
+
    hardware/maple-mini.rst
    hardware/maple-native.rst
 
diff --git a/docs/source/maple-ide-install.rst b/docs/source/maple-ide-install.rst
index ce50c49..92d1a96 100644
--- a/docs/source/maple-ide-install.rst
+++ b/docs/source/maple-ide-install.rst
@@ -61,6 +61,13 @@ First, extract all the files in the ZIP file to a suitable location on
 your system (like your Desktop folder).  Next, you have to install
 some drivers.  Sorry!
 
+.. note:: Note that while these instructions work on Windows XP,
+   changes in Windows 7 mean that you won't be able to install the IDE
+   without disabling driver signing on your computer.  We're working
+   on resolving this situation.  For now, `users on the forum have
+   reported some workarounds
+   <http://forums.leaflabs.com/topic.php?id=73>`_.
+
 First, install DFU drivers (for uploading code to your Maple) using
 the following steps.
 
diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst
index ca902f3..08fa5c1 100644
--- a/docs/source/maple-quickstart.rst
+++ b/docs/source/maple-quickstart.rst
@@ -6,7 +6,7 @@
  Maple Quickstart Guide
 ========================
 
-You'll need a `Maple board <http://leaflabs.com/store/>`_, a `mini-b
+You'll need a `Maple board <http://leaflabs.com/store/>`_, a `Mini-B
 USB cable <http://www.google.com/products?q=mini-b+usb+cable>`_, a
 functional computer, and possibly root (or "administrator") access to
 that computer.
diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst
index 8e766bd..836f777 100644
--- a/docs/source/unix-toolchain.rst
+++ b/docs/source/unix-toolchain.rst
@@ -8,7 +8,7 @@
 
 This is a tutorial for using the Maple with a standard Unix toolchain.
 It's not necessary to do this in order to program the Maple; you can
-always use our `IDE <maple-ide-install>`_ instead.
+always :ref:`install the Maple IDE <maple-ide-install>` instead.
 
 You'll need a Maple board, a mini-b USB cable, a functional computer,
 and root access to that computer. This guide assumes you've had
@@ -16,10 +16,10 @@ success with the IDE on your machine and that you are fairly
 comfortable with the Unix command line; some previous experience with
 editing your shell startup script (.bashrc, .tcshrc, etc.) and using
 `make <http://www.gnu.org/software/make/>`_ is recommended. For
-generic installation/setup issues, the `IDE install
-<http://leaflabs.com/docs/libmaple/install/>`_ and
-:ref:`troubleshooting` pages may be helpful. If all else fails, try
-our `forum`_, or `contact us directly`_\ !
+generic installation/setup issues, the :ref:`IDE installation
+<maple-ide-install>` and :ref:`troubleshooting` pages may be
+helpful. If all else fails, try our `forum`_, or `contact us
+directly`_\ !
 
 We currently have instructions for 32- and 64-bit Linux and OS X Snow
 Leopard. If you're on another Unix platform, Windows, or an earlier
@@ -28,7 +28,7 @@ directions on your own. As a jumping off point, you might want to
 begin with these `stripped down distributions
 <http://static.leaflabs.com/pub/codesourcery/>`_ of the `CodeSourcery
 GCC compiler tools <http://www.codesourcery.com/sgpp/features.html>`_
-(including win32 versions). If you do have success on other platforms,
+(including Win32 versions). If you do have success on other platforms,
 please post in the forums, so we can fold your tips into this
 document!
 
@@ -325,7 +325,7 @@ something like :file:`/dev/ttyACMXXX` on Linux or
 :file:`/dev/tty.usbmodemXXX` on OS X, but it might have a slightly
 different name on your system. To open up a session, run ::
 
-  $ screen /dev/tty-whatever-it-is
+  $ screen /dev/ttyXXX
 
 If the interactive test program built and uploaded correctly, you
 should be able to connect without any errors reported by
@@ -334,14 +334,17 @@ there are a number of commands which demonstrate Maple peripheral
 features. As of October 2010, the HardwareSerial library is blocking,
 so using any commands which would write to the USART Serial ports will
 cause the program to hang. To exit the screen session, type :kbd:`C-a
-C-\\` (control-a, followed by control-backslash), and type ``y`` when
-prompted if you're sure.
+C-\\` (control-a, followed by control-backslash) on Mac, or :kbd:`C-a
+k` (control-a k) on Linux, and type ``y`` when prompted if you're
+sure.
 
-Using :command:`screen` in this way sometimes messes up your session.
-If your shell starts acting up after you exit screen, you should be
-able to fix it with ::
+.. note:: 
 
-  $ reset && clear
+   Using :command:`screen` in this way sometimes messes up your
+   terminal session on OS X.  If your shell starts acting up after you
+   exit screen, you should be able to fix it with ::
+
+       $ reset && clear
 
 .. _toolchain-projects: