aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/arduino-compatibility.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/arduino-compatibility.rst')
-rw-r--r--docs/source/arduino-compatibility.rst271
1 files changed, 0 insertions, 271 deletions
diff --git a/docs/source/arduino-compatibility.rst b/docs/source/arduino-compatibility.rst
deleted file mode 100644
index c200411..0000000
--- a/docs/source/arduino-compatibility.rst
+++ /dev/null
@@ -1,271 +0,0 @@
-.. highlight:: cpp
-
-.. _arduino-compatibility:
-
-=============================
- Maple-Arduino Compatibility
-=============================
-
-.. contents:: Contents
- :local:
-
-Overview
---------
-
-The biggest difference between the Maple and most Arduino boards is
-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 (which makes up executable binary program) 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 `avr-gcc
-<http://www.nongnu.org/avr-libc/>`_ 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 or multiplying two 32-bit integers) in a
-single instruction, while an Arduino processor would have to split up
-large operations into several smaller ones. In a lot of cases 8-bit
-operations are plenty (integers 0-255, single characters of text,
-etc.), but if you're dealing with higher resolution data, the speed up
-could be significant.
-
-A trade-off is that code could be larger as well; program instructions
-and memory locations can be up to 32 bits each. However, removal of
-extra instructions and fancy packing together of simple instructions
-means that programs aren't much larger (or are even smaller).
-
-Header Numbering and Incompatibilities
---------------------------------------
-
-.. FIXME [Maple-specific values]
-
-The numbering of headers is different; on the Maple each GPIO has a
-unique number: 0, 1, 2, all the way up to 37 (actually, there are
-:ref:`a few more <lang-disabledebugports>`...). On the Arduino, the
-analog pins are numbered separately (A0-A5) from the digital pins (D0\
--D13).
-
-The incompatible hardware differences are:
-
-* :ref:`I2C <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
- increased capacitance). Alternatively, |i2c| can be bit-banged
- 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.
-
-* **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 (D14) 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
- 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
- debugging; it uses :ref:`JTAG <jtag>`.
-
-
-Software Language/Library Changes
----------------------------------
-
-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
- full 32-bit (4 byte) integer values instead of the regular 16-bit (2
- byte) Arduino values.
-
-* **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 pins (labeled "PWM" on the
- silkscreen) can be configured in ``PWM`` and ``PWM_OPEN_DRAIN``
- modes, and the analog input pins (labeled "AIN") can be configured
- in ``INPUT_ANALOG`` mode. See the :ref:`GPIO documentation <gpio>`
- for more information.
-
-* :ref:`Serial port <lang-serial>` **syntax**: like the `Arduino Mega
- <http://arduino.cc/en/Main/ArduinoBoardMega>`_, the Maple has
- multiple :ref:`USART ports <lang-serial>`. By default, ``Serial``
- is not mapped to any of them. Use ``Serial1`` through ``Serial3``
- instead.
-
-* **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).
-
-* **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.
-
-Shield and Device Compatibility
--------------------------------
-
-.. list-table::
- :header-rows: 1
-
- * - Shield/Device
- - Compatible?
- - Notes
-
- * - Ethernet shield
- - Yes!
- - Tested; no library yet
-
- * - WiFi Shield
- - Yes!
- - Tested; preliminary library support
-
- * - 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
-
-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. (:ref:`Patches are
- welcome! <libmaple-contributing>`).
-
-- 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.