diff options
Diffstat (limited to 'docs/source/compatibility.rst')
| -rw-r--r-- | docs/source/compatibility.rst | 232 |
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. |