Skip to content

Commit 97dd879

Browse files
author
Akshay Sharma
committed
Merge branch 'Language_content' of https://github.com/arduino/reference-en into Language_content
2 parents e2018bd + 1841dfa commit 97dd879

File tree

3 files changed

+325
-0
lines changed

3 files changed

+325
-0
lines changed

‎Language/Variables/Constants/constants.adoc

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
:source-highlighter: pygments
2+
:pygments-style: arduino
3+
:ext-relative: adoc
4+
5+
6+
= Constants
7+
8+
9+
// OVERVIEW SECTION STARTS
10+
[#overview]
11+
--
12+
13+
[float]
14+
=== Description
15+
Constants are predefined expressions in the Arduino language. They are used to make the programs easier to read. We classify constants in groups:
16+
17+
[float]
18+
== Defining Logical Levels: true and false (Boolean Constants)
19+
There are two constants used to represent truth and falsity in the Arduino language: `true`, and `false`.
20+
21+
[float]
22+
=== false
23+
`false` is the easier of the two to define. false is defined as 0 (zero).
24+
[%hardbreaks]
25+
26+
[float]
27+
=== true
28+
`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.
29+
[%hardbreaks]
30+
31+
Note that the `true` and `false` constants are typed in lowercase unlike `HIGH`, `LOW`, `INPUT`, and `OUTPUT`.
32+
[%hardbreaks]
33+
34+
[float]
35+
== Defining Pin Levels: HIGH and LOW
36+
When reading or writing to a digital pin there are only two possible values a pin can take/be-set-to: `HIGH` and `LOW`.
37+
38+
[float]
39+
=== HIGH
40+
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:
41+
42+
- a voltage greater than 3 volts is present at the pin (5V boards)
43+
- a voltage greater than 2 volts is present at the pin (3.3V boards)
44+
[%hardbreaks]
45+
46+
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.
47+
[%hardbreaks]
48+
49+
When a pin is configured to OUTPUT with `pinMode()`, and set to `HIGH` with `digitalWrite()`, the pin is at:
50+
51+
- 5 volts (5V boards)
52+
- 3.3 volts (3.3V boards)
53+
54+
In this state it can source current, e.g. light an LED that is connected through a series resistor to ground.
55+
[%hardbreaks]
56+
57+
[float]
58+
=== LOW
59+
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:
60+
61+
- a voltage less than 3 volts is present at the pin (5V boards)
62+
- a voltage less than 2 volts is present at the pin (3.3V boards)
63+
64+
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).
65+
[%hardbreaks]
66+
67+
[float]
68+
== Defining Digital Pins modes: INPUT, INPUT_PULLUP, and OUTPUT
69+
Digital pins can be used as `INPUT`, `INPUT_PULLUP`, or `OUTPUT`. Changing a pin with `pinMode()` changes the electrical behavior of the pin.
70+
71+
[float]
72+
=== Pins Configured as INPUT
73+
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.
74+
[%hardbreaks]
75+
76+
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.
77+
[%hardbreaks]
78+
79+
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.
80+
[%hardbreaks]
81+
82+
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.
83+
[%hardbreaks]
84+
85+
[float]
86+
=== Pins Configured as INPUT_PULLUP
87+
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()`.
88+
[%hardbreaks]
89+
90+
See the http://arduino.cc/en/Tutorial/InputPullupSerial[Input Pullup Serial^] tutorial for an example of this in use.
91+
[%hardbreaks]
92+
93+
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).
94+
[%hardbreaks]
95+
96+
[float]
97+
=== Pins Configured as OUTPUT
98+
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.
99+
[%hardbreaks]
100+
101+
Pins configured as outputs can be damaged or destroyed if they are connected to either the ground or positive power rails.
102+
[%hardbreaks]
103+
104+
[float]
105+
== Defining built-ins: LED_BUILTIN
106+
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.
107+
108+
--
109+
// OVERVIEW SECTION ENDS
110+
111+
112+
113+
// HOW TO USE SECTION STARTS
114+
[#howtouse]
115+
--
116+
117+
118+
[float]
119+
=== See also
120+
121+
[role="language"]
122+
* #LANGUAGE# link:integerConstants{ext-relative}[Integer Constants]
123+
* #LANGUAGE# link:floatingPointConstants{ext-relative}[Floating Point Constants]
124+
125+
--
126+
// HOW TO USE SECTION ENDS

‎Language/Variables/Constants/floatingPointConstants.adoc

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
:source-highlighter: pygments
2+
:pygments-style: arduino
3+
:ext-relative: adoc
4+
5+
6+
= Floating Point Constants
7+
8+
9+
// OVERVIEW SECTION STARTS
10+
[#overview]
11+
--
12+
13+
[float]
14+
=== Description
15+
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.
16+
[%hardbreaks]
17+
18+
--
19+
// OVERVIEW SECTION ENDS
20+
21+
22+
23+
// HOW TO USE SECTION STARTS
24+
[#howtouse]
25+
--
26+
27+
[float]
28+
=== Example Code
29+
30+
[source,arduino]
31+
----
32+
n = 0.005; // 0.005 is a floating point constant
33+
----
34+
[%hardbreaks]
35+
36+
[float]
37+
=== Notes and Warnings
38+
Floating point constants can also be expressed in a variety of scientific notation. 'E' and 'e' are both accepted as valid exponent indicators.
39+
[%hardbreaks]
40+
41+
|===
42+
|floating-point constant |evaluates to: |also evaluates to:
43+
44+
|10.0
45+
|10
46+
|
47+
48+
|2.34E5
49+
|2.34 * 10^5
50+
|234000
51+
52+
|67e-12
53+
|67.0 * 10^-12
54+
|0.000000000067
55+
56+
|===
57+
[%hardbreaks]
58+
59+
60+
61+
[float]
62+
=== See also
63+
64+
[role="language"]
65+
* #LANGUAGE# link:constants{ext-relative}[Constants]
66+
* #LANGUAGE# link:integerConstants{ext-relative}[Integer Constants]
67+
68+
--
69+
// HOW TO USE SECTION ENDS

‎Language/Variables/Constants/integerConstants.adoc

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
:source-highlighter: pygments
2+
:pygments-style: arduino
3+
:ext-relative: adoc
4+
5+
6+
= Integer Constants
7+
8+
9+
// OVERVIEW SECTION STARTS
10+
[#overview]
11+
--
12+
13+
[float]
14+
=== Description
15+
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).
16+
[%hardbreaks]
17+
18+
Normally, integer constants are treated as base 10 (decimal) integers, but special notation (formatters) may be used to enter numbers in other bases.
19+
[%hardbreaks]
20+
21+
|===
22+
|Base |Example |Formatter |Comment
23+
24+
|10 (decimal)
25+
|123
26+
|none
27+
|
28+
29+
|2 (binary)
30+
|B1111011
31+
|leading 'B'
32+
|only works with 8 bit values (0 to 255) characters 0&1 valid
33+
34+
|8 (octal)
35+
|0173
36+
|leading "0"
37+
|characters 0-7 valid
38+
39+
|16 (hexadecimal)
40+
|0x7B
41+
|leading "0x"
42+
|characters 0-9, A-F, a-f valid
43+
|===
44+
[%hardbreaks]
45+
46+
--
47+
// OVERVIEW SECTION ENDS
48+
49+
50+
51+
// HOW TO USE SECTION STARTS
52+
[#howtouse]
53+
--
54+
[float]
55+
== Decimal (base 10)
56+
This is the common-sense math with which you are acquainted. Constants without other prefixes are assumed to be in decimal format.
57+
58+
[float]
59+
=== Example Code:
60+
[source,arduino]
61+
----
62+
n = 101; // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1)
63+
----
64+
[%hardbreaks]
65+
66+
[float]
67+
== Binary (base 2)
68+
Only the characters 0 and 1 are valid.
69+
70+
[float]
71+
=== Example Code:
72+
[source,arduino]
73+
----
74+
n = B101; // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1)
75+
----
76+
77+
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:
78+
[source,arduino]
79+
----
80+
myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte`
81+
----
82+
[%hardbreaks]
83+
84+
[float]
85+
== Octal (base 8)
86+
Only the characters 0 through 7 are valid. Octal values are indicated by the prefix "0" (zero).
87+
88+
[float]
89+
=== Example Code:
90+
[source,arduino]
91+
----
92+
n = 0101; // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1)
93+
----
94+
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.
95+
[%hardbreaks]
96+
97+
[float]
98+
== Hexadecimal (base 16)
99+
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).
100+
101+
[float]
102+
=== Example Code:
103+
[source,arduino]
104+
----
105+
n = 0x101; // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1)
106+
----
107+
[%hardbreaks]
108+
109+
110+
[float]
111+
=== Notes and Warnings
112+
*U & L formatters:*
113+
114+
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:
115+
116+
- a 'u' or 'U' to force the constant into an unsigned data format. Example: 33u
117+
- a 'l' or 'L' to force the constant into a long data format. Example: 100000L
118+
- a 'ul' or 'UL' to force the constant into an unsigned long constant. Example: 32767ul
119+
120+
[%hardbreaks]
121+
122+
[float]
123+
=== See also
124+
125+
[role="language"]
126+
* #LANGUAGE# link:constants{ext-relative}[Constants]
127+
* #LANGUAGE# link:floatingPointConstants{ext-relative}[Floating Point Constants]
128+
129+
--
130+
// HOW TO USE SECTION ENDS

0 commit comments

Comments
 (0)