lots more docs

19 files changed, 1109 insertions, 27 deletions

diff --git a/source/_static/img/blinky-to-flash.png b/source/_static/img/blinky-to-flash.png
new file mode 100755
index 0000000..0320c5b
--- /dev/null
+++ b/source/_static/img/blinky-to-flash.png
diff --git a/source/_static/img/blinky.png b/source/_static/img/blinky.png
new file mode 100755
index 0000000..bda4cee
--- /dev/null
+++ b/source/_static/img/blinky.png
diff --git a/source/_static/img/codeblocks_build.png b/source/_static/img/codeblocks_build.png
new file mode 100644
index 0000000..c98bcdc
--- /dev/null
+++ b/source/_static/img/codeblocks_build.png
diff --git a/source/_static/img/codeblocks_makefile.png b/source/_static/img/codeblocks_makefile.png
new file mode 100644
index 0000000..a0ef21f
--- /dev/null
+++ b/source/_static/img/codeblocks_makefile.png
diff --git a/source/_static/img/codeblocks_maketargets.png b/source/_static/img/codeblocks_maketargets.png
new file mode 100644
index 0000000..bbb68cb
--- /dev/null
+++ b/source/_static/img/codeblocks_maketargets.png
diff --git a/source/_static/img/codeblocks_newproject.png b/source/_static/img/codeblocks_newproject.png
new file mode 100644
index 0000000..8d08d1f
--- /dev/null
+++ b/source/_static/img/codeblocks_newproject.png
diff --git a/source/_static/img/libmaple-screenshot-small.png b/source/_static/img/libmaple-screenshot-small.png
new file mode 100644
index 0000000..f2be783
--- /dev/null
+++ b/source/_static/img/libmaple-screenshot-small.png
diff --git a/source/_static/img/verify-success.png b/source/_static/img/verify-success.png
new file mode 100755
index 0000000..6928674
--- /dev/null
+++ b/source/_static/img/verify-success.png
diff --git a/source/_static/img/verify_button.png b/source/_static/img/verify_button.png
new file mode 100644
index 0000000..37100db
--- /dev/null
+++ b/source/_static/img/verify_button.png
diff --git a/source/conf.py b/source/conf.py
index e9c55b2..7f2b3b4 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -44,7 +44,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'libmaple'
+project = u'Maple'
 copyright = u'2010, LeafLabs, LLC'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -169,7 +169,7 @@ html_static_path = ['_static']
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'libmapledoc'
+htmlhelp_basename = 'mapledoc'
 
 
 # -- Options for LaTeX output -------------------------------------------------
@@ -183,7 +183,7 @@ htmlhelp_basename = 'libmapledoc'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target file, title, author, documentclass [howto/manual])
 latex_documents = [
-  ('index', 'libmaple.tex', u'libmaple Documentation',
+  ('index', 'maple.tex', u'Maple Documentation',
    u'LeafLabs, LLC', 'manual'),
 ]
 
@@ -216,7 +216,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'libmaple', u'libmaple Documentation',
+    ('index', 'maple', u'Maple Documentation',
      [u'LeafLabs, LLC'], 1)
 ]
 
diff --git a/source/index.rst b/source/index.rst
index 92b2d5d..ec7313d 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -3,25 +3,29 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+.. _index:
+
 Maple Documentation Index
 =========================
 
 Welcome!  This is the documentation index for programming your Maple.
-It contains technical documentation, as well as some getting started
-guides and example projects.
+It contains tutorials, quickstarts, and technical documentation.
 
-.. TODO add projects
+If you just got a new Maple, you probably want the :ref:`Maple
+quickstart <maple-quickstart>`.
 
-Parts of the documentation:
+Table of contents:
 
 .. toctree::
    :maxdepth: 2
 
-   Language reference <language>
-   Library reference <libraries>
-   Unix toolchain <unix-toolchain>
-   libmaple (C library) API <libmaple>
+   Maple Quickstart Guide <maple-quickstart>
+   Maple IDE Installation Guide <maple-ide-install>
+   Wiring/Arduino Language Reference <language>
+   Wiring/Arduino Library Reference <libraries>
+   libmaple Documentation and APIs <libmaple>   
    Maple bootloader <bootloader>
+   Troubleshooting <troubleshooting>
 
 Indices and tables
 ==================
diff --git a/source/language.rst b/source/language.rst
index 3772872..6634f9d 100644
--- a/source/language.rst
+++ b/source/language.rst
@@ -1,25 +1,31 @@
+.. highlight:: c++
+
 .. _language:
 
 ==========================
  Maple Language Reference
 ==========================
 
-The Maple can be programmed in a mostly-complete subset of the the
-`Wiring <http://www.wiring.org.co/reference/>`_ language, which is the
-same language used to program the `Arduino <http://arduino.cc/>`_
-boards.  The entire language will be supported in a future release.
-Please see the extensive `language reference
+The Maple can be programmed in the `Wiring
+<http://www.wiring.org.co/reference/>`_ language, which is the same
+language used to program the `Arduino <http://arduino.cc/>`_ boards.
+The entire language will be supported in a future release.  Please see
+the extensive `language reference
 <http://arduino.cc/en/Reference/HomePage>`_ on the Arduino webpage for
 more information, or follow a direct link below.
 
+C or C++ programmers curious about the differences between the Wiring
+language and C++ may wish to skip to the
+:ref:`arduino_c_for_c_hackers`.
+
 Unique Maple Additions
 ----------------------
 
 ``ASSERT(...)``
     The ``ASSERT()`` function can be very useful for basic program
-    debugging. The function accepts a boolean; for example:
+    debugging. The function accepts a boolean; for example::
 
-      ``ASSERT(state == WAIT);``
+      ASSERT(state == WAIT);
 
     zero is false and any other number is true. If the boolean is true
     the assertion passes and the program continues as usual. If it is
@@ -31,9 +37,9 @@ Unique Maple Additions
 
     Including assertions in a program increases the program size. When
     using libmaple **from the command line only**, they can be
-    disabled by making the definition
+    disabled by making the definition ::
 
-      ``#define DEBUG_LEVEL DEBUG_NONE``
+      #define DEBUG_LEVEL DEBUG_NONE
 
     before including either wirish or libmaple. In this case, all
     assertions will pass without any lost clock cycles.  Note that
@@ -326,6 +332,163 @@ Arduino Documentation Links
 .. _community-contributed code: http://www.arduino.cc/playground/Main/GeneralCodeLibrary
 .. _newlib: http://sourceware.org/newlib/
 
+.. _arduino_c_for_c_hackers:
+
+Note for C/C++ Programmers
+--------------------------
+
+This is a note for programmers comfortable with C or C++ (although,
+you C programmers should remember that `C++ is not a superset of C
+<http://en.wikipedia.org/wiki/Compatibility_of_C_and_C%2B%2B>`_) who
+want a better understanding of the differences between C++ and the
+Wiring language.  The good news is that the differences are relatively
+few.
+
+A *sketch* is the IDE's notion of a project; it consists of one or
+more files written in the Wiring language, which is mostly the same as
+C++.  The major difference between the two is that in Wiring, it's not
+necessary to declare global functions before they are used.  That is,
+the following is valid Wiring, and ``f()`` returns ``5``::
+
+  int f() {
+    return g();
+  }
+
+  int g() {
+    return 5;
+  }
+
+All of the files in a sketch share the same (global) namespace.  That
+is, the behavior is as if all of a sketch's files were part of the
+same translation unit, so they don't have to include one another in
+order to access each other's definitions.  The only other major
+difference between Wiring and C++ is that Wiring doesn't support
+dynamically allocated memory -- that is, ``new`` and ``delete`` won't
+work.  As of |today|, Maple only has 20 KB RAM, anyway, so it's
+doubtful that static allocation is not what you want.
+
+The Wiring language also does not require you to define your own
+``main`` method (in fact, it forbids you from doing so).  Instead, you
+are required to define two functions, ``setup`` and ``loop``, with
+type signatures ::
+
+  void setup(void)
+  void loop(void)
+
+Once a sketch is uploaded to a Maple and begins to run, ``setup()`` is
+called once, and then ``loop()`` is called repeatedly.  The IDE
+compilation process proceeds via a source-to-source translation from
+the files in a sketch to C++.
+
+This translation process first concatenates the sketch files, then
+parses the result to produce a list of all functions defined in the
+global scope.  (We borrow this stage from the Arduino IDE, which in
+turn borrows it from Wiring.  It uses regular expressions to parse
+C++, which is, of course, `Bad and Wrong
+<http://www.retrologic.com/jargon/B/Bad-and-Wrong.html>`_.  An
+upcoming rewrite of the IDE performs this preprocessing step
+correctly, using a real parser.  Until then, you have our apologies.)
+The order in which the individual sketch files are concatenated is not
+defined; it is unwise to write code that depends on a particular
+ordering.
+
+The concatenated sketch files are then appended onto a file which
+includes `WProgram.h
+<http://github.com/leaflabs/libmaple/blob/master/wirish/WProgram.h>`_
+(which includes the wirish and libmaple libraries, and declares
+``setup()`` and ``loop()``), and then provides declarations for all
+the function definitions found in the previous step.  At this point,
+we have a file that is a valid C++ translation unit, but lacks a
+``main()`` method.  The final step of compilation provides this
+method, which behaves roughly like::
+
+  int main(void) {
+    setup();
+    while (true) loop();
+  }
+
+(The truth is a little bit more complicated, but not by much).  
+
+As an example, consider a sketch with two files.  The first file
+contains ``setup()`` and ``loop()``::
+
+  int the_pin;
+
+  void setup() {
+    the_pin = choose_a_pin();
+    pinMode(the_pin, OUTPUT);
+  }
+
+  void loop() {
+    static int toggle = 0;
+    toggle ^= 1;
+    digitalWrite(the_pin, toggle);
+  }
+
+The second file contains the (not very useful) implementation for
+``choose_a_pin()``::
+
+  int choose_a_pin() {
+     return random(5, 15);
+  }
+
+Then the results of the concatenation process might be ::
+
+  int the_pin;
+
+  void setup() {
+    the_pin = choose_a_pin();
+    pinMode(the_pin, OUTPUT);
+  }
+
+  void loop() {
+    static int toggle = 0;
+    toggle ^= 1;
+    digitalWrite(the_pin, toggle);
+  }
+
+  int choose_a_pin(void);
+
+  int choose_a_pin() {
+     return random(5, 15);
+  }
+
+Which could plausibly be turned into the final source file ::
+
+  #include "WProgram.h"
+
+  void setup(void);
+  void loop(void);
+  int choose_a_pin(void);
+
+  int the_pin;
+
+  void setup() {
+    the_pin = choose_a_pin();
+    pinMode(the_pin, OUTPUT);
+  }
+
+  void loop() {
+    static int toggle = 0;
+    toggle ^= 1;
+    digitalWrite(the_pin, toggle);
+  }
+
+  int choose_a_pin(void);
+
+  int choose_a_pin() {
+     return random(5, 15);
+  }
+
+  int main() {
+    setup();
+    while (true) loop();
+  }
+
+(Recall that it's legal C++ for a function to be declared multiple
+times, as long as it's defined exactly once).
+
+
 Recommended Reading
 -------------------
 
diff --git a/source/libmaple-api.rst b/source/libmaple-api.rst
new file mode 100644
index 0000000..df9a4d9
--- /dev/null
+++ b/source/libmaple-api.rst
@@ -0,0 +1,7 @@
+.. _libmaple_api:
+
+========================
+ libmaple API reference
+========================
+
+Stub.
diff --git a/source/libmaple.rst b/source/libmaple.rst
index c7e5c83..620fdfa 100644
--- a/source/libmaple.rst
+++ b/source/libmaple.rst
@@ -1,5 +1,37 @@
+.. highlight:: sh
+
+.. _libmaple:
+
 ====================
  libmaple Reference
 ====================
 
-Stub.
+.. image:: /_static/img/libmaple-screenshot-small.png
+   :align: center
+   :alt: libmaple screenshot
+
+`LeafLabs libmaple <libmaple-libmaple>`_ is the low level library we have developed for for the ARM
+Cortex-M3 chips manufactured by STMicroelectronics used in the Maple
+boards (the `STM32F103x`_ series). We found the generic peripheral
+libraries too painful to build on top of, and reimplemented the
+functionality we needed in a simpler (and less general) form.
+
+.. _libmaple-libmaple: http://github.com/leaflabs/libmaple
+.. _STM32F103x: http://www.st.com/stonline/stappl/productcatalog/app?path=/pages/stcom/PcStComPartNumberSearch.searchPartNumber&search=stm32f103
+
+This library is transparently included in the `Maple IDE
+<http://leaflabs.com/docs/maple-ide/>`_, but we develop it separately
+using good old Unix command line tools and release it for advanced
+users who might chafe at the “sketch” programming model of the
+IDE. Included are some examples, a Makefile, and the compatibility
+wrappers and code to imitate the Arduino programming library.
+
+**Check out the latest source**::
+
+    git clone git://github.com/leaflabs/libmaple.git
+
+.. toctree::
+   :maxdepth: 2
+
+   Unix Toolchain Quickstart <unix-toolchain>
+   libmaple API reference <libmaple-api>
diff --git a/source/libraries.rst b/source/libraries.rst
index 374b71c..1f298fa 100644
--- a/source/libraries.rst
+++ b/source/libraries.rst
@@ -1,7 +1,119 @@
+.. highlight:: c++
+.. default-domain:: cpp
+
 .. _libraries:
 
 =========================
  Maple Library Reference
 =========================
 
-Stub
+This page briefly summarizes the Arduino libraries that have been ported to Maple. You can use a library from within a sketch by going to Sketch > Import Library... from within the IDE, then choosing the library you want.
+
+Any incompatibilities between the Maple and Arduino versions are noted in the description of the library.
+
+* :ref:`LiquidCrystal <liquid_crystal>`
+* :ref:`Wire <wire>`
+
+.. _liquid_crystal:
+
+LiquidCrystal
+-------------
+
+The LiquidCrystal library allows Maple to control LCD screens. For more information, see the Arduino LiquidCrystal documentation.
+Compatibility Note
+
+At this time, no incompatibilities between the Maple and Arduino versions are known. Any observed differences should be considered bugs, and reported on the forums.
+
+.. _wire:
+
+Wire
+----
+
+We provide a soft (bit-banged) implementation of the `Wire I2C library
+<http://arduino.cc/en/Reference/WireBegin>`_.
+
+Compatibility Note
+^^^^^^^^^^^^^^^^^^
+
+This implementation is synchronous, and thus supports only a subset of
+the full Wire interface (however, the functionality which is supported
+is fully compatible with Arduino). For now, please use the function
+reference which follows when developing projects using our
+implementation.
+
+Please note that the current implementation only supports master mode
+using a bit-banged (software) protocol. Future enhancements will use
+the hardware i2c peripheral on the stm32 as well as the DMA for
+performance. Support for slave, smBUS, and multimaster modes are also
+slated for inclusion in the enhanced Wire port.
+
+Function Reference
+^^^^^^^^^^^^^^^^^^
+
+``Wire.begin()``
+    Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL
+    (this is compatible with the pin settings on the Arduino Mega).
+
+``Wire.begin(sda, scl)``
+    Like ``Wire.begin()``, but with the given pins as SDA and
+    SCL.
+
+``Wire.beginTransmission(slave_address)``
+    Set up a transmission to a slave device with the given (7-bit)
+    address. Bytes subsequently queued for transmission (using
+    ``Wire.send``) will be sent to ``slave_address`` when ``void
+    Wire.endTransmission()`` is called.
+
+``void Wire.send(byte)``
+    Queues the given byte (``uint8`` or ``int``) to the slave address
+    previously specified by a call to ``Wire.beginTransmission``. At
+    most 32 bytes may be queued in a single transmission.
+
+``Wire.send(string)``
+    Queues a given string (``char*``) for transmission. The characters
+    of the string are individually queued for transmission as
+    bytes. At most 32 bytes may be queued in a single transmission.
+
+``Wire.send(buffer, length)``
+    Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with
+    ``length`` elements, for transmission. At most 32 bytes may be
+    queued in a single transmission.
+
+``Wire.endTransmission()``
+    Ends a transmission (begun by ``Wire.beginTransmission(uint8)``),
+    and actually sends the bytes queued by calls to Wire.send.
+
+    The return value is one of the following status codes:
+
+    * ``SUCCESS``: All bytes were transmitted successfully.
+
+    * ``EDATA``: More than 32 bytes were queued for transmission. No
+      bytes are actually sent when this happens.
+
+    * ``ENACKADDR``: Did not receive ACK on transmit of address. No
+      bytes are actually sent when this happens.
+
+    * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some
+      bytes may have been sent when this happens; however, the
+      transmission is aborted after the first byte of data which is
+      not ACKed by the slave device.
+
+    * ``EOTHER``: Other error occurred.
+
+``Wire.requestFrom(address, num_bytes)``
+    Requests ``num_bytes`` bytes from 7-bit slave address
+    address. Returns the actual number of bytes read. These bytes may
+    subsequently be read one at a time using ``Wire.receive()``.
+
+    Note: if ``num_bytes`` exceeds the size of the transmit/receive
+    buffer (currently 32), it will be truncated to 32.
+
+``Wire.receive()``
+    Get and return the next byte read during the previous call to
+    ``Wire.requestFrom(uint8, int)``. You can check how many bytes are
+    left to read using ``uint8 Wire.available()``.
+
+``Wire.available()``
+    Returns the number of bytes which are still available for reading
+    (with ``Wire.receive()``) from the last call to
+    ``Wire.requestFrom(uint8, int)``.
diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst
new file mode 100644
index 0000000..b84df76
--- /dev/null
+++ b/source/maple-ide-install.rst
@@ -0,0 +1,10 @@
+.. _maple-ide-install:
+
+========================
+ Maple IDE Installation
+========================
+
+.. _maple-ide-install-java:
+.. _maple-ide-install-windows-drivers:
+
+Stub.
diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst
new file mode 100644
index 0000000..8184772
--- /dev/null
+++ b/source/maple-quickstart.rst
@@ -0,0 +1,256 @@
+.. highlight:: sh
+
+.. _maple-quickstart:
+
+========================
+ Maple Quickstart Guide
+========================
+
+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.
+
+If you have trouble along the way try the :ref:`install page
+<maple-ide-install>` for more detailed download and installation
+instructions, and the :ref:`troubleshooting page <troubleshooting>`
+for help with some common problems.  If all else fails, try our `forum
+<http://forums.leaflabs.com>`_, or `contact us directly
+<http://leaflabs.com/contact>`_!
+
+The major steps are:
+
+* :ref:`Download and install the IDE <maple-quickstart-download>`
+
+* :ref:`(Windows) Resolve driver issues <maple-ide-install-windows-drivers>`
+
+* :ref:`Run the IDE <maple-quickstart-run-ide>`, then :ref:`compile
+  and upload a simple Blink program <maple-quickstart-compile-blinky>`
+
+* Test the USB serial connection with a HelloWorld 
+
+.. _maple-quickstart-download:
+
+1. Download the IDE
+-------------------
+
+Choose the correct version for your operating system:
+
+.. list-table::
+   :widths: 15 30 50
+   :header-rows: 1
+
+   * - Platform
+     - Status
+     - IDE Package
+   * - Windows
+     - Tested on 32bit Windows XP
+     - `maple-ide-LATEST-windowsxp32.zip <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-windowsxp32.zip>`_ (about 75mb)
+   * - Linux
+     - Tested on Ubuntu 9.10 (64bit) and 10.04 (32bit)
+     - `maple-ide-LATEST-linux32.tgz <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-linux32.tgz>`_ (about 30mb)
+
+       `maple-ide-LATEST-linux64.tgz <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-linux64.tgz>`_ (about 30mb)
+   * - Mac OSX
+     - Tested on Snow Leopard 10.6 (64bit and 32bit)
+     - `maple-ide-LATEST-macosx-10_6.dmg <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-macosx-10_6.dmg>`_ (about 40mb)
+
+.. note::
+
+  The Linux release requires that you have a Java runtime (JRE)
+  installed. If you're on Linux, don't have a JRE, and don't know how
+  to install one, see the :ref:`installation page
+  <maple-ide-install-java>`.
+
+The package bundles together a compiler, an upload utility, a software
+library, and a simple GUI text editor. All this software is `free and
+open <http://fsf.org/>`_; we are grateful to the `Arduino
+<http://arduino.cc/>`_, `CodeSourcery
+<http://www.codesourcery.com/>`_, `GNU <http://gnu.org/>`_, and
+`OpenMoko <http://openmoko.com/>`_ developers, as well as many others,
+who allow us to reuse their software.
+
+2. Install the IDE
+------------------
+
+**Windows:**
+
+First, extract all the files in the ZIP file to a suitable location on
+your system (like your Desktop folder).
+
+Next, you'll have to install drivers; see the :ref:`installation page
+<maple-ide-install-windows-drivers>` for more details. Sorry!
+
+**Linux:**
+
+Extract the tarball to an appropriate location (like your
+home directory or desktop).
+
+Make sure you have a Java runtime (JRE) installed; if you can run
+:command:`java` from the shell, you should be fine.  For instructions
+on installing a JRE, try the :ref:`installation page
+<maple-ide-install-java>` or searching the package manager for your
+distribution.
+
+Next, run the script :file:`install-udev-rules.sh` in the extracted
+IDE directory.  It will ask for root permissions.  You now need to
+restart udev::
+
+  sudo /etc/init.d/udev restart
+
+This will grant members of the group ``plugdev`` read/write access to
+Maple devices over USB.  Make sure that you are in that group.  (For
+more information on why this is part of the install process, see the
+:ref:`Unix toolchain quickstart <toolchain-udev>`).
+
+**OS X:**
+
+Double-click on the :file:`.dmg` file you downloaded in :ref:`Step 1
+<maple-quickstart-download>`.
+
+Next, drag and drop the Maple IDE icon into your computer's
+Applications folder.
+
+.. _maple-quickstart-run-ide:
+
+3. Run the IDE
+--------------
+
+**Windows:**
+
+Double-click on the :command:`maple-ide` program from within the
+extracted IDE directory.
+
+**Linux:**
+
+Run :file:`maple-ide` from the shell, or double click on it if your
+window system supports it.
+
+**OS X:**
+
+Double-click the :command:`Maple IDE` application you dragged into
+your computer's :file:`Applications` folder.
+
+.. _maple-quickstart-compile-blinky:
+
+4. Compile a program!
+---------------------
+
+Let's load up a simple example program that blinks the status LED.
+From the File menu, select Examples > Digital > Blink:
+
+.. image:: /_static/img/blinky.png
+   :align: center
+   :alt: Click "Blink"
+
+Next, select Tools > Board > "LeafLabs Maple ... to FLASH":
+
+.. image:: /_static/img/blinky-to-flash.png
+   :align: center
+   :alt: Upload to FLASH
+
+.. note::
+
+   You have the option between RAM and FLASH programming: FLASH saves
+   the program into permanent memory so the program will be run every
+   time the Maple is reset, while RAM simply injects the compiled
+   program into the processor's memory.
+
+   Programming to RAM is faster to upload and a buggy program can be
+   wiped away with a simple reset, while FLASH memory is larger and is
+   the only option for permanently uploading a program.
+
+.. image:: /_static/img/verify_button.png
+   :align: left
+   :alt: Verify button
+
+Now press the "verify" button (furthest to the left with a "play"
+arrow) to compile the code.  Some output should scroll by in the
+bottom window, and then a confirmation message will appear:
+
+.. image:: /_static/img/verify-success.png
+   :align: center
+   :alt: Code verified successfully.
+
+5. Upload that program!
+-----------------------
+
+Now it's (finally!) time to plug in your Maple. Use a mini-b cable,
+making sure that the power source jumper is on the USB header
+first.
+
+The Maple should blink a short pattern on the blue status LED every
+time it is plugged in, reset, or reprogrammed, just to let you know
+it's there. If it ever starts throbbing in a slow, smooth pattern that
+means you've got a problem: see the troubleshooting page.
+
+On OS X, a modem setup dialog will pop up every time you plug in the
+Maple.  If you go to System Preferences Network Settings and accept
+the default ("unconfigured") settings, the dialog won't pop up and
+everything will work fine.
+
+If all systems are go, select the Board type and Serial Port
+(something like /dev/ttyACM0, /dev/cu.usbmodem5d21, or COM3 depending
+on your platform) from the Tools menu. Then press the "upload" button
+(right arrow to a bunch of dots) to upload your program to the
+Maple. You should see some text and a progress bar flash by in the
+status window of the IDE, then some blinky patterns on the Maple, and
+then a constant blink with whatever time period you programmed in
+above.
+
+Go ahead and modify the file a little bit: if you change the
+'delay(1000);' numbers to a different value the speed of the blink
+will change. The value is a time in milliseconds to pause before
+continuing with the program, so by default the LED will be on for 1
+second, then off for 1 second, etc.
+
+.. warning::
+
+   This step is the most common source of problems, especially on
+   Windows.
+
+   The situation is much improved over the past, but if you have
+   trouble, try doing things again, unplugging your Maple and plugging
+   it back in, using :ref:`perpetual bootloader mode
+   <troubleshooting-perpetual-bootloader>`, or restarting the
+   IDE.
+
+   Please report any problems in the forums.  If we don't know it's
+   broken, we can't fix it!
+
+6. Use the serial port monitor!
+-------------------------------
+
+As a last step to make sure everything has been configured correctly,
+let's upload a hello world program that will send text from the Maple
+back to the IDE over the USB connection. From File select Examples,
+Stubs, HelloWorld, and make sure the correct board and serial port
+targets are selected from the Tools pull-down. And of course you could
+change the text to be printed out; make sure you leave the double
+quotes around it though or you'll get a compile error.
+
+Open the serial monitor window (button on the far right) and make sure
+the 9600 baud speed is selected. Then go back to the code editing
+window and upload your program (upload will recompile your code
+automatically if there's been any change since the last "verify"). You
+should get text spit at you over the serial monitor right after the
+program is uploaded. Shout back! We can hear you!
+
+7. Go forth exuberantly!
+------------------------
+
+We really hope you got this far and didn't frown or make a bitter
+lemon face too often getting here. Where you go now is up to you:
+perhaps you've got some crazy project cooking, or a longer tutorial to
+work through, or maybe now is a good time for a trip to the kitchen
+for a delicious sandwich.
+
+If you blew through this guide and are the kind of person who drinks
+their coffee straight and has more than a 100 lines of vim or emacs
+customization and doesn't even have a mouse plugged into your computer
+you may want to look at the Unix Toolchain quickstart guide to getting
+working with your old friends make, jtag, and gcc.
+
+Let us know what you come up with! Tag internet content with
+#leaflabs, post in the forums, track us down in the real world,
+whatever. We love projects!
diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst
new file mode 100644
index 0000000..0aba027
--- /dev/null
+++ b/source/troubleshooting.rst
@@ -0,0 +1,9 @@
+.. _troubleshooting:
+
+=======================
+ Maple Troubleshooting
+=======================
+
+.. _troubleshooting-perpetual-bootloader:
+
+Stub.
diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst
index 8f7ce7c..9939979 100644
--- a/source/unix-toolchain.rst
+++ b/source/unix-toolchain.rst
@@ -1,5 +1,494 @@
-================
- Unix Toolchain
-================
+.. highlight:: sh
 
-Stub
+.. _unix-toolchain:
+
+===========================
+ Unix Toolchain Quickstart
+===========================
+
+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
+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 <http://leaflabs.com/contact>`_!
+
+.. _forum: http://forums.leaflabs.com
+
+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
+version of OS X, we're guessing that you can translate/port these
+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,
+please post in the forums, so we can fold your tips into this
+document!
+
+* :ref:`Linux setup <toolchain-linux-setup>`
+* :ref:`OS X setup <toolchain-osx-setup>`
+* :ref:`Test compilation <toolchain-test>`
+* :ref:`Upload a program <toolchain-upload>`
+* :ref:`Communicate over USB-serial interface <toolchain-serialusb>`
+* :ref:`Starting your own projects <toolchain-projects>`
+* :ref:`Debug with OpenOCD <toolchain-openocd>`
+* :ref:`Do it all with Code::Blocks <toolchain-codeblocks>`
+* :ref:`Go forth exuberantly! <toolchain-exuberantly>`
+
+.. _toolchain-linux-setup:
+
+Linux Setup
+-----------
+
+These instructions are oriented towards Linux users using a
+contemporary Debian-based distribution.
+
+**1. Collect and Install Tools**
+
+First I'll give the commands to run, then explain::
+
+  $ sudo aptitude install build-essential git-core wget screen dfu-util \
+                          openocd python python-serial 
+
+You'll want to install a bunch of developer "basics" like
+:command:`make`, :command:`tar`, etc.  A good catch-all for these
+tools is the "build-essential" meta-package on most debian platforms:
+installing this fake package will pull in dozens of useful tools
+without bogging your system down too much. ``git-core`` is the name of
+the git package; `Git <http://git-scm.com/>`_ is a distributed code
+versioning system we use to track changes in our source
+code. :command:`wget` is a simple tool to download files over http
+from the command line, and is optional (you could pull in the required
+downloads using a browser). :command:`screen` is a really cool virtual
+terminal program; in the context of Maple, we use it to connect to
+serial port devices.
+
+:command:`dfu-util` is a tool from the `OpenMoko`_ project that we use
+to upload programs to the Maple over USB.
+
+.. _OpenMoko: http://openmoko.com/
+
+:command:`openocd` is a `JTAG
+<http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ control
+program used in conjunction with an ARM JTAG device to do in circuit
+debugging (pause/resume program execution, upload and download code,
+read out register status, etc). (optional)
+
+Lastly, our reset script (which sends control signals over the
+USB-serial connection to restart and enter the bootloader) is written
+in Python and requires the `PySerial
+<http://pyserial.sourceforge.net/>`_ library (the ``python-serial``
+package; this could also be installed with `easy_install
+<http://peak.telecommunity.com/DevCenter/EasyInstall>`_).
+
+**2. Fetch libmaple and Compiler Toolchain** ::
+
+  $ cd ~ 
+  $ git clone git://github.com/leaflabs/libmaple.git libmaple 
+  $ cd libmaple 
+  $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz
+  $ tar xvf arm-*-linux32.tar.gz
+  $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up 
+
+This step is fairly straightforward: do a git clone of the `libmaple
+repository <http://github.com/leaflabs/libmaple>`_ to some directory,
+then download and extract the ARM compiler toolchain.
+
+The :file:`arm/bin/` directory will need to be added to
+:envvar:`PATH`; you can check that this worked by entering
+``arm-none-`` and hitting tab to auto-complete (bash should show a
+bunch of results).  Regardless of where you put the toolchain, make
+sure to preserve its internal directory layout, as the binaries make
+relative path calls and references.
+
+.. _toolchain-udev:
+
+**3. Install udev Rules**
+
+From the libmaple directory, ::
+
+  $ groups # make sure it includes plugdev; if not add, yourself to it 
+  $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules 
+  $ sudo /etc/init.d/udev restart 
+
+As a security precaution on linux, unknown USB devices can only be
+accessed by the superuser. This udev script identifies the Maple based
+on its vendor and product IDs, mounts it to :file:`/dev/maple`, and
+grants read/write permissions to the ``plugdev`` group. After
+restarting :command:`udev` you'll need to fully unplug or power cycle
+any Maples connected to the computer.
+
+**So far, so good?**
+
+Great! Test your setup by :ref:`compiling a sample program
+<toolchain-test>`.
+
+.. _toolchain-osx-setup:
+
+OS X Setup
+----------
+
+These instructions have been tested successfully on OS X 10.6.4. As
+stated previously, this document assumes a general level of Unix
+aptitude on the part of the reader; if you're uncomfortable using
+Terminal (or if you don't know what that means), then you should
+probably stick with using the `Maple IDE
+<http://leaflabs.com/docs/maple-ide/>`_ to develop programs. Some of
+these software packages might be available on `MacPorts
+<http://www.macports.org/>`_. The author had some bad experiences with
+MacPorts a few years ago, though, and hasn't touched it since. Of
+course, your mileage may vary.
+
+**1. Collect and Install Tools**
+
+You will need the following tools to get started:
+
+ 1. `XCode <http://developer.apple.com/technologies/xcode.html>`_: If
+ you're reading this, you've probably already got this. Provides
+ compilers and other basic tools of the trade. It's a free download,
+ but requires registration (gross, we know).
+
+ 2. `Git <http://git-scm.com/>`_: All of our code is tracked by a
+ distributed versioning system called git. A `Mac installer
+ <http://code.google.com/p/git-osx-installer/downloads/list?can=3>`_
+ is available.
+
+ 3. :command:`dfu-util`: A tool from `OpenMoko`_ that we use to upload
+ programs to the Maple over USB. If you're feeling masochistic, there
+ are instructions for `building dfu-util from source
+ <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_.
+
+ However, if you've got better things to do, you can steal a dfu-util
+ binary from a program called `Openmoko Flasher
+ <http://www.handheld-linux.com/wiki.php?page=Openmoko%20Flasher>`_. To
+ do this, first `download Openmoko Flasher
+ <http://projects.goldelico.com/p/omflasher/downloads/>`_, then copy
+ the .app into your :file:`/Applications` folder (or wherever you
+ like). Let's pretend you saved the .app to the directory
+
+   :file:`/Applications/OpenMoko Flasher.app`
+
+ Then the :command:`dfu-util` binary resides in
+
+   :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util`
+
+ To get access to it from the command line, just make a symbolic link
+ to the binary from some place on your :envvar:`PATH`::
+
+   $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \
+           /somewhere/on/your/PATH/dfu-util
+
+ .. note:: 
+   Just copying the binary somewhere doesn't work, as it relies on
+   dynamically linked libraries found elsewhere in the .app
+   bundle. It's possible to pull just the relevant pieces out of the
+   .app, but you're on your own.
+
+ To make sure this worked, try plugging in your Maple, making sure
+ it's in bootloader mode (you can do this by pressing RESET, then
+ quickly pressing BUT and holding it for several seconds), then
+ running ::
+
+   $ dfu-util -l
+
+ If you see some lines that look like ::
+
+   Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00"
+   Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000"
+
+ then you're all set.
+
+ 4. PySerial: our reset script (which sends control signals over the
+ USB-serial connection to restart and enter the bootloader) is written
+ in Python and requires the `PySerial
+ <http://pyserial.sourceforge.net/>`_ library. Download the `latest
+ version <http://pypi.python.org/pypi/pyserial>`_. After you download
+ and untar, install it with ::
+
+   $ cd /path/to/pyserial-x.y
+   $ python setup.py build
+   $ sudo python setup.py install
+
+ The package is also available via :command:`easy_install`, so if
+ you're comfortable using that, you could also install it with ::
+
+   $ easy_install pyserial
+
+**2. Fetch libmaple and Compiler Toolchain**
+
+You first need to clone libmaple::
+
+  $ cd ~
+  $ git clone git://github.com/leaflabs/libmaple.git libmaple
+
+Then you need to get the cross-compilers we use to build a
+project. These are just modified versions of GCC; you can `download
+them for OS X here
+<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-osx32.tar.gz>`_. Assuming
+you saved this file to
+
+  :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz`
+
+you can then unpack the archive and let OS X know where the compilers
+live with ::
+
+  $ cd ~/Downloads
+  $ tar -xvzf gcc-blah-blah-macosx32.tar.gz
+  $ mv arm ~/libmaple/arm
+
+After that's done, you'll probably want to update your shell startup
+script to stick :file:`~/libmaple/arm/bin` into your :envvar:`PATH`.
+
+**So far, so good?**
+
+Great! Go on to the next section, where you test everything out.
+
+.. _toolchain-test:
+
+Test compilation
+----------------
+
+Get back into the libmaple directory (this tutorial assumes you put it
+in :file:`~/libmaple`) and test that you've installed all the compilation
+tools correctly::
+
+  $ cd ~/libmaple
+  $ cp main.cpp.example main.cpp
+  $ make clean
+  $ make
+
+If it all works out, you should end up seeing something like this::
+
+  find build -iname *.o | xargs arm-none-eabi-size -t
+     text    data     bss     dec     hex filename
+      482       4      24     510     1fe build/wirish/comm/HardwareSerial.o
+      260       0       0     260     104 build/wirish/comm/HardwareSPI.o
+       60       0       0      60      3c build/wirish/wirish.o
+
+  [...]
+
+     2196       0       1    2197     895 build/libmaple/usb/usb_lib/usb_core.o
+     1904       0       0    1904     770 build/libmaple/usb/usb_lib/usb_regs.o
+       56       0       0      56      38 build/libmaple/usb/usb_lib/usb_init.o
+      344       0       0     344     158 build/libmaple/usb/usb_hardware.o
+     6637       0      58    6695    1a27 build/main.o
+    21499     201     391   22091    564b (TOTALS)
+
+  Final Size:
+  arm-none-eabi-size build/maple.out
+     text    data     bss     dec     hex filename
+    21824     200     552   22576    5830 build/maple.out
+  Flash build
+
+Woo! It worked. The ``dec`` field at the end gives the total program
+size in bytes. The long listing of object files above the ``Final
+Size`` helps to identify bloated code.  As you write larger projects,
+you may find that they use too much space. If that happens, the
+file-by-file listing will help you track down the fatties porking up
+your program.
+
+.. _toolchain-upload:
+
+Upload a program
+----------------
+
+Ok, let's blow away the little example program and upload the
+interactive test session to your Maple.  This will let you interact
+textually with the Maple via USB-serial. If you're on Linux, then
+before executing :command:`make install`, you'll want to have the udev
+rules setup :ref:`as described above <toolchain-udev>`.  Plug in your Maple
+using the mini-b USB cable; then run ::
+
+  $ cd ~/libmaple
+  $ cp examples/test-session.cpp main.cpp
+  $ make clean
+  $ make
+  $ make install
+
+A number of things can go wrong at this stage.  Simple debugging steps
+include using :ref:`perpetual bootloader mode
+<troubleshooting-perpetual-bootloader>`, restarting the Maple a couple
+times, :command:`make clean`, etc. If nothing works, the `forum`_ is
+your friend.
+
+.. _toolchain-serialusb:
+
+Communicate over USB-serial interface
+-------------------------------------
+
+Okay, now that we've flashed the interactive test session to the
+Maple, let's test it out. The device for the maple should look
+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
+
+If the interactive test program built and uploaded correctly, you
+should be able to connect without any errors reported by
+:command:`screen`. Type ``h`` or hit the space bar to get a response;
+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.
+
+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 ::
+
+  $ reset && clear
+
+.. _toolchain-projects:
+
+Starting your own projects
+--------------------------
+
+So everything worked, and you want to start your own project? Great!
+It's easy. Just set the environment variable :envvar:`LIB_MAPLE_HOME`
+in your shell startup script to point to the libmaple repository you
+cloned (this tutorial assumes you put it in :file:`~/libmaple`). For
+example, if you use bash as your shell, just put this line in your
+:file:`~/.bashrc` or :file:`~/.bash_profile`::
+
+  export LIB_MAPLE_HOME=~/libmaple
+
+Now, in order to start your own projects, just grab a copy of the
+:file:`Makefile` and skeleton :file:`main.cpp` we provided in the
+libmaple repository, and you're good to go::
+
+  $ cd
+  $ mkdir my-awesome-project
+  $ cp ~/libmaple/Makefile ~/libmaple/build-targets.mk my-awesome-project
+  $ cp ~/libmaple/main.cpp.example my-awesome-project/main.cpp
+
+(TEMPORARY: The file :file:`build-targets.mk` is where the rule to
+build the object file for :file:`main.cpp` lives. If you have multiple
+source files, you'll probably need to look at it and edit as
+appropriate. We're sorry about that and will update the Makefile
+structure later to remove this pain point.) Then hack away! You can
+:command:`make`, :command:`make clean`, and :command:`make install`
+from your new directory :file:`my-awesome-project` just like you did
+in the libmaple repository.
+
+.. note::
+
+  We update the libmaple repository fairly frequently with bugfixes
+  and other improvements.  In order get access to these in your local
+  copy of the repository, you should periodically update it with::
+
+    $ cd $LIB_MAPLE_HOME
+    $ git pull
+
+  The `commits page
+  <http://github.com/leaflabs/libmaple/commits/master>`_ for the
+  github repository is a good place to watch for bleeding-edge
+  updates; our `blog <http://leaflabs.com/blog/>`_ is the place to
+  watch for major releases.  We keep releases of libmaple and the
+  Maple IDE in lockstep, so any IDE updates will have corresponding
+  library updates.
+
+.. _toolchain-openocd:
+
+Debug with OpenOCD
+------------------
+
+TODO. For now see `this great guide
+<http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se.
+
+.. _toolchain-codeblocks:
+
+Do it all with Code::Blocks
+---------------------------
+
+.. TODO this really should reflect the new, more pleasant build system
+
+Optional. `Code::Blocks <http://www.codeblocks.org/>`_ is a generic
+cross platform IDE.  We don't personally use it for development, so we
+haven't worked out all the kinks (e.g., debugging isn't integrated),
+but it might be helpful for people who are allergic to `vim
+<http://www.vim.org/>`_ and/or `Emacs
+<http://www.gnu.org/software/emacs/>`_. The simple configuration
+described here just calls down to the :file:`Makefile`, so follow the
+above directions to get the command line tools configured (you'll
+definitely need the arm-none-eabi-* tools on your :envvar:`PATH`),
+then `install Code::Blocks
+<http://www.codeblocks.org/downloads/26>`_. You can do this on Linux
+with::
+
+  $ sudo aptitude install codeblocks 
+
+The first time it runs you'll maybe want to disable all the glitzy
+"Getting Started" crap (when will they learn?). We've added a .cbp
+"projects" file to the libmaple repository: you can try using that one
+by copying it from :file:`support/codeblocks/libmaple.cbp` to the top
+level directory, but no promises (it might be missing new source files
+etc). It's probably worth reading through these instructions as well
+to get a feel for how it all works.
+
+To create your own "libmaple" project, start with an "Empty Project"
+with the "Folder to create project in" set to your
+:envvar:`LIB_MAPLE_HOME`. Make sure that the "Resulting filename" is
+in the top level directory as well.
+
+.. image:: /_static/img/codeblocks_newproject.png
+   :align: center
+   :alt: Code::Blocks new project wizard
+
+Select the "GNU GCC Compiler" (it won't be used, anyway) and disable
+the "Debug" configuration in the next window. Now you should have a
+project with no files; add files by right clicking on the project in
+the left panel file hierarchy and "Add files recursively". Import both
+the :file:`wirish` and :file:`libmaple` directories recursively, then
+add :file:`main.cpp` separately.
+
+.. image:: /_static/img/codeblocks_makefile.png
+   :align: center
+   :alt: Code::Blocks targets options
+
+Next we have to configure the Makefile targets. Go to the
+"Properties..." menu under "Project" and check the "This is a custom
+Makefile" box. Then go to the "Build targets" tab and create "ram" and
+"flash" targets, both of type "Console application" and without the
+Auto-generated filename prefixes or extensions. Set the Output
+filename to :file:`support/codeblocks/program_flash.sh` and
+:file:`support/codeblocks/program_ram.sh` respectively; these scripts
+just call the program_ram/program_flash make targets and are a hack to
+get the "run" button to upload code to the Maple. The IDE will warn
+that these files will be overwritten, but they won't be. For both the
+"flash" and "ram" targets, click the "Build options..." button (below
+"Virtual targets..." etc) and go to the far right tab ("'Make'
+commands"). Edit the Clean project/target line so it's just "clean"
+(not "clean$target"), and set the "Build project/target" and "Compile
+single file" commands to ``$make -f $makefile MAPLE_TARGET=$target``
+and ``$make -f $makefile MAPLE_TARGET=$target $file``, respectively.
+
+.. image:: /_static/img/codeblocks_maketargets.png
+   :align: center
+   :alt: Code::Blocks make targets
+
+Save all these changes, go back to the main IDE window, and try to
+build/run. "Build" will compile everything, "Run" will run the upload
+script in a terminal window (if there are problems they will flash by
+very quickly; you can start Code::Blocks in a terminal window and
+check the output in that base window if necessary), and "Rebuild" will
+clean before rebuilding.
+
+.. image:: /_static/img/codeblocks_build.png
+   :align: center
+   :alt: Success!
+
+.. _toolchain-exuberantly:
+
+Go forth exuberantly!
+---------------------
+
+Let us know what you come up with! Use #leaflabs on Twitter, post in
+the `forum`_, track us down in the real world, whatever. We love
+projects!