From 89fc89a6e008cf30fffb56a55ee1607510c0692f Mon Sep 17 00:00:00 2001 From: Akshay Sharma Date: Thu, 19 Feb 2015 23:36:32 +0530 Subject: [PATCH 1/4] Fix title error unsigned char --- Language/Variables/Data Types/unsignedChar.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Language/Variables/Data Types/unsignedChar.adoc b/Language/Variables/Data Types/unsignedChar.adoc index 475c0bd63..2685ec48c 100644 --- a/Language/Variables/Data Types/unsignedChar.adoc +++ b/Language/Variables/Data Types/unsignedChar.adoc @@ -3,7 +3,7 @@ :ext-relative: adoc -= Entity title() += unsigned char // OVERVIEW SECTION STARTS From 1841dfaed77bacfbe8721379538f5dfa9ee34746 Mon Sep 17 00:00:00 2001 From: Ram Das Date: Fri, 20 Feb 2015 00:28:30 +0530 Subject: [PATCH 2/4] Add contents for Variables/Constants --- Language/Variables/Constants/constants.adoc | 126 +++++++++++++++++ .../Constants/floatingPointConstants.adoc | 69 ++++++++++ .../Variables/Constants/integerConstants.adoc | 130 ++++++++++++++++++ 3 files changed, 325 insertions(+) create mode 100644 Language/Variables/Constants/constants.adoc create mode 100644 Language/Variables/Constants/floatingPointConstants.adoc create mode 100644 Language/Variables/Constants/integerConstants.adoc diff --git a/Language/Variables/Constants/constants.adoc b/Language/Variables/Constants/constants.adoc new file mode 100644 index 000000000..961271773 --- /dev/null +++ b/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 diff --git a/Language/Variables/Constants/floatingPointConstants.adoc b/Language/Variables/Constants/floatingPointConstants.adoc new file mode 100644 index 000000000..fcd15aa19 --- /dev/null +++ b/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 diff --git a/Language/Variables/Constants/integerConstants.adoc b/Language/Variables/Constants/integerConstants.adoc new file mode 100644 index 000000000..d633d2454 --- /dev/null +++ b/Language/Variables/Constants/integerConstants.adoc @@ -0,0 +1,130 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += Integer Constants + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Integer constants are numbers that are used directly in a sketch, like 123. By default, these numbers are treated as link:../Data%20Types{ext-relative}[int] but you can change this with the U and L modifiers (see below). +[%hardbreaks] + +Normally, integer constants are treated as base 10 (decimal) integers, but special notation (formatters) may be used to enter numbers in other bases. +[%hardbreaks] + +|=== +|Base |Example |Formatter |Comment + +|10 (decimal) +|123 +|none +| + +|2 (binary) +|B1111011 +|leading 'B' +|only works with 8 bit values (0 to 255) characters 0&1 valid + +|8 (octal) +|0173 +|leading "0" +|characters 0-7 valid + +|16 (hexadecimal) +|0x7B +|leading "0x" +|characters 0-9, A-F, a-f valid +|=== +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- +[float] +== Decimal (base 10) +This is the common-sense math with which you are acquainted. Constants without other prefixes are assumed to be in decimal format. + +[float] +=== Example Code: +[source,arduino] +---- +n = 101; // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) +---- +[%hardbreaks] + +[float] +== Binary (base 2) +Only the characters 0 and 1 are valid. + +[float] +=== Example Code: +[source,arduino] +---- +n = B101; // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) +---- + +The binary formatter only works on bytes (8 bits) between 0 (B0) and 255 (B11111111). If it is convenient to input an int (16 bits) in binary form you can do it a two-step procedure such as: +[source,arduino] +---- +myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte` +---- +[%hardbreaks] + +[float] +== Octal (base 8) +Only the characters 0 through 7 are valid. Octal values are indicated by the prefix "0" (zero). + +[float] +=== Example Code: +[source,arduino] +---- +n = 0101; // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) +---- +It is possible to generate a hard-to-find bug by (unintentionally) including a leading zero before a constant and having the compiler unintentionally interpret your constant as octal. +[%hardbreaks] + +[float] +== Hexadecimal (base 16) +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". Note that A-F may be syted in upper or lower case (a-f). + +[float] +=== Example Code: +[source,arduino] +---- +n = 0x101; // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) +---- +[%hardbreaks] + + +[float] +=== Notes and Warnings +*U & L formatters:* + +By default, an integer constant is treated as an int with the attendant limitations in values. To specify an integer constant with another data type, follow it with: + + - a 'u' or 'U' to force the constant into an unsigned data format. Example: 33u + - a 'l' or 'L' to force the constant into a long data format. Example: 100000L + - a 'ul' or 'UL' to force the constant into an unsigned long constant. Example: 32767ul + +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:constants{ext-relative}[Constants] +* #LANGUAGE# link:floatingPointConstants{ext-relative}[Floating Point Constants] + +-- +// HOW TO USE SECTION ENDS From 09458728ddffa64bc1a764d7c1c33f439bf1cedb Mon Sep 17 00:00:00 2001 From: Akshay Sharma Date: Fri, 20 Feb 2015 00:38:38 +0530 Subject: [PATCH 3/4] Add Variables/Utilities PROGMEM and sizeof --- Language/Variables/Utilities/PROGMEM.adoc | 175 +++++++++++++++++++++- Language/Variables/Utilities/sizeof.adoc | 81 +++++++++- 2 files changed, 254 insertions(+), 2 deletions(-) diff --git a/Language/Variables/Utilities/PROGMEM.adoc b/Language/Variables/Utilities/PROGMEM.adoc index 979a2ddde..047c5fa97 100644 --- a/Language/Variables/Utilities/PROGMEM.adoc +++ b/Language/Variables/Utilities/PROGMEM.adoc @@ -1 +1,174 @@ -//still to write +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += PROGMEM + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Store data in flash (program) memory instead of SRAM. There's a description of the various http://www.arduino.cc/playground/Learning/Memory[types of memory] available on an Arduino board. + +The `PROGMEM` keyword is a variable modifier, it should be used only with the datatypes defined in pgmspace.h. It tells the compiler "put this information into flash memory", instead of into SRAM, where it would normally go. + + PROGMEM is part of the http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html[pgmspace.h] library. So you first need to include the library at the top your sketch, like this: + +`#include ` +[%hardbreaks] + + +[float] +=== Syntax +`dataType variableName[] PROGMEM = {dataInt0, dataInt1, dataInt3...};` + +`program memory dataType` - any program memory variable type (see below) +`variableName` - the name for your array of data + +Note that because PROGMEM is a variable modifier, there is no hard and fast rule about where it should go, so the Arduino compiler accepts all of the definitions below, which are also synonymous. However experiments have indicated that, in various versions of Arduino (having to do with GCC version), PROGMEM may work in one location and not in another. The "string table" example below has been tested to work with Arduino 13. Earlier versions of the IDE may work better if PROGMEM is included after the variable name. + +`dataType variableName[] PROGMEM = {}; // use this form` + +`dataType PROGMEM variableName[] = {}; // not this one` + +`PROGMEM dataType variableName[] = {}; // use this form` + +While `PROGMEM` could be used on a single variable, it is really only worth the fuss if you have a larger block of data that needs to be stored, which is usually easiest in an array, (or another C data structure beyond our present discussion). + +Using `PROGMEM` is also a two-step procedure. After getting the data into Flash memory, it requires special methods (functions), also defined in the http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html[pgmspace.h] library, to read the data from program memory back into SRAM, so we can do something useful with it. + +As mentioned above, it is important to use the datatypes outlined in http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html[pgmspace.h]. Some cryptic bugs are generated by using ordinary datatypes for program memory calls. Below is a list of variable types to use. Floating point numbers in program memory do not appear to be supported. + + `prog_char` - a signed char (1 byte) -127 to 128 + + `prog_uchar` - an unsigned char (1 byte) 0 to 255 + + `prog_int16_t` - a signed int (2 bytes) -32,767 to 32,768 + + `prog_uint16_t` - an unsigned int (2 bytes) 0 to 65,535 + + `prog_int32_t` - a signed long (4 bytes) -2,147,483,648 to * 2,147,483,647. + + `prog_uint32_t` - an unsigned long (4 bytes) 0 to 4,294,967,295 + [%hardbreaks] +-- +// 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 ◄◄◄◄◄ +The following code fragments illustrate how to read and write unsigned chars (bytes) and ints (2 bytes) to PROGMEM. + +[source,arduino] +---- +#include + + +// save some unsigned ints +PROGMEM prog_uint16_t charSet[] = { 65000, 32796, 16843, 10, 11234}; + +// save some chars +prog_uchar signMessage[] PROGMEM = {"I AM PREDATOR, UNSEEN COMBATANT. CREATED BY THE UNITED STATES DEPART"}; + +unsigned int displayInt; +int k; // counter variable +char myChar; + +// read back a 2-byte int + displayInt = pgm_read_word_near(charSet + k) + +// read back a char +myChar = pgm_read_byte_near(signMessage + k); + +---- +*Arrays of strings* + +It is often convenient when working with large amounts of text, such as a project with an LCD display, to setup an array of strings. Because strings themselves are arrays, this is in actually an example of a two-dimensional array. + +These tend to be large structures so putting them into program memory is often desirable. The code below illustrates the idea. + +[source,arduino] +---- +/* + PROGMEM string demo + How to store a table of strings in program memory (flash), + and retrieve them. + + Information summarized from: + http://www.nongnu.org/avr-libc/user-manual/pgmspace.html + + Setting up a table (array) of strings in program memory is slightly complicated, but + here is a good template to follow. + + Setting up the strings is a two-step process. First define the strings. + +*/ + +#include +prog_char string_0[] PROGMEM = "String 0"; // "String 0" etc are strings to store - change to suit. +prog_char string_1[] PROGMEM = "String 1"; +prog_char string_2[] PROGMEM = "String 2"; +prog_char string_3[] PROGMEM = "String 3"; +prog_char string_4[] PROGMEM = "String 4"; +prog_char string_5[] PROGMEM = "String 5"; + + +// Then set up a table to refer to your strings. + +PROGMEM const char *string_table[] = // change "string_table" name to suit +{ + string_0, + string_1, + string_2, + string_3, + string_4, + string_5 }; + +char buffer[30]; // make sure this is large enough for the largest string it must hold + +void setup() +{ + Serial.begin(9600); +} + + +void loop() +{ + /* Using the string table in program memory requires the use of special functions to retrieve the data. + The strcpy_P function copies a string from program space to a string in RAM ("buffer"). + Make sure your receiving string in RAM is large enough to hold whatever + you are retrieving from program space. */ + + + for (int i = 0; i < 6; i++) + { + strcpy_P(buffer, (char*)pgm_read_word(&(string_table[i]))); // Necessary casts and dereferencing, just copy. + Serial.println( buffer ); + delay( 500 ); + } +} +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +[%hardbreaks] + +[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="example"] +* #EXAMPLE# http://www.arduino.cc/playground/Learning/Memory[Types of memory available on an Arduino board] + +[role="definition"] +* #DEFINITION# link:array{ext-relative}[array] + +* #DEFINITION# link:string{ext-relative}[string] +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Variables/Utilities/sizeof.adoc b/Language/Variables/Utilities/sizeof.adoc index 07e74a1cb..db2781ea8 100644 --- a/Language/Variables/Utilities/sizeof.adoc +++ b/Language/Variables/Utilities/sizeof.adoc @@ -1 +1,80 @@ -// still to write +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += sizeof + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== +The sizeof operator returns the number of bytes in a variable type, or the number of bytes occupied by an array. +[%hardbreaks] + + +[float] +=== Syntax +`sizeof(variable)` + + +[float] +=== Parameters +`variable`: any variable type or array (e.g. int, float, byte) + +[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 ◄◄◄◄◄ +The `sizeof` operator is useful for dealing with arrays (such as strings) where it is convenient to be able to change the size of the array without breaking other parts of the program. + +This program prints out a text string one character at a time. Try changing the text phrase. + +[source,arduino] +---- +char myStr[] = "this is a test"; +int i; + +void setup(){ + Serial.begin(9600); +} + +void loop() { + for (i = 0; i < sizeof(myStr) - 1; i++){ + Serial.print(i, DEC); + Serial.print(" = "); + Serial.write(myStr[i]); + Serial.println(); + } + delay(5000); // slow down the program +} +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Note that `sizeof` returns the total number of bytes. So for larger variable types such as ints, the for loop would look something like this. Note also that a properly formatted string ends with the NULL symbol, which has ASCII value 0. + +[source,arduino] +---- +for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { + // do something with myInts[i] +} +---- +[%hardbreaks] From e2018bd17201a94ccaf9019a1f86e62ff9ffb270 Mon Sep 17 00:00:00 2001 From: Akshay Sharma Date: Fri, 20 Feb 2015 01:03:57 +0530 Subject: [PATCH 4/4] Add Function attachinterupt and map --- .../External Interrupts/attachInterrupt.adoc | 128 +++++++++++++++++- Language/Functions/Math/map.adoc | 27 +++- 2 files changed, 150 insertions(+), 5 deletions(-) diff --git a/Language/Functions/External Interrupts/attachInterrupt.adoc b/Language/Functions/External Interrupts/attachInterrupt.adoc index 2a2650c1c..dc999282b 100644 --- a/Language/Functions/External Interrupts/attachInterrupt.adoc +++ b/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 diff --git a/Language/Functions/Math/map.adoc b/Language/Functions/Math/map.adoc index b7212f502..1b685b8a0 100644 --- a/Language/Functions/Math/map.adoc +++ b/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