Document the boards.

docs/boards.rst

@@ -1,2 +1,59 @@
-Featherwings
-============
+Boards
+======
+
+Support for a board is loaded by including ``feather/feather.h`` - this
+will pull in support for the appropriate board. The boards that are 
+currently supported are
+
+* Feather M0-based boards; this has been tested with the Feather M0 basic
+  and the Feather M0 with RFM95 LoRa radio.
+* The Feather M4 Express.
+
+It may work on other M0 or M4-based boards, but these haven't been tested.
+
+
+The ``Board`` abstract base class
+---------------------------------
+
+The ``Board`` class defines a few virtual methods common to all Feathers:
+
+* ``double voltage()`` returns the current battery voltage as read from
+  the onboard voltage divider.
+* ``setup(int baudrate, bool wait)`` starts the serial console at the given
+  baudrate; if ``wait`` is ``true``, it will wait for a serial connection
+  before continuing with the boot process. It will also load support for the
+  ``%f`` verb in ``printf``, and seed the random number generator.
+* ``uint32_t random()`` returns a random number; for boards that support a
+  true random number generator, it will be a cryptographically valid random
+  number generator; otherwise, it's a best-effort random number generated by
+  repeatedly sampling the unused analog pin.
+* ``seed`` uses a random number from ``Board::random`` to seed the Arduino
+  random number generator.
+
+
+Feather M0
+----------
+
+The ``FeatherM0`` class is instantiated using one of three constructors:
+
++ The default constructor, ``FeatherM0()``, is a wrapper for 
+  ``FeatherM0(INPUT, UNUSED_ANALOG)``.
++ ``FeatherM0(int pin9Mode)`` is a wrapper for ``FeatherM0(pin9Mode, UNUSED_ANALOG)``.
++ ``FeatherM0(int pin9Mode, int unusedAnalog)`` explicitly defines the pin 9 mode
+  and the unused analog port.
+
+The Feather M0's voltage divider is on pin 9; in order to be read, it has to be
+put in the ``INPUT`` mode. Afterwards, it will be reset to whatever the ``pin9Mode``
+is. For example, when using the OLED featherwing (described later), it should be
+set to ``INPUT_PULLUP``.
+
+The unused analog pin is used for the random number generator as described above.
+
+
+Feather M4
+----------
+
+The ``FeatherM4`` class is instantiated using a default constructor. It has a
+true random number generator that is used for the seeding process and for
+returning random numbers.
+

docs/organisation.rst

@@ -1,3 +1,9 @@
 Organisation
 ============
 
+The code is roughly organised into three pieces:
+
+* boards, which are the computing base (e.g. the Feather M0),
+* featherwings and peripherals, and
+* everything else - scheduling, etc.
+