merge libmaple docs ("leaflabs-docs") into ./docs

In the past, libample documentation was forked out of this repository
because the documentation had increased in scope. For the librambutan,
and the rambutan project in general, we will try to keep documentation
closer to the source code, so the librambutan-specific documentation
should live here. Other sections of leaflabs-docs will be culled in a
following commit.

This merge attempts to maintain history by using a subtree strategy.
Followed directions at:

    http://nuclearsquid.com/writings/subtree-merging-and-you/

Full history for files should be accessible using the "--follow" flag to
git log, eg:

    git log --follow docs/source/adc.rst

It should be possible to pull patches from leaflabs-docs with:

    git pull -s subtree leaflabs-docs master

... at least until the docs in this repository diverge significantly.

1 files changed, 77 insertions, 0 deletions

diff --git a/docs/source/i2c.rst b/docs/source/i2c.rst
new file mode 100644
index 0000000..a206ed4
--- /dev/null
+++ b/docs/source/i2c.rst
@@ -0,0 +1,77 @@
+.. _i2c:
+
+|i2c|
+=====
+
+|i2c| is a crude and easy-to-hack serial protocol that requires only
+two wires/channels for communication between Maple and many other
+devices.
+
+.. contents:: Contents
+   :local:
+
+Overview
+--------
+
+Communication via |i2c| is broken up into messages.  Every message is
+between a *master* device, which initiates the message, and a *slave*
+device, which responds.
+
+Slaves are addressed using 7-bit addresses (up to 127 unique devices);
+10-bit addressing is also possible.  Every message consists of an
+arbitrary combination of 8-bit reads and writes as requested by the
+master.  Higher level functionality, such as reading a particular
+register value, is achieved by writing to set the memory location then
+reading to pull out the data.
+
+Note that the master/slave designation is on a message-by-message
+basis. Maple can act as both a master (messages initiated by user
+code) and slave device (responding to requests via configurable
+interrupt handlers) at the same time (though slave mode is currently
+unimplemented).
+
+Hardware/Circuit Design
+-----------------------
+
+.. FIXME [0.1.0] Link to board-specific values (BOARD_I2C1_SDA_PIN, etc.)
+
+Maple boards have two |i2c| ports.  Maples reliably communicate with
+up to a 400kHz clock speed; this doesn't translate into a 400kbps
+data rate except in extreme cases because of addressing and protocol
+overhead.  We have tested clock speeds up to a megahertz and have had
+mixed results; in theory, it could be possible to achieve even higher
+rates, but signal quality degrades rapidly, and the bus becomes
+unreliable.
+
+Proper wiring and pull-up resistor selection are essential when
+incorporating |i2c| into a circuit, especially with data rates above
+100kHz. In the lab, we usually use approximately 5kΩ resistors with
+|vcc| (3.3V) as the high voltage, and try to connect the pullup
+voltage as close to the SDA and SCL pins as possible.  We recommend
+looking at the ST reference website for |i2c| (see the
+:ref:`recommended reading <i2c-recommended-reading>` below), starting
+with a slow clock rate (10kHz), and, if possible, using an
+oscilloscope to debug any issues.
+
+Function Reference
+------------------
+
+Currently, only low-level support in :ref:`libmaple-i2c` exists.  A
+Wiring-style library is planned for a future release.
+
+SMBus
+-----
+
+The STM32 microcontroller has hardware support for SMBus, but software
+for it is not yet implemented.
+
+.. _i2c-recommended-reading:
+
+Recommended Reading
+-------------------
+
+* `I2C Bus <http://www.i2c-bus.org/>`_
+* `Wikipedia: I2C <http://en.wikipedia.org/wiki/I%C2%B2C>`_
+* `Arduino I2C/TWI reference <http://www.arduino.cc/en/Reference/Wire>`_
+* ST `Application note STM32F10xxx I2C optimized examples
+  <http://www.st.com/st-web-ui/static/active/en/resource/technical/document/application_note/CD00209826.pdf>`_ (PDF)