aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/lang/api
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-05-09 16:43:27 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2011-05-09 16:49:08 -0400
commit19ea6ba4ea3f1ecb9830cf4d3e1366513f4f96e3 (patch)
treea43f7e0fb3650ca54f245b750a078a0e8c356504 /docs/source/lang/api
parent868fb1c273e562a1140abfa948022c9d4f55bccf (diff)
parent1e2e177f6dae62e040c674b617744c73be187062 (diff)
downloadlibrambutan-19ea6ba4ea3f1ecb9830cf4d3e1366513f4f96e3.tar.gz
librambutan-19ea6ba4ea3f1ecb9830cf4d3e1366513f4f96e3.zip
Merge branch 'refactor'
This merges the libmaple refactor work into master. The contents of libmaple proper (/libmaple/) are almost completely incompatible with previous APIs in master. See /docs/source/libmaple/overview.rst for more information on the new design. Wirish incompatibilities are limited to the HardwareTimer class; however, there are several new deprecations, most likely to be removed in 0.1.0.
Diffstat (limited to 'docs/source/lang/api')
-rw-r--r--docs/source/lang/api/abs.rst3
-rw-r--r--docs/source/lang/api/analogread.rst78
-rw-r--r--docs/source/lang/api/analogwrite.rst43
-rw-r--r--docs/source/lang/api/attachinterrupt.rst57
-rw-r--r--docs/source/lang/api/bit.rst12
-rw-r--r--docs/source/lang/api/bitclear.rst13
-rw-r--r--docs/source/lang/api/bitread.rst11
-rw-r--r--docs/source/lang/api/bitset.rst9
-rw-r--r--docs/source/lang/api/bitwrite.rst7
-rw-r--r--docs/source/lang/api/board-values.rst180
-rw-r--r--docs/source/lang/api/boardusespin.rst27
-rw-r--r--docs/source/lang/api/cc-attribution.txt9
-rw-r--r--docs/source/lang/api/constants.rst36
-rw-r--r--docs/source/lang/api/constrain.rst5
-rw-r--r--docs/source/lang/api/cos.rst6
-rw-r--r--docs/source/lang/api/delay.rst6
-rw-r--r--docs/source/lang/api/delaymicroseconds.rst11
-rw-r--r--docs/source/lang/api/detachinterrupt.rst8
-rw-r--r--docs/source/lang/api/digitalread.rst39
-rw-r--r--docs/source/lang/api/digitalwrite.rst39
-rw-r--r--docs/source/lang/api/disabledebugports.rst31
-rw-r--r--docs/source/lang/api/enabledebugports.rst31
-rw-r--r--docs/source/lang/api/hardwarespi.rst215
-rw-r--r--docs/source/lang/api/hardwaretimer.rst548
-rw-r--r--docs/source/lang/api/highbyte.rst6
-rw-r--r--docs/source/lang/api/isbuttonpressed.rst5
-rw-r--r--docs/source/lang/api/loop.rst3
-rw-r--r--docs/source/lang/api/lowbyte.rst2
-rw-r--r--docs/source/lang/api/map.rst2
-rw-r--r--docs/source/lang/api/max.rst5
-rw-r--r--docs/source/lang/api/micros.rst2
-rw-r--r--docs/source/lang/api/millis.rst2
-rw-r--r--docs/source/lang/api/min.rst3
-rw-r--r--docs/source/lang/api/pinmode.rst8
-rw-r--r--docs/source/lang/api/pow.rst5
-rw-r--r--docs/source/lang/api/pwmwrite.rst12
-rw-r--r--docs/source/lang/api/random.rst6
-rw-r--r--docs/source/lang/api/randomseed.rst2
-rw-r--r--docs/source/lang/api/serial.rst86
-rw-r--r--docs/source/lang/api/serialusb.rst72
-rw-r--r--docs/source/lang/api/setup.rst2
-rw-r--r--docs/source/lang/api/shiftout.rst99
-rw-r--r--docs/source/lang/api/sin.rst3
-rw-r--r--docs/source/lang/api/sq.rst3
-rw-r--r--docs/source/lang/api/tan.rst3
-rw-r--r--docs/source/lang/api/toggleled.rst2
-rw-r--r--docs/source/lang/api/volatile.rst8
-rw-r--r--docs/source/lang/api/waitforbuttonpress.rst2
48 files changed, 977 insertions, 790 deletions
diff --git a/docs/source/lang/api/abs.rst b/docs/source/lang/api/abs.rst
index 0cc6c23..d9f1ca3 100644
--- a/docs/source/lang/api/abs.rst
+++ b/docs/source/lang/api/abs.rst
@@ -45,5 +45,4 @@ Arduino Compatibility
Maple's implementation of ``abs()`` is compatible with Arduino.
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst
index 35c6fbc..6665a94 100644
--- a/docs/source/lang/api/analogread.rst
+++ b/docs/source/lang/api/analogread.rst
@@ -20,53 +20,56 @@ Library Documentation
Discussion
----------
-Reads the value from the specified analog pin. The Maple board
-contains a 16-channel, 12-bit analog to digital converter. This means
-that it will map input voltages between 0 and 3.3 volts into integer
-values between 0 and 4095. This yields a resolution between readings
-of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors
+Reads the value from the specified analog pin. The Maple boards
+contain 16-channel, 12-bit analog to digital converters. This means
+that a converter will map input voltages between 0 and 3.3 volts into
+integer values between 0 and 4095. However, a number of factors
interfere with getting full accuracy and precision. For more
information, see :ref:`adc`.
Before calling analogRead() on a pin, that pin must first be
-configured for analog input, using :ref:`lang-pinMode` (you only
-have to do this once, so it's usually done in :ref:`lang-setup`\ ).
+configured for analog input, using :ref:`lang-pinMode`. You only have
+to do this once, so it's usually done in :ref:`lang-setup`\ .
Parameter Discussion
--------------------
The pin parameter is the number of the analog input pin to read from.
-Header pins on the Maple with ADC functionality (marked as "AIN" on
-the silkscreen) are:
-
- 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28
-
-Note that pins 3, 27, and 28 are not marked AIN on the silkscreen
-for Maple revisions through Rev 5, however, they **do work** as
-analog input pins.
+The pins which support analog to digital conversion have ``AIN``
+listed underneath their number on your board's silkscreen. These pin
+numbers are available to your program in the :ref:`boardADCPins
+<lang-board-values-adc-pins>` board-specific array. The number of
+pins which are capable of analog to digital conversion on your board
+is given by the ``BOARD_NR_ADC_PINS`` constant. These values are
+documented for each board in the :ref:`Board Hardware Documentation
+<index-boards>` pages.
+
+.. note:: Pin 3 is not marked ``AIN`` on the silkscreen for Maple
+ revisions through Rev 5; however **it does work** as an analog
+ input pin.
Note
----
If the analog input pin is not connected to anything, the value
-returned by analogRead() will fluctuate based on a number of factors
-(e.g. the values of the other analog inputs, how close your hand is to
-the board, etc.) in a seemingly random way.
-
+returned by ``analogRead()`` will fluctuate due to a number of reasons
+(like the values of the other analog inputs, how close your hand is to
+the board, etc.) in a "random" way.
Example
-------
- ::
+::
+ int analogPin = 3; // Potentiometer wiper (middle terminal) connected
+ // to analog pin 3. outside leads to ground and +3.3V.
+ // You may have to change this value if your board
+ // cannot perform ADC conversion on pin 3.
- int analogPin = 3; // potentiometer wiper (middle terminal) connected
- // to analog pin 3. outside leads to ground and +3.3V
int val = 0; // variable to store the value read
void setup() {
pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input
- SerialUSB.begin(); // set up usb virtual COM port
}
void loop() {
@@ -75,7 +78,6 @@ Example
// a serial monitor
}
-
Arduino Compatibility
---------------------
@@ -97,23 +99,21 @@ shift <lang-bitshift>` the value of a Maple readout by 2, like so::
// be aware that you're losing a lot of precision if you do this
int adc_reading = analogRead(pin) >> 2;
+.. FIXME [0.1.0] Mention that Native can do analogReference()
+
On the Arduino, the input range and resolution can be changed using
-their implementation of `analogReference()
-<http://arduino.cc/en/Reference/AnalogReference>`_\ . Because of the
-way its hardware (as of Rev 5) was designed, it's not possible to
-implement analogReference on the Maple, so this function doesn't
-exist. If your inputs lie in a different voltage range than 0V--3.3V,
-you'll need to bring them into that range before using analogRead.
-Some basic tools to accomplish this are `resistor dividers
-<http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener diodes
-<http://en.wikipedia.org/wiki/Voltage_source#Zener_voltage_source>`_\
-. However, opamps and other powered components can also be used if
-greater precision is required.
-
-See also
+the `analogReference()
+<http://arduino.cc/en/Reference/AnalogReference>`_ function. Because
+of hardware restrictions, this function is not available on the Maple
+and Maple RET6 Edition. If your inputs lie in a different voltage
+range than 0V--3.3V, you'll need to bring them into that range before
+using ``analogRead()``. See the :ref:`ADC reference <adc-range>` for
+more information.
+
+See Also
--------
-- :ref:`ADC note <adc>`
+- :ref:`ADC tutorial <adc>`
- `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/analogwrite.rst b/docs/source/lang/api/analogwrite.rst
index 9147b96..dd2192a 100644
--- a/docs/source/lang/api/analogwrite.rst
+++ b/docs/source/lang/api/analogwrite.rst
@@ -52,7 +52,7 @@ you much more precise control over the duty cycle of your PWM output.
If you're porting code from the Arduino and want a quick-and-dirty
fix, one solution is to :ref:`map <lang-map>` the argument to
-analogWrite into the right range::
+analogWrite() into the right range::
// Arduino code:
analogWrite(pin, duty);
@@ -65,14 +65,14 @@ This will convert values in the range 0-255 to values in the range
which control PWM output. See the :ref:`timers reference <timers>`
for more information.
-Another fix is to consult the :ref:`pin mapping mega table
-<pin-mapping-mega-table>` to find the timer which controls PWM on the
-pin you're using, then set that Timer's overflow to 255. Subsequent
-calls to analogWrite() should work as on the Arduino (with the same
-loss of precision). Note, however, that that affects the overflow for
-the **entire timer**, so other code relying on that timer (such as any
-:ref:`interrupts <lang-attachinterrupt>` the timer controls) will
-likely need to be modified as well.
+Another fix is to consult your board's :ref:`pin maps <gpio-pin-maps>`
+to find the timer which controls PWM on the pin you're using, then set
+that Timer's overflow to 255. Subsequent calls to analogWrite()
+should work as on the Arduino (with the same loss of precision).
+Note, however, that that affects the overflow for the **entire
+timer**, so other code relying on that timer (such as any
+:ref:`interrupts <lang-hardwaretimer-interrupts>` the timer controls)
+will likely need to be modified as well.
Difference 2: You must use pinMode() to set up PWM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -140,24 +140,28 @@ If your application definitely requires Arduino's PWM frequency, then
the steps are:
1. Figure out which :ref:`timer <lang-hardwaretimer>` controls PWM
- output on your pin (\ :ref:`this table <pwm-timer-table>` is your
- friend here). Let's say it's ``Timern``\ , where ``n`` is some
- number 1, 2, 3, or 4.
+ output on your pin (\ :ref:`your board's Timer Pin Map
+ <gpio-pin-maps>` is your friend here).
-2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's
- period to approximately 2041 microseconds, which is a frequency of
- approximately 490 Hz.
+2. Let's say it's timer ``n``, where ``n`` is some number. You'll
+ then need to put "``HardwareTimer timer(n);``" with your variables,
+ as described in the :ref:`HardwareTimer
+ <lang-hardwaretimer-getting-started>` reference.
+
+3. In your :ref:`lang-setup`, put "``timer.setPeriod(2041);``". This
+ will set the timer's period to approximately 2041 microseconds,
+ which is a frequency of approximately 490 Hz.
Be aware that this will change the period for the **entire timer**\ ,
and will affect anything else in your program that depends on that
timer. The important examples are :ref:`timer interrupts
-<lang-hardwaretimer-attachinterrupt>` and :ref:`PWM
+<lang-hardwaretimer-interrupts>` and :ref:`PWM
<timers-pwm-conflicts>`\ .
-See also
+See Also
--------
-- :ref:`Maple PWM tutorial <pwm>`
+- :ref:`pwm`
.. rubric:: Footnotes
@@ -169,5 +173,4 @@ See also
Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative)
integer with size 2 bytes can hold the values between 0 and 65,535.
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/attachinterrupt.rst b/docs/source/lang/api/attachinterrupt.rst
index 7c5a6c7..39902ac 100644
--- a/docs/source/lang/api/attachinterrupt.rst
+++ b/docs/source/lang/api/attachinterrupt.rst
@@ -5,9 +5,8 @@
attachInterrupt()
=================
-Used to specify a function to call when an external interrupt (like an
-GPIO changing from LOW to HIGH, a button getting pressed, etc.)
-occurs.
+Used to specify a function to call when an :ref:`external interrupt
+<external-interrupts>` occurs.
.. contents:: Contents
:local:
@@ -15,9 +14,9 @@ occurs.
Library Documentation
---------------------
-.. FIXME once breathe knows how to get the correct attachInterupt
-.. (right now it's copying from HardwareTimer), replace with a
-.. doxygenfunction directive
+.. FIXME [doxygenfunction] once Breathe knows how to get the correct
+.. attachInterupt (right now it's copying from HardwareTimer), replace
+.. with a doxygenfunction directive
.. cpp:function:: void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode)
@@ -47,49 +46,29 @@ Discussion
Because the function will run in interrupt context, inside of it,
:ref:`lang-delay` won't work, and the value returned by
-:ref:`lang-millis` will not increment. Serial data received while
-in the function may be lost. You should declare as ``volatile`` any
+:ref:`lang-millis` will not increment. Serial data received while in
+the function may be lost. You should declare as ``volatile`` any
global variables that you modify within the attached function.
-There are a few constraints you should be aware of if you're using
-more than one interrupt at a time; the :ref:`external-interrupts` page
-has the details.
-
-Using Interrupts
-----------------
-
-Interrupts are useful for making things happen automatically in
-microcontroller programs, and can help solve timing problems. A
-good task for using an interrupt might be reading a rotary encoder,
-or monitoring user input.
-
-If you wanted to insure that a program always caught the pulses
-from a rotary encoder, never missing a pulse, it would make it very
-tricky to write a program to do anything else, because the program
-would need to constantly poll the sensor lines for the encoder, in
-order to catch pulses when they occurred. Other sensors have a
-similar interface dynamic too, such as trying to read a sound
-sensor that is trying to catch a click, or an infrared slot sensor
-(photo-interrupter) trying to catch a coin drop. In all of these
-situations, using an interrupt can free the microcontroller to get
-some other work done while not missing the doorbell.
+There are a few limits you should be aware of if you're using more
+than one interrupt at a time; the :ref:`External Interrupts
+<external-interrupts-exti-line>` page has more information.
Example
-------
-::
+ ::
- int maple_led_pin = 13;
volatile int state = LOW; // must declare volatile, since it's
- // modified within the blink handler
+ // modified within the blink() handler
void setup() {
- pinMode(maple_led_pin, OUTPUT);
+ pinMode(BOARD_LED_PIN, OUTPUT);
attachInterrupt(0, blink, CHANGE);
}
void loop() {
- digitalWrite(maple_led_pin, state);
+ digitalWrite(BOARD_LED_PIN, state);
}
void blink() {
@@ -106,10 +85,10 @@ additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5
number goes with which pin -- just tell ``attachInterrupt()`` the pin
you want.
-See also
+See Also
--------
-- :ref:`detachInterrupt <lang-detachinterrupt>`
-- :ref:`external-interrupts`
+- :ref:`lang-detachinterrupt`
+- :ref:`external-interrupts`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bit.rst b/docs/source/lang/api/bit.rst
index dd5c050..3df042c 100644
--- a/docs/source/lang/api/bit.rst
+++ b/docs/source/lang/api/bit.rst
@@ -12,33 +12,27 @@ Syntax
``bit(n)``
-
Parameters
----------
* **n** the bit to set.
-
Value
-----
The value of an integer with the given bit set.
-
Arduino Compatibility
---------------------
-The Maple implementation of bit is compatible with Arduino.
+The Maple implementation of ``bit()`` is compatible with Arduino.
-
-See also
+See Also
--------
-
- :ref:`lang-bitread`
- :ref:`lang-bitwrite`
- :ref:`lang-bitset`
- :ref:`lang-bitclear`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bitclear.rst b/docs/source/lang/api/bitclear.rst
index 941f912..f487059 100644
--- a/docs/source/lang/api/bitclear.rst
+++ b/docs/source/lang/api/bitclear.rst
@@ -10,7 +10,6 @@ Syntax
``bitClear(x, n)``
-
Parameters
----------
@@ -19,20 +18,17 @@ Parameters
* **n** which bit to clear, starting at 0 for the least-significant
(rightmost) bit
-
Returns
-------
-None.
-
+Nothing.
Arduino Compatibility
---------------------
-This implementation is compatible with that of Arduino.
+The Maple implementation of ``bitClear()`` is compatible with Arduino.
-
-See also
+See Also
--------
- :ref:`bit <lang-bit>`\ ()
@@ -40,5 +36,4 @@ See also
- :ref:`bitWrite <lang-bitwrite>`\ ()
- :ref:`bitSet <lang-bitset>`\ ()
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bitread.rst b/docs/source/lang/api/bitread.rst
index 46b4478..fd9fbbe 100644
--- a/docs/source/lang/api/bitread.rst
+++ b/docs/source/lang/api/bitread.rst
@@ -5,13 +5,11 @@ bitRead()
(Macro) Gets the value of a bit in a number.
-
Syntax
------
``bitRead(x, n)``
-
Parameters
----------
@@ -20,27 +18,22 @@ Parameters
* **n** which bit to read, starting at 0 for the least-significant
(rightmost) bit
-
Value
-----
The value of the bit (0 or 1).
-
Arduino Compatibility
---------------------
The Maple implementation of ``bitRead`` is compatible with Arduino.
-
-See also
+See Also
--------
-
- :ref:`lang-bit`
- :ref:`lang-bitwrite`
- :ref:`lang-bitset`
- :ref:`lang-bitclear`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bitset.rst b/docs/source/lang/api/bitset.rst
index ccd76de..83ab5f8 100644
--- a/docs/source/lang/api/bitset.rst
+++ b/docs/source/lang/api/bitset.rst
@@ -5,13 +5,11 @@ bitSet()
(Macro) Sets (writes a 1 to) a bit of a numeric variable.
-
Syntax
------
``bitSet(x, n)``
-
Parameters
----------
@@ -20,19 +18,16 @@ Parameters
* **n** which bit to set, starting at 0 for the least-significant
(rightmost) bit
-
Value
-----
None.
-
Arduino Compatibility
---------------------
The Maple implementation of bitSet is compatible with Arduino.
-
See Also
--------
@@ -41,6 +36,4 @@ See Also
- :ref:`lang-bitwrite`
- :ref:`lang-bitclear`
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bitwrite.rst b/docs/source/lang/api/bitwrite.rst
index b3feff2..6106545 100644
--- a/docs/source/lang/api/bitwrite.rst
+++ b/docs/source/lang/api/bitwrite.rst
@@ -32,9 +32,9 @@ Nothing.
Arduino Compatibility
---------------------
-Maple's version of ``bitWrite()`` is compatible with Arduino.
+Maple's implementation of ``bitWrite()`` is compatible with Arduino.
-See also
+See Also
--------
- :ref:`bit() <lang-bit>`
@@ -42,5 +42,4 @@ See also
- :ref:`bitSet() <lang-bitSet>`
- :ref:`bitClear() <lang-bitClear>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/board-values.rst b/docs/source/lang/api/board-values.rst
new file mode 100644
index 0000000..05e3837
--- /dev/null
+++ b/docs/source/lang/api/board-values.rst
@@ -0,0 +1,180 @@
+.. _lang-board-values:
+
+Board-Specific Constants
+========================
+
+There are a number of board-specific values: constants or variables
+which are different depending on which LeafLabs board you have.
+
+This page lists and documents the board-specific values. You should
+use these when appropriate in your own programs. This will help make
+it easier to share your code with other people who have different
+boards. Some example usages are given :ref:`below
+<lang-board-values-examples>`.
+
+The actual values for each board are given in the :ref:`Board Hardware
+Documentation <index-boards>`.
+
+.. contents:: Contents
+ :local:
+
+Constants
+---------
+
+- ``CLOCK_SPEED_MHZ``: Clock speed of your board, in megahertz
+ (MHz). This is the same as ``CYCLES_PER_MICROSECOND``.
+
+- ``CLOCK_SPEED_HZ``: Clock speed of your board, in hertz (Hz). This
+ is the same as ``CLOCK_SPEED_MHZ * 1000000``.
+
+- ``CYCLES_PER_MICROSECOND``: Number of CPU cycles per microsecond on
+ your board.
+
+.. _lang-board-values-but:
+
+- ``BOARD_BUTTON_PIN``: Pin connected to the built-in button (labeled
+ "BUT" on your board's silkscreen).
+
+.. _lang-board-values-led:
+
+- ``BOARD_LED_PIN``: Pin connected to the built-in LED.
+
+- ``BOARD_NR_GPIO_PINS``: Total number of :ref:`GPIO pins <gpio>` that
+ are broken out to headers. Some of these might already be connected
+ to external hardware (like the built-in LED and button). To find
+ out if a pin is in use, see :ref:`boardUsesPin()
+ <lang-boardusespin>` (and also :ref:`boardUsedPins
+ <lang-board-values-used-pins>`).
+
+.. _lang-board-values-nr-pwm-pins:
+
+- ``BOARD_NR_PWM_PINS``: Total *number* of GPIO pins that can be used
+ for :ref:`PWM <pwm>`. The actual *pins* that can do PWM are in the
+ :ref:`boardPWMPins <lang-board-values-pwm-pins>` array.
+
+.. _lang-board-values-nr-adc-pins:
+
+- ``BOARD_NR_ADC_PINS``: Total number of GPIO pins that can be used
+ for :ref:`analog-to-digital conversion <adc>`. The actual pins that
+ can do ADC conversion are in the :ref:`boardADCPins
+ <lang-board-values-adc-pins>` array.
+
+.. _lang-board-values-nr-used-pins:
+
+- ``BOARD_NR_USED_PINS``: Total number of GPIO pins that are already
+ connected to some external hardware (like a built-in LED) on the
+ board. The actual pins that that are already used are in the
+ :ref:`boardUsedPins <lang-board-values-used-pins>` array. To see if
+ a pin is already in use, use the :ref:`boardUsesPin()
+ <lang-boardusespin>` function.
+
+.. _lang-board-values-usart:
+
+- USART (serial port) related constants:
+
+ * ``BOARD_USART1_TX_PIN``, ``BOARD_USART2_TX_PIN``, ``BOARD_USART3_TX_PIN``:
+ TX pins for the 3 USARTS.
+
+ * ``BOARD_USART1_RX_PIN``, ``BOARD_USART2_RX_PIN``, ``BOARD_USART3_RX_PIN``:
+ RX pins for the 3 USARTS.
+
+ * ``BOARD_UART4_TX_PIN``, ``BOARD_UART5_TX_PIN``: TX pins for
+ UARTs 4 and 5 (high-density boards like Maple Native only).
+
+ * ``BOARD_UART4_RX_PIN``, ``BOARD_UART5_RX_PIN``: RX pins for
+ UARTs 4 and 5 (high-density boards like Maple Native only).
+
+ * ``BOARD_NR_USARTS``: Number of serial ports on the board. This
+ number includes UARTs 4 and 5 if they are available.
+
+.. _lang-board-values-debug:
+
+- Debug (JTAG, SW-Debug) related constants: ``BOARD_JTMS_SWDIO_PIN``,
+ ``BOARD_JTCK_SWCLK_PIN``, ``BOARD_JTDI_PIN``, ``BOARD_JTDO_PIN``,
+ and ``BOARD_NJTRST_PIN``.
+
+ These constants are the pin numbers for :ref:`GPIOs <gpio>` used by
+ the :ref:`jtag` and Serial-Wire Debug peripherals. Except for the
+ Maple Mini, these pins are usually reserved for special purposes by
+ default (i.e., they are in :ref:`boardUsedPins
+ <lang-board-values-used-pins>`). However, they can be used as
+ ordinary GPIOs if you call the :ref:`lang-disabledebugports`
+ function. (Be careful with this on the Maple, as writing to
+ ``BOARD_NJTRST_PIN`` may cause your board to reset!).
+
+.. _lang-board-values-pwm-pins:
+
+.. _lang-board-values-adc-pins:
+
+.. _lang-board-values-used-pins:
+
+Pin Arrays
+----------
+
+Some :ref:`arrays <lang-array>` of pin numbers are available which you
+can use to find out certain important information about a given pin.
+
+- ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM
+ <pwm>` output, using :ref:`pwmWrite() <lang-pwmwrite>`. The total
+ number of these pins is :ref:`BOARD_NR_PWM_PINS
+ <lang-board-values-nr-pwm-pins>`.
+
+- ``boardADCPins``: Pin numbers of each pin capable of :ref:`ADC
+ <adc>` conversion, using :ref:`analogRead() <lang-analogread>`. The
+ total number of these pins is :ref:`BOARD_NR_ADC_PINS
+ <lang-board-values-nr-adc-pins>`.
+
+- ``boardUsedPins``: Pin numbers of each pin that, by default, is used
+ for some special purpose by the board. The total number of these
+ pins is :ref:`BOARD_NR_USED_PINS <lang-board-values-nr-used-pins>`.
+ To check if a pin is used for a special purpose, use
+ :ref:`boardUsesPin() <lang-boardusespin>`.
+
+.. _lang-board-values-examples:
+
+Examples
+--------
+
+:ref:`BOARD_LED_PIN <lang-board-values-led>` On the Maple, the
+built-in LED is connected to pin 13. On the Maple Mini, however, it
+is connected to pin 33. You can write a "blinky" program that works
+on all LeafLabs boards using ``BOARD_LED_PIN`` and :ref:`toggleLED()
+<lang-toggleled>`::
+
+ void setup() {
+ pinMode(BOARD_LED_PIN, OUTPUT);
+ }
+
+ void loop() {
+ toggleLED();
+ delay(100);
+ }
+
+:ref:`BOARD_BUTTON_PIN <lang-board-values-but>`: Similarly, you can
+write a single program that prints a message whenever the button is
+pressed which will work on all LeafLabs boards using
+``BOARD_BUTTON_PIN`` and :ref:`isButtonPressed()
+<lang-isbuttonpressed>`::
+
+ void setup() {
+ pinMode(BOARD_BUTTON_PIN, INPUT);
+ }
+
+ void loop() {
+ if (isButtonPressed()) {
+ SerialUSB.println("You pressed the button!");
+ }
+ }
+
+See Also
+--------
+
+- :ref:`lang-boardusespin`
+- :ref:`lang-isbuttonpressed`
+- :ref:`lang-waitforbuttonpress`
+- :ref:`lang-pinmode`
+- :ref:`lang-toggleled`
+- :ref:`lang-analogread`
+- :ref:`lang-pwmwrite`
+- :ref:`lang-enabledebugports`
+- :ref:`lang-disabledebugports`
diff --git a/docs/source/lang/api/boardusespin.rst b/docs/source/lang/api/boardusespin.rst
new file mode 100644
index 0000000..126c4a0
--- /dev/null
+++ b/docs/source/lang/api/boardusespin.rst
@@ -0,0 +1,27 @@
+.. highlight:: cpp
+
+.. _lang-boardusespin:
+
+boardUsesPin()
+==============
+
+Each LeafLabs board connects some pins to external hardware. The most
+important examples of this are the pins connected to the built-in LED
+and button. You can check if a board uses a particular pin using this
+function.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: boardUsesPin
+
+See Also
+--------
+
+- :ref:`Board-specific values <lang-board-values>`
+- :ref:`boardUsedPins <lang-board-values-used-pins>`
+- :ref:`BOARD_LED_PIN <lang-board-values-led>`
+- :ref:`toggleLED() <lang-toggleled>`
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
+- :ref:`isButtonPressed() <lang-isbuttonpressed>`
+- :ref:`waitForButtonPress() <lang-waitforbuttonpress>`
diff --git a/docs/source/lang/api/cc-attribution.txt b/docs/source/lang/api/cc-attribution.txt
deleted file mode 100644
index e100140..0000000
--- a/docs/source/lang/api/cc-attribution.txt
+++ /dev/null
@@ -1,9 +0,0 @@
-.. Included in all this directory's files in order to satisfy the
-.. Arduino CC Attribution-ShareAlike 3.0 License
-
-.. admonition:: License and Attribution
-
- This documentation page was adapted from the `Arduino Reference
- Documentation <http://arduino.cc/en/Reference/HomePage>`_\ , which
- is released under a `Creative Commons Attribution-ShareAlike 3.0
- License <http://creativecommons.org/licenses/by-sa/3.0/>`_.
diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst
index 72738b8..00c1a5c 100644
--- a/docs/source/lang/api/constants.rst
+++ b/docs/source/lang/api/constants.rst
@@ -61,14 +61,6 @@ pin is configured as an ``INPUT`` (using :ref:`pinMode()
<lang-digitalread>`, the microcontroller will report ``HIGH`` if a
voltage of 3 volts or more is present at the pin.
-.. TODO? Following seems false; check it out sometime, leave out for now:
-
-.. A pin may also be configured as an ``INPUT`` with ``pinMode()``, and
-.. subsequently made ``HIGH`` with :ref:`digitalWrite()
-.. <lang-digitalwrite>`, this will set the internal pullup resistors,
-.. which will *steer* the input pin to a HIGH reading unless it is pulled
-.. LOW by external circuitry.
-
When a pin is configured to ``OUTPUT`` with pinMode, and set to
``HIGH`` with :ref:`digitalWrite() <lang-digitalwrite>`, the pin is at
3.3 volts. In this state it can *source* current, e.g. light an LED
@@ -301,23 +293,16 @@ exponent indicators. Some examples are given in the following table:
Board-Specific Constants
------------------------
-This section documents constants whose value might change across
-different LeafLabs boards. You can use these constants to help ensure
-that your code will be portable across different boards.
-
-.. TODO replace "upcoming" when Mini, Native come out
-
-.. _lang-constants-led:
-
-- ``BOARD_LED_PIN``: the number of the pin which connects to the
- built-in LED. On the Maple, this is pin 13, but it's not guaranteed
- to be the same in upcoming boards like the Maple Mini.
-
-.. _lang-constants-but:
+There are several :ref:`board-specific constants <lang-board-values>`
+whose value depends on which LeafLabs board you have. If you use
+them, it will help make sure that your code will work well on all
+LeafLabs boards, not just the one you have. This will make it much
+easier to share your code with others.
-- ``BOARD_BUTTON_PIN``: the number of the pin which connects to the
- built-in button (labeled "BUT"). On the Maple, this is pin 38, but
- it's not guaranteed to be the same in other boards.
+For example, the pin number connected to the board's built-in LED is
+different on the different boards, but the board-specific constant
+:ref:`BOARD_LED_PIN <lang-board-values-led>` will always be the
+correct value for each board.
See Also
--------
@@ -333,5 +318,6 @@ See Also
- :ref:`unsigned long long <lang-unsignedlonglong>`
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`
+- :ref:`Board-Specific Values <lang-board-values>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/constrain.rst b/docs/source/lang/api/constrain.rst
index d19b61c..28af1e3 100644
--- a/docs/source/lang/api/constrain.rst
+++ b/docs/source/lang/api/constrain.rst
@@ -59,11 +59,10 @@ Arduino Compatibility
Maple's implementation of ``constrain()`` is compatible with Arduino.
-See also
+See Also
--------
- :ref:`min() <lang-min>`
- :ref:`max() <lang-max>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/cos.rst b/docs/source/lang/api/cos.rst
index 3fbb0af..c340f09 100644
--- a/docs/source/lang/api/cos.rst
+++ b/docs/source/lang/api/cos.rst
@@ -19,14 +19,12 @@ Note that the Maple implementation comes from `newlib
<http://sourceware.org/newlib/>`_\ , while Arduino's is that of
`avr-libc <http://avr-libc.nongnu.org/>`_\ .
-See also
+See Also
--------
-
- :ref:`sin() <lang-sin>`
- :ref:`tan() <lang-tan>`
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/delay.rst b/docs/source/lang/api/delay.rst
index 90ca268..9ef06a0 100644
--- a/docs/source/lang/api/delay.rst
+++ b/docs/source/lang/api/delay.rst
@@ -57,10 +57,9 @@ Example
.. _lang-delay-seealso:
-See also
+See Also
--------
-
- :ref:`millis() <lang-millis>`
- :ref:`micros() <lang-micros>`
- :ref:`delayMicroseconds() <lang-delayMicroseconds>`
@@ -68,5 +67,4 @@ See also
<http://arduino.cc/en/Tutorial/BlinkWithoutDelay>`_ example (works
unmodified on Maple)
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/delaymicroseconds.rst b/docs/source/lang/api/delaymicroseconds.rst
index 24a8286..7078660 100644
--- a/docs/source/lang/api/delaymicroseconds.rst
+++ b/docs/source/lang/api/delaymicroseconds.rst
@@ -48,9 +48,9 @@ Arduino Compatibility
---------------------
While we have made every effort we could to ensure that the timing of
-delayMicroseconds is as accurate as possible, we cannot guarantee it
-will behave as the Arduino implementation down to the microsecond,
-especially for smaller values of ``us``.
+``delayMicroseconds()`` is as accurate as possible, we cannot
+guarantee it will behave as the Arduino implementation down to the
+microsecond, especially for smaller values of ``us``.
See Also
--------
@@ -59,7 +59,4 @@ See Also
- :ref:`micros <lang-micros>`
- :ref:`delay <lang-delay>`
-
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/detachinterrupt.rst b/docs/source/lang/api/detachinterrupt.rst
index 41642a7..82ce974 100644
--- a/docs/source/lang/api/detachinterrupt.rst
+++ b/docs/source/lang/api/detachinterrupt.rst
@@ -9,9 +9,8 @@ Used to disable an interrupt specified with
Library Documentation
---------------------
-.. FIXME once breathe knows how to get the correct detachInterupt
-.. (right now it's copying from HardwareTimer), replace with a
-.. doxygenfunction directive
+.. FIXME [Breathe] once we can get the correct detachInterupt(),
+.. replace with doxygenfunction.
.. cpp:function:: void detachInterrupt(uint8 pin)
@@ -39,5 +38,6 @@ See Also
--------
- :ref:`attachInterrupt() <lang-attachInterrupt>`
+- :ref:`external-interrupts`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/digitalread.rst b/docs/source/lang/api/digitalread.rst
index 3502587..ccf4a4c 100644
--- a/docs/source/lang/api/digitalread.rst
+++ b/docs/source/lang/api/digitalread.rst
@@ -8,51 +8,44 @@ digitalRead()
Reads the value from a specified digital pin, either :ref:`HIGH
<lang-constants-high>` or :ref:`LOW <lang-constants-low>`.
-
Library Documentation
---------------------
.. doxygenfunction:: digitalRead
+Discussion
+----------
+
+If the pin isn't connected to anything, ``digitalRead()`` can return
+either HIGH or LOW (and this will change in a way that seems random).
Example
-------
-The following example turns the LED on when the button is pressed::
-
- int ledPin = 13; // LED connected to Maple pin 13
- int buttonPin = 38; // BUT connected to Maple pin 38
+The following example turns the LED on or off when the button is pressed::
void setup() {
- pinMode(ledPin, OUTPUT);
- pinMode(buttonPin, INPUT);
+ pinMode(BOARD_LED_PIN, OUTPUT);
+ pinMode(BOARD_BUTTON_PIN, INPUT);
}
void loop() {
- int val = digitalRead(buttonPin); // reads the input pin
- digitalWrite(ledPin, val);
+ int val = digitalRead(BOARD_BUTTON_PIN); // reads the input pin
+ togglePin(BOARD_LED_PIN, val);
}
-Note
-----
-
-If the pin isn't connected to anything, ``digitalRead()`` can return
-either HIGH or LOW (and this can change in a way that seems random).
-
Arduino Compatibility
---------------------
The Maple version of ``digitalRead()`` is compatible with Arduino.
-
See Also
--------
-- :ref:`pinMode <lang-pinMode>`
-- :ref:`digitalWrite <lang-digitalWrite>`
-
-
-
-
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
+- :ref:`lang-isButtonPressed`
+- :ref:`lang-pinmode`
+- :ref:`lang-digitalWrite`
+- :ref:`lang-togglepin`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/digitalwrite.rst b/docs/source/lang/api/digitalwrite.rst
index 6124d5f..376cbc3 100644
--- a/docs/source/lang/api/digitalwrite.rst
+++ b/docs/source/lang/api/digitalwrite.rst
@@ -21,42 +21,26 @@ If the pin has been configured as an ``OUTPUT`` with :ref:`pinMode()
<lang-pinmode>` its voltage will be set to the corresponding value:
3.3V for ``HIGH``, and 0V (ground) for ``LOW``.
-.. TODO make the following paragraphs true, but refer the reader to
-.. INPUT_PULLUP and INPUT_PULLDOWN:
-
-If the pin is configured as an ``INPUT``, writing a ``HIGH`` value
-with ``digitalWrite()`` will enable an internal pullup resistor.
-Writing ``LOW`` will disable the pullup. The pullup resistor is enough
-to light an LED dimly, so if LEDs appear to work, but very dimly, this
-is a likely cause. The remedy is to set the pin to an output with the
-:ref:`pinMode() <lang-pinmode>` function.
-
-.. note:: Pin 13 is harder to use as an input than the other pins
- because it has an LED and resistor soldered to it in series. If you
- enable its internal pull-up resistor, it will likely hang at around
- 1.1V instead of the expected 3.3V because the onboard LED and
- series resistor pull the voltage level down. If you must use pin 13
- as a digital input, use an external pull-down resistor.
+Because it is soldered to an LED and resistor in series, your board's
+:ref:`BOARD_LED_PIN <lang-board-values-led>` will respond slightly
+more slowly as an output than the other pins.
Example
-------
The following example sets pin 13 to ``HIGH``, makes a one-second-long
delay, sets the pin back to ``LOW``, and delays again, causing a
-blinking pattern::
-
-
- int ledPin = 13; // LED connected to digital pin 13
+blinking pattern (you could also use :ref:`lang-toggleled`)::
void setup() {
- pinMode(ledPin, OUTPUT); // sets the digital pin as output
+ pinMode(BOARD_LED_PIN, OUTPUT); // sets the digital pin as output
}
void loop() {
- digitalWrite(ledPin, HIGH); // sets the LED on
- delay(1000); // waits for a second
- digitalWrite(ledPin, LOW); // sets the LED off
- delay(1000); // waits for a second
+ digitalWrite(BOARD_LED_PIN, HIGH); // sets the LED on
+ delay(1000); // waits for a second
+ digitalWrite(BOARD_LED_PIN, LOW); // sets the LED off
+ delay(1000); // waits for a second
}
See Also
@@ -64,5 +48,8 @@ See Also
- :ref:`pinMode <lang-pinmode>`
- :ref:`digitalRead <lang-digitalread>`
+- :ref:`BOARD_LED_PIN <lang-board-values-led>`
+- :ref:`lang-toggleled`
+- :ref:`lang-togglepin`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/disabledebugports.rst b/docs/source/lang/api/disabledebugports.rst
new file mode 100644
index 0000000..43ac337
--- /dev/null
+++ b/docs/source/lang/api/disabledebugports.rst
@@ -0,0 +1,31 @@
+.. highlight:: cpp
+
+.. _lang-disabledebugports:
+
+disableDebugPorts()
+===================
+
+Used to disable the JTAG and Serial Wire debugging ports.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: disableDebugPorts
+
+Example
+-------
+
+ ::
+
+ void setup() {
+ disableDebugPorts();
+ }
+
+ void loop() {
+ // Now you can use the debug port pins as ordinary pins
+ }
+
+See Also
+--------
+
+* :ref:`lang-enabledebugports`
diff --git a/docs/source/lang/api/enabledebugports.rst b/docs/source/lang/api/enabledebugports.rst
new file mode 100644
index 0000000..bee2b0a
--- /dev/null
+++ b/docs/source/lang/api/enabledebugports.rst
@@ -0,0 +1,31 @@
+.. highlight:: cpp
+
+.. _lang-enabledebugports:
+
+enableDebugPorts()
+==================
+
+Used to enable the JTAG and Serial Wire debugging ports.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: enableDebugPorts
+
+Example
+-------
+
+ ::
+
+ void setup() {
+ enableDebugPorts();
+ // Now you can debug using JTAG and SW-Debug
+ }
+
+ void loop() {
+ }
+
+See Also
+--------
+
+* :ref:`lang-disabledebugports`
diff --git a/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst
index 53a225d..289ded5 100644
--- a/docs/source/lang/api/hardwarespi.rst
+++ b/docs/source/lang/api/hardwarespi.rst
@@ -5,160 +5,161 @@
HardwareSPI
===========
-This class is used for creating objects to manage the Maple's built-in
-SPI ports. The Maple has two SPI ports. The relevant pins
-corresponding to each port's logic signals are documented in the
-following table (and on the Maple silkscreen):
+This page describes how to use the built-in SPI ports. It does not
+describe the SPI protocol itself. For more information about SPI, see
+the :ref:`SPI reference <spi>`.
-.. _lang-hardwarespi-pinout:
+.. contents:: Contents
+ :local:
-.. list-table::
- :header-rows: 1
+Getting Started
+---------------
- * - Port number
- - NSS
- - MOSI
- - MISO
- - SCK
+.. TODO [0.1.0] Add a note about calling disableDebugPorts() when
+.. using SPI3 on Maple Native
- * - 1
- - 10
- - 11
- - 12
- - 13
+In order to get started, you'll first need to define a ``HardwareSPI``
+variable, which you'll use to control the SPI port. Do this by
+putting the line "``HardwareSPI spi(number);``" with your variables,
+where ``number`` is the SPI port's number.
- * - 2
- - 31
- - 32
- - 33
- - 34
+Here's an example (we'll fill in :ref:`setup() <lang-setup>` and
+:ref:`loop() <lang-loop>` later)::
-If you use a SPI port, you cannot simultaneously use its associated
-pins for other purposes.
+ // Use SPI port number 1
+ HardwareSPI spi(1);
-Library Documentation
----------------------
+ void setup() {
+ // Your setup code
+ }
+
+ void loop() {
+ // Do stuff with SPI
+ }
-Using the SPI Class
-^^^^^^^^^^^^^^^^^^^
+Turning the SPI Port On
+-----------------------
-You can declare that you want to use SPI in your sketch by putting
-``HardwareSPI Spi(number);`` with your variables, where ``number`` is
-1 or 2, depending on which SPI you want to use. Then you can use the
-functions described in the next section. For example::
+Now it's time to turn your SPI port on. Do this with the ``begin()``
+function (an example is given below).
- // Use SPI 1
- HardwareSpi Spi(1);
+.. FIXME [0.0.10] Breathe doesn't include the class; fix & submit pull req
+
+.. doxygenfunction:: HardwareSPI::begin
+
+The speed at which the SPI port communicates is configured using a
+``SPIFrequency`` value:
+
+.. FIXME [0.1.0] Breathe's enum output is enormous; shrink & submit pull req
+
+.. doxygenenum:: SPIFrequency
+
+.. note:: Due to hardware issues, you can't use the frequency
+ ``SPI_140_625KHz`` with SPI port 1.
+
+You'll need to determine the correct values for ``frequency``,
+``bitOrder``, and ``mode`` yourself, by consulting the datasheet for
+the device you're communicating with. Continuing our example from
+before, we'll add a call to ``begin()`` to our ``setup()``::
+
+ // Use SPI port number 1
+ HardwareSPI spi(1);
void setup() {
- Spi.begin(SPI_18MHZ);
+ // Turn on the SPI port
+ spi.begin(SPI_18MHZ, MSBFIRST, 0);
}
void loop() {
- // Get the next byte from the peripheral
- uint8 byte = Spi.recv();
+ // Do stuff with SPI
}
-HardwareSPI Class Reference
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you call ``begin()`` with no arguments (as in "``spi.begin();``"),
+it's the same as if you wrote "``spi.begin(SPI_1_125MHZ, MSBFIRST,
+0);``".
-.. cpp:class:: HardwareSPI
+Communicating Over SPI
+----------------------
- Class for interacting with SPI.
+Now that you've got your SPI port set up, it's time to start
+communicating. You can send data using ``HardwareSPI::write()``,
+receive data using ``HardwareSPI::read()``, and do both using
+``HardwareSPI::transfer()``.
-.. cpp:function:: HardwareSPI::HardwareSPI(uint32 spi_num)
+.. cpp:function:: void HardwareSPI::write(byte data)
- Construct an object for managing a SPI peripheral. ``spi_num``
- must be 1 or 2; see the :ref:`table above
- <lang-hardwarespi-pinout>` for pinout information.
+ Send a single byte of data.
-.. cpp:function:: void HardwareSPI::begin(SPIFrequency freq, uint32 endianness, uint32 mode)
+ **Parameters**:
- Configure the baudrate of the given SPI port and set up the header
- pins appropriately.
+ - ``data``: Byte to send
- Parameters:
+.. cpp:function:: byte HardwareSPI::read()
- - ``freq``: one of the ``SPIFrequency`` values, given :ref:`below
- <lang-hardwarespi-spifrequency>`.
+ Get the next available, unread byte. If there aren't any unread
+ bytes, this function will wait until one is received.
- - ``endianness``: either ``LSBFIRST`` (little-endian) or
- ``MSBFIRST`` (big-endian).
+.. cpp:function:: byte HardwareSPI::transmit(byte data)
- - ``mode``: one of 0, 1, 2, or 3, and specifies which SPI mode is
- used. The mode number determines a combination of polarity and
- phase according to the following table:
+ Send a byte, then return the next byte received.
- .. list-table::
- :header-rows: 1
+ **Parameters:**
- * - Mode
- - Polarity
- - Phase
+ - ``data``: Byte to send
- * - 0
- - 0
- - 0
+ **Returns:** Next unread byte
- * - 1
- - 0
- - 1
+Continuing our example from before, let's send a number over SPI and
+print out whatever we get back over :ref:`lang-serialusb`::
- * - 2
- - 1
- - 0
+ // Use SPI port number 1
+ HardwareSPI spi(1);
- * - 3
- - 1
- - 1
+ void setup() {
+ // Turn on the SPI port
+ spi.begin(SPI_18MHZ, MSBFIRST, 0);
+ }
- For more information on polarity and phase, see the
- :ref:`external references, below <lang-hardwarespi-seealso>`.
+ void loop() {
+ // Send 245 over SPI, and wait for a response.
+ spi.write(245);
+ byte response = spi.read();
+ // Print out the response received.
+ SerialUSB.print("response: ");
+ SerialUSB.println(response, DEC);
+ }
+
+HardwareSPI Class Reference
+---------------------------
+
+There are a number of other things you can accomplish with your
+``spi`` object. A full function listing follows.
-.. cpp:function:: void HardwareSPI::begin()
+.. doxygenclass:: HardwareSPI
+ :members: HardwareSPI, begin, beginSlave, end, read, write, transfer
- A convenience ``begin()``, equivalent to ``begin(SPI_1_125MHZ,
- MSBFIRST, 0)``.
+Deprecated Functions
+--------------------
-.. cpp:function:: uint8 HardwareSpi::send(uint8 *data, uint32 length)
+The following functions are defined for now, but they have been
+deprecated, and will be removed in a future Maple IDE release. You
+shouldn't use them in new programs, and you should change any of your
+programs which do use them to the up-to-date functions discussed
+above.
+
+.. cpp:function:: uint8 HardwareSPI::send(uint8 *data, uint32 length)
Writes ``data`` into the port buffer to be transmitted as soon as
possible, where ``length`` is the number of bytes to send from
``data``. Returns the last byte shifted back from slave.
-.. cpp:function:: uint8 HardwareSpi::send(uint8 data)
+.. cpp:function:: uint8 HardwareSPI::send(uint8 data)
Writes the single byte ``data`` into the port buffer to be
transmitted as soon as possible. Returns the data byte shifted
back from the slave.
-.. cpp:function:: uint8 HardwareSpi::recv()
+.. cpp:function:: uint8 HardwareSPI::recv()
Reads a byte from the peripheral. Returns the next byte in the
buffer.
-
-SPI Speeds
-^^^^^^^^^^
-
-.. _lang-hardwarespi-spifrequency:
-
-The possible SPI speeds are configured using the ``SPIFrequency`` enum:
-
-.. doxygenenum:: SPIFrequency
-
-.. _lang-hardwarespi-seealso:
-
-See Also
---------
-
-* `Wikipedia Article on Serial Peripheral Interface Bus (SPI)
- <http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus>`_
-* `Arduino reference on SPI
- <http://www.arduino.cc/playground/Code/Spi>`_
-* `Hardcore SPI on Arduino <http://klk64.com/arduino-spi/>`_ by kik64
-* STMicro documentation for STM32F103RB microcontroller:
-
- * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf)
- * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf)
-
-
diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst
index c7a630d..09245f0 100644
--- a/docs/source/lang/api/hardwaretimer.rst
+++ b/docs/source/lang/api/hardwaretimer.rst
@@ -5,369 +5,341 @@
HardwareTimer
=============
-This class defines the public API for interfacing with the STM32's
-built-in timer peripherals. More information on these peripherals
-(including code examples) is available in the :ref:`timers reference
-<timers>`.
+This page describes how to control the built-in timers. It does not
+describe how the timers work on your board. For more information on
+that, the :ref:`timers reference <timers>`.
-Library Documentation
----------------------
+.. warning:: The timer interface is still taking shape, and is
+ expected to change significantly between releases. Because of
+ that, the functionality described in this page shouldn't be
+ considered stable.
-HardwareTimer Class Reference
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ If you want a timer API that will be consistent between releases of
+ the Maple IDE, your best bet for now is to use the low-level
+ support in :ref:`libmaple-timer`.
-To interact with a particular timer, call one of the methods
-documented below on one of the predefined ``HardwareTimer`` instances.
-For example, to set the prescale factor on timer 1 to 5, call
-``Timer1.setPrescaleFactor(5)``.
+.. contents:: Contents
+ :local:
-.. TODO add code examples that people can copy and paste in case
-.. they're unfamiliar with namespace syntax
+.. _lang-hardwaretimer-getting-started:
-.. cpp:class:: HardwareTimer
+Getting Started
+---------------
- Class for interacting with a timer. There are four predefined
- instances available on the Maple: ``Timer1``, ``Timer2``,
- ``Timer3``, and ``Timer4``.
+You'll first need to define a ``HardwareTimer`` variable, which you'll
+use to control the timer. Do this by putting the line
+"``HardwareTimer timer(number);``" with your variables, where
+``number`` is the timer's number.
-.. _lang-hardwaretimer-attachinterrupt:
+Here's an example (we'll fill in :ref:`setup() <lang-setup>` and
+:ref:`loop() <lang-loop>` later)::
-.. cpp:function:: void HardwareTimer::attachInterrupt(int channel, voidFuncPtr handler)
+ // Use timer 1
+ HardwareTimer timer(1);
- Attach an interrupt handler to the given ``channel``. This
- interrupt handler will be called when the timer's counter reaches
- the given channel :ref:`compare <lang-hardwaretimer-setcompare>`
- value.
+ void setup() {
+ // Your setup code
+ }
- ``handler`` should be a function which takes no arguments and has
- :ref:`void <lang-void>` value; i.e. it should have signature ::
+ void loop() {
+ // ...
+ }
- void handler(void);
+Configuring the Prescaler and Overflow
+--------------------------------------
- You can later detach the interrupt using :ref:`detachInterrupt()
- <lang-hardwaretimer-detachinterrupt>`.
+After defining your ``timer`` variable, you'll probably want to
+configure how fast your timer's counter changes (using the prescaler)
+and when it gets reset to zero (using the overflow value). You can do
+that with the ``setPrescaleFactor()`` and ``setOverflow()`` functions.
- .. note:: The function (often called an *interrupt service
- routine*, or ISR) should attempt to return as quickly as
- possible. :ref:`Blinking the LED <lang-toggleled>`, some
- logic, :ref:`PWM <pwm>` updates, and :ref:`Serial
- <lang-serial>` writes are fine; writing to
- :ref:`SerialUSB <lang-serialusb>` or :ref:`waiting
- <lang-waitforbuttonpress>` for user input can take a long
- time and prevent other interrupts from firing on time.
-
- Tip: if you have a :ref:`delay() <lang-delay>` in your
- ISR, you're probably doing it wrong.
-
-.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler)
-
- Equivalent to :ref:`attachInterrupt
- <lang-hardwaretimer-attachinterrupt>`\ ``(1, handler)``.
-
-.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler)
-
- Equivalent to :ref:`attachInterrupt
- <lang-hardwaretimer-attachinterrupt>`\ ``(2, handler)``.
-
-.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler)
+.. _lang-hardwaretimer-setprescalefactor:
- Equivalent to :ref:`attachInterrupt
- <lang-hardwaretimer-attachinterrupt>`\ ``(3, handler)``.
+.. doxygenfunction:: HardwareTimer::setPrescaleFactor
+ :no-link:
-.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler)
+.. _lang-hardwaretimer-setoverflow:
- Equivalent to :ref:`attachInterrupt
- <lang-hardwaretimer-attachinterrupt>`\ ``(4, handler)``.
+.. doxygenfunction:: HardwareTimer::setOverflow
+ :no-link:
-.. _lang-hardwaretimer-setchannelmode:
+For example::
-.. cpp:function:: void HardwareTimer::setChannelMode(int channel, TimerMode mode)
+ // Use timer 1
+ HardwareTimer timer(1);
- Set the given channel of this timer to the given :ref:`mode
- <lang-hardwaretimer-modes>`. The parameter ``channel`` is one of
- 1, 2, 3, and 4, and corresponds to the compare channel you would
- like to set. Refer to the full :ref:`pin mapping table
- <pin-mapping-mega-table>` to match up timer channels and pin
- numbers.
+ void setup() {
+ timer.setPrescaleFactor(5);
+ timer.setOverflow(255);
+ }
-.. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode)
+ void loop() {
+ // ...
+ }
- Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\
- ``(1, mode)``.
+You may also find the ``setPeriod()`` function useful:
-.. cpp:function:: void HardwareTimer::setChannel2Mode(TimerMode mode)
+.. _lang-hardwaretimer-setperiod:
- Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\
- ``(2, mode)``.
+.. doxygenfunction:: HardwareTimer::setPeriod
+ :no-link:
-.. cpp:function:: void HardwareTimer::setChannel3Mode(TimerMode mode)
+For example::
- Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\
- ``(3, mode)``.
+ // Use timer 1
+ HardwareTimer timer(1);
-.. cpp:function:: void HardwareTimer::setChannel4Mode(TimerMode mode)
+ void setup() {
+ // Have the timer repeat every 20 milliseconds
+ int microseconds_per_millisecond = 1000;
+ timer.setPeriod(20 * microseconds_per_millisecond);
+ }
- Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\
- ``(4, mode)``.
+ void loop() {
+ // ...
+ }
+
+.. _lang-hardwaretimer-interrupts:
+
+Using Timer Interrupts
+----------------------
+
+.. TODO [0.2.0] Improve the interrupts section, here or in timers.rst
+
+In order to use timer interrupts, we recommend the following sequence:
+
+* Pause the timer.
+* Configure the prescaler and overflow.
+* Pick a timer channel to handle the interrupt and set the channel's
+ :ref:`mode <lang-hardwaretimer-timermode>` to ``TIMER_OUTPUT_COMPARE``.
+* Set the channel compare value appropriately (this controls what counter value,
+ from 0 to overflow - 1). If you just want to make the interrupt fire once
+ every time the timer overflows, and you don't care what the timer count is,
+ the channel compare value can just be 1.
+* Attach an interrupt handler to the channel.
+* Refresh the timer.
+* Resume the timer.
+
+Here are two complete examples.
+
+**LED blink**: This example blinks the built-in LED without doing
+anything in ``loop()``. ::
+
+ #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles
+
+ // We'll use timer 2
+ HardwareTimer timer(2);
+
+ void setup() {
+ // Set up the LED to blink
+ pinMode(BOARD_LED_PIN, OUTPUT);
+
+ // Pause the timer while we're configuring it
+ timer.pause();
+
+ // Set up period
+ timer.setPeriod(LED_RATE); // in microseconds
+
+ // Set up an interrupt on channel 1
+ timer.setChannel1Mode(TIMER_OUTPUT_COMPARE);
+ timer.setCompare(TIMER_CH1, 1); // Interrupt 1 count after each update
+ timer.attachCompare1Interrupt(handler_led);
+
+ // Refresh the timer's count, prescale, and overflow
+ timer.refresh();
+
+ // Start the timer counting
+ timer.resume();
+ }
+
+ void loop() {
+ // Nothing! It's all in the handler_led() interrupt:
+ }
+
+ void handler_led(void) {
+ toggleLED();
+ }
+
+**Racing Counters**: This example shows how to use multiple timers at
+the same time. ::
+
+ int count3 = 0;
+ int count4 = 0;
+
+ // We'll use timers 3 and 4
+ HardwareTimer timer3(3);
+ HardwareTimer timer4(4);
+
+ void setup() {
+ // Set up the button for input
+ pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP);
+
+ // Set up timers to add 1 to their counts each time
+ // their interrupts fire.
+ timer3.setMode(TIMER_CH1, TIMER_OUTPUT_COMPARE);
+ timer4.setMode(TIMER_CH1, TIMER_OUTPUT_COMPARE);
+ timer3.pause();
+ timer4.pause();
+ timer3.setCount(0);
+ timer4.setCount(0);
+ timer3.setOverflow(30000);
+ timer4.setOverflow(30000);
+ timer3.setCompare(TIMER_CH1, 1000); // somewhere in the middle
+ timer4.setCompare(TIMER_CH1, 1000);
+ timer3.attachCompare1Interrupt(handler3);
+ timer4.attachCompare1Interrupt(handler4);
+ timer3.refresh();
+ timer4.refresh();
+ timer3.resume();
+ timer4.resume();
+ }
+
+ void loop() {
+ // Display the running counts
+ SerialUSB.print("Count 3: ");
+ SerialUSB.print(count3);
+ SerialUSB.print("\t\tCount 4: ");
+ SerialUSB.println(count4);
+
+ // While the button is held down, pause timer 4
+ for (int i = 0; i < 1000; i++) {
+ if (digitalRead(BOARD_BUTTON_PIN)) {
+ timer4.pause();
+ } else {
+ timer4.resume();
+ }
+ delay(1);
+ }
+ }
+
+ void handler3(void) {
+ count3++;
+ }
+
+ void handler4(void) {
+ count4++;
+ }
+
+``HardwareTimer`` Class Reference
+---------------------------------
+
+This section gives a full listing of the capabilities of a
+``HardwareTimer``.
+
+.. doxygenclass:: HardwareTimer
+ :members: HardwareTimer, pause, resume, getPrescaleFactor, setPrescaleFactor, getOverflow, setOverflow, getCount, setCount, setPeriod, setMode, getCompare, setCompare, attachInterrupt, detachInterrupt, refresh
+
+.. _lang-hardwaretimer-timermode:
+
+.. doxygenenum:: timer_mode
+
+Deprecated Functionality
+------------------------
+
+The following functionality exists for now, but it has been
+deprecated, and will be removed in a future Maple IDE release. You
+shouldn't use it in new programs, and you should change any of your
+programs which do use them to use the up-to-date features described
+above.
+
+The ``TimerMode`` type from previous releases has been renamed
+``timer_mode``. The mode ``TIMER_OUTPUTCOMPARE`` is still present,
+but will be removed in a future release. Use ``TIMER_OUTPUT_COMPARE``
+instead.
-.. _lang-hardwaretimer-getcompare:
+.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler)
-.. cpp:function:: uint16 HardwareTimer::getCompare(int channel)
+ Use ``attachInterrupt(1, handler)`` instead.
- Gets the compare value for the given ``channel``, from 1 to 4. See
- :ref:`setCompare() <lang-hardwaretimer-setcompare>`.
+.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler)
-.. cpp:function:: uint16 HardwareTimer::getCompare1()
+ Use ``attachInterrupt(2, handler)`` instead.
- Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\
- ``(1, mode)``.
+.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler)
-.. cpp:function:: uint16 HardwareTimer::getCompare2()
+ Use ``attachInterrupt(3, handler)`` instead.
- Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\
- ``(2, mode)``.
+.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler)
-.. cpp:function:: uint16 HardwareTimer::getCompare3()
+ Use ``attachInterrupt(4, handler)`` instead.
- Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\
- ``(3, mode)``.
+.. _lang-hardwaretimer-setchannelmode:
-.. cpp:function:: uint16 HardwareTimer::getCompare4()
+.. cpp:function:: void HardwareTimer::setChannelMode(int channel, timer_mode mode)
- Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\
- ``(4, mode)``.
+ Use ``setMode(channel, mode)`` instead.
-.. _lang-hardwaretimer-setcompare:
+.. cpp:function:: void HardwareTimer::setChannel1Mode(timer_mode mode)
-.. cpp:function:: void HardwareTimer::setCompare(int channel, uint16 compare)
+ Use ``setMode(1, mode)`` instead.
- Sets the compare value for the given ``channel`` to ``compare``.
- If ``compare`` is greater than this timer's overflow value, it will
- be truncated to the overflow value. The default compare value is
- 65,535 (the largest unsigned 16-bit integer value).
+.. cpp:function:: void HardwareTimer::setChannel2Mode(timer_mode mode)
- When the counter reaches this value the interrupt for this channel
- will fire if the given ``channel`` :ref:`mode
- <lang-hardwaretimer-setchannelmode>` is ``TIMER_OUTPUTCOMPARE`` and
- an interrupt is :ref:`attached
- <lang-hardwaretimer-attachinterrupt>`.
+ Use ``setMode(2, mode)`` instead.
- By default, this only changes the relative offsets between events
- on a single timer ("phase"); they don't control the frequency with
- which they occur. However, a common trick is to increment the
- compare value manually in the interrupt handler so that the event
- will fire again after the increment period. There can be a
- different increment value for each channel, so this trick allows
- events to be programmed at 4 different rates on a single
- timer. Note that function call overheads mean that the smallest
- increment rate is at least a few microseconds.
+.. cpp:function:: void HardwareTimer::setChannel3Mode(timer_mode mode)
-.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare)
+ Use ``setMode(3, mode)`` instead.
- Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\
- ``(1, compare)``.
+.. cpp:function:: void HardwareTimer::setChannel4Mode(timer_mode mode)
-.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare)
+ Use ``setMode(4, mode)`` instead.
- Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\
- ``(2, compare)``.
+.. cpp:function:: uint16 HardwareTimer::getCompare1()
-.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare)
+ Use ``getCompare(1, mode)`` instead.
- Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\
- ``(3, compare)``.
+.. cpp:function:: uint16 HardwareTimer::getCompare2()
-.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare)
+ Use ``getCompare(2, mode)`` instead.
- Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\
- ``(4, compare)``.
+.. cpp:function:: uint16 HardwareTimer::getCompare3()
-.. cpp:function:: uint16 HardwareTimer::getCount()
+ Use ``getCompare(3, mode)`` instead.
- Gets the current timer count. Due to function call overhead, the
- return value will be increasingly accurate with smaller prescale
- values. Also see :ref:`setCount() <lang-hardwaretimer-setcount>`.
+.. cpp:function:: uint16 HardwareTimer::getCompare4()
-.. _lang-hardwaretimer-setcount:
+ Use ``getCompare(4, mode)`` instead.
-.. cpp:function:: void HardwareTimer::setCount(uint16 val)
+.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare)
- Set the timer's current count to ``val``.
+ Use ``setCompare(1, compare)`` instead.
- Note that there is some function call overhead associated with
- calling this method, so using it is not a robust way to get
- multiple timers to share a count value.
+.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare)
- If ``val`` exceeds the timer's :ref:`overflow value
- <lang-hardwaretimer-getoverflow>`, it is truncated to the overflow
- value.
+ Use ``setCompare(2, compare)`` instead.
+.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare)
-.. _lang-hardwaretimer-detachinterrupt:
+ Use ``setCompare(3, compare)`` instead.
-.. cpp:function:: void HardwareTimer::detachInterrupt(int channel)
+.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare)
- Remove the interrupt handler attached to the given ``channel``, if
- any. The handler will no longer be called by this timer.
+ Use ``setCompare(4, compare)`` instead.
.. cpp:function:: void HardwareTimer::detachCompare1Interrupt()
- Equivalent to :ref:`detachInterrupt
- <lang-hardwaretimer-detachinterrupt>`\ ``(1)``.
+ Use ``detachInterrupt(1)`` instead.
.. cpp:function:: void HardwareTimer::detachCompare2Interrupt()
- Equivalent to :ref:`detachInterrupt
- <lang-hardwaretimer-detachinterrupt>`\ ``(2)``.
+ Use ``detachInterrupt(2)`` instead.
.. cpp:function:: void HardwareTimer::detachCompare3Interrupt()
- Equivalent to :ref:`detachInterrupt
- <lang-hardwaretimer-detachinterrupt>`\ ``(3)``.
+ Use ``detachInterrupt(3)`` instead.
.. cpp:function:: void HardwareTimer::detachCompare4Interrupt()
- Equivalent to :ref:`detachInterrupt
- <lang-hardwaretimer-detachinterrupt>`\ ``(4)``.
-
-.. _lang-hardwaretimer-generateupdate:
+ Use ``detachInterrupt(4)`` instead.
.. cpp:function:: void HardwareTimer::generateUpdate()
- Re-initializes the counter (to 0 in upcounting mode, which is the
- default), and generates an update of the prescale and overflow
- registers.
-
-.. _lang-hardwaretimer-getoverflow:
-
-.. cpp:function:: uint16 HardwareTimer::getOverflow()
-
- Gets the timer's overflow value. See :ref:`setOverflow()
- <lang-hardwaretimer-setoverflow>`.
-
-.. _lang-hardwaretimer-setoverflow:
-
-.. cpp:function:: void HardwareTimer::setOverflow(uint16 val)
-
- Sets the timer overflow (or "reload") value to ``val``.
-
- When the timer's counter reaches this, value it resets to
- zero. Its default value is 65535 (the largest unsigned 16-bit
- integer); setting the overflow to anything lower will cause
- interrupts to be called more frequently (see :ref:`setPeriod()
- <lang-hardwaretimer-setperiod>` function for a shortcut).
-
- After the next :ref:`timer update
- <lang-hardwaretimer-generateupdate>`, this number will be the
- maximum value for the timer's channel compare values.
-
-.. _lang-hardwaretimer-pause:
-
-.. cpp:function:: void HardwareTimer::pause()
-
- Stop the timer's counter, without affecting its configuration.
-
- The timer will no longer count or fire interrupts after this
- function is called, until it is resumed. This function is useful
- during timer setup periods, in order to prevent interrupts from
- firing before the timer is fully configured.
-
- Note that there is some function call overhead associated with this
- method, so using it in concert with :ref:`resume()
- <lang-hardwaretimer-resume>` is not a robust way to align multiple
- timers to the same count value.
-
-.. _lang-hardwaretimer-setperiod:
-
-.. cpp:function:: uint16 HardwareTimer::setPeriod(uint32 microseconds)
-
- Configure the :ref:`prescaler
- <lang-hardwaretimer-getprescalefactor>` and :ref:`overflow
- <lang-hardwaretimer-getoverflow>` values to generate a timer reload
- with a period as close to the given number of ``microseconds`` as
- possible.
-
- The return value is the new overflow value, which may be used to
- set channel compare values. However, if a clock that fires an
- interrupt every given number of microseconds is all that is
- desired, and the relative "phases" are unimportant, channel compare
- values may all be set to 1.
-
-.. _lang-hardwaretimer-getprescalefactor:
-
-.. cpp:function:: uint16 HardwareTimer::getPrescaleFactor()
-
- Returns the timer's prescale factor. See
- :ref:`setPrescaleFactor() <lang-hardwaretimer-setprescalefactor>`.
-
-.. _lang-hardwaretimer-setprescalefactor:
-
-.. cpp:function:: void HardwareTimer::setPrescaleFactor(uint16 factor)
-
- Set the timer's prescale factor to ``factor``.
-
- The prescaler acts as a clock divider to slow down the rate at
- which the counter increments.
-
- For example, the system clock rate is 72MHz, so the counter will
- reach 65535 in (13.89 nanoseconds) × (65535 counts) = (910.22
- microseconds), or about a thousand times a second. If the
- prescaler equals 1098, then the clock rate is effectively 72MHz /
- 1098 = 65.56KHz, and the counter will reach 65536 in (15.25
- microseconds) × (65536 counts) = (0.999 seconds), or about once
- per second.
-
- The :ref:`setPeriod() <lang-hardwaretimer-setperiod>` method may
- also be used as a convenient alternative.
-
-.. _lang-hardwaretimer-resume:
-
-.. cpp:function:: void HardwareTimer::resume()
-
- Resume a paused timer, without affecting its configuration.
-
- The timer will resume counting and firing interrupts as
- appropriate.
-
- Note that there is some function call overhead associated with
- using this method, so using it in concert with :ref:`pause()
- <lang-hardwaretimer-pause>` is not a robust way to align multiple
- timers to the same count value.
-
-.. cpp:function:: timer_dev_num HardwareTimer::getTimerNum()
-
- Returns the :ref:`timer device number
- <lang-hardwaretimer-timer-dev-num>` associated with the timer. For
- example, ``Timer1.getTimerNum()`` would return ``TIMER1``.
-
- In most cases, you should not need to use this function. If you do
- use it, be careful; the constant ``TIMER1`` is *not equal* to the
- number 1; similarly, ``TIMER2`` is *not* the number 2, etc. Be
- sure to refer to the timer device number by name.
-
-.. _lang-hardwaretimer-modes:
-
-Timer Modes
-^^^^^^^^^^^
-.. doxygenenum:: TimerMode
-
-.. _lang-hardwaretimer-timer-dev-num:
-
-Timer Device Numbers
-^^^^^^^^^^^^^^^^^^^^
-
-These provide a lower-level interface for interacting with timers.
-They are mostly useful in context with the :ref:`getTimer()
-<lang-hardwaretimer-gettimer>` function. **Be careful** when using
-these not to confuse e.g. ``TIMER1`` with the number 1; they are
-different.
-
-.. doxygenenum:: timer_dev_num
-
-.. _lang-hardwaretimer-convenience:
-
-.. _lang-hardwaretimer-gettimer:
+ Use ``refresh()`` instead.
-Other Functions
-^^^^^^^^^^^^^^^
-.. doxygenfunction:: getTimer
+In previous releases, to interact with a particular timers, you would
+use one of the predefined ``HardwareTimer`` instances ``Timer1``,
+``Timer2``, ``Timer3``, and ``Timer4``. These are still available for
+now, but they are also deprecated, and will be removed in a future
+release. As detailed in :ref:`lang-hardwaretimer-getting-started`,
+you should define your own ``HardwareTimer`` variables.
diff --git a/docs/source/lang/api/highbyte.rst b/docs/source/lang/api/highbyte.rst
index 50a1fa6..4cb6f9b 100644
--- a/docs/source/lang/api/highbyte.rst
+++ b/docs/source/lang/api/highbyte.rst
@@ -52,8 +52,4 @@ See Also
- :ref:`lowByte() <lang-lowbyte>`
-
-
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/isbuttonpressed.rst b/docs/source/lang/api/isbuttonpressed.rst
index dbff0c9..8c350b9 100644
--- a/docs/source/lang/api/isbuttonpressed.rst
+++ b/docs/source/lang/api/isbuttonpressed.rst
@@ -4,7 +4,8 @@ isButtonPressed()
=================
Check whether the board's built-in button (labeled BUT on the
-silkscreen) is pressed.
+silkscreen) is pressed. The pin number of the built-in button is
+given by the constant ``BOARD_BUTTON_PIN``.
Library Documentation
---------------------
@@ -14,4 +15,6 @@ Library Documentation
See Also
--------
+- :ref:`Board-specific values <lang-board-values>`
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
- :ref:`lang-waitforbuttonpress`
diff --git a/docs/source/lang/api/loop.rst b/docs/source/lang/api/loop.rst
index d8f6183..c2a5097 100644
--- a/docs/source/lang/api/loop.rst
+++ b/docs/source/lang/api/loop.rst
@@ -15,7 +15,6 @@ Example
::
-
int buttonPin = 38;
// setup initializes serial and the button pin
@@ -42,4 +41,4 @@ See Also
- :ref:`setup() <lang-setup>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/lowbyte.rst b/docs/source/lang/api/lowbyte.rst
index 58e622f..c513711 100644
--- a/docs/source/lang/api/lowbyte.rst
+++ b/docs/source/lang/api/lowbyte.rst
@@ -22,4 +22,4 @@ Returns
The low byte's value (this will be between 0 and 255).
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/map.rst b/docs/source/lang/api/map.rst
index 79122b3..69661a0 100644
--- a/docs/source/lang/api/map.rst
+++ b/docs/source/lang/api/map.rst
@@ -65,4 +65,4 @@ See Also
- :ref:`constrain() <lang-constrain>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/max.rst b/docs/source/lang/api/max.rst
index d38eebe..d356f08 100644
--- a/docs/source/lang/api/max.rst
+++ b/docs/source/lang/api/max.rst
@@ -53,7 +53,7 @@ functions inside the parentheses. It may lead to incorrect results::
Arduino Compatibility
---------------------
-The Maple version of ``max()`` is compatible with Arduino.
+The Maple implementation of ``max()`` is compatible with Arduino.
See Also
--------
@@ -61,5 +61,4 @@ See Also
- :ref:`min() <lang-min>`
- :ref:`constrain() <lang-constrain>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/micros.rst b/docs/source/lang/api/micros.rst
index f12976b..de85303 100644
--- a/docs/source/lang/api/micros.rst
+++ b/docs/source/lang/api/micros.rst
@@ -43,4 +43,4 @@ See Also
- :ref:`delay() <lang-delay>`
- :ref:`delayMicroseconds() <lang-delaymicroseconds>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/millis.rst b/docs/source/lang/api/millis.rst
index 0288c56..db0531c 100644
--- a/docs/source/lang/api/millis.rst
+++ b/docs/source/lang/api/millis.rst
@@ -49,4 +49,4 @@ See Also
- :ref:`delay <lang-delay>`
- :ref:`delayMicroseconds <lang-delaymicroseconds>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/min.rst b/docs/source/lang/api/min.rst
index 1245f6f..3307105 100644
--- a/docs/source/lang/api/min.rst
+++ b/docs/source/lang/api/min.rst
@@ -62,5 +62,4 @@ See Also
- :ref:`max() <lang-max>`
- :ref:`constrain() <lang-constrain>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/pinmode.rst b/docs/source/lang/api/pinmode.rst
index 03cbcfa..8cee3e5 100644
--- a/docs/source/lang/api/pinmode.rst
+++ b/docs/source/lang/api/pinmode.rst
@@ -60,13 +60,13 @@ set up a pin for these purposes before a call to, e.g.,
:ref:`lang-analogRead`. In practice, this should only add a few lines
to your :ref:`lang-setup` function.
-.. TODO verify following before putting it in:
+.. TODO [0.1.0] verify following before putting it in:
.. ``OUTPUT_OPEN_DRAIN``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``, and
.. ``PWM_OPEN_DRAIN`` modes represent functionality not currently
.. available on Arduino boards.
-See also
+See Also
--------
- :ref:`lang-constants`
@@ -74,6 +74,4 @@ See also
- :ref:`lang-digitalread`
- Maple :ref:`GPIO <gpio>` reference page
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/pow.rst b/docs/source/lang/api/pow.rst
index 4280400..219a866 100644
--- a/docs/source/lang/api/pow.rst
+++ b/docs/source/lang/api/pow.rst
@@ -10,8 +10,6 @@ Library Documentation
.. doxygenfunction:: pow
-.. TODO LATER some examples
-
See Also
--------
@@ -19,5 +17,4 @@ See Also
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/pwmwrite.rst b/docs/source/lang/api/pwmwrite.rst
index 9d50077..5cc112e 100644
--- a/docs/source/lang/api/pwmwrite.rst
+++ b/docs/source/lang/api/pwmwrite.rst
@@ -11,8 +11,13 @@ pwmWrite(), the pin will output a steady square wave with the given
duty cycle. You can change the duty cycle later by calling pwmWrite()
again with the same pin and a different duty.
-On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8,
-9, 11, 12, 14, 24, 27, and 28.
+The pins which support PWM have ``PWM`` listed underneath their number
+on your board's silkscreen. These pin numbers are available to your
+program in the :ref:`boardPWMPins <lang-board-values-pwm-pins>`
+board-specific array. The number of pins which are capable of PWM on
+your board is given by the ``BOARD_NR_PWM_PINS`` constant. These
+values are documented for each board in the :ref:`Board Hardware
+Documentation <index-boards>` pages.
The Arduino function :ref:`analogWrite() <lang-analogwrite>` is an
alias for ``pwmWrite()``, but it is badly named, and its use is
@@ -52,4 +57,5 @@ potentiometer::
See Also
--------
-- :ref:`Maple PWM tutorial <pwm>`
+- :ref:`Maple PWM tutorial <pwm>`
+- :ref:`boardPWMPins <lang-board-values-pwm-pins>`
diff --git a/docs/source/lang/api/random.rst b/docs/source/lang/api/random.rst
index dd8871d..9875ee6 100644
--- a/docs/source/lang/api/random.rst
+++ b/docs/source/lang/api/random.rst
@@ -10,9 +10,7 @@ The ``random()`` function generates pseudo-random numbers.
Library Documentation
---------------------
-.. FIXME keep tracking Sphinx/Breathe's ability to reference
-.. overloaded functions so we can use doxygenfunction instead of
-.. manually documenting.
+.. FIXME [Breathe] use doxygenfunction when possible
.. cpp:function:: random(long max)
@@ -70,4 +68,4 @@ See Also
- :ref:`randomSeed() <lang-randomseed>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/randomseed.rst b/docs/source/lang/api/randomseed.rst
index d0a15b7..ca7b75f 100644
--- a/docs/source/lang/api/randomseed.rst
+++ b/docs/source/lang/api/randomseed.rst
@@ -57,4 +57,4 @@ See Also
- :ref:`random() <lang-random>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/serial.rst b/docs/source/lang/api/serial.rst
index 58002e3..0821f43 100644
--- a/docs/source/lang/api/serial.rst
+++ b/docs/source/lang/api/serial.rst
@@ -12,46 +12,20 @@ devices.
Introduction
------------
-The Maple has three serial ports (also known as a UARTs or USARTs):
-``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the
-pins summarized in the following table:
+.. FIXME [0.0.10] UART4, UART5
-.. list-table::
- :header-rows: 1
-
- * - Serial port
- - TX, RX, CK
- - CTS, RTS (if present)
-
- * - ``Serial1``
- - 7, 8, 6
- -
-
- * - ``Serial2``
- - 1, 0, 10
- - 2, 3
-
- * - ``Serial3``
- - 29, 30, 31
- - 32, 33
-
-Thus, if you use a particular serial port, you cannot also use its
-communication pins for other purposes at the same time.
-
-If you want to communicate with the Maple using the provided USB port,
-use :ref:`SerialUSB <lang-serialusb>` instead.
-
-To use them to communicate with an external TTL serial device, connect
-the TX pin to your device's RX pin, the RX to your device's TX pin,
-and the ground of your Maple to your device's ground.
+To use a serial port to communicate with an external serial device,
+connect the TX pin to your device's RX pin, the RX to your device's TX
+pin, and your Maple board's ground to your device's ground.
.. warning:: Don't connect these pins directly to an RS232 serial
port; they operate at +/- 12V and can damage your board.
-
Library Documentation
---------------------
+.. FIXME [0.1.0] Tutorial-style usage introduction
+
All of the ``Serial[1,2,3]`` objects are instances of the
``HardwareSerial`` class, which is documented in this section. (This
means that you can use any of these functions on any of ``Serial1``,
@@ -87,7 +61,7 @@ means that you can use any of these functions on any of ``Serial1``,
.. cpp:function:: HardwareSerial::flush()
- Removes the contents of the Serial's associated USART RX FIFO.
+ Throw away the contents of the serial port's receiver (RX) buffer.
That is, clears any buffered characters, so that the next character
read is guaranteed to be new.
@@ -113,34 +87,25 @@ means that you can use any of these functions on any of ``Serial1``,
Print the argument's digits over the USART, in decimal format.
-.. cpp:function:: HardwareSerial::print(long long n)
+.. cpp:function:: HardwareSerial::print(long n)
Print the argument's digits over the USART, in decimal format.
Negative values will be prefixed with a ``'-'`` character.
-.. cpp:function:: HardwareSerial::print(unsigned long long n)
+.. cpp:function:: HardwareSerial::print(unsigned long n)
Print the argument's digits over the USART, in decimal format.
-.. _lang-serial-print-n-base:
-
-.. cpp:function:: HardwareSerial::print(int n, int base)
-
- Print the digits of ``n`` over the USART, in base ``base``. The
- ``base`` value 2 corresponds to binary, 8 to octal, 10 to decimal,
- and 16 to hexadecimal (you can also use the symbolic constants
- ``BIN``, ``OCT``, ``DEC``, ``HEX``). If ``base`` is 10, negative
- values will be prefixed with a ``'-'`` character (otherwise, ``n``
- will be interpreted as an unsigned quantity).
-
-.. cpp:function:: HardwareSerial::print(long long n, int base)
+.. cpp:function:: HardwareSerial::print(long n, int base)
- Same behavior as the above :ref:`print(int n, int base)
- <lang-serial-print-n-base>`, except with 64-bit values.
+ Print the digits of ``n`` over the USART, in base ``base`` (which
+ may be between 2 and 16). The ``base`` value 2 corresponds to
+ binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. Negative
+ values will be prefixed with a ``'-'`` character.
.. cpp:function:: HardwareSerial::print(double n)
- Print ``n``, accurate to 6 digits after the decimal point.
+ Print ``n``, accurate to 2 digits after the decimal point.
.. _lang-serial-println:
@@ -164,19 +129,15 @@ means that you can use any of these functions on any of ``Serial1``,
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(long long n)
+.. cpp:function:: HardwareSerial::println(long n)
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(unsigned long long n)
+.. cpp:function:: HardwareSerial::println(unsigned long n)
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(int n, int base)
-
- Like ``print(n, b)``, followed by ``"\r\n"``.
-
-.. cpp:function:: HardwareSerial::println(long long n, int base)
+.. cpp:function:: HardwareSerial::println(long n, int base)
Like ``print(n, b)``, followed by ``"\r\n"``.
@@ -219,11 +180,12 @@ Arduino Compatibility Note
--------------------------
Unlike the Arduino, none of the Maple's serial ports is connected to
-the USB port on the Maple board (for that, use :ref:`SerialUSB
-<lang-serialusb>`). Thus, to use these pins to communicate with your
-personal computer, you will need an additional USB-to-serial adaptor.
+the USB port on the Maple board. If you want to communicate using the
+built-in USB port, use :ref:`SerialUSB <lang-serialusb>` instead. You
+will need an additional USB-to-serial adapter to communicate between a
+USART and your computer.
-.. TODO LATER port these examples over
+.. FIXME [0.1.0] port these examples over
.. Examples
.. --------
@@ -236,4 +198,4 @@ personal computer, you will need an additional USB-to-serial adaptor.
.. - `Serial Call Response <http://arduino.cc/en/Tutorial/SerialCallResponse>`_
.. - `Serial Call Response ASCII <http://arduino.cc/en/Tutorial/SerialCallResponseASCII>`_
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/serialusb.rst b/docs/source/lang/api/serialusb.rst
index 87fa641..ed466f2 100644
--- a/docs/source/lang/api/serialusb.rst
+++ b/docs/source/lang/api/serialusb.rst
@@ -16,9 +16,8 @@ Introduction
In addition to three :ref:`serial ports <lang-serial>`, the Maple's
STM32 microprocessor includes a dedicated USB peripheral. This
peripheral is used to emulate a regular serial port for use as a
-terminal (text read/write). The emulated terminal is relatively slow
-and inefficient; it is best for transferring data at regular serial
-speeds (kilobaud).
+terminal. The emulated terminal is relatively slow; it is best for
+transferring data at regular serial speeds (kilobaud).
Library access to the emulated serial port is provided through the
``SerialUSB`` object. You can mostly use ``SerialUSB`` as a drop-in
@@ -30,14 +29,14 @@ replacement for ``Serial1``, ``Serial2``, and ``Serial3``.
This means that if you have a number of calls to one of the
``SerialUSB`` ``write()`` or ``print()`` functions in your code,
- and you are not monitoring the emulated on a computer, your program
- will run much, much slower than if it is being monitored or totally
- disconnected (run off of a battery).
+ and you are not monitoring ``SerialUSB`` on a computer, your
+ program will run much slower than if it is being monitored or
+ totally disconnected (run off of a battery).
You can avoid this behavior by :ref:`deciphering the port status
- using the DTR and RTS line status <lang-serialusb-safe-print>`; the
+ using the DTR and RTS line status <lang-serialusb-safe-print>` (the
behavior of these control lines is platform dependent and we no
- longer interpret them by default.
+ longer interpret them by default).
Library Documentation
---------------------
@@ -109,35 +108,26 @@ world!")``.
Print the argument's digits over the USB connection, in decimal format.
-.. cpp:function:: USBSerial::print(long long n)
+.. cpp:function:: USBSerial::print(long n)
Print the argument's digits over the USB connection, in decimal
format. Negative values will be prefixed with a ``'-'`` character.
-.. cpp:function:: USBSerial::print(unsigned long long n)
+.. cpp:function:: USBSerial::print(unsigned long n)
Print the argument's digits over the USB connection, in decimal
format.
-.. _lang-serial-print-n-base:
+.. cpp:function:: USBSerial::print(long n, int base)
-.. cpp:function:: USBSerial::print(int n, int base)
-
- Print the digits of ``n`` over USB, in base ``base``. The ``base``
- value 2 corresponds to binary, 8 to octal, 10 to decimal, and 16 to
- hexadecimal (you can also use the symbolic constants ``BIN``,
- ``OCT``, ``DEC``, ``HEX``). If ``base`` is 10, negative values
- will be prefixed with a ``'-'`` character (otherwise, ``n`` will be
- interpreted as an unsigned quantity).
-
-.. cpp:function:: HardwareSerial::print(long long n, int base)
-
- Same behavior as the above :ref:`print(int n, int base)
- <lang-serialusb-print-n-base>`, except with 64-bit values.
+ Print the digits of ``n`` over the USB connection, in base ``base``
+ (which may be between 2 and 16). The ``base`` value 2 corresponds
+ to binary, 8 to octal, 10 to decimal, and 16 to hexadecimal.
+ Negative values will be prefixed with a ``'-'`` character.
.. cpp:function:: USBSerial::print(double n)
- Print ``n``, accurate to 6 digits after the decimal point.
+ Print ``n``, accurate to 2 digits after the decimal point.
.. _lang-serialusb-println:
@@ -161,19 +151,15 @@ world!")``.
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: USBSerial::println(long long n)
+.. cpp:function:: USBSerial::println(long n)
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: USBSerial::println(unsigned long long n)
+.. cpp:function:: USBSerial::println(unsigned long n)
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: USBSerial::println(int n, int base)
-
- Like ``print(n, b)``, followed by ``"\r\n"``.
-
-.. cpp:function:: USBSerial::println(long long n, int base)
+.. cpp:function:: USBSerial::println(long n, int base)
Like ``print(n, b)``, followed by ``"\r\n"``.
@@ -224,7 +210,7 @@ running from battery, or connected but not monitored. You may need to
experiment with the DTR/RTS logic for your platform and device
configuration. ::
- #define LED_PIN 13
+ #define LED_PIN BOARD_LED_PIN
void setup() {
/* Set up the LED to blink */
@@ -232,22 +218,22 @@ configuration. ::
}
void loop() {
- // LED will stay off if we are disconnected;
- // will blink quickly if USB is unplugged (battery etc)
+ // LED will stay off if we are disconnected, and will blink
+ // quickly if USB is unplugged (battery power, etc.).
if(SerialUSB.isConnected()) {
digitalWrite(LED_PIN, 1);
}
delay(100);
- // If this logic fails to detect if bytes are going to
- // be read by the USB host, then the println() will fully
- // many times, causing a very slow LED blink.
- // If the characters are printed and read, the blink will
- // only slow a small amount when "really" connected, and fast
- // when the virtual port is only configured.
+ // If this logic fails to detect if bytes are going to be read
+ // by the USB host, then the println() take a long time,
+ // causing a very slow LED blink. If the characters are
+ // printed and read, the blink will only slow a small amount
+ // when "really" connected, and will be fast fast when the
+ // virtual port is only configured.
if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) {
- for(int i=0; i<10; i++) {
- SerialUSB.println(123456,BIN);
+ for(int i = 0; i < 10; i++) {
+ SerialUSB.println(123456, BIN);
}
}
digitalWrite(LED_PIN, 0);
diff --git a/docs/source/lang/api/setup.rst b/docs/source/lang/api/setup.rst
index 837ddd6..1e8e3b8 100644
--- a/docs/source/lang/api/setup.rst
+++ b/docs/source/lang/api/setup.rst
@@ -26,4 +26,4 @@ Example
// ...
}
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/shiftout.rst b/docs/source/lang/api/shiftout.rst
new file mode 100644
index 0000000..1d9ba12
--- /dev/null
+++ b/docs/source/lang/api/shiftout.rst
@@ -0,0 +1,99 @@
+.. highlight:: cpp
+
+.. _lang-shiftout:
+
+shiftOut()
+==========
+
+Shift out a byte of data, one bit at a time.
+
+.. contents:: Contents
+ :local:
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: shiftOut
+
+Discussion
+----------
+
+This is a software implementation. There is also a hardware :ref:`SPI
+<spi>` library available which will be faster and consume less CPU
+cycles than this function.
+
+Note that the ``dataPin`` and ``clockPin`` must already be configured
+to :ref:`OUTPUT <lang-constants-output>` mode by a call to
+:ref:`pinMode() <lang-pinmode>`.
+
+Also note that since shiftOut() outputs 1 byte (8 bits) at a time, it
+requires multiple steps to output values larger than 255.
+
+Examples
+--------
+
+To use these examples, replace ``dataPin`` and ``clockPin`` with the
+numbers of the pins you want to use::
+
+ /* MSBFIRST example */
+
+ uint16 data = 500;
+ // shift out high byte
+ shiftOut(dataPin, clockPin, MSBFIRST, (data >> 8));
+ // shift out low byte
+ shiftOut(dataPin, clockPin, MSBFIRST, data);
+
+ /* LSBFIRST serial */
+
+ data = 500;
+ // shift out low byte
+ shiftOut(dataPin, clockPin, LSBFIRST, data);
+ // shift out high byte
+ shiftOut(dataPin, clockPin, LSBFIRST, (data >> 8));
+
+Arduino Tutorial Example
+------------------------
+
+This Arduino example runs unmodified on the Maple. For accompanying
+circuit, see the `tutorial on controlling a 74HC595 shift register
+<http://arduino.cc/en/Tutorial/ShiftOut>`_.
+
+::
+
+ //**************************************************************//
+ // Name : shiftOutCode, Hello World //
+ // Author : Carlyn Maw, Tom Igoe //
+ // Date : 25 Oct, 2006 //
+ // Version : 1.0 //
+ // Notes : Code for using a 74HC595 Shift Register //
+ // : to count from 0 to 255 //
+ //**************************************************************//
+
+ // Pin connected to ST_CP of 74HC595
+ int latchPin = 8;
+ // Pin connected to SH_CP of 74HC595
+ int clockPin = 12;
+ // Pin connected to DS of 74HC595
+ int dataPin = 11;
+
+ void setup() {
+ // Set pins to output because they are addressed in the main loop
+ pinMode(latchPin, OUTPUT);
+ pinMode(clockPin, OUTPUT);
+ pinMode(dataPin, OUTPUT);
+ }
+
+ void loop() {
+ // Count up routine
+ for (int j = 0; j < 256; j++) {
+ // Ground latchPin and hold low for as long as you are transmitting
+ digitalWrite(latchPin, LOW);
+ shiftOut(dataPin, clockPin, LSBFIRST, j);
+ // Return the latch pin high to signal chip that it
+ // no longer needs to listen for information
+ digitalWrite(latchPin, HIGH);
+ delay(1000);
+ }
+ }
+
+.. include:: /lang/cc-attribution.txt
diff --git a/docs/source/lang/api/sin.rst b/docs/source/lang/api/sin.rst
index 398b8f3..3e28c0b 100644
--- a/docs/source/lang/api/sin.rst
+++ b/docs/source/lang/api/sin.rst
@@ -28,5 +28,4 @@ See Also
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/sq.rst b/docs/source/lang/api/sq.rst
index bd32648..96724d3 100644
--- a/docs/source/lang/api/sq.rst
+++ b/docs/source/lang/api/sq.rst
@@ -42,5 +42,4 @@ Arduino Compatibility
Maple's implementation of ``sq()`` is compatible with Arduino.
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/tan.rst b/docs/source/lang/api/tan.rst
index 4bbe0db..b1aed31 100644
--- a/docs/source/lang/api/tan.rst
+++ b/docs/source/lang/api/tan.rst
@@ -22,10 +22,9 @@ Note that the Maple implementation comes from `newlib
See Also
--------
-
- :ref:`sin <lang-sin>`
- :ref:`cos <lang-cos>`
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/toggleled.rst b/docs/source/lang/api/toggleled.rst
index 0cc20c2..54a7d64 100644
--- a/docs/source/lang/api/toggleled.rst
+++ b/docs/source/lang/api/toggleled.rst
@@ -13,5 +13,5 @@ Library Documentation
See Also
--------
-- :ref:`BOARD_LED_PIN <lang-constants-led>`
+- :ref:`BOARD_LED_PIN <lang-board-values-led>`
- :ref:`togglePin() <lang-togglepin>`
diff --git a/docs/source/lang/api/volatile.rst b/docs/source/lang/api/volatile.rst
index 276bb6a..1b72897 100644
--- a/docs/source/lang/api/volatile.rst
+++ b/docs/source/lang/api/volatile.rst
@@ -24,8 +24,8 @@ for efficiency).
A variable should be declared ``volatile`` whenever its value can be
changed by something beyond the control of the code section in which
it appears, such as an :ref:`external interrupt
-<external-interrupts>`. On the Maple, the only place that this is
-likely to occur is in sections of code associated with interrupts.
+<external-interrupts>`. (The only place that this is likely to occur
+in most programs is inside of code called by interrupts).
Example
-------
@@ -55,11 +55,11 @@ Example
}
}
-See also
+See Also
--------
- :ref:`External Interrupts <external-interrupts>`
- :ref:`lang-attachinterrupt`
- :ref:`lang-detachinterrupt`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/waitforbuttonpress.rst b/docs/source/lang/api/waitforbuttonpress.rst
index 34c5066..a5bd45c 100644
--- a/docs/source/lang/api/waitforbuttonpress.rst
+++ b/docs/source/lang/api/waitforbuttonpress.rst
@@ -14,4 +14,6 @@ Library Documentation
See Also
--------
+- :ref:`Board-specific values <lang-board-values>`
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
- :ref:`lang-isbuttonpressed`