aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/compatibility.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/compatibility.rst')
-rw-r--r--docs/source/compatibility.rst232
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.