diff options
Diffstat (limited to 'docs/source/libraries.rst')
| -rw-r--r-- | docs/source/libraries.rst | 176 |
1 files changed, 31 insertions, 145 deletions
diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst index 7623963..2bc8b11 100644 --- a/docs/source/libraries.rst +++ b/docs/source/libraries.rst @@ -10,13 +10,13 @@ .. Note: if you port an Arduino library and document it here, be sure .. to update compatibility.rst to reflect that fact. -This page briefly summarizes the Arduino libraries that have been -ported to Maple. You can use a library from within a sketch by going -to Sketch > Import Library... from within the IDE, then choosing the -library you want. +This page lists the extra libraries that are part of the :ref:`Maple +IDE <ide>` (along with the rest of :ref:`libmaple <libmaple>`). You +can use a library from within a sketch by going to Sketch > Import +Library... from within the IDE, then choosing the library you want. -Any incompatibilities between the Maple and Arduino versions are noted -in the description of the library. +Any incompatibilities between the Maple and Arduino versions of a +library are noted in the library's documentation. .. contents:: Contents :local: @@ -25,70 +25,47 @@ in the description of the library. :hidden: libs/servo.rst + libs/wire.rst -.. _libraries-servo: - -Servo ------ - -The Servo library is provided for convenient control of RC -servomotors. For more information, see the :ref:`Servo <libs-servo>` -reference. +.. admonition:: **Looking for Something Else?** -**Compatibility Note** + - See the :ref:`language` for information on the core functions + used for programming a Maple board. -The Servo class provides a public interface identical to the Arduino -version's documented functionality (as of Arduino 0021), so in most -cases, this library will be a drop-in replacement. + - If you're looking for something from the C standard library (like + ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler + <arm-gcc>` used to compile your programs is configured to link + against `newlib <http://sourceware.org/newlib/>`_, and allows the + use of any of its header files. However, dynamic memory allocation + (``malloc()``, etc.) is not available. -However, there are some differences, essentially at the level of -implementation details. + - If you're looking for low-level hardware support libraries, see + the :ref:`libmaple Reference`. -The major difference is that while the Arduino implementation drives -the servos with "bit-banged" :ref:`PWM <pwm>`, the Maple -implementation uses :ref:`timers <timers>` to drive the PWM directly. - -Consequently, **the Maple implementation only allows Servo instances -to** :ref:`attach <libs-servo-attach>` **to pins that support PWM**. - -To determine if a pin supports PWM (15 Maple pins do), you can either -check if "PWM" appears next to its number on the Maple silkscreen, or -consult the :ref:`pwmWrite() <lang-pwmwrite>` documentation. - -RC Servos expect a pulse approximately every 20ms. In the Maple -implementation, :ref:`periods <lang-hardwaretimer-setperiod>` are set -for entire timers, rather than individual channels. Thus, -``attach()``\ ing a Servo to a pin can interfere with other pins -associated with the same timer\ [#fard-servo]_. +.. _libraries-servo: -Because of this, we recommend connecting multiple servomotors to pins -which share a timer, in order to keep as many timers free for other -purposes as possible. Consult the :ref:`table provided in the timers -reference <timers-pin-channel-map>` to match up pins and timer -channels. +Servo +----- -Another difference: although it is not publicly documented to do so, -the Arduino implementation of `attach() -<http://arduino.cc/en/Reference/ServoAttach>`_ returns the timer -channel associated with the newly-attached pin, or 0 on failure (as of -Arduino 0021). The Maple implementation returns true on success, and -false on failure (and this is its documented behavior). +The :ref:`Servo <libs-servo>` library is provided for convenient +control of RC servomotors. .. _libraries-liquid-crystal: LiquidCrystal ------------- -.. TODO 0.0.10 make our own LiquidCrystal docs +.. TODO [0.1.0] LiquidCrystal docs under libs/liquidcrystal.rst The LiquidCrystal library allows Maple to control LCD screens. For more information, see the `Arduino LiquidCrystal documentation <http://www.arduino.cc/en/Reference/LiquidCrystal>`_. -**Compatibility Note** +**Arduino Compatibility** At this time, no incompatibilities between the Maple and Arduino -versions are known. Any observed differences should be considered +versions are known (although the Maple version should perform +significantly faster). Any observed differences should be considered bugs, and reported on the forums. .. _libraries-wire: @@ -96,99 +73,8 @@ bugs, and reported on the forums. Wire ---- -We provide a soft (bit-banged) implementation of the `Wire I2C library -<http://arduino.cc/en/Reference/WireBegin>`_. - -**Compatibility Note** - -This implementation is synchronous, and thus supports only a subset of -the full Wire interface (however, the functionality which is supported -is fully compatible with Arduino). For now, please use the function -reference which follows when developing projects using our -implementation. - -Please note that the current implementation only supports master mode -using a bit-banged (software) protocol. Future enhancements will use -the hardware i2c peripheral on the stm32 as well as the DMA for -performance. Support for slave, smBUS, and multimaster modes are also -slated for inclusion in the enhanced Wire port. - -.. TODO 0.0.10 Wire docs in the cpp domain in own page under /libs/ - -Wire Function Reference -^^^^^^^^^^^^^^^^^^^^^^^ - -``Wire.begin()`` - Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL - (this is compatible with the pin settings on the Arduino Mega). - -``Wire.begin(sda, scl)`` - Like ``Wire.begin()``, but with the given pins as SDA and - SCL. - -``Wire.beginTransmission(slave_address)`` - Set up a transmission to a slave device with the given (7-bit) - address. Bytes subsequently queued for transmission (using - ``Wire.send``) will be sent to ``slave_address`` when ``void - Wire.endTransmission()`` is called. - -``void Wire.send(byte)`` - Queues the given byte (``uint8`` or ``int``) to the slave address - previously specified by a call to ``Wire.beginTransmission``. At - most 32 bytes may be queued in a single transmission. - -``Wire.send(string)`` - Queues a given string (``char*``) for transmission. The characters - of the string are individually queued for transmission as - bytes. At most 32 bytes may be queued in a single transmission. - -``Wire.send(buffer, length)`` - Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with - ``length`` elements, for transmission. At most 32 bytes may be - queued in a single transmission. - -``Wire.endTransmission()`` - Ends a transmission (begun by ``Wire.beginTransmission(uint8)``), - and actually sends the bytes queued by calls to Wire.send. - - The return value is one of the following status codes: - - * ``SUCCESS``: All bytes were transmitted successfully. - - * ``EDATA``: More than 32 bytes were queued for transmission. No - bytes are actually sent when this happens. - - * ``ENACKADDR``: Did not receive ACK on transmit of address. No - bytes are actually sent when this happens. - - * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some - bytes may have been sent when this happens; however, the - transmission is aborted after the first byte of data which is - not ACKed by the slave device. - - * ``EOTHER``: Other error occurred. - -``Wire.requestFrom(address, num_bytes)`` - Requests ``num_bytes`` bytes from 7-bit slave address - address. Returns the actual number of bytes read. These bytes may - subsequently be read one at a time using ``Wire.receive()``. - - Note: if ``num_bytes`` exceeds the size of the transmit/receive - buffer (currently 32), it will be truncated to 32. - -``Wire.receive()`` - Get and return the next byte read during the previous call to - ``Wire.requestFrom(uint8, int)``. You can check how many bytes are - left to read using ``uint8 Wire.available()``. - -``Wire.available()`` - Returns the number of bytes which are still available for reading - (with ``Wire.receive()``) from the last call to - ``Wire.requestFrom(uint8, int)``. - -.. rubric:: Footnotes +.. FIXME [0.1.0] Update with hard Wire implementation info -.. [#fard-servo] The Arduino implementation also captures timer - channels in groups as more Servo objects are attached, but the - details of which channels have their periods reset when are - slightly different. +We currently provide a soft (bit-banged) implementation of the +:ref:`Wire <libs-wire>` I2C library. A hardware version is planned +for Maple IDE release 0.1.0. |