Merge remote branch 'leaf/master'

1 files changed, 182 insertions, 50 deletions

diff --git a/docs/source/compatibility.rst b/docs/source/compatibility.rst
index 8872a1b..848a3d3 100644
--- a/docs/source/compatibility.rst
+++ b/docs/source/compatibility.rst
@@ -17,10 +17,13 @@ that the Maple uses a 32-bit ARM Cortex-M3 architecture chip while the
 Arduinos have 8-bit Atmel AVR chips. The different instruction set
 means that machine code (executable binary programs) is incompatible
 between the two, and a different compiler (actually just a different
-version of `gcc <http://gcc.gnu.org/>`_) is required. The compiler for
-the regular Arduino IDE is the popular :command:`avr-gcc` package; the
-compiler for the Maple version of the IDE is CodeSourcery's edition of
-gcc for the ARM EABI target (:command:`arm-non-eabi-gcc`).
+version of `gcc <http://gcc.gnu.org/>`_) is required.
+
+The compiler for the regular Arduino IDE is the popular
+:command:`avr-gcc` package; the compiler for the Maple version of the
+IDE is CodeSourcery's edition of gcc for the ARM EABI target
+(:command:`arm-non-eabi-gcc`).  A (preliminary) reference on
+:ref:`using arm-none-eabi-gcc <arm-gcc>` is available.
 
 The bitwidth of the processor means that the Maple can process 32-bit
 operations (like adding two 32-bit integers) in a single instruction,
@@ -45,8 +48,8 @@ numbered separately (A0-A5) from the digital pins (D0\ -D13).
 
 The incompatible hardware differences are:
 
-* |i2c| port: on most Arduinos, the |i2c| port is Analog Input
-  4 (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5
+* **I2C port**: on most Arduinos, the |i2c| port is Analog Input 4
+  (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5
   (SCL) and D9 (SDA), and |i2c| port 2 is D29 (SCL) and D30 (SDA).
 
   It should be possible to skywire, sacrificing signal quality (due to
@@ -54,81 +57,210 @@ The incompatible hardware differences are:
   reasonably well in software. This peripheral could potentially be
   rerouted internally, but we haven't looked into it.
 
-* :ref:`PWM <pwm>` on D10: all the other standard Arduino PWM headers have PWM
-  functionality on the Maple (D2,D3,D6,D9,D11), but not D10. We did
-  our best! It may be possible to reroute this peripheral internally
-  using low level configuration, but we haven't looked in to it.
+* :ref:`PWM <pwm>` **on D10**: all the other standard Arduino PWM
+  headers have PWM functionality on the Maple (D2,D3,D6,D9,D11), but
+  not D10. We did our best! It may be possible to reroute this
+  peripheral internally using low level configuration, but we haven't
+  looked in to it.
 
-* No External Voltage Reference: The Arduino has an Aref pin which
+* **No External Voltage Reference**: The Arduino has an Aref pin which
   allows the use of an external ADC voltage reference; the Maple has
   an extra GPIO pin (14) with PWM capability in this spot, and does
   not allow an external voltage reference to be configured.
 
-* EEPROM: the Maple does not have any internal EEPROM. This
+* **EEPROM**: the Maple does not have any internal EEPROM. This
   functionality can be emulated with regular persistent flash memory,
   or with an external EEPROM chip.
 
-* ISP Programming: the Maple does not use an ISP/ICSP bus for
+* **ISP Programming**: the Maple does not use an ISP/ICSP bus for
   debugging; it uses :ref:`JTAG <jtag>`.
 
 
 Software Language/Library Changes
 ---------------------------------
 
-With :ref:`one notable exception <language-no-word>`, the entire
-Arduino language is supported.  However, there are some subtle
+With :ref:`a few exceptions <language-missing-features>`, the entire
+Wiring/Arduino language is supported.  However, there are some subtle
 differences, most of which are improvements:
 
-* 32-bit integers: many standard functions either expect or return
+* **32-bit integers**: many standard functions either expect or return
   full 32-bit (4 byte) integer values instead of the regular 16-bit (2
   byte) Arduino values.
 
-* `pinMode()`_ types: any :ref:`GPIO <gpio>` (including analog pins)
-  can be configured into one of the following modes with a single call
-  to `pinMode()`_: ``OUTPUT``, ``OUTPUT_OPEN_DRAIN``,
-  ``INPUT_FLOATING``, ``INPUT_PULLUP``,
+* **64-bit doubles**: The :ref:`double <lang-double>` type is a full
+  double-precision floating point type on the Maple; it is a
+  single-precision floating point value on the Arduino.
+
+* :ref:`pinMode() <lang-pinmode>` **types**: any :ref:`GPIO <gpio>`
+  (including analog pins) can be configured into one of the following
+  modes with a single call to ```pinMode()``: ``OUTPUT``,
+  ``OUTPUT_OPEN_DRAIN``, ``INPUT_FLOATING``, ``INPUT_PULLUP``,
   ``INPUT_PULLDOWN``. Additionally, the PWM and Analog Input pins can
   be configured as ``INPUT_ANALOG`` and ``PWM`` respectively. See the
   :ref:`GPIO documentation <gpio>` for more information.
 
-  .. TODO: reference libmaple docs above when they're done
-
-* Serial1 syntax: like the `Arduino Mega
+* :ref:`Serial port <lang-serial>` **syntax**: like the `Arduino Mega
   <http://arduino.cc/en/Main/ArduinoBoardMega>`_, the Maple has
-  multiple USART ports.  By default, Serial is not mapped to any of
-  them, use ``Serial1`` through ``Serial3`` instead.
-
-  .. TODO: reference libmaple docs for Serial[n] above when they're done
-
-* 16-bit :ref:`PWM <pwm>`: Arduino boards support 8-bit PWM, which
-  means that calls to `analogWrite()`_ take values between 0 (always
-  off) and 255 (always on).  The Maple supports 16-bit PWM, so the
-  corresponding values should be between 0 (always off) and 65535
-  (always on).
-
-* 12-bit :ref:`ADC <adc>`: Arduino boards support 10-bit ADC, which
-  means that calls to `analogRead()`_ will return values between 0 and
-  1023.  The Maple supports 12-bit ADC, so the same call will instead
-  return values between 0 and 4095.
-
-
-.. class:: ported-feature
+  multiple :ref:`USART ports <lang-serial>`.  By default, ``Serial``
+  is not mapped to any of them, use ``Serial1`` through ``Serial3``
+  instead.
 
-I am supported!
+* **16-bit** :ref:`PWM <pwm>`: Arduino boards support 8-bit PWM, which
+  means that calls to :ref:`analogWrite() <lang-analogwrite>` take
+  values between 0 (always off) and 255 (always on).  The Maple
+  supports 16-bit PWM, so the corresponding values should be between 0
+  (always off) and 65535 (always on).
 
-This should be ordinary
+* **12-bit** :ref:`ADC <adc>`: Arduino boards support 10-bit ADC, which
+  means that calls to :ref:`analogRead() <lang-analogread>` will
+  return values between 0 and 1023.  The Maple supports 12-bit ADC, so
+  the same call will instead return values between 0 and 4095.
 
-.. class:: non-ported-feature
+Shield and Device Compatibility
+-------------------------------
 
-I can't do it :(
+.. list-table::
+   :header-rows: 1
 
-Also ordinary
+   * - Shield/Device
+     - Compatible?
+     - Notes
 
-.. class:: partly-ported-feature
+   * - Ethernet shield
+     - Yes!
+     - Tested; no library yet
 
-I sorta work
+   * - WiFi Shield
+     - Yes!
+     - Tested; preliminary library support
 
-And I am also ordinary
+   * - MIDI shield
+     - Yes!
+     - Tested; no library yet
+
+   * - XBee shield
+     - Unknown
+     -
+
+   * - Bluetooth shield
+     - Unknown
+     - Some Bluetooth <-> UART boards have been tested and are known
+       to work.
+
+   * - Cellular shield
+     - Unknown
+     -
+
+Library Porting Status
+----------------------
+
+The state of currently ported Arduino libraries is the
+:ref:`libraries`.
+
+.. TODO Update as libraries are ported.
+
+.. list-table::
+   :header-rows: 1
+
+
+   * - Library
+     - Ported?
+     - Notes
+
+   * - Wire
+     - Preliminary
+     - In progress; see :ref:`library reference <libraries-wire>`.
+
+   * - LiquidCrystal
+     - **Yes**
+     - :ref:`Included since IDE 0.0.7 <libraries-liquid-crystal>`
+
+   * - Ethernet
+     - Not yet
+     - Planned
+
+   * - EEPROM
+     - (Unsupported) third-party emulation
+     - The Maple doesn't have EEPROM; it uses flash instead.  There is
+       an `EEPROM emulation library
+       <http://akb77.com/g/mcu/maple-eeprom-emulation-library/>`_ by
+       `x893 <http://akb77.com/g/>`_, but we haven't tested it.
+
+   * - Firmata
+     - Not yet
+     - Planned
+
+   * - Matrix
+     - Not yet
+     - Planned
+
+   * - Servo
+     - **Yes**
+     - :ref:`Included since IDE 0.0.9 <libraries-servo>`
+
+   * - SoftwareSerial
+     - Not yet
+     - Planned
+
+   * - Sprite
+     - Not yet
+     - Planned
+
+   * - Stepper
+     - Not yet
+     - Planned
 
-Stub (unfinished)
+Sketch and Library Porting HOWTO
+--------------------------------
+
+In addition to the suggestions in this section, you may find many of
+the individual :ref:`language reference <language>` pages useful.  As
+appropriate, these have "Arduino Compatibility" sections; one good
+example is the :ref:`analogWrite() <lang-analogwrite-compatibility>`
+function.
 
+- Check the hardware and header differences above, and see if your
+  project or shield needs to be modified (eg, add 3.3V level
+  converters or reroute PWM to header D10).
+
+- Check for ported library functionality. We intend to port all of the
+  core and popular libraries (like Wire, Ethernet, and the LCD screen
+  driver), but this task is not yet finished. (Patches are welcome!)
+
+- Check for peripheral conflicts; changing the configuration of timers
+  and bus speeds for a feature on one header may impact all the
+  features on that hardware "port".  For example, changing the timer
+  prescaler to do long PWM pulses could impact |i2c| communications on
+  nearby headers.
+
+- Rewrite any low-level code. This could potentially be very
+  difficult, but hopefully you've used the Arduino libraries to
+  abstract away the registers and other hardware-specific
+  details. Your sketch probably doesn't have any low-level code; a
+  library which wraps a particular peripheral very well may.  Some
+  help is available in the :ref:`arm-gcc` reference.
+
+- Redeclare variable sizes if necessary: generics like ``int`` will
+  probably work unless you depend on side-effects like rollover.
+
+- Check every ``pinMode()``: the Maple has more modes for GPIO
+  pins. For example, make sure to set analog pins to ``INPUT_ANALOG``
+  before reading and PWM pins to ``PWM`` before writing.  The full set
+  of pin modes is documented in the :ref:`lang-pinmode` reference.
+
+- Modify PWM writes: ``pinMode()`` must be set to ``PWM``, the
+  frequency of the PWM pulse configured, and the duty cycle written
+  with up to 16-bit resolution.
+
+- Modify ADC reads: :ref:`lang-analogread` takes the full pin number
+  (not 0-5) and returns a full 12-bit reading. The ADC pin must have
+  its ``pinMode()`` set to ``INPUT_ANALOG``.
+
+- Possibly convert all Serial-over-USB communications to use
+  :ref:`lang-serialusb` instead of a USART :ref:`serial port
+  <lang-serial>`. The Maple has a dedicated USB port which is not
+  connected to the USART TX/RX pins in any way.
+
+- Check timing: Maple clock cycles are just 13.9 nanoseconds, though
+  the peripheral bus speeds (which limit GPIO output) are clocked
+  slower.