aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-08-03 20:01:50 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2011-08-03 20:01:50 -0400
commit7756783c967fa7468bcf803ce8a24404b1094109 (patch)
treef9df73d94edab675658ab12e7ba0f89fa3319271
parent2ffc358cd2e69108d2c2137e73fec68071b11c6d (diff)
downloadlibrambutan-7756783c967fa7468bcf803ce8a24404b1094109.tar.gz
librambutan-7756783c967fa7468bcf803ce8a24404b1094109.zip
Improve external interrupts documentation.
Simplify and remove redundancies from external-interrupts.rst. Move a pin configuration detail from that page into the attachInterrupt() API page (attachinterrupt.rst). Fix and explain what's going on in the example sketch in attachinterrupt.rst.
-rw-r--r--source/external-interrupts.rst32
-rw-r--r--source/lang/api/attachinterrupt.rst36
2 files changed, 40 insertions, 28 deletions
diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst
index 60a87f1..1ab65be 100644
--- a/source/external-interrupts.rst
+++ b/source/external-interrupts.rst
@@ -5,13 +5,11 @@
External Interrupts
===================
-External interrupts can be used to make a voltage change on a pin
-cause a function to be called. Each :ref:`GPIO pin <gpio>` can be
-used to detect transitions, such as when the voltage goes from
-:ref:`LOW <lang-constants-low>` to :ref:`HIGH <lang-constants-high>`,
-or from ``HIGH`` to ``LOW``. This can be used to avoid checking for
-changes on a pin "manually" by waiting in a loop until the pin
-changes.
+External interrupts can be used to make a voltage change on a
+:ref:`pin <gpio>` (the pin going from :ref:`LOW <lang-constants-low>`
+to :ref:`HIGH <lang-constants-high>`, or vice-versa) to cause a
+function to be called. This can be used to avoid checking for changes
+on a pin "manually" by waiting in a loop until the pin changes.
.. _contents: Contents
:local:
@@ -20,16 +18,16 @@ Overview
--------
External interrupts are often used to detect when events happen
-outside of the Maple. These can be used to tell Maple when events
-happen, such as when a sensor has data ready to be read, or when a
-button has been pushed. When such an event happens, an interrupt is
-raised, and the Maple stops whatever it was doing to react to it by
-calling a function (called an *interrupt handler*) which you specify
-using :ref:`lang-attachinterrupt`.
+outside of the Maple. Example events include when a sensor has data
+ready to be read, or when a button has been pushed. When such an
+event happens, an interrupt is raised, and the Maple stops whatever it
+was doing (it is "interrupted"), and reacts to the event by calling a
+function (called an *interrupt handler*) which you specify using
+:ref:`lang-attachinterrupt`.
.. _external-interrupts-exti-line:
-Every pin can generate an external interrupt, but there are some
+Any pin can be used for external interrupts, but there are some
restrictions. At most 16 different external interrupts can be used at
one time. Further, you can't just pick any 16 pins to use. This is
because every pin on the Maple connects to what is called an *EXTI
@@ -45,12 +43,6 @@ EXTI lines:
* :ref:`Maple RET6 Edition <maple-ret6-exti-map>`
* :ref:`Maple Mini <maple-mini-exti-map>`
-.. note::
-
- You should set the :ref:`pin mode <lang-pinmode>` of your desired
- pin to an input mode (e.g. ``INPUT``, ``INPUT_PULLUP``,
- ``INPUT_PULLDOWN``).
-
Function Reference
------------------
diff --git a/source/lang/api/attachinterrupt.rst b/source/lang/api/attachinterrupt.rst
index 39902ac..58e4764 100644
--- a/source/lang/api/attachinterrupt.rst
+++ b/source/lang/api/attachinterrupt.rst
@@ -41,6 +41,12 @@ Library Documentation
.. doxygentypedef:: voidFuncPtr
+.. note::
+
+ You should set the :ref:`pin mode <lang-pinmode>` of your desired
+ pin to an input mode (e.g. ``INPUT``, ``INPUT_PULLUP``,
+ ``INPUT_PULLDOWN``).
+
Discussion
----------
@@ -50,31 +56,45 @@ Because the function will run in interrupt context, inside of it,
the function may be lost. You should declare as ``volatile`` any
global variables that you modify within the attached function.
-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.
+There are some limits you should be aware of if you're using
+``attachInterrupt()`` with more than one pin; the :ref:`External
+Interrupts <external-interrupts-exti-line>` page has more information.
Example
-------
- ::
+The following example blinks the LED any time pin 0 changes from
+``HIGH`` to ``LOW`` or vice versa. ::
volatile int state = LOW; // must declare volatile, since it's
// modified within the blink() handler
void setup() {
- pinMode(BOARD_LED_PIN, OUTPUT);
- attachInterrupt(0, blink, CHANGE);
+ pinMode(BOARD_LED_PIN, OUTPUT);
+ pinMode(0, INPUT);
+ attachInterrupt(0, blink, CHANGE);
}
void loop() {
- digitalWrite(BOARD_LED_PIN, state);
+ digitalWrite(BOARD_LED_PIN, state);
}
void blink() {
- state = !state;
+ if (state == HIGH) {
+ state = LOW;
+ } else { // state must be LOW
+ state = HIGH;
+ }
}
+In this example, the function ``blink()`` is the interrupt handler.
+Whenever the state on pin 0 changes, ``blink()`` gets called. It
+reacts to the change by changing the ``state`` variable to ``LOW`` if
+it is ``HIGH``, and to ``HIGH`` if it is ``LOW``. It then exits,
+letting the board get back to calling ``loop()``. Since ``loop()``
+sets the LED pin to whatever ``state`` is, changing the voltage on pin
+0 will toggle the LED.
+
Arduino Compatibility
---------------------