Language Reference
Arduino programming language can be divided in three main parts: functions,
values (variables and constants), and structure.
Functions
For controlling the Arduino board and performing computations.
Digital I/O
digitalRead()
Reference > Language > Functions > Digital io > Digitalread
digitalRead()
[Digital I/O]
Description
Reads the value from a specified digital pin, either HIGH or LOW.
Syntax
digitalRead(pin)
Parameters
pin: the Arduino pin number you want to read
Returns
HIGH or LOW
Example Code
Sets pin 13 to the same value as pin 7, declared as an input.
int ledPin = 13; // LED connected to digital pin 13
int inPin = 7; // pushbutton connected to digital pin 7
int val = 0; // variable to store the read value
void setup() {
pinMode(ledPin, OUTPUT); // sets the digital pin 13 as output
pinMode(inPin, INPUT); // sets the digital pin 7 as input
}
void loop() {
val = digitalRead(inPin); // read the input pin
digitalWrite(ledPin, val); // sets the LED to the button's value
}
Notes and Warnings
If the pin isn’t connected to anything, digitalRead() can return
either HIGH or LOW (and this can change randomly).
The analog input pins can be used as digital pins, referred to as A0, A1, etc.
The exception is the Arduino Nano, Pro Mini, and Mini’s A6 and A7 pins, which
can only be used as analog inputs.
digitalWrite()
Reference > Language > Functions > Digital io > Digitalwrite
digitalWrite()
[Digital I/O]
Description
Write a HIGH or a LOW value to a digital pin.
If the pin has been configured as an OUTPUT with pinMode(), its voltage will be
set to the corresponding value: 5V (or 3.3V on 3.3V boards) for HIGH, 0V
(ground) for LOW.
If the pin is configured as an INPUT, digitalWrite() will enable (HIGH) or
disable (LOW) the internal pullup on the input pin. It is recommended to set
the pinMode() to INPUT_PULLUP to enable the internal pull-up resistor. See
the Digital Pins tutorial for more information.
If you do not set the pinMode() to OUTPUT, and connect an LED to a pin, when
calling digitalWrite(HIGH), the LED may appear dim. Without explicitly
setting pinMode(), digitalWrite() will have enabled the internal pull-up
resistor, which acts like a large current-limiting resistor.
Syntax
digitalWrite(pin, value)
Parameters
pin: the Arduino pin number.
value: HIGH or LOW.
Returns
Nothing
Example Code
The code makes the digital pin 13 an OUTPUT and toggles it by alternating
between HIGH and LOW at one second pace.
void setup() {
pinMode(13, OUTPUT); // sets the digital pin 13 as output
}
void loop() {
digitalWrite(13, HIGH); // sets the digital pin 13 on
delay(1000); // waits for a second
digitalWrite(13, LOW); // sets the digital pin 13 off
delay(1000); // waits for a second
}
Notes and Warnings
The analog input pins can be used as digital pins, referred to as A0, A1, etc.
The exception is the Arduino Nano, Pro Mini, and Mini’s A6 and A7 pins, which
can only be used as analog inputs.
pinMode()
Reference > Language > Functions > Digital io > Pinmode
pinMode()
[Digital I/O]
Description
Configures the specified pin to behave either as an input or an output. See
the Digital Pins page for details on the functionality of the pins.
It is possible to enable the internal pullup resistors with the
mode INPUT_PULLUP. Additionally, the INPUT mode explicitly disables the
internal pullups.
Syntax
pinMode(pin, mode)
Parameters
pin: the Arduino pin number to set the mode of.
mode: INPUT, OUTPUT, or INPUT_PULLUP. See the Digital Pins page for a more
complete description of the functionality.
Returns
Nothing
Example Code
The code makes the digital pin 13 OUTPUT and Toggles it HIGH and LOW
void setup() {
pinMode(13, OUTPUT); // sets the digital pin 13 as output
}
void loop() {
digitalWrite(13, HIGH); // sets the digital pin 13 on
delay(1000); // waits for a second
digitalWrite(13, LOW); // sets the digital pin 13 off
delay(1000); // waits for a second
}
Notes and Warnings
The analog input pins can be used as digital pins, referred to as A0, A1, etc.
Analog I/O
analogRead()
analogReadResolution()
analogReference()
analogWrite()
analogWriteResolution()
Advanced I/O
noTone()
pulseIn()
pulseInLong()
shiftIn()
shiftOut()
tone()
Time
delay()
Reference > Language > Functions > Time > Delay
delay()
[Time]
Description
Pauses the program for the amount of time (in milliseconds) specified as
parameter. (There are 1000 milliseconds in a second.)
Syntax
delay(ms)
Parameters
ms: the number of milliseconds to pause. Allowed data types: unsigned long.
Returns
Nothing
Example Code
The code pauses the program for one second before toggling the output pin.
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
}
Notes and Warnings
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 Blink Without Delay sketch, which
loops, polling the millis() function until enough time has elapsed. More
knowledgeable programmers usually avoid the use of delay() for timing of
events longer than 10’s of milliseconds unless the Arduino sketch is very
simple.
Certain things do go on while the delay() function is controlling the Atmega
chip, however, because the delay function does not disable interrupts. Serial
communication that appears at the RX pin is recorded, PWM (analogWrite)
values and pin states are maintained, and interrupts will work as they should.
delayMicroseconds()
micros()
millis()
Reference > Language > Functions > Time > Millis
millis()
[Time]
Description
Returns the number of milliseconds passed since the Arduino board began
running the current program. This number will overflow (go back to zero),
after approximately 50 days.
Syntax
time = millis()
Parameters
None
Returns
Number of milliseconds passed since the program started. Data
type: unsigned long.
Example Code
This example code prints on the serial port the number of milliseconds
passed since the Arduino board started running the code itself.
unsigned long myTime;
void setup() {
Serial.begin(9600);
}
void loop() {
Serial.print("Time: ");
myTime = millis();
Serial.println(myTime); // prints time since program started
delay(1000); // wait a second so as not to send massive
amounts of data
}
Notes and Warnings
The return value for millis() is of type unsigned long, logic errors may
occur if a programmer tries to do arithmetic with smaller data types
such as int. Even signed long may encounter errors as its maximum
value is half that of its unsigned counterpart.
millis() is incremented (for 16 MHz AVR chips and some others) every
1.024 milliseconds, then incrementing by 2 (rather than 1) every 41 or
42 ticks, to pull it back into synch; thus some millis() values are skipped.
For accurate timing over short intervals, consider using micros().
millis() will wrap around to 0 after about 49 days (micros in about 71
minutes).
Reconfiguration of the microcontroller’s timers may result in
inaccurate millis() readings. The "Arduino AVR Boards" and "Arduino
megaAVR Boards" cores use Timer0 to generate millis(). The
"Arduino ARM (32-bits) Boards" and "Arduino SAMD (32-bits ARM
Cortex-M0+) Boards" cores use the SysTick timer.
Math
abs()
constrain()
map()
max()
min()
pow()
sq()
sqrt()
Trigonometry
cos()
sin()
tan()
Characters
isAlpha()
isAlphaNumeric()
isAscii()
isControl()
isDigit()
isGraph()
isHexadecimalDigit()
isLowerCase()
isPrintable()
isPunct()
isSpace()
isUpperCase()
isWhitespace()
Random Numbers
random()
randomSeed()
Bits and Bytes
bit()
bitClear()
bitRead()
bitSet()
bitWrite()
highByte()
lowByte()
External Interrupts
attachInterrupt()
detachInterrupt()
digitalPinToInterrupt()
Interrupts
interrupts()
noInterrupts()
Communication
Print
Serial
SPI
Stream
Wire
USB
Keyboard
Mouse
Variables
Arduino data types and constants.
Constants
Floating Point Constants
HIGH | LOW
Reference > Language > Variables > Constants > Highlow
HIGH | LOW
[Constants]
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. These are the same as true and false,
as well as 1 and 0.
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 pinMode(), and read with digitalRead(), the Arduino (ATmega)
will report HIGH if:
a voltage greater than 3.0V is present at the pin (5V boards)
a voltage greater than 2.0V is present at the pin (3.3V boards)
A pin may also be configured as an INPUT with pinMode(), and subsequently
made HIGH with 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 can be done alternatively by
passing INPUT_PULLUP as argument to the pinMode() function, as explained in
more detail in the section "Defining Digital Pins modes: INPUT,
INPUT_PULLUP, and OUTPUT" further below.
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.
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 1.5V is present at the pin (5V boards)
a voltage less than 1.0V (Approx) 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).
INPUT | INPUT_PULLUP | OUTPUT
Reference > Language > Variables > Constants > Inputoutputpullup
INPUT | INPUT_PULLUP | OUTPUT
[Constants]
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.
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.
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 draw too
much current when the switch is closed. See the Digital Read Serial tutorial
for more information.
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.
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.
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().
See the Input Pullup Serial tutorial for an example of this in use.
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).
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.
Pins configured as outputs can be damaged or destroyed if they are
connected to either the ground or positive power rails.
Integer Constants
LED_BUILTIN
true | false
Conversion
(unsigned int)
(unsigned long)
byte()
char()
float()
Reference > Language > Variables > Conversion > Floatcast
float()
[Conversion]
Description
Converts a value to the float data type.
Syntax
float(x)
(float)x (C-style type conversion)
Parameters
x: a value. Allowed data types: any type.
Returns
Data type: float.
Notes and Warnings
See the reference for float for details about the precision and limitations of
floating point numbers on Arduino.
int()
Reference > Language > Variables > Conversion > Intcast
int()
[Conversion]
Description
Converts a value to the int data type.
Syntax
int(x)
(int)x (C-style type conversion)
Parameters
x: a value. Allowed data types: any type.
Returns
Data type: int.
long()
word()
Data Types
array
bool
Reference > Language > Variables > Data types > Bool
bool
[Data Types]
Description
A bool holds one of two values, true or false. (Each bool variable occupies
one byte of memory.)
Syntax
bool var = val;
Parameters
var: variable name.
val: the value to assign to that variable.
Example Code
This code shows how to use the bool datatype.
int LEDpin = 5; // LED on pin 5
int switchPin = 13; // momentary switch on 13, other side connected to
ground
bool running = false;
void setup() {
pinMode(LEDpin, OUTPUT);
pinMode(switchPin, INPUT);
digitalWrite(switchPin, HIGH); // turn on pullup resistor
}
void loop() {
if (digitalRead(switchPin) == LOW) {
// switch is pressed - pullup keeps pin high normally
delay(100); // delay to debounce switch
running = !running; // toggle running variable
digitalWrite(LEDpin, running); // indicate via LED
}
boolean
byte
char
double
float
int
long
short
size_t
string
String()
unsigned char
unsigned int
unsigned long
void
word
Variable Scope & Qualifiers
const
scope
static
volatile
Utilities
PROGMEM
sizeof()
Structure
The elements of Arduino (C++) code.
Sketch
loop()
Reference > Language > Structure > Sketch > Loop
loop()
[Sketch]
Description
After creating a setup() function, which initializes and sets the initial values,
the loop() function does precisely what its name suggests, and loops
consecutively, allowing your program to change and respond. Use it to
actively control the Arduino board.
Example Code
int buttonPin = 3;
// setup initializes serial and the button pin
void setup() {
Serial.begin(9600);
pinMode(buttonPin, INPUT);
}
// loop checks the button pin each time,
// and will send serial if it is pressed
void loop() {
if (digitalRead(buttonPin) == HIGH) {
Serial.write('H');
}
else {
Serial.write('L');
}
delay(1000);
}
setup()
Reference > Language > Structure > Sketch > Setup
setup()
[Sketch]
Description
The setup() function is called when a sketch starts. Use it to initialize
variables, pin modes, start using libraries, etc. The setup() function will only
run once, after each powerup or reset of the Arduino board.
Example Code
int buttonPin = 3;
void setup() {
Serial.begin(9600);
pinMode(buttonPin, INPUT);
}
void loop() {
// ...
}
Control Structure
break
continue
do...while
else
Reference > Language > Structure > Control structure > Else
else
[Control Structure]
Description
The if…else allows greater control over the flow of code than the
basic if statement, by allowing multiple tests to be grouped. An else clause
(if at all exists) will be executed if the condition in the if statement results
in false. The else can proceed another if test, so that multiple, mutually
exclusive tests can be run at the same time.
Each test will proceed to the next one until a true test is encountered. When a
true test is found, its associated block of code is run, and the program then
skips to the line following the entire if/else construction. If no test proves to
be true, the default else block is executed, if one is present, and sets the
default behavior.
Note that an else if block may be used with or without a
terminating else block and vice versa. An unlimited number of such else
if branches are allowed.
Syntax
if (condition1) {
// do Thing A
}
else if (condition2) {
// do Thing B
}
else {
// do Thing C
}
Example Code
Below is an extract from a code for temperature sensor system
if (temperature >= 70) {
// Danger! Shut down the system.
}
else if (temperature >= 60) { // 60 <= temperature < 70
// Warning! User attention required.
}
else { // temperature < 60
// Safe! Continue usual tasks.
}
for
Reference > Language > Structure > Control structure > For
for
[Control Structure]
Description
The for statement is used to repeat a block of statements enclosed in curly
braces. An increment counter is usually used to increment and terminate the
loop. The for statement is useful for any repetitive operation, and is often
used in combination with arrays to operate on collections of data/pins.
Syntax
for (initialization; condition; increment) {
// statement(s);
}
Parameters
initialization: happens first and exactly once.
condition: each time through the loop, condition is tested; if it’s true, the
statement block, and the increment is executed, then the condition is tested
again. When the condition becomes false, the loop ends.
increment: executed each time through the loop when condition is true.
Example Code
// Brighten an LED using a PWM pin
int PWMpin = 10; // LED in series with 470 ohm resistor from pin 10
to ground
void setup() {
// no setup needed
}
void loop() {
for (int i = 0; i <= 255; i++) {
analogWrite(PWMpin, i);
delay(10);
}
}
Notes and Warnings
The C++ for loop is much more flexible than for loops found in some other
computer languages, including BASIC. Any or all of the three header elements
may be omitted, although the semicolons are required. Also the statements
for initialization, condition, and increment can be any valid C++ statements
with unrelated variables, and use any C++ datatypes including floats. These
types of unusual for statements may provide solutions to some rare
programming problems.
For example, using a multiplication in the increment line will generate a
logarithmic progression:
for (int x = 2; x < 100; x = x * 1.5) {
println(x);
}
Generates: 2,3,4,6,9,13,19,28,42,63,94
Another example, fade an LED up and down with one for loop:
void loop() {
int x = 1;
for (int i = 0; i > -1; i = i + x) {
analogWrite(PWMpin, i);
if (i == 255) {
x = -1; // switch direction at peak
}
delay(10);
}
}
goto
if
Reference > Language > Structure > Control structure > If
if
[Control Structure]
Description
The if statement checks for a condition and executes the following
statement or set of statements if the condition is 'true'.
Syntax
if (condition) {
//statement(s)
}
Parameters
condition: a boolean expression (i.e., can be true or false).
Example Code
The brackets may be omitted after an if statement. If this is done, the next
line (defined by the semicolon) becomes the only conditional statement.
if (x > 120) digitalWrite(LEDpin, HIGH);
if (x > 120)
digitalWrite(LEDpin, HIGH);
if (x > 120) {digitalWrite(LEDpin, HIGH);}
if (x > 120) {
digitalWrite(LEDpin1, HIGH);
digitalWrite(LEDpin2, HIGH);
}
// all are correct
Notes and Warnings
The statements being evaluated inside the parentheses require the use of
one or more operators shown below.
Comparison Operators:
x == y (x is equal to y)
x != y (x is not equal to y)
x < y (x is less than y)
x > y (x is greater than y)
x <= y (x is less than or equal to y)
x >= y (x is greater than or equal to y)
Beware of accidentally using the single equal sign (e.g. if (x = 10) ). The
single equal sign is the assignment operator, and sets x to 10 (puts the value
10 into the variable x). Instead use the double equal sign (e.g. if (x == 10) ),
which is the comparison operator, and tests whether x is equal to 10 or not.
The latter statement is only true if x equals 10, but the former statement will
always be true.
This is because C++ evaluates the statement if (x=10) as follows: 10 is
assigned to x (remember that the single equal sign is the (assignment
operator)), so x now contains 10. Then the 'if' conditional evaluates 10, which
always evaluates to TRUE, since any non-zero number evaluates to TRUE.
Consequently, if (x = 10) will always evaluate to TRUE, which is not the
desired result when using an 'if' statement. Additionally, the variable x will be
set to 10, which is also not a desired action.
return
switch...case
while
Reference > Language > Structure > Control structure > While
while
[Control Structure]
Description
A while loop will loop continuously, and infinitely, until the expression inside
the parenthesis, () becomes false. Something must change the tested
variable, or the while loop will never exit. This could be in your code, such as
an incremented variable, or an external condition, such as testing a sensor.
Syntax
while (condition) {
// statement(s)
}
Parameters
condition: a boolean expression that evaluates to true or false.
Example Code
var = 0;
while (var < 200) {
// do something repetitive 200 times
var++;
}
Further Syntax
#define (define)
#include (include)
/* */ (block comment)
// (single line comment)
; (semicolon)
{} (curly braces)
Arithmetic Operators
% (remainder)
* (multiplication)
+ (addition)
- (subtraction)
/ (division)
= (assignment operator)
Comparison Operators
!= (not equal to)
< (less than)
<= (less than or equal to)
== (equal to)
> (greater than)
>= (greater than or equal to)
Boolean Operators
! (logical not)
&& (logical and)
|| (logical or)
Pointer Access Operators
& (reference operator)
* (dereference operator)
Bitwise Operators
& (bitwise and)
<< (bitshift left)
>> (bitshift right)
^ (bitwise xor)
| (bitwise or)
~ (bitwise not)
Compound Operators
%= (compound remainder)
&= (compound bitwise and)
*= (compound multiplication)
++ (increment)
+= (compound addition)
-- (decrement)
-= (compound subtraction)
/= (compound division)
^= (compound bitwise xor)
|= (compound bitwise or)
