Using Functions in a Sketch

Learn how to define and use functions in a Sketch.

Segmenting code into functions allows a programmer to create modular pieces of code that perform a defined task and then return to the area of code from which the function was "called". The typical case for creating a function is when one needs to perform the same action multiple times in a program.

For programmers accustomed to using BASIC, functions in Arduino provide (and extend) the utility of using subroutines (GOSUB in BASIC).

Standardizing code fragments into functions has several advantages:

  • Functions help the programmer stay organized. Often this helps to conceptualize the program.

  • Functions codify one action in one place so that the function only has to be thought out and debugged once.

  • This also reduces chances for errors in modification, if the code needs to be changed.

Functions make the whole sketch smaller and more compact because sections of code are reused many times. They make it easier to reuse code in other programs by making it more modular, and as a nice side effect, using functions also often makes the code more readable. There are two required functions in an Arduino sketch, setup() and loop(). Other functions must be created outside the brackets of those two functions. As an example, we will create a simple function to multiply two numbers.

Example

FuncAnatomy

To "call" our simple multiply function, we pass it parameters of the datatype that it is expecting:

1void loop(){
2int i = 2;
3int j = 3;
4int k;
5
6k = myMultiplyFunction(i, j); // k now contains 6
7}

Our function needs to be declared outside any other function, so "myMultiplyFunction()" can go either above or below the "loop()" function.

The entire sketch would then look like this:

1void setup(){
2 Serial.begin(9600);
3}
4
5void loop() {
6 int i = 2;
7 int j = 3;
8 int k;
9
10 k = myMultiplyFunction(i, j); // k now contains 6
11 Serial.println(k);
12 delay(500);
13}
14
15int myMultiplyFunction(int x, int y){
16 int result;
17 result = x * y;
18 return result;
19}

Another example

This function will read a sensor five times with analogRead() and calculate the average of five readings. It then scales the data to 8 bits (0-255), and inverts it, returning the inverted result.

1int ReadSens_and_Condition(){
2 int i;
3 int sval = 0;
4
5 for (i = 0; i < 5; i++){
6 sval = sval + analogRead(0); // sensor on analog pin 0
7 }
8
9 sval = sval / 5; // average
10 sval = sval / 4; // scale to 8 bits (0 - 255)
11 sval = 255 - sval; // invert output
12 return sval;
13}

To call our function we just assign it to a variable.

1int sens;
2
3sens = ReadSens_and_Condition();

As you can see, even if a function does not have parameters and no returns is expected "(" and ")" brackets plus ";" must be given.

Suggest changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. If you see anything wrong, you can edit this page here.

License

The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.