1 files changed, 114 insertions, 0 deletions
diff --git a/docs/source/lang/api/attachinterrupt.rst b/docs/source/lang/api/attachinterrupt.rst
new file mode 100644
index 0000000..58e4764
--- /dev/null
+++ b/docs/source/lang/api/attachinterrupt.rst
@@ -0,0 +1,114 @@
+.. highlight:: cpp
+
+.. _lang-attachinterrupt:
+
+attachInterrupt()
+=================
+
+Used to specify a function to call when an :ref:`external interrupt
+<external-interrupts>` occurs.
+
+.. contents:: Contents
+   :local:
+
+Library Documentation
+---------------------
+
+.. 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)
+
+   Registers an interrupt handler on a pin.
+
+   The interrupt will be triggered on a given transition on the pin,
+   as specified by the mode parameter.  The handler runs in interrupt
+   context.  The new handler will replace whatever handler is
+   currently registered for the pin, if any.
+
+   *Parameters*
+
+      - ``pin`` - Maple pin number
+
+      - ``handler`` - Function to run upon external interrupt trigger.
+        The handler should take no arguments, and have void return type.
+
+      - ``mode`` - Type of transition to trigger on, e.g. falling,
+        rising, etc.
+
+.. doxygenenum:: ExtIntTriggerMode
+
+.. 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
+----------
+
+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
+global variables that you modify within the attached function.
+
+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);
+        pinMode(0, INPUT);
+        attachInterrupt(0, blink, CHANGE);
+    }
+
+    void loop() {
+        digitalWrite(BOARD_LED_PIN, state);
+    }
+
+    void blink() {
+        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
+---------------------
+
+Most Arduino boards have two external interrupts: numbers 0 (on
+digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an
+additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5
+(pin 18).  On the Maple, you don't have to remember which interrupt
+number goes with which pin -- just tell ``attachInterrupt()`` the pin
+you want.
+
+See Also
+--------
+
+- :ref:`lang-detachinterrupt`
+- :ref:`external-interrupts`
+
+.. include:: /arduino-cc-attribution.txt