1 files changed, 115 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..7c5a6c7
--- /dev/null
+++ b/docs/source/lang/api/attachinterrupt.rst
@@ -0,0 +1,115 @@
+.. highlight:: cpp
+
+.. _lang-attachinterrupt:
+
+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.
+
+.. contents:: Contents
+   :local:
+
+Library Documentation
+---------------------
+
+.. FIXME 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
+
+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 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.
+
+Example
+-------
+
+::
+
+    int maple_led_pin = 13;
+    volatile int state = LOW; // must declare volatile, since it's
+                              // modified within the blink handler
+
+    void setup() {
+      pinMode(maple_led_pin, OUTPUT);
+      attachInterrupt(0, blink, CHANGE);
+    }
+
+    void loop() {
+      digitalWrite(maple_led_pin, state);
+    }
+
+    void blink() {
+      state = !state;
+    }
+
+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:`detachInterrupt <lang-detachinterrupt>`
+-  :ref:`external-interrupts`
+
+.. include:: cc-attribution.txt