aboutsummaryrefslogtreecommitdiffstats
path: root/source/lang/api
diff options
context:
space:
mode:
Diffstat (limited to 'source/lang/api')
-rw-r--r--source/lang/api/abs.rst49
-rw-r--r--source/lang/api/analogread.rst154
-rw-r--r--source/lang/api/analogwrite.rst169
-rw-r--r--source/lang/api/attachinterrupt.rst102
-rw-r--r--source/lang/api/bit.rst44
-rw-r--r--source/lang/api/bitclear.rst44
-rw-r--r--source/lang/api/bitread.rst46
-rw-r--r--source/lang/api/bitset.rst46
-rw-r--r--source/lang/api/bitwrite.rst46
-rw-r--r--source/lang/api/cc-attribution.txt9
-rw-r--r--source/lang/api/constants.rst304
-rw-r--r--source/lang/api/constrain.rst69
-rw-r--r--source/lang/api/cos.rst32
-rw-r--r--source/lang/api/delay.rst72
-rw-r--r--source/lang/api/delaymicroseconds.rst65
-rw-r--r--source/lang/api/detachinterrupt.rst37
-rw-r--r--source/lang/api/digitalread.rst58
-rw-r--r--source/lang/api/digitalwrite.rst68
-rw-r--r--source/lang/api/highbyte.rst59
-rw-r--r--source/lang/api/loop.rst45
-rw-r--r--source/lang/api/lowbyte.rst25
-rw-r--r--source/lang/api/map.rst68
-rw-r--r--source/lang/api/max.rst65
-rw-r--r--source/lang/api/micros.rst46
-rw-r--r--source/lang/api/millis.rst52
-rw-r--r--source/lang/api/min.rst66
-rw-r--r--source/lang/api/pinmode.rst77
-rw-r--r--source/lang/api/pow.rst23
-rw-r--r--source/lang/api/pwmwrite.rst49
-rw-r--r--source/lang/api/random.rst73
-rw-r--r--source/lang/api/randomseed.rst60
-rw-r--r--source/lang/api/serial.rst226
-rw-r--r--source/lang/api/serialusb.rst242
-rw-r--r--source/lang/api/setup.rst29
-rw-r--r--source/lang/api/sin.rst32
-rw-r--r--source/lang/api/sq.rst46
-rw-r--r--source/lang/api/tan.rst31
-rw-r--r--source/lang/api/volatile.rst65
38 files changed, 2793 insertions, 0 deletions
diff --git a/source/lang/api/abs.rst b/source/lang/api/abs.rst
new file mode 100644
index 0000000..0cc6c23
--- /dev/null
+++ b/source/lang/api/abs.rst
@@ -0,0 +1,49 @@
+.. highlight:: cpp
+
+.. _lang-abs:
+
+
+abs()
+======
+
+(Macro) computes the absolute value of a number.
+
+Syntax
+------
+
+::
+
+ abs(x)
+
+Parameters
+----------
+
+**x**: the number.
+
+Returns
+-------
+
+**x**: if **x** is greater than or equal to 0.
+
+**-x**: if **x** is less than 0.
+
+Warning
+-------
+
+Because of the way ``abs()`` is implemented, avoid using other
+functions or causing side effects inside the parentheses, as it may
+lead to incorrect results::
+
+ abs(a++); // avoid this - yields incorrect results
+
+ abs(a); // use this instead -
+ a++; // keep other operations outside abs()
+
+
+Arduino Compatibility
+---------------------
+
+Maple's implementation of ``abs()`` is compatible with Arduino.
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/analogread.rst b/source/lang/api/analogread.rst
new file mode 100644
index 0000000..c614aca
--- /dev/null
+++ b/source/lang/api/analogread.rst
@@ -0,0 +1,154 @@
+.. highlight:: cpp
+
+.. _lang-analogread:
+
+.. _lang-api-analogread:
+
+analogRead()
+============
+
+Used to perform ADC conversion.
+
+.. contents:: Contents
+ :local:
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: analogRead
+
+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
+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`\ ).
+
+It takes about 0.8 microseconds (.0000008 seconds) to read an analog
+input, so the maximum sample rate using this function is approximately
+1.3 million samples per second\ [#fsamp]_.
+
+
+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.
+
+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.
+
+
+Example
+-------
+
+ ::
+
+
+ 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() {
+ val = analogRead(analogPin); // read the input pin
+ SerialUSB.println(val); // print the value, for debugging with
+ // a serial monitor
+ }
+
+
+Arduino Compatibility
+---------------------
+
+The Arduino board contains a 6 channel (8 channels on the Mini and
+Nano, 16 on the Mega), 10-bit analog to digital converter with an
+input voltage range of 0V--5V. This means that it will map input
+voltages between 0 and 5 volts (which is **larger** than Maple's range
+of 0V-3.3V) into integer values between 0 and 1023 (which is
+**smaller** than the Maple's range of 0--4095).
+
+This yields a theoretical resolution between readings of: 5 volts /
+1024 units or .0049 volts (4.9 mV) per unit on Arduino boards, which
+is larger, and thus less precise, than Maple's 0.0008 volts (0.8 mV).
+
+If your program expects Arduino-style 10-bit ADC, you can :ref:`right
+shift <lang-bitshift>` the value of a Maple readout by 2, like so::
+
+ // right shift means that the result will be between 0 and 1023;
+ // be aware that you're losing a lot of precision if you do this
+ int adc_reading = analogRead(pin) >> 2;
+
+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.
+
+Finally, On the Arduino, it takes significantly longer to read analog
+input: about 100 microseconds (0.0001 s), so the maximum reading rate
+is 10,000 times a second.
+
+
+See also
+--------
+
+- :ref:`ADC note <adc>`
+- `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
+
+
+.. rubric:: Footnotes
+
+.. [#fsamp] This is based on the current configuration of a 55.5 cycle
+ sample time, at 72 MHz. However, the minimum sample time *possible*
+ is 1.5 cycles, leading to a theoretical maximum of approximately 48
+ million samples per second (of course, doing anything with the
+ readings also consumes cycles, so this maximum can't be reached in
+ practice).
+
+ See the `STM32 Reference Manual <full-manual>`_, §§11.12.4--5
+ (pp. 225--226), for more information on the low-level bit twiddling
+ currently necessary to change the sample time. For examples of how
+ the ADCs are configured in libmaple, see `adc.h
+ <http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.h>`_
+ and `adc.c
+ <http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.c>`_\
+ . Be aware that changing the sample time has important
+ consequences related to the impedance of the device connected to
+ the input pin. If you want to make changes, as a minimum, you
+ should first read ST's application notes on `ADC modes
+ <stm32-adc-modes>`_ and `ADC oversampling
+ <stm32-adc-oversampling>`_.
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/analogwrite.rst b/source/lang/api/analogwrite.rst
new file mode 100644
index 0000000..01820ef
--- /dev/null
+++ b/source/lang/api/analogwrite.rst
@@ -0,0 +1,169 @@
+.. highlight:: cpp
+
+.. _lang-analogwrite:
+
+.. _lang-api-analogwrite:
+
+
+analogWrite()
+=============
+
+.. note::
+
+ On the Maple, calling analogWrite() is the same as calling
+ :ref:`lang-pwmwrite`\ ; see that function's documentation for more
+ information.
+
+ This is because PWM is not true analog output (i.e., is not the
+ output of a `DAC
+ <http://en.wikipedia.org/wiki/Digital-to-analog_converter>`_\ ), so
+ the function is badly named. For instance, **analogWrite() has
+ absolutely nothing to do with** :ref:`lang-analogread`\ , which is
+ potentially confusing.
+
+ The alias of analogWrite() to pwmWrite() is provided (sigh) for the
+ sake of compatibility with Arduino, but we recommend using
+ :ref:`lang-pwmwrite` when writing new software, for clarity.
+
+.. contents:: Contents
+ :local:
+
+.. _lang-analogwrite-compatibility:
+
+Arduino Compatibility
+---------------------
+
+There are a few important differences between Arduino's `analogWrite()
+<http://arduino.cc/en/Reference/AnalogWrite>`_ and Maple's
+:ref:`lang-pwmwrite` that you should keep in mind. In each case, we
+have some recommendations you can use to help converting from Arduino
+to Maple.
+
+Difference 1: Duty cycle range is different
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The first and most important difference is that the largest possible
+value for the duty cycle is much bigger on the Maple. Using Arduino's
+analogWrite(), the duty cycle ranges between 0--255 (always off --
+always on)\ [#fbytemax]_\ . Using Maple's pwmWrite(), the duty cycle
+ranges from 0--65,535 by default\ [#fuint16max]_\ .
+
+This is a good thing! The greater range of values on the Maple gives
+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::
+
+ // Arduino code:
+ analogWrite(pin, duty);
+
+ // Becomes Maple code:
+ analogWrite(pin, map(duty, 0, 255, 0, 65535));
+
+This will convert values in the range 0-255 to values in the range
+0--65,635, which is the correct default range for all of the timers
+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.
+
+Difference 2: You must use pinMode() to set up PWM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The second difference is that on the Maple, you **must** set up the pin
+for PWM output using :ref:`lang-pinmode`\ , with argument ``PWM``.
+This should just be one extra line of code in your
+:ref:`lang-setup` function. Example::
+
+ void setup() {
+ // set up pin 9 for PWM
+ pinMode(9, PWM);
+ }
+
+This also means that you can't later call :ref:`lang-digitalread`
+or :ref:`lang-digitalwrite` on that pin (unless some time in
+between, you use pinMode() to reconfigure that pin for ``INPUT`` or
+``OUTPUT``; see the :ref:`lang-pinmode` page for more information).
+
+Difference 3: No PWM on pin 10
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8,
+9, 11, 12, and 14, or twelve pins in total. That is at least as
+*many* PWM pins as any Arduino board, but there are differences in
+*which* pins support it.
+
+* On **most Arduino boards** (those with the ATmega168 or ATmega328;
+ this includes the **Arduino Uno**), this function works on pins 3,
+ 5, 6, 9, 10, and 11, or six pins total. Note that these boards
+ support PWM on pin 10, while Maple does not.
+
+* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve pins
+ total. Note that this board supports PWM on pins 4, 10, and 13,
+ while the Maple does not. Maple supports PWM on pins 0, 1, and 14,
+ which the Mega does not, making the total number of pins supporting
+ PWM equal on these boards.
+
+* **Older Arduino boards** with an ATmega8 only support analogWrite() on
+ pins 9, 10, and 11. Maple does not support PWM on pin 10.
+
+In all cases, Arduino boards support PWM on pin 10, unlike Maple. We
+did our best to make PWM as pin-compatible as possible; however,
+circuit layout constraints prevented us from achieving perfect
+compatibility.
+
+The "safest" pins to use for PWM output are pins 9 and 11. These pins
+work on any Arduino board and on Maple. The "safe" pins, which work
+on most recent Arduino boards, the Arduino Mega and the Maple, are
+pins 3, 5, 6, 9, and 11. Thus, if you want your project to be as
+portable as possible between Maple and Arduino, we recommend using the
+"safest" pins first, then the "safe" pins, as necessary.
+
+Difference 4: PWM frequency
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The frequency of the PWM signal (i.e., the frequency of a complete
+on/off cycle) on the Arduino is approximately 490 Hz.
+
+On the Maple, the frequency is configurable, defaulting to about 1100
+Hz, or 1.1 KHz. This is because the PWM frequency is the frequency of
+the timer which controls PWM output on the particular pin (\
+:ref:`the PWM tutorial has the details <pwm>`\ ).
+
+If your application absolutely requires Arduino's PWM frequency (it
+probably doesn't), then the steps are:
+
+1. Figure out which timer 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.
+
+2. Call ``Timern.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. One example is :ref:`interrupts <timers-attachinterrupt>`\ .
+You've been :ref:`warned <timers-pwm-conflicts>`\ .
+
+See also
+--------
+
+- :ref:`Maple PWM tutorial <pwm>`
+
+.. rubric:: Footnotes
+
+.. [#fbytemax] This is because the value for the duty cycle on Arduino
+ must fit in 1 byte of memory, and an unsigned (i.e., nonnegative)
+ integer with size 1 byte can hold the values between 0 and 255.
+
+.. [#fuint16max] This is because the value for the duty cycle on the
+ 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
diff --git a/source/lang/api/attachinterrupt.rst b/source/lang/api/attachinterrupt.rst
new file mode 100644
index 0000000..0b8907f
--- /dev/null
+++ b/source/lang/api/attachinterrupt.rst
@@ -0,0 +1,102 @@
+.. 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
+---------------------
+
+.. doxygenfunction:: attachInterrupt
+
+.. 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
diff --git a/source/lang/api/bit.rst b/source/lang/api/bit.rst
new file mode 100644
index 0000000..dd5c050
--- /dev/null
+++ b/source/lang/api/bit.rst
@@ -0,0 +1,44 @@
+.. _lang-bit:
+
+bit()
+=====
+
+(Macro) Computes the value of an (unsigned) integer with the specified
+bit set (``bit(0)`` is 1, ``bit(1)`` is 2, ``bit(2)`` is 4, then 8,
+16, 32, etc.).
+
+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.
+
+
+See also
+--------
+
+
+- :ref:`lang-bitread`
+- :ref:`lang-bitwrite`
+- :ref:`lang-bitset`
+- :ref:`lang-bitclear`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/bitclear.rst b/source/lang/api/bitclear.rst
new file mode 100644
index 0000000..941f912
--- /dev/null
+++ b/source/lang/api/bitclear.rst
@@ -0,0 +1,44 @@
+.. _lang-bitclear:
+
+bitClear()
+==========
+
+(Macro) Clears (writes a 0 to) a bit of a numeric variable.
+
+Syntax
+------
+
+``bitClear(x, n)``
+
+
+Parameters
+----------
+
+* **x** the numeric variable whose bit to clear
+
+* **n** which bit to clear, starting at 0 for the least-significant
+ (rightmost) bit
+
+
+Returns
+-------
+
+None.
+
+
+Arduino Compatibility
+---------------------
+
+This implementation is compatible with that of Arduino.
+
+
+See also
+--------
+
+- :ref:`bit <lang-bit>`\ ()
+- :ref:`bitRead <lang-bitread>`\ ()
+- :ref:`bitWrite <lang-bitwrite>`\ ()
+- :ref:`bitSet <lang-bitset>`\ ()
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/bitread.rst b/source/lang/api/bitread.rst
new file mode 100644
index 0000000..46b4478
--- /dev/null
+++ b/source/lang/api/bitread.rst
@@ -0,0 +1,46 @@
+.. _lang-bitread:
+
+bitRead()
+=========
+
+(Macro) Gets the value of a bit in a number.
+
+
+Syntax
+------
+
+``bitRead(x, n)``
+
+
+Parameters
+----------
+
+* **x** the number from which to read the bit.
+
+* **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
+--------
+
+
+- :ref:`lang-bit`
+- :ref:`lang-bitwrite`
+- :ref:`lang-bitset`
+- :ref:`lang-bitclear`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/bitset.rst b/source/lang/api/bitset.rst
new file mode 100644
index 0000000..ccd76de
--- /dev/null
+++ b/source/lang/api/bitset.rst
@@ -0,0 +1,46 @@
+.. _lang-bitset:
+
+bitSet()
+========
+
+(Macro) Sets (writes a 1 to) a bit of a numeric variable.
+
+
+Syntax
+------
+
+``bitSet(x, n)``
+
+
+Parameters
+----------
+
+* **x** the numeric variable whose bit to set
+
+* **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
+--------
+
+- :ref:`lang-bit`
+- :ref:`lang-bitread`
+- :ref:`lang-bitwrite`
+- :ref:`lang-bitclear`
+
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/bitwrite.rst b/source/lang/api/bitwrite.rst
new file mode 100644
index 0000000..b3feff2
--- /dev/null
+++ b/source/lang/api/bitwrite.rst
@@ -0,0 +1,46 @@
+.. highlight:: cpp
+
+.. _lang-bitwrite:
+
+bitWrite()
+==========
+
+(Macro) Writes a bit of a numeric variable.
+
+Syntax
+------
+
+::
+
+ bitWrite(x, n, b)
+
+Parameters
+----------
+
+**x**: the numeric variable whose bit to write.
+
+**n**: which bit of the number to write, starting at 0 for the
+least-significant (rightmost) bit.
+
+**b**: the value to write to the bit (0 or 1).
+
+Returns
+-------
+
+Nothing.
+
+Arduino Compatibility
+---------------------
+
+Maple's version of ``bitWrite()`` is compatible with Arduino.
+
+See also
+--------
+
+- :ref:`bit() <lang-bit>`
+- :ref:`bitRead() <lang-bitRead>`
+- :ref:`bitSet() <lang-bitSet>`
+- :ref:`bitClear() <lang-bitClear>`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/cc-attribution.txt b/source/lang/api/cc-attribution.txt
new file mode 100644
index 0000000..e100140
--- /dev/null
+++ b/source/lang/api/cc-attribution.txt
@@ -0,0 +1,9 @@
+.. 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/source/lang/api/constants.rst b/source/lang/api/constants.rst
new file mode 100644
index 0000000..bc5c894
--- /dev/null
+++ b/source/lang/api/constants.rst
@@ -0,0 +1,304 @@
+.. _lang-constants:
+
+Constants
+=========
+
+Constants are like predefined variables, whose values can't
+change. They are used to make the programs easier to read and modify.
+This page describes the most commonly used constants.
+
+.. contents:: Contents
+ :local:
+
+.. _lang-constants-bool:
+
+Boolean Constants
+-----------------
+
+There are two constants used to represent truth and falsity: ``true``,
+and ``false``.
+
+.. _lang-constants-false:
+
+false
+^^^^^
+
+``false`` is the false ``bool`` value. An integer which is 0 evaluates
+to ``false`` as a boolean.
+
+.. _lang-constants-true:
+
+true
+^^^^
+
+``true`` is the true ``bool`` value. As an integer, ``true`` is often
+said to be 1. This is correct in the sense that ``true`` evaluates to
+1 as an integer. However, any integer which is *non-zero* is ``true``
+as a :ref:`bool <lang-booleanvariables>`. So -1, 2 and -200 are all
+"true", in the sense that these numbers are treated the same as
+``true`` in a boolean context.
+
+Note that the ``true`` and ``false`` constants are typed in lowercase;
+unlike e.g. ``HIGH``, ``LOW``, ``INPUT``, and ``OUTPUT`` (which are
+described below).
+
+
+Pin Levels: HIGH and LOW
+------------------------
+
+When reading or writing to a digital pin there are only two possible
+values a pin can be set to: ``HIGH`` and ``LOW``.
+
+.. _lang-constants-high:
+
+HIGH
+^^^^
+
+The meaning of ``HIGH`` (in reference to a pin) is somewhat different
+depending on whether the pin is set to ``INPUT`` or ``OUTPUT``. When a
+pin is configured as an ``INPUT`` (using :ref:`pinMode()
+<lang-pinmode>`), and read with :ref:`digitalRead()
+<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
+that is connected through a series resistor to ground, or to another
+pin configured as an output and set to ``LOW``.
+
+.. _lang-constants-low:
+
+LOW
+^^^
+
+The meaning of ``LOW`` also has a different meaning depending on
+whether a pin is set to ``INPUT`` or ``OUTPUT``. When a pin is
+configured as an ``INPUT`` with :ref:`pinMode() <lang-pinmode>`, and
+read with :ref:`digitalRead() <lang-digitalread>`, the microcontroller
+will report ``LOW`` if a voltage of 2 volts or less is present at the
+pin.
+
+When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to
+``LOW`` with :ref:`digitalWrite() <lang-digitalwrite>`, the
+microcontroller will attempt to keep that pin's voltage at 0V. In this
+state it can *sink* current, e.g. light an LED that is connected
+through a series resistor to +3.3V, or to another pin configured as an
+output, and set to ``HIGH``.
+
+Pin Modes
+---------
+
+Digital pins can be used in a variety of modes. The basic modes,
+``INPUT`` and ``OUTPUT``, have been introduced above. Changing a pin
+from ``INPUT`` TO ``OUTPUT`` with :ref:`pinMode() <lang-pinmode>`
+drastically changes the electrical behavior of the pin.
+
+This section describes the basic digital pin modes (``INPUT`` and
+``OUTPUT``) only. For a detailed description of all possible pin
+modes, see the :ref:`pinMode() <lang-pinmode>` reference page.
+
+.. _lang-constants-input:
+
+INPUT
+^^^^^
+
+Maple (STM32) pins configured as ``INPUT`` are said to be in a
+high-impedance state. One way of explaining this is that pins
+configured as ``INPUT`` make extremely small demands on the circuit
+that they are sampling. This makes them useful for reading a sensor,
+but not powering an LED.
+
+.. _lang-constants-output:
+
+OUTPUT
+^^^^^^
+
+Pins configured as ``OUTPUT`` with :ref:`pinMode() <lang-pinmode>` are
+said to be in a low-impedance state. This means that they can provide
+a substantial amount of current to other circuits. STM32 pins can
+source (provide positive current) or sink (provide negative current)
+up to 50 mA (milliamps) of current to other devices/circuits. This
+makes them useful for powering LEDs, but useless for reading sensors.
+
+Pins configured as outputs can also be damaged or destroyed if short
+circuited to either ground or 3.3V power rails. The amount of current
+provided by an STM32 pin is also not enough to power most relays or
+motors, and some interface circuitry will be required.
+
+.. _lang-constants-integers:
+
+Integer Constants
+-----------------
+
+Integer constants (or more properly speaking, integer *literals*) are
+numbers used directly in a sketch, like ``123``. By default, an
+integer literal is treated as a (signed) :ref:`int <lang-int>`, but
+you can change this with the U and L modifiers (see :ref:`below
+<lang-constants-integers-u-l>`). You can specify negative numbers by
+putting a minus sign in front, like ``-123``.
+
+Normally, integer literals are treated as base 10 (decimal) integers,
+but special notation (formatters) may be used to enter numbers in
+other bases. These are summarized in the following table:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Base
+ - Example
+ - Formatter
+ - Comment
+
+ * - 10 (decimal)
+ - ``123``
+ - None
+ -
+
+ * - 2 (binary)
+ - ``0b1111011``
+ - Leading "0b"
+ - GCC extension; not standard C++
+
+ * - 8 (octal)
+ - ``0173``
+ - Leading "0"
+ - Characters 0-7 valid
+
+ * - 16 (hexadecimal)
+ - ``0x7B``
+ - Leading "0x"
+ - Characters 0-9, A-F (or a-f) valid
+
+Binary constants (like ``B1111011``) for values between 0 and 255 are
+supported for compatibility with Arduino only. Their use in new
+programs is discouraged.
+
+.. _lang-constants-integers-dec:
+
+**Decimal** is base 10. This is the common number system we learn in
+school. Integer literals without other prefixes are assumed to be in
+decimal format.
+
+For example, the decimal literal ``101`` is one hundred and one: 1×10\
+:sup:`2` + 0×10\ :sup:`1` + 1×10\ :sup:`0` = 101.
+
+.. _lang-constants-integers-bin:
+
+**Binary** is base two. Only characters 0 and 1 are valid. Binary
+literals are indicated by the prefix ``0b`` (this is a :ref:`GCC
+<arm-gcc>` extension; it's not standard C++).
+
+For example, the binary literal ``0b101`` is five: 1×2\ :sup:`2` +
+0×2\ :sup:`1` + 1×2\ :sup:`0` = 5.
+
+.. _lang-constants-integers-oct:
+
+**Octal** is base eight. Only characters 0 through 7 are valid. Octal
+literals are indicated by the prefix ``0``.
+
+For example, the octal literal ``0101`` is sixty five: 1×8\ :sup:`2` +
+0×8\ :sup:`1` + 1×8\ :sup:`0` = 65.
+
+.. warning:: Bugs sometimes result by (unintentionally) including a
+ leading "0" before an integer literal, which makes the compiler
+ interpret it in octal.
+
+.. _lang-constants-integers-hex:
+
+**Hexadecimal** (or "hex") is base sixteen. Valid characters are 0
+through 9 and letters A through F; A has the value 10, B is 11, up to
+F, which is 15. Hex values are indicated by the prefix ``0x``. A-F
+may be typed in upper or lower case (a-f).
+
+For example, the hexadecimal literal ``0x101`` is two hundred fifty
+seven: 1×16\ :sup:`2` + 0×16\ :sup:`1` + 1×16\ :sup:`0` = 257.
+
+The hexadecimal literal ``0xCF2`` is three thousand, three hundred
+fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314.
+
+(Remember that in hex, ``A`` means 10, and counting up, ``B``\ =11, so
+``C``\ =12 and ``F``\ =15).
+
+.. _lang-constants-integers-u-l:
+
+U and L Suffixes
+^^^^^^^^^^^^^^^^
+
+By default, an integer constant is treated as an :ref:`int
+<lang-int>`, with the attendant :ref:`limitations in values
+<lang-int-overflow>`. To specify an integer constant with another data
+type, follow it with:
+
+- a ``u`` or ``U`` to interpret the constant as an unsigned value.
+ For example, ``33U`` is an :ref:`unsigned int <lang-unsignedint>`.
+
+- an ``l`` or ``L`` to interpret the constant as a long value. For
+ example, ``100000L`` is a :ref:`long <lang-long>`.
+
+- a ``ul`` or ``UL`` to do both. For example, ``32767UL`` is an
+ :ref:`unsigned long <lang-unsignedlong>`.
+
+.. _lang-constants-fp:
+
+Floating-Point Constants
+------------------------
+
+Similar to integer literals, floating point constants (properly:
+floating-point *literals*) are used to make code more readable.
+Floating point literals are swapped at compile time for the value to
+which the expression evaluates.
+
+A floating point literal is any number which includes a decimal point.
+For instance, ``3.0`` is a floating-point literal for the number 3.
+By default, a floating-point literal is a :ref:`double <lang-double>`.
+In order for the literal to be interpreted as a :ref:`float
+<lang-float>`, you can write ``f`` directly after it. For example,
+``3.0f`` is a floating-point literal with type ``float``.
+
+Floating point constants can also be expressed in a variety of
+scientific notation. ``E`` and ``e`` are both accepted as valid
+exponent indicators. Some examples are given in the following table:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Floating-point literal
+ - Evaluates to
+ - Alternate expression
+
+ * - ``10.0``
+ - 10
+ -
+
+ * - ``2.34E5``
+ - 2.34×10\ :sup:`5`
+ - ``234000.0``
+
+ * - ``67e-12``
+ - 67.0×10\ :sup:`-12`
+ - ``0.000000000067``
+
+See Also
+--------
+
+- :ref:`pinMode() <lang-pinmode>`
+- :ref:`Boolean Variables <lang-booleanvariables>`
+- :ref:`#define <lang-define>`
+- :ref:`int <lang-int>`
+- :ref:`unsigned int <lang-unsignedint>`
+- :ref:`long <lang-long>`
+- :ref:`unsigned long <lang-unsignedlong>`
+- :ref:`float <lang-float>`
+- :ref:`double <lang-double>`
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/constrain.rst b/source/lang/api/constrain.rst
new file mode 100644
index 0000000..d19b61c
--- /dev/null
+++ b/source/lang/api/constrain.rst
@@ -0,0 +1,69 @@
+.. highlight:: cpp
+
+.. _lang-constrain:
+
+constrain()
+===========
+
+(Macro) Constrains a number to be within a range.
+
+Syntax
+------
+
+::
+
+ constrain(x, a, b)
+
+
+Parameters
+----------
+
+**x**: the number to constrain
+
+**a**: the lower end of the range
+
+**b**: the upper end of the range
+
+Returns
+-------
+
+**x**: if **x** is between **a** and **b**
+
+**a**: if **x** is less than **a**
+
+**b**: if **x** is greater than **b**
+
+Example
+-------
+
+::
+
+ // limits range of sensor values to between 10 and 150:
+ sensVal = constrain(sensVal, 10, 150);
+
+
+Warning
+-------
+
+Because of the way ``constrain()`` is implemented, avoid using other
+functions or causing side effects inside the parentheses, as it may
+lead to incorrect results::
+
+ constrain(x,a++,b); // avoid this - yields incorrect results
+
+ constrain(x,a,b); // use this instead-
+ a++; // keep other math outside constrain()
+
+Arduino Compatibility
+---------------------
+
+Maple's implementation of ``constrain()`` is compatible with Arduino.
+
+See also
+--------
+
+- :ref:`min() <lang-min>`
+- :ref:`max() <lang-max>`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/cos.rst b/source/lang/api/cos.rst
new file mode 100644
index 0000000..3fbb0af
--- /dev/null
+++ b/source/lang/api/cos.rst
@@ -0,0 +1,32 @@
+.. _lang-cos:
+
+cos()
+=====
+
+Calculates the cosine of an angle.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: cos
+
+Arduino Compatibility
+---------------------
+
+The Maple ``cos()`` implementation is compatible with Arduino.
+
+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
+--------
+
+
+- :ref:`sin() <lang-sin>`
+- :ref:`tan() <lang-tan>`
+- :ref:`float <lang-float>`
+- :ref:`double <lang-double>`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/delay.rst b/source/lang/api/delay.rst
new file mode 100644
index 0000000..90ca268
--- /dev/null
+++ b/source/lang/api/delay.rst
@@ -0,0 +1,72 @@
+.. highlight:: cpp
+
+.. _lang-delay:
+
+delay()
+=======
+
+Pauses the program for at least a given number of milliseconds. (There
+are 1000 milliseconds in a second.)
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: delay
+
+
+Discussion
+----------
+
+While it is easy to create a blinking LED with the ``delay()``
+function, and many sketches use short delays for such tasks as switch
+debouncing, the use of ``delay()`` in a sketch has significant
+drawbacks. No other reading of sensors, mathematical calculations, or
+pin manipulation can go on during the delay function, so in effect, it
+brings most other activity to a halt. For alternative approaches to
+controlling timing see the :ref:`millis() <lang-millis>` function
+and the "Blink Without Delay" sketch cited :ref:`below
+<lang-delay-seealso>`\ . More knowledgeable programmers usually
+avoid the use of ``delay()`` for timing of events longer than tens of
+milliseconds, unless the sketch is very simple.
+
+Certain things *do* go on while the ``delay()`` function is
+controlling the STM32 chip, however, because the delay function does
+not disable interrupts. Serial communication that appears at the RX
+pin is recorded, PWM (see :ref:`pwmWrite() <lang-pwmwrite>`\ ) values
+and pin states are maintained, and :ref:`interrupts
+<lang-attachinterrupt>` will work as they should.
+
+
+Example
+-------
+
+::
+
+ int ledPin = 13; // LED connected to pin 13
+
+ void setup() {
+ pinMode(ledPin, 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
+ }
+
+.. _lang-delay-seealso:
+
+See also
+--------
+
+
+- :ref:`millis() <lang-millis>`
+- :ref:`micros() <lang-micros>`
+- :ref:`delayMicroseconds() <lang-delayMicroseconds>`
+- (Arduino) `Blink Without Delay
+ <http://arduino.cc/en/Tutorial/BlinkWithoutDelay>`_ example (works
+ unmodified on Maple)
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/delaymicroseconds.rst b/source/lang/api/delaymicroseconds.rst
new file mode 100644
index 0000000..24a8286
--- /dev/null
+++ b/source/lang/api/delaymicroseconds.rst
@@ -0,0 +1,65 @@
+.. highlight:: cpp
+
+.. _lang-delaymicroseconds:
+
+delayMicroseconds()
+===================
+
+Pauses the program for the amount of time (in microseconds)
+specified as parameter. There are a thousand microseconds in a
+millisecond, and a million microseconds in a second.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: delayMicroseconds
+
+
+Example
+-------
+
+The following example configures pin number 8 to work as an output
+pin, and sends a train of pulses with a period of roughly 100
+microseconds::
+
+ int outPin = 8;
+
+ void setup() {
+ pinMode(outPin, OUTPUT); // sets the digital pin as output
+ }
+
+ void loop() {
+ digitalWrite(outPin, HIGH); // sets the pin on
+ delayMicroseconds(50); // pauses for 50 microseconds
+ digitalWrite(outPin, LOW); // sets the pin off
+ delayMicroseconds(50); // pauses for 50 microseconds
+ }
+
+
+Caveats and Known Issues
+------------------------
+
+The longest time ``delayMicroseconds()`` can delay is bounded by its
+argument type and the STM32 clock rate to be (2^32 - 1) / 12
+microseconds, or less than 6 minutes. For longer pauses, use of
+:ref:`lang-delay` is possible.
+
+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``.
+
+See Also
+--------
+
+- :ref:`millis <lang-millis>`
+- :ref:`micros <lang-micros>`
+- :ref:`delay <lang-delay>`
+
+
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/detachinterrupt.rst b/source/lang/api/detachinterrupt.rst
new file mode 100644
index 0000000..adb2439
--- /dev/null
+++ b/source/lang/api/detachinterrupt.rst
@@ -0,0 +1,37 @@
+.. _lang-detachinterrupt:
+
+detachInterrupt()
+=================
+
+Used to disable an interrupt specified with
+:ref:`lang-attachinterrupt`\ .
+
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: detachInterrupt
+
+Arduino Compatibility
+---------------------
+
+There is one important difference between the Maple version of
+detachInterrupt and the Arduino version. On the Maple, the argument
+to ``detachInterrupt()`` is the *pin* on which the interrupt is
+attached, while on the Arduino, the argument is the *interrupt
+number*, which is different from the pin the interrupt is enabled on.
+
+If you're calling this function, you've already called
+:ref:`lang-attachinterrupt` to set up your interrupt handler, so
+just call ``detachInterrupt()`` with the same pin argument you gave to
+``attachInterrupt()``.
+
+See Also
+--------
+
+- :ref:`attachInterrupt() <lang-attachInterrupt>`
+
+
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/digitalread.rst b/source/lang/api/digitalread.rst
new file mode 100644
index 0000000..3502587
--- /dev/null
+++ b/source/lang/api/digitalread.rst
@@ -0,0 +1,58 @@
+.. highlight:: cpp
+
+.. _lang-digitalread:
+
+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
+
+
+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
+
+ void setup() {
+ pinMode(ledPin, OUTPUT);
+ pinMode(buttonPin, INPUT);
+ }
+
+ void loop() {
+ int val = digitalRead(buttonPin); // reads the input pin
+ digitalWrite(ledPin, 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>`
+
+
+
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/digitalwrite.rst b/source/lang/api/digitalwrite.rst
new file mode 100644
index 0000000..6124d5f
--- /dev/null
+++ b/source/lang/api/digitalwrite.rst
@@ -0,0 +1,68 @@
+.. highlight:: cpp
+
+.. _lang-digitalwrite:
+
+digitalWrite()
+==============
+
+Write a :ref:`HIGH <lang-constants-high>` or a :ref:`LOW
+<lang-constants-low>` value to a pin configured as :ref:`OUTPUT
+<lang-constants-output>`.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: digitalWrite
+
+Discussion
+----------
+
+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.
+
+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
+
+ void setup() {
+ pinMode(ledPin, 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
+ }
+
+See Also
+--------
+
+- :ref:`pinMode <lang-pinmode>`
+- :ref:`digitalRead <lang-digitalread>`
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/highbyte.rst b/source/lang/api/highbyte.rst
new file mode 100644
index 0000000..50a1fa6
--- /dev/null
+++ b/source/lang/api/highbyte.rst
@@ -0,0 +1,59 @@
+.. highlight:: cpp
+
+.. _lang-highbyte:
+
+highByte()
+==========
+
+(Macro) Extracts the second lowest byte of an integral data type.
+
+.. warning:: This macro is provided for compatibility with Arduino
+ only. It returns the second-least significant byte in an integral
+ value. It makes sense to call this the "high" byte on a 16-bit
+ ``int`` microcontroller like the Atmel chips on Arduinos, but it
+ makes no sense at all on a 32-bit microcontroller like the STM32s
+ in the Maple line.
+
+ In short: we provide this so that existing Arduino code works as
+ expected, but **strongly discourage its use** in new programs.
+
+Syntax
+------
+
+::
+
+ highByte(x)
+
+Parameters
+----------
+
+**x**: a value of any integral type.
+
+Returns
+-------
+
+Second lowest byte in **x**.
+
+Example
+-------
+
+::
+
+ int x = 0xDEADBEEF;
+ SerialUSB.println(x, HEX); // prints "BE"
+
+Arduino Compatibility
+---------------------
+
+The Maple version of ``highByte()`` is compatible with Arduino.
+
+See Also
+--------
+
+- :ref:`lowByte() <lang-lowbyte>`
+
+
+
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/loop.rst b/source/lang/api/loop.rst
new file mode 100644
index 0000000..d8f6183
--- /dev/null
+++ b/source/lang/api/loop.rst
@@ -0,0 +1,45 @@
+.. highlight:: cpp
+
+.. _lang-loop:
+
+loop()
+======
+
+After creating a :ref:`setup() <lang-setup>` function, which
+initializes your sketch, the ``loop()`` function gets called
+repeatedly, allowing your program to change and respond. Use it to
+actively control your Maple board.
+
+Example
+-------
+
+::
+
+
+ int buttonPin = 38;
+
+ // setup initializes serial and the button pin
+ void setup() {
+ SerialUSB.begin();
+ pinMode(buttonPin, INPUT);
+ }
+
+ // loop() checks the button pin each time it executes,
+ // and will print 'H' if it is pressed, 'L' otherwise
+ void loop() {
+ if (digitalRead(buttonPin) == HIGH) {
+ SerialUSB.println('H');
+ } else {
+ SerialUSB.println('L');
+ }
+
+ delay(1000);
+ }
+
+See Also
+--------
+
+- :ref:`setup() <lang-setup>`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/lowbyte.rst b/source/lang/api/lowbyte.rst
new file mode 100644
index 0000000..58e622f
--- /dev/null
+++ b/source/lang/api/lowbyte.rst
@@ -0,0 +1,25 @@
+.. _lang-lowbyte:
+
+lowByte()
+=========
+
+Extracts the low-order (rightmost) byte of a variable (e.g. a
+word).
+
+Syntax
+------
+
+lowByte(x)
+
+Parameters
+----------
+
+**x**: a value of any type. However, if a non-integral type is used,
+the results will be strange.
+
+Returns
+-------
+
+The low byte's value (this will be between 0 and 255).
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/map.rst b/source/lang/api/map.rst
new file mode 100644
index 0000000..79122b3
--- /dev/null
+++ b/source/lang/api/map.rst
@@ -0,0 +1,68 @@
+.. highlight:: cpp
+
+.. _lang-map:
+
+map()
+=====
+
+Re-maps a number from one range to another.
+
+.. contents:: Contents
+ :local:
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: map
+
+Discussion
+----------
+
+``map()`` does not constrain values to within the range, because
+out-of-range values are sometimes intended and useful. The
+:ref:`constrain() <lang-constrain>` macro may be used either before or
+after this function, if limits to the ranges are desired.
+
+Note that the "lower bounds" of either range may be larger or smaller
+than the "upper bounds" so that ``map()`` may be used to reverse a
+range of numbers; for example::
+
+ y = map(x, 1, 50, 50, 1);
+
+The function also handles negative numbers well, so that this
+example ::
+
+ y = map(x, 1, 50, 50, -100);
+
+is also valid.
+
+The ``map()`` function uses integer math (its arguments and return
+values all have type :ref:`long <lang-long>`), so it will not generate
+fractions, when the math might indicate that it should do so.
+Fractional remainders are truncated, and are not rounded or averaged.
+
+Example
+-------
+
+::
+
+ /* Map an ADC reading (12 bits) to 16-bit PWM (0 to 65,535) */
+
+ void setup() {
+ pinMode(0, INPUT_ANALOG);
+ pinMode(9, PWM);
+ }
+
+ void loop() {
+ int val = analogRead(0);
+ val = map(val, 0, 4095, 0, 65535);
+ analogWrite(9, val);
+ }
+
+
+See Also
+--------
+
+- :ref:`constrain() <lang-constrain>`
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/max.rst b/source/lang/api/max.rst
new file mode 100644
index 0000000..d38eebe
--- /dev/null
+++ b/source/lang/api/max.rst
@@ -0,0 +1,65 @@
+.. highlight:: cpp
+
+.. _lang-max:
+
+max()
+=====
+
+(Macro) Calculates the maximum of two numbers.
+
+Syntax
+------
+
+::
+
+ max(x, y)
+
+Parameters
+----------
+
+**x**: the first number; may be any number or numeric expression.
+
+**y**: the second number; may be any number or numeric expression.
+
+
+Returns
+-------
+
+The larger of the two parameter values.
+
+Example
+-------
+
+::
+
+ sensVal = max(senVal, 20); // assigns sensVal to the larger of sensVal or 20
+ // (effectively ensuring that it is at least 20)
+
+.. note:: Perhaps counter-intuitively, max() is often used to
+ constrain the lower end of a variable's range, while :ref:`min()
+ <lang-min>` is used to constrain the upper end of the range.
+
+Warning
+-------
+
+Because of the way ``max()`` is implemented, avoid using other
+functions inside the parentheses. It may lead to incorrect results::
+
+ max(a--, 0); // avoid this - yields incorrect results
+
+ a--; // use this instead -
+ max(a, 0); // keep other operations outside max()
+
+Arduino Compatibility
+---------------------
+
+The Maple version of ``max()`` is compatible with Arduino.
+
+See Also
+--------
+
+- :ref:`min() <lang-min>`
+- :ref:`constrain() <lang-constrain>`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/micros.rst b/source/lang/api/micros.rst
new file mode 100644
index 0000000..f12976b
--- /dev/null
+++ b/source/lang/api/micros.rst
@@ -0,0 +1,46 @@
+.. highlight:: cpp
+
+.. _lang-micros:
+
+micros()
+========
+
+Returns the number of microseconds since the Maple board began running
+the current program. This number will overflow (go back to zero),
+after approximately 70 minutes.
+
+.. note:: There are 1,000 microseconds in a millisecond, and 1,000,000
+ microseconds in a second.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: micros
+
+Example
+-------
+
+::
+
+ unsigned int time;
+
+ void setup() {
+ }
+
+ void loop() {
+ SerialUSB.print("Time: ");
+ time = micros();
+ // prints time since program started
+ SerialUSB.println(time);
+ // wait a second so as not to send massive amounts of data
+ delay(1000);
+ }
+
+See Also
+--------
+
+- :ref:`millis() <lang-millis>`
+- :ref:`delay() <lang-delay>`
+- :ref:`delayMicroseconds() <lang-delaymicroseconds>`
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/millis.rst b/source/lang/api/millis.rst
new file mode 100644
index 0000000..54e4507
--- /dev/null
+++ b/source/lang/api/millis.rst
@@ -0,0 +1,52 @@
+.. highlight:: cpp
+
+.. _lang-millis:
+
+millis()
+========
+
+Returns the number of milliseconds since the Maple board began running
+the current program. This number will overflow (go back to zero) after
+approximately 50 days.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: millis
+
+Example
+-------
+
+The following time prints the value returned by ``millis()`` roughly
+once per second::
+
+ unsigned int time;
+
+ void setup() {
+ }
+
+ void loop() {
+ SerialUSB.print("Time: ");
+ time = millis();
+ // prints time since program started
+ Serial.println(time);
+
+ // wait a second so as not to send massive amounts of data
+ delay(1000);
+ }
+
+Tip
+---
+
+Since the return value for ``millis()`` is an :ref:`unsigned long
+<lang-unsignedlong>`, overflow errors may occur if you try to do math
+with other data types, such as :ref:`ints <lang-int>`.
+
+See Also
+--------
+
+- :ref:`micros <lang-micros>`
+- :ref:`delay <lang-delay>`
+- :ref:`delayMicroseconds <lang-delaymicroseconds>`
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/min.rst b/source/lang/api/min.rst
new file mode 100644
index 0000000..1245f6f
--- /dev/null
+++ b/source/lang/api/min.rst
@@ -0,0 +1,66 @@
+.. highlight:: cpp
+
+.. _lang-min:
+
+min()
+=====
+
+(Macro) Calculates the minimum of two numbers.
+
+Syntax
+------
+
+::
+
+ min(x,y)
+
+Parameters
+----------
+
+**x**: the first number; may be any number or numeric expression.
+
+**y**: the second number; may be any number or numeric expression.
+
+Returns
+-------
+
+The smaller of the two numbers.
+
+Example
+-------
+
+::
+
+ sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100
+ // ensuring that it never gets above 100.
+
+
+.. note:: Perhaps counter-intuitively, max() is often used to
+ constrain the lower end of a variable's range, while min() is used
+ to constrain the upper end of the range.
+
+
+Warning
+-------
+
+Because of the way ``min()`` is implemented, avoid using other
+functions inside the parentheses. It may lead to incorrect results::
+
+ min(a++, 100); // avoid this - yields incorrect results
+
+ a++; // use this instead -
+ min(a, 100); // keep other operations outside min()
+
+Arduino Compatibility
+---------------------
+
+The Maple version of ``min()`` is compatible with Arduino.
+
+See Also
+--------
+
+- :ref:`max() <lang-max>`
+- :ref:`constrain() <lang-constrain>`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/pinmode.rst b/source/lang/api/pinmode.rst
new file mode 100644
index 0000000..b9095da
--- /dev/null
+++ b/source/lang/api/pinmode.rst
@@ -0,0 +1,77 @@
+.. highlight:: cpp
+
+.. _lang-pinmode:
+
+pinMode()
+=========
+
+.. contents:: Contents
+ :local:
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: pinMode
+
+.. doxygenenum:: WiringPinMode
+
+Discussion
+----------
+
+``pinMode()`` is usually called within :ref:`lang-setup` in order to
+configure a pin for a certain usage (although it may be called
+anywhere).
+
+Example
+-------
+
+::
+
+ int ledPin = 13; // LED connected to digital pin 13
+
+ void setup() {
+ pinMode(ledPin, 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
+ }
+
+Arduino Compatibility
+---------------------
+
+.. TODO check out Arduino vs. Maple static discilpline cutoffs to
+.. ensure accuracy of following:
+
+The libmaple implementation of ``pinMode()`` supports the ``INPUT``
+and ``OUTPUT`` modes with semantics identical to that of the Arduino
+function (however, be advised that the Maple, as a 3.3V device, will
+only drive 3.3V to an ``OUTPUT`` pin that has been set ``HIGH``).
+
+``INPUT_ANALOG`` and ``PWM`` modes were added because the Maple does
+not distinguish between analog and digital pins the same way the
+Arduino does. Unlike the Arduino, you **must call** ``pinMode()`` to
+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:
+
+.. ``OUTPUT_OPEN_DRAIN``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``, and
+.. ``PWM_OPEN_DRAIN`` modes represent functionality not currently
+.. available on Arduino boards.
+
+See also
+--------
+
+- :ref:`lang-constants`
+- :ref:`lang-digitalwrite`
+- :ref:`lang-digitalread`
+- Maple :ref:`GPIO <gpio>` reference page
+
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/pow.rst b/source/lang/api/pow.rst
new file mode 100644
index 0000000..4280400
--- /dev/null
+++ b/source/lang/api/pow.rst
@@ -0,0 +1,23 @@
+.. _lang-pow:
+
+pow()
+=====
+
+Calculates the value of a number raised to a power.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: pow
+
+.. TODO LATER some examples
+
+See Also
+--------
+
+- :ref:`sqrt() <lang-sqrt>`
+- :ref:`float <lang-float>`
+- :ref:`double <lang-double>`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/pwmwrite.rst b/source/lang/api/pwmwrite.rst
new file mode 100644
index 0000000..7a1d51f
--- /dev/null
+++ b/source/lang/api/pwmwrite.rst
@@ -0,0 +1,49 @@
+.. highlight:: cpp
+
+.. _lang-pwmwrite:
+
+pwmWrite()
+==========
+
+Writes a :ref:`PWM wave <pwm>` to a pin. You can use this to make an
+LED get brighter or dimmer, control a servomotor, etc. After a call to
+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.
+
+.. contents:: Contents
+ :local:
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: pwmWrite
+
+Example
+-------
+
+Sets the output to the LED proportional to the value read from the
+potentiometer::
+
+ int ledPin = 13; // LED connected to pin 13 (Maple)
+ int analogPin = 3; // potentiometer connected to analog pin 3
+ int val = 0; // variable to store the read value
+
+ void setup() {
+ pinMode(ledPin, OUTPUT); // sets the LED pin as output
+
+ pinMode(analogPin, PWM); // sets the potentiometer pin as PWM
+ // output
+ }
+
+ void loop() {
+ val = analogRead(analogPin); // read the input pin
+
+ analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095,
+ // analogWrite values from 0 to 65535
+ }
+
+See Also
+--------
+
+- :ref:`Maple PWM tutorial <pwm>`
diff --git a/source/lang/api/random.rst b/source/lang/api/random.rst
new file mode 100644
index 0000000..f2a9762
--- /dev/null
+++ b/source/lang/api/random.rst
@@ -0,0 +1,73 @@
+.. highlight:: cpp
+
+.. _lang-random:
+
+random()
+========
+
+The ``random()`` function generates pseudo-random numbers.
+
+.. TODO keep tracking Sphinx/Breathe's ability to reference overloaded
+.. functions so we can use doxygenfunction instead of manually
+.. documenting this.
+
+Library Documentation
+---------------------
+
+.. cpp:function:: random(long max)
+
+ Same as a call to ``random(0, max)``.
+
+.. cpp:function:: random(long min, long max)
+
+ Generate a pseudo-random number with given lower and upper bounds.
+
+ *Parameters*
+
+ - ``min`` - Lower bound on the returned value, inclusive
+ - ``max`` - Upper bound on the returned value, exclusive
+
+ *Returns*: A pseudo-random number in the range [min, max).
+
+Discussion
+----------
+
+If it is important for a sequence of values generated by
+:ref:`random() <lang-random>` to differ, on subsequent executions of a
+sketch, use :ref:`randomSeed() <lang-randomseed>` to initialize the
+random number generator with a fairly random input, such as
+:ref:`analogRead() <lang-analogread>` on an unconnected pin.
+
+Conversely, it can occasionally be useful to use pseudorandom
+sequences that repeat exactly. This can be accomplished by calling
+``randomSeed()`` with a fixed number, before starting the random
+sequence.
+
+Example
+-------
+
+The following sketch initializes the random seed based on an :ref:`ADC
+<adc>` reading of pin 0. If this pin is unconnected, the Sketch
+should print different values to the :ref:`serial monitor
+<ide-serial-monitor>` each time it is run::
+
+ long randNumber;
+
+ void setup() {
+ pinMode(0, INPUT_ANALOG);
+ randomSeed(analogRead(0));
+ }
+
+ void loop() {
+ randNumber = random(300);
+ SerialUSB.println(randNumber);
+
+ delay(50);
+ }
+
+See Also
+--------
+
+- :ref:`randomSeed() <lang-randomseed>`
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/randomseed.rst b/source/lang/api/randomseed.rst
new file mode 100644
index 0000000..d0a15b7
--- /dev/null
+++ b/source/lang/api/randomseed.rst
@@ -0,0 +1,60 @@
+.. highlight:: cpp
+
+.. _lang-randomseed:
+
+randomSeed()
+============
+
+``randomSeed()`` initializes the `pseudorandom number generator
+<http://en.wikipedia.org/wiki/Pseudorandom_number_generator>`_,
+causing it to start at an arbitrary point in its random sequence.
+This sequence, while very long, and random, is always the same.
+
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: randomSeed
+
+Discussion
+----------
+
+If it is important for a sequence of values generated by
+:ref:`random() <lang-random>` to differ, on subsequent executions of a
+sketch, use ``randomSeed()`` to initialize the random number generator
+with a fairly random input, such as :ref:`analogRead()
+<lang-analogread>` on an unconnected pin.
+
+Conversely, it can occasionally be useful to use pseudorandom
+sequences that repeat exactly. This can be accomplished by calling
+``randomSeed()`` with a fixed number, before starting the random
+sequence.
+
+Example
+-------
+
+The following sketch initializes the random seed based on an :ref:`ADC
+<adc>` reading of pin 0. If this pin is unconnected, the Sketch
+should print different values to the :ref:`serial monitor
+<ide-serial-monitor>` each time it is run::
+
+ long randNumber;
+
+ void setup() {
+ pinMode(0, INPUT_ANALOG);
+ randomSeed(analogRead(0));
+ }
+
+ void loop() {
+ randNumber = random(300);
+ SerialUSB.println(randNumber);
+
+ delay(50);
+ }
+
+See Also
+--------
+
+- :ref:`random() <lang-random>`
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst
new file mode 100644
index 0000000..ca89b31
--- /dev/null
+++ b/source/lang/api/serial.rst
@@ -0,0 +1,226 @@
+.. _lang-serial:
+
+Serial Ports (``Serial1``, ``Serial2``, ``Serial3``)
+====================================================
+
+Used for communication between the Maple board and a computer or other
+devices.
+
+.. contents:: Contents
+ :local:
+
+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:
+
+.. 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.
+
+.. warning:: Don't connect these pins directly to an RS232 serial
+ port; they operate at +/- 12V and can damage your board.
+
+
+Library Documentation
+---------------------
+
+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``,
+``Serial2``, and ``Serial3``).
+
+.. cpp:class:: HardwareSerial
+
+ Serial port class. Predefined instances are ``Serial1``,
+ ``Serial2``, and ``Serial3``.
+
+.. cpp:function:: HardwareSerial::begin(unsigned int baud)
+
+ Set up a ``HardwareSerial`` object for communications. This method
+ must be called before attempting to use the ``HardwareSerial``
+ object (typically, you call this in your :ref:`setup()
+ <lang-setup>` function).
+
+.. cpp:function:: HardwareSerial::end()
+
+ Disables the USART associated with this object, allowing any
+ associated communication pins to be used for other purposes.
+
+.. cpp:function:: unsigned int HardwareSerial::available()
+
+ Returns the number of bytes available for reading.
+
+.. cpp:function:: unsigned char HardwareSerial::read()
+
+ Returns the next available, unread character. If there are no
+ available characters (you can check this with :cpp:func:`available
+ <HardwareSerial::available>`), the call will block until one
+ becomes available.
+
+.. cpp:function:: HardwareSerial::flush()
+
+ Removes the contents of the Serial's associated USART RX FIFO.
+ That is, clears any buffered characters, so that the next character
+ read is guaranteed to be new.
+
+.. cpp:function:: HardwareSerial::print(unsigned char b)
+
+ Print the given byte over the USART.
+
+.. cpp:function:: HardwareSerial::print(char c)
+
+ Print the given character over the USART. 7-bit clean characters
+ are typically interpreted as ASCII text.
+
+.. cpp:function:: HardwareSerial::print(const char *str)
+
+ Print the given null-terminated string over the USART.
+
+.. cpp:function:: HardwareSerial::print(int 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 int n)
+
+ Print the argument's digits over the USART, in decimal format.
+
+.. 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 n)
+
+ Print the argument's digits over the USART, in decimal format.
+
+.. cpp:function:: HardwareSerial::print(long n, int base)
+
+ 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 2 digits after the decimal point.
+
+.. _lang-serial-println:
+
+.. cpp:function:: HardwareSerial::println(char c)
+
+ Like ``print(c)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println(const char *c)
+
+ Like ``print(c)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println(unsigned char b)
+
+ Like ``print(b)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println(int n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println(unsigned int n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println(long n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println(unsigned long n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println(long n, int base)
+
+ Like ``print(n, b)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println(double n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println()
+
+ Prints ``"\r\n"`` over the USART.
+
+.. cpp:function:: HardwareSerial::write(unsigned char ch)
+
+ Sends one character over the USART. This function is currently
+ blocking, although nonblocking writes are a planned future
+ extension.
+
+ This is a low-level function. One of the ``print()`` or
+ ``println()`` functions is likely to be more useful when printing
+ multiple characters, when formatting numbers for printing, etc.
+
+.. cpp:function:: HardwareSerial::write(const char* str)
+
+ Send the given null-terminated character string over the USART.
+
+ This is a low-level function. One of the ``print()`` or
+ ``println()`` functions is likely to be more useful when printing
+ multiple characters, when formatting numbers for printing, etc.
+
+.. cpp:function:: HardwareSerial::write(void *buf, unsigned int size)
+
+ Writes the first ``size`` bytes of ``buf`` over the USART. Each
+ byte is transmitted as an individual character.
+
+ This is a low-level function. One of the ``print()`` or
+ ``println()`` functions is likely to be more useful when printing
+ multiple characters, when formatting numbers for printing, etc.
+
+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.
+
+.. TODO LATER port these examples over
+
+.. Examples
+.. --------
+
+.. - `ASCII Table <http://arduino.cc/en/Tutorial/ASCIITable>`_
+.. - `Dimmer <http://arduino.cc/en/Tutorial/Dimmer>`_
+.. - `Graph <http://arduino.cc/en/Tutorial/Graph>`_
+.. - `Physical Pixel <http://arduino.cc/en/Tutorial/PhysicalPixel>`_
+.. - `Virtual Color Mixer <http://arduino.cc/en/Tutorial/VirtualColorMixer>`_
+.. - `Serial Call Response <http://arduino.cc/en/Tutorial/SerialCallResponse>`_
+.. - `Serial Call Response ASCII <http://arduino.cc/en/Tutorial/SerialCallResponseASCII>`_
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst
new file mode 100644
index 0000000..af3a7e0
--- /dev/null
+++ b/source/lang/api/serialusb.rst
@@ -0,0 +1,242 @@
+.. highlight:: cpp
+
+.. _lang-serialusb:
+
+``SerialUSB``
+=============
+
+Used for communication between the Maple board and a computer.
+
+.. contents:: Contents
+ :local:
+
+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).
+
+Library access to the emulated serial port is provided through the
+``SerialUSB`` object. You can mostly use ``SerialUSB`` as a drop-in
+replacement for ``Serial1``, ``Serial2``, and ``Serial3``.
+
+.. warning:: The ``SerialUSB`` functionality includes a 50 millisecond
+ timeout for writes, and does not try to detect if the USB host is
+ "really" connected, or just enumerated and initialized.
+
+ 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).
+
+ You can avoid this behavior by :ref:`deciphering the port status
+ 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.
+
+Library Documentation
+---------------------
+
+The ``SerialUSB`` object is an instance of the ``USBSerial`` class,
+which is documented in this section. This means that you can use any
+of these functions by writing
+``SerialUSB.functionName(arguments...)``. For example, to print the
+message "hello, world!", you can write ``USBSerial.println("hello,
+world!")``.
+
+.. cpp:class:: USBSerial
+
+ Emulated serial-over-USB class. ``SerialUSB`` is the predefined
+ instance.
+
+.. cpp:function:: USBSerial::begin()
+
+ Set up the USB peripheral for emulated serial communication. The
+ peripheral is configured this way by default; calling this function
+ should only be necessary if you have disabled the peripheral using
+ ``SerialUSB.end()``.
+
+.. _lang-serialusb-end:
+
+.. cpp:function:: USBSerial::end()
+
+ Disables the USB peripheral.
+
+.. cpp:function:: unsigned int USBSerial::available()
+
+ Returns the number of bytes available for reading.
+
+.. _lang-serialusb-read:
+
+.. cpp:function:: unsigned char USBSerial::read()
+
+ Returns the next available, unread character. If there are no
+ available characters (you can check this with :cpp:func:`available
+ <USBSerial::available>`), the call will block until one
+ becomes available.
+
+.. cpp:function:: USBSerial::flush()
+
+ Removes the contents of the Serial's associated input buffer. That
+ is, clears any buffered characters, so that the next character read
+ is guaranteed to be new.
+
+.. cpp:function:: USBSerial::print(unsigned char b)
+
+ Print the given byte over the USB connection.
+
+.. cpp:function:: USBSerial::print(char c)
+
+ Print the given character over the USB connection. 7-bit clean characters
+ are typically interpreted as ASCII text.
+
+.. cpp:function:: USBSerial::print(const char *str)
+
+ Print the given null-terminated string over the USB connection.
+
+.. cpp:function:: USBSerial::print(int 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 int n)
+
+ Print the argument's digits over the USB connection, in decimal format.
+
+.. 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 n)
+
+ Print the argument's digits over the USB connection, in decimal
+ format.
+
+.. cpp:function:: USBSerial::print(long n, int base)
+
+ 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 2 digits after the decimal point.
+
+.. _lang-serialusb-println:
+
+.. cpp:function:: USBSerial::println(char c)
+
+ Like ``print(c)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(const char *c)
+
+ Like ``print(c)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(unsigned char b)
+
+ Like ``print(b)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(int n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(unsigned int n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(long n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(unsigned long n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(long n, int base)
+
+ Like ``print(n, b)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(double n)
+
+ Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println()
+
+ Prints ``"\r\n"`` over the USB connection.
+
+.. cpp:function:: USBSerial::write(unsigned char ch)
+
+ Sends one character over the USB connection. This function is
+ currently blocking, although nonblocking writes are a planned
+ future extension.
+
+ This is a low-level function. One of the ``print()`` or
+ ``println()`` functions is likely to be more useful when printing
+ multiple characters, when formatting numbers for printing, etc.
+
+.. cpp:function:: USBSerial::write(const char* str)
+
+ Send the given null-terminated character string over the USB
+ connection.
+
+ This is a low-level function. One of the ``print()`` or
+ ``println()`` functions is likely to be more useful when printing
+ multiple characters, when formatting numbers for printing, etc.
+
+.. cpp:function:: USBSerial::write(void *buf, unsigned int size)
+
+ Writes the first ``size`` bytes of ``buf`` over the USB connection.
+ Each byte is transmitted as an individual character.
+
+ This is a low-level function. One of the ``print()`` or
+ ``println()`` functions is likely to be more useful when printing
+ multiple characters, when formatting numbers for printing, etc.
+
+Examples
+--------
+
+.. _lang-serialusb-safe-print:
+
+**Safe print**: This function should run smoothly and not block; the
+LED should blink at roughly the same speed whether being monitored,
+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
+
+ void setup() {
+ /* Set up the LED to blink */
+ pinMode(LED_PIN, OUTPUT);
+ }
+
+ void loop() {
+ // LED will stay off if we are disconnected;
+ // will blink quickly if USB is unplugged (battery 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(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) {
+ for(int i=0; i<10; i++) {
+ SerialUSB.println(123456,BIN);
+ }
+ }
+ digitalWrite(LED_PIN, 0);
+ delay(100);
+ }
+
diff --git a/source/lang/api/setup.rst b/source/lang/api/setup.rst
new file mode 100644
index 0000000..837ddd6
--- /dev/null
+++ b/source/lang/api/setup.rst
@@ -0,0 +1,29 @@
+.. highlight:: cpp
+
+.. _lang-setup:
+
+setup()
+=======
+
+The ``setup()`` function is called when a sketch starts. Use it to
+initialize :ref:`variables <lang-variables>`, :ref:`pin modes
+<lang-pinmode>`, start using :ref:`libraries <libraries>`, etc. The
+``setup()`` function will only run once, after each power-up or reset
+of the Maple board.
+
+Example
+-------
+
+::
+
+ int buttonPin = 38;
+
+ void setup() {
+ pinMode(buttonPin, INPUT);
+ }
+
+ void loop() {
+ // ...
+ }
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/sin.rst b/source/lang/api/sin.rst
new file mode 100644
index 0000000..398b8f3
--- /dev/null
+++ b/source/lang/api/sin.rst
@@ -0,0 +1,32 @@
+.. _lang-sin:
+
+sin()
+=====
+
+Calculates the `sine <http://en.wikipedia.org/wiki/Sine>`_ of an
+angle.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: sin
+
+Arduino Compatibility
+---------------------
+
+The Maple version of ``sin()`` is compatible with Arduino.
+
+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
+--------
+
+- :ref:`cos <lang-cos>`
+- :ref:`tan <lang-tan>`
+- :ref:`float <lang-float>`
+- :ref:`double <lang-double>`
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/sq.rst b/source/lang/api/sq.rst
new file mode 100644
index 0000000..bd32648
--- /dev/null
+++ b/source/lang/api/sq.rst
@@ -0,0 +1,46 @@
+.. highlight:: cpp
+
+.. _lang-sq:
+
+sq()
+====
+
+(Macro) computes the square of a number.
+
+Syntax
+------
+
+::
+
+ sq(a)
+
+Parameters
+----------
+
+**a**: the number.
+
+Returns
+-------
+
+**a** squared (**a** × **a**).
+
+Warning
+-------
+
+Because of the way ``sq()`` is implemented, avoid using other
+functions or causing side effects inside the parentheses, as it may
+lead to incorrect results::
+
+ b = sq(a++); // avoid this - yields incorrect results
+
+ b = sq(a); // use this instead -
+ a++; // keep other operations outside sq()
+
+
+Arduino Compatibility
+---------------------
+
+Maple's implementation of ``sq()`` is compatible with Arduino.
+
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/tan.rst b/source/lang/api/tan.rst
new file mode 100644
index 0000000..4bbe0db
--- /dev/null
+++ b/source/lang/api/tan.rst
@@ -0,0 +1,31 @@
+.. _lang-tan:
+
+tan()
+=====
+
+Calculates the tangent of an angle.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: tan
+
+Arduino Compatibility
+---------------------
+
+The Maple version of ``tan()`` is compatible with Arduino.
+
+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
+--------
+
+
+- :ref:`sin <lang-sin>`
+- :ref:`cos <lang-cos>`
+- :ref:`float <lang-float>`
+- :ref:`double <lang-double>`
+
+.. include:: cc-attribution.txt
diff --git a/source/lang/api/volatile.rst b/source/lang/api/volatile.rst
new file mode 100644
index 0000000..276bb6a
--- /dev/null
+++ b/source/lang/api/volatile.rst
@@ -0,0 +1,65 @@
+.. highlight:: cpp
+
+.. _lang-volatile:
+
+``volatile``
+============
+
+The ``volatile`` keyword known is a variable *qualifier*. It is
+usually used before the datatype of a variable, to modify the way in
+which the compiler treats the variable.
+
+Declaring a variable ``volatile`` is a directive to the compiler. The
+compiler is software which translates your C++ code into the machine
+code, which are the real instructions for the STM32 chip in the
+Maple. (The particular compiler we provide for use with the Maple is a
+version of :ref:`GCC <arm-gcc>`).
+
+Specifically, it directs the compiler to read the variable's value
+fresh every time it is used, rather than "backing up" the value and
+reading from its backup copy. (Compilers often "back up" a variable's
+value in RAM into a storage location called a *register*; this is done
+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.
+
+Example
+-------
+
+::
+
+ // toggles LED when interrupt pin changes state
+
+ int pin = 13;
+ volatile int state = LOW;
+
+ void setup() {
+ pinMode(pin, OUTPUT);
+ attachInterrupt(0, blink, CHANGE);
+ }
+
+ void loop() {
+ digitalWrite(pin, state);
+ }
+
+ void blink() {
+ if (state == HIGH) {
+ state = LOW;
+ } else {
+ // state must be HIGH
+ state = HIGH;
+ }
+ }
+
+See also
+--------
+
+- :ref:`External Interrupts <external-interrupts>`
+- :ref:`lang-attachinterrupt`
+- :ref:`lang-detachinterrupt`
+
+.. include:: cc-attribution.txt