Merge pull request #6 from arduino/Language_content

Language content. Ok but PROGMEM needs to be modified according to arduino/Arduino#1536

Author: agdl

Language/Functions/External Interrupts/attachInterrupt.adoc

@@ -1 +1,127 @@
-// still working on this file
+:source-highlighter: pygments
+:pygments-style: arduino
+:ext-relative: adoc
+
+
+= attachInterrupt()
+
+
+// OVERVIEW SECTION STARTS
+[#overview]
+--
+
+[float]
+=== Description
+Specifies a named Interrupt Service Routine (ISR) to call when an interrupt occurs. Replaces any previous function that was attached to the interrupt. Most Arduino boards have two external interrupts: numbers 0 (on digital pin 2) and 1 (on digital pin 3). The table below shows the available interrupt pins on various boards.
+
+Board	          int.0	    int.1	    int.2     int.3	   int.4	   int.5
+
+Uno, Ethernet	    2	        3
+
+Mega2560	        2	        3	       21	       20	      19	      18
+
+Leonardo	        3	        2        0	       1	      7
+
+Due	                          (see below)
+
+The Arduino Due board has powerful interrupt capabilities that allows you to attach an interrupt function on all available pins. You can directly specify the pin number in `attachInterrupt()`.
+[%hardbreaks]
+
+=== Notes and Warnings
+Inside the attached function, `delay()` won't work and the value returned by `millis()` will not increment. Serial data received while in the function may be lost. You should declare as volatile any variables that you modify within the attached function. See the section on ISRs below for more information.
+[%hardbreaks]
+
+[float]
+== Using Interrupts
+
+Interrupts are useful for making things happen automatically in microcontroller programs, and can help solve timing problems. Good tasks for using an interrupt may include reading a rotary encoder, or monitoring user input.
+
+If you wanted to insure that a program always caught the pulses from a rotary encoder, so that it never misses 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 input.
+
+[float]
+== About Interrupt Service Routines
+
+ISRs are special kinds of functions that have some unique limitations most other functions do not have. An ISR cannot have any parameters, and they shouldn't return anything.
+
+Generally, an ISR should be as short and fast as possible. If your sketch uses multiple ISRs, only one can run at a time, other interrupts will be ignored (turned off) until the current one is finished. as delay() and millis() both rely on interrupts, they will not work while an ISR is running. `delayMicroseconds()`, which does not rely on interrupts, will work as expected.
+
+Typically global variables are used to pass data between an ISR and the main program. To make sure variables used in an ISR are updated correctly, declare them as volatile.
+
+For more information on interrupts, see http://gammon.com.au/interrupts[Nick Gammon's notes].
+
+[float]
+=== Syntax
+`attachInterrupt(interrupt, ISR, mode)` +
+`attachInterrupt(pin, ISR, mode)` 	         _(Arduino Due only)_
+
+
+[float]
+=== Parameters
+`interrupt`: 	the number of the interrupt (`int`)
+`pin`: 	      the pin number 	            _(Arduino Due only)_
+`ISR`: 	      the ISR to call when the interrupt occurs; this function must take no parameters and return nothing. This function is sometimes referred to as an interrupt service routine.
+`mode`: 	    defines when the interrupt should be triggered. Four contstants are predefined as valid values:
+
+* *LOW* to trigger the interrupt whenever the pin is low, +
+* *CHANGE* to trigger the interrupt whenever the pin changes value +
+* *RISING* to trigger when the pin goes from low to high, +
+* *FALLING* for when the pin goes from high to low. +
+ The Due board allows also:
+* *HIGH* to trigger the interrupt whenever the pin is high.  _(Arduino Due only)_
+
+[float]
+=== Returns
+Nothing
+
+--
+// OVERVIEW SECTION ENDS
+
+
+
+
+// HOW TO USE SECTION STARTS
+[#howtouse]
+--
+
+[float]
+=== Example Code
+// Describe what the example code is all about and add relevant code   ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄
+
+
+[source,arduino]
+----
+int pin = 13;
+volatile int state = LOW;
+
+void setup()
+{
+  pinMode(pin, OUTPUT);
+  attachInterrupt(0, blink, CHANGE);
+}
+
+void loop()
+{
+  digitalWrite(pin, state);
+}
+
+void blink()
+{
+  state = !state;
+}
+----
+[%hardbreaks]
+
+[float]
+
+
+[float]
+=== See also
+// Link relevant content by category, such as other Reference terms (please add the tag #LANGUAGE#),
+// definitions (please add the tag #DEFINITION#), and examples of Projects and Tutorials
+// (please add the tag #EXAMPLE#)  ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄
+[role="language"]
+* #LANGUAGE# link:detachInterrupt{ext-relative}[detachInterrupt]
+
+
+--
+// HOW TO USE SECTION ENDS

Language/Functions/Math/map.adoc

@@ -16,6 +16,17 @@ Re-maps a number from one range to another. That is, a value of *fromLow* would
 
 Does not constrain values to within the range, because out-of-range values are sometimes intended and useful. The `constrain()` function 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 the `map()` function 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 and works well.
+
+The `map()` function uses integer math so will not generate fractions, when the math might indicate that it should do so. Fractional remainders are truncated, and are not rounded or averaged.
 [%hardbreaks]
 
 
@@ -70,7 +81,17 @@ void loop()
 [%hardbreaks]
 
 [float]
-=== Notes and Warnings
+=== Appendix
+
+For the mathematically inclined, here's the whole function
+
+[source,arduino]
+----
+long map(long x, long in_min, long in_max, long out_min, long out_max)
+{
+  return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
+}
+----
 [%hardbreaks]
 
 [float]
@@ -79,9 +100,7 @@ void loop()
 // definitions (please add the tag #DEFINITION#), and examples of Projects and Tutorials
 // (please add the tag #EXAMPLE#)  ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄
 [role="language"]
-* #LANGUAGE#
-* #DEFINITION#
-* #EXAMPLE#
+* #LANGUAGE# link:constrain{ext-relative}[constrain()]
 
 --
 // HOW TO USE SECTION ENDS

Language/Variables/Constants/constants.adoc

@@ -0,0 +1,126 @@
+:source-highlighter: pygments
+:pygments-style: arduino
+:ext-relative: adoc
+
+
+= Constants
+
+
+// OVERVIEW SECTION STARTS
+[#overview]
+--
+
+[float]
+=== Description
+Constants are predefined expressions in the Arduino language. They are used to make the programs easier to read. We classify constants in groups:
+
+[float]
+== Defining Logical Levels: true and false (Boolean Constants)
+There are two constants used to represent truth and falsity in the Arduino language: `true`, and `false`.
+
+[float]
+=== false
+`false` is the easier of the two to define. false is defined as 0 (zero).
+[%hardbreaks]
+
+[float]
+=== true
+`true` is often said to be defined as 1, which is correct, but true has a wider definition. Any integer which is non-zero is true, in a Boolean sense. So -1, 2 and -200 are all defined as true, too, in a Boolean sense.
+[%hardbreaks]
+
+Note that the `true` and `false` constants are typed in lowercase unlike `HIGH`, `LOW`, `INPUT`, and `OUTPUT`.
+[%hardbreaks]
+
+[float]
+== Defining Pin Levels: HIGH and LOW
+When reading or writing to a digital pin there are only two possible values a pin can take/be-set-to: `HIGH` and `LOW`.
+
+[float]
+=== HIGH
+The meaning of `HIGH` (in reference to a pin) is somewhat different depending on whether a pin is set to an `INPUT` or `OUTPUT`. When a pin is configured as an `INPUT` with link:../../Functions/Digital%20IO/pinMode{ext-relative}[pinMode()], and read with link:../../Functions/Digital%20IO/digitalRead{ext-relative}[digitalRead()], the Arduino (ATmega) will report `HIGH` if:
+
+  - a voltage greater than 3 volts is present at the pin (5V boards)
+  - a voltage greater than 2 volts is present at the pin (3.3V boards)
+[%hardbreaks]
+
+A pin may also be configured as an INPUT with `pinMode()`, and subsequently made HIGH with link:../../Functions/Digital%20IO/digitalWrite{ext-relative}[digitalWrite()]. This will enable the internal 20K pullup resistors, which will _pull up_ the input pin to a `HIGH` reading unless it is pulled `LOW` by external circuitry. This is how `INPUT_PULLUP` works and is described below in more detail.
+[%hardbreaks]
+
+When a pin is configured to OUTPUT with `pinMode()`, and set to `HIGH` with `digitalWrite()`, the pin is at:
+
+  - 5 volts (5V boards)
+  - 3.3 volts (3.3V boards)
+
+In this state it can source current, e.g. light an LED that is connected through a series resistor to ground.
+[%hardbreaks]
+
+[float]
+=== 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 `pinMode()`, and read with `digitalRead()`, the Arduino (ATmega) will report LOW if:
+
+  - a voltage less than 3 volts is present at the pin (5V boards)
+  - a voltage less than 2 volts is present at the pin (3.3V boards)
+
+When a pin is configured to `OUTPUT` with `pinMode()`, and set to `LOW` with `digitalWrite()`, the pin is at 0 volts (both 5V and 3.3V boards). In this state it can sink current, e.g. light an LED that is connected through a series resistor to +5 volts (or +3.3 volts).
+[%hardbreaks]
+
+[float]
+== Defining Digital Pins modes: INPUT, INPUT_PULLUP, and OUTPUT
+Digital pins can be used as `INPUT`, `INPUT_PULLUP`, or `OUTPUT`. Changing a pin with `pinMode()` changes the electrical behavior of the pin.
+
+[float]
+=== Pins Configured as INPUT
+Arduino (ATmega) pins configured as `INPUT` with `pinMode()` are said to be in a _high-impedance_ state. Pins configured as `INPUT` make extremely small demands on the circuit that they are sampling, equivalent to a series resistor of 100 Megohms in front of the pin. This makes them useful for reading a sensor.
+[%hardbreaks]
+
+If you have your pin configured as an `INPUT`, and are reading a switch, when the switch is in the open state the input pin will be "floating", resulting in unpredictable results. In order to assure a proper reading when the switch is open, a pull-up or pull-down resistor must be used. The purpose of this resistor is to pull the pin to a known state when the switch is open. A 10 K ohm resistor is usually chosen, as it is a low enough value to reliably prevent a floating input, and at the same time a high enough value to not not draw too much current when the switch is closed. See the http://arduino.cc/en/Tutorial/DigitalReadSerial[Digital Read Serial^] tutorial for more information.
+[%hardbreaks]
+
+If a pull-down resistor is used, the input pin will be `LOW` when the switch is open and `HIGH` when the switch is closed.
+[%hardbreaks]
+
+If a pull-up resistor is used, the input pin will be `HIGH` when the switch is open and `LOW` when the switch is closed.
+[%hardbreaks]
+
+[float]
+=== Pins Configured as INPUT_PULLUP
+The ATmega microcontroller on the Arduino has internal pull-up resistors (resistors that connect to power internally) that you can access. If you prefer to use these instead of external pull-up resistors, you can use the `INPUT_PULLUP` argument in `pinMode()`.
+[%hardbreaks]
+
+See the http://arduino.cc/en/Tutorial/InputPullupSerial[Input Pullup Serial^] tutorial for an example of this in use.
+[%hardbreaks]
+
+Pins configured as inputs with either `INPUT` or `INPUT_PULLUP` can be damaged or destroyed if they are connected to voltages below ground (negative voltages) or above the positive power rail (5V or 3V).
+[%hardbreaks]
+
+[float]
+=== Pins Configured as OUTPUT
+Pins configured as `OUTPUT` with `pinMode()` are said to be in a _low-impedance_ state. This means that they can provide a substantial amount of current to other circuits. ATmega pins can source (provide current) or sink (absorb current) up to 40 mA (milliamps) of current to other devices/circuits. This makes them useful for powering LEDs because LEDs typically use less than 40 mA. Loads greater than 40 mA (e.g. motors) will require a transistor or other interface circuitry.
+[%hardbreaks]
+
+Pins configured as outputs can be damaged or destroyed if they are connected to either the ground or positive power rails.
+[%hardbreaks]
+
+[float]
+== Defining built-ins: LED_BUILTIN
+Most Arduino boards have a pin connected to an on-board LED in series with a resistor. The constant `LED_BUILTIN` is the number of the pin to which the on-board LED is connected. Most boards have this LED connected to digital pin 13.
+
+--
+// OVERVIEW SECTION ENDS
+
+
+
+// HOW TO USE SECTION STARTS
+[#howtouse]
+--
+
+
+[float]
+=== See also
+
+[role="language"]
+* #LANGUAGE# link:integerConstants{ext-relative}[Integer Constants]
+* #LANGUAGE# link:floatingPointConstants{ext-relative}[Floating Point Constants]
+
+--
+// HOW TO USE SECTION ENDS

Language/Variables/Constants/floatingPointConstants.adoc

@@ -0,0 +1,69 @@
+:source-highlighter: pygments
+:pygments-style: arduino
+:ext-relative: adoc
+
+
+= Floating Point Constants
+
+
+// OVERVIEW SECTION STARTS
+[#overview]
+--
+
+[float]
+=== Description
+Similar to integer constants, floating point constants are used to make code more readable. Floating point constants are swapped at compile time for the value to which the expression evaluates.
+[%hardbreaks]
+
+--
+// OVERVIEW SECTION ENDS
+
+
+
+// HOW TO USE SECTION STARTS
+[#howtouse]
+--
+
+[float]
+=== Example Code
+
+[source,arduino]
+----
+n = 0.005;  // 0.005 is a floating point constant
+----
+[%hardbreaks]
+
+[float]
+=== Notes and Warnings
+Floating point constants can also be expressed in a variety of scientific notation. 'E' and 'e' are both accepted as valid exponent indicators.
+[%hardbreaks]
+
+|===
+|floating-point constant |evaluates to: |also evaluates to:
+
+|10.0
+|10
+|
+
+|2.34E5
+|2.34 * 10^5
+|234000
+
+|67e-12
+|67.0 * 10^-12
+|0.000000000067
+
+|===
+[%hardbreaks]
+
+
+
+[float]
+=== See also
+
+[role="language"]
+* #LANGUAGE# link:constants{ext-relative}[Constants]
+* #LANGUAGE# link:integerConstants{ext-relative}[Integer Constants]
+
+--
+// HOW TO USE SECTION ENDS