Your First Arduino Function

We just looked at an Arduino statement, and we're feeling pretty comfortable with that. Lets back up a little and look where the statement lives:

// the setup function runs once when you press reset or power the board
void setup() {
  // initialize digital pin 13 as an output.
  pinMode(13, OUTPUT);
}

OK we've got those comments, each starting with //. We know comments are clues that will help you understand what a program does. This one has a cryptic message: the setup function runs once when you press reset or power the board

Which is a little odd because you just learned that pinMode is the name of a function you can call. So what does the comment mean by "setup function" - shouldn't it say pinMode?

Wizardry

Remember at the end of the last section we talked about how you couldn't just make up a function request like writeMyHomework(CHEMISTRY)? That there is no wizard inside the Arduino that obeys your commands? That someone, somewhere has to tell the Arduino what a function has to do?

Well, you might be wondering how to do that and now you do because what you are looking at is the function definition of a new function called setup

What is a function?

Personally, I don't like to use the word function because its a little technical. Instead I like to refer to these parts of code as a procedure because its a word more people are familiar with.

A procedure is a collection of statements. Its used to group statements together so that we can refer to them all with one name. Its just like a procedure that we use to perform a task step-by-step, such as at school, work or home.

Here is the format for a procedure:

Returned value

Procedure name

(input values)

{ statements }

void

setup

( )

{  pinMode(13, OUTPUT); }

To better understand procedures, lets use an analogy to the kinds of procedures we're used to

// a procedure for washing the cat
clean cat wash the cat (dirty cat)
{
turn on the shower.
find the cat
.
grab the cat
.
put cat under shower
.
wait three minutes. // wait for the cat to get clean!
put cat under shower.
release the cat.
}

This is a procedure for washing the cat.

The name of the procedure is wash the cat, it uses a dirty cat as the input and returns a clean cat upon success.

There are two brackets, an open bracket { and a closed bracket }, that are used to indicate the beginning and end of the procedure. Inside the procedure are a bunch of statements, indicating the correct procedure for washing a cat. If you perform all of the statements, in order, then you should be able to turn a dirty cat into a clean cat.

Back to setup()

Looking again at the setup procedure

// the setup function runs once when you press reset or power the board
void setup() {
  // initialize digital pin 13 as an output.
  pinMode(13, OUTPUT);
}

We see that it is named setup and it has no input values and it returns, umm... something called a void

void setup() {

Now you're probably asking yourself "what is void?" Well thats a computer-scientist way of saying nothing. That is, this procedure doesnt return anything. If you studied the Old Testament you may remember the line And the earth was without form, and void in Genesis 1:2. That verse is telling you there was nothing where the earth would be, because it was void

Having a void return doesn't mean it doesn't do anything, just that it doesn't have a tangible number, cat, or whatever, to show when its complete)

The setup procedure is pretty simple (simpler than washing a cat, that is for sure). It only contains one statement:

pinMode(13, OUTPUT);

That plus the brackets makes the setup function definition complete.

Note that function/procedure definitions are not statements, they do not have a ; at the end, but there are ; after each statement inside the function.

The Secret of Setup

Finally, you may be wondering, what is so special about this function definition?

Glad you asked!

setup() is a special function. As the comment explains, it runs once and only once, when the Arduino first powers up or when it is reset
This guide was first published on Sep 02, 2016. It was last updated on Sep 02, 2016.
This page (Your First Arduino Function) was last updated on Aug 14, 2020.