diff options
Diffstat (limited to 'docs/source/libs')
| -rw-r--r-- | docs/source/libs/servo.rst | 92 | ||||
| -rw-r--r-- | docs/source/libs/wire.rst | 104 |
2 files changed, 0 insertions, 196 deletions
diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst deleted file mode 100644 index 80288c6..0000000 --- a/docs/source/libs/servo.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. highlight:: cpp - -.. _libs-servo: - -Servo -===== - -This documents the Servo library for controlling RC servomotors. It -is implemented as a thin layer over the built-in :ref:`timer -peripherals <timers>`. - -You can use this library in the :ref:`IDE <ide>` by choosing the Servo -item under the Sketch > Import Library... menu. - -If you are using the :ref:`Unix toolchain <unix-toolchain>`, the -library is located in the ``/libraries/Servo/`` :ref:`libmaple` -directory. - -.. contents:: Contents - :local: - -Servo Class Reference ---------------------- - -You can construct a Servo object by including the declaration :: - - Servo servo; - -in your sketch. This will create a Servo object called ``servo``. -You can then use any of its methods; for instance, to control a -servomotor attached to pin 9, you could write :: - - servo.attach(9); - -.. doxygenclass:: Servo - :members: - -Arduino Compatibility ---------------------- - -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. - -However, there are some differences, essentially at the level of -implementation details. - -The major difference is that while the Arduino implementation drives -servos with "bit-banged" PWM (in the sense that timer interrupt -handlers are used to manually toggle pins), the Maple implementation -uses :ref:`timers <timers>` to drive the PWM directly. - -Consequently, **the Maple implementation only allows Servo instances -to attach to pins that support PWM**. - -To determine if a pin supports PWM, you can either check if "PWM" -appears next to its number on your board's silkscreen, or look for it -in the list of :ref:`boardPWMPins <lang-board-values-pwm-pins>` in -your board's :ref:`hardware documentation <index-boards>`. - -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]_. - -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 your board's :ref:`Timer Pin Map -<gpio-pin-maps>` to match up pins and timer channels. - -And here's some fine print: - -- 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 :ref:`true - <lang-constants-true>` on success, and :ref:`false - <lang-constants-false>` on failure (and this is its documented - behavior). - -- In another bit of undocumented behavior, the Arduino implementation - of write() also treats its argument as an angle or a pulse width - depending on its value. This is a bad idea, and we don't do it. - -.. rubric:: Footnotes - -.. [#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. diff --git a/docs/source/libs/wire.rst b/docs/source/libs/wire.rst deleted file mode 100644 index 2c5bed9..0000000 --- a/docs/source/libs/wire.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. highlight:: cpp - -.. _libs-wire: - -Wire -==== - -.. TODO [0.1.0] Format this correctly, using Breathe - -This page documents the Wire library for the :ref:`i2c` protocol. You -can use this library in the :ref:`Maple IDE <ide>` by choosing the -Wire item under the Sketch > Import Library... menu. - -If you are using the :ref:`Unix toolchain <unix-toolchain>`, the -library is located in the ``/libraries/Wire/`` :ref:`libmaple` -directory. - -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)``. - -Arduino Compatibility ---------------------- - -.. FIXME [0.1.0] Replace this section when i2c Wire wrapper is done - -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. For now, use of the hardware -:ref:`i2c` peripheral is only available through :ref:`libmaple-i2c`. - - |