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)