Sub-programs, Functions

In many cases, the program grows to a size that becomes hardly manageable as a single unit. It isn't easy to navigate through the code that occupies many screens. In such a situation, subprograms can help. Subprograms are named functions in C and C++; while they are associated with an object, they are called methods (in this chapter, the name function will be used). The function contains a set of statements that usually form some logical part of the code that can be separately tested and verified, making the whole program easy to manage. Grouping many functions by creating a library stored in a separate file is possible. This is how external libraries are constructed.

Functions are the set of statements that are always executed when the function is called. A function can accept arguments as input data and return the resulting value. Two functions from the Arduino programming model mentioned before are already known – setup() and loop(). The programmer usually tries to make several functions containing all the statements and then calls them in the setup() or loop() functions.

The structure of the function is as follows:

type functionName(arguments) //A return type, name, and arguments of the function
{
  //The body of a function – statements to execute
}

For example, a function that periodically turns on and off the LED can look like this:

void exampleFunction() 
{
  digitalWrite(13, HIGH); //the LED is ON		
  delay(1000);			
  digitalWrite(13, LOW);  //the LED is OFF				
  delay(1000);	
}

The example above shows that the return type of aexampleFunction function is void, which means the function does not return any value. This function also does not have any arguments because the brackets are empty.

This function should be called inside the loop() function in the following way:

void loop()
{
  exampleFunction(); //the call of the defined function inside loop()
}

The whole code in the Arduino environment looks like this:

void loop()
{
  exampleFunction(); //the call of the defined function inside loop()
}
 
void exampleFunction() 
{
  digitalWrite(13, HIGH); //the LED is ON		
  delay(1000);			
  digitalWrite(13, LOW);  //the LED is OFF				
  delay(1000);	
}

It can be seen that the function is defined outside the loop() or setup() functions.

When some specific result must be returned as a result of a function, then the function return type should be indicated, for example:

//the return type is "int"
int  sumOfTwoNumbers(int x, int y) 
{
    //the value next to the "return" should have the "int" type; 
    //this is what will be returned as a result.
    return (x+y); 
}

In the loop(), this function would be called in the following way:

void loop()
{
  //the call of the defined function inside the loop()
  int result = sumOfTwoNumbers(2, 3); 
}

Every programming SDK, including Arduino IDE, comes with several ready-made functions that help develop applications, significantly reducing the effort and time of writing programs. These functions are written to handle inputs and outputs, process texts, communicate using serial ports, manipulate bits and bytes, and perform mathematical calculations. Refer to Arduino or other SDK documentation for details.

The popularity of microcontrollers and embedded programming caused the growth of communities of enthusiasts who create a vast of helpful software. This usually comes as a set of functions designed to handle specific tasks, e.g. interfacing with a family of graphical displays or communicating using the chosen protocol. Functions created for one purpose are grouped, forming the library. The number of libraries and their different version is so significant that software developers use a particular library manager to ensure that libraries are up-to-date or keep them in stable versions.

In the MCU world, is is common to use libraries that require a user (software developer) to implement a specific part of the code that is later automatically called by the library routines. Those functions are frequently called handlers and enable developers to inject their actions for a predefined set of activities without modifying library code. For this reason, the library contains a placeholder variable that can be assigned an executable code (a function body). This is handled with the use of pointers. A sample function handler variable is presented in the following code, along with the user function definition, assignment to the handler variable and a call to the handler:

int (*hUserImplementedFunction)(int); //Function handler variable 
                                      //(no code is here; 
                                      //it is just a pointer to the code, 
                                      //currently NULL, pointing to "nowhere"
...
int fMulx2(int a) {                   //User's implementation of the function. 
  return (2*a);                       //Multiply the argument 'a' value by 2
                                      //and return it to the callee.
  }                                   //Note: argument types and return types
                                      //must match with the variable above
...
 
hUserImplementedFunction = fMulx2;    //assign a function to the handler
                                      //starting from now, 
                                      //hUserImplementedFunction 
                                      //contains an address of the fMulx2 function
...
int j;                                      
if (hUserImplementedFunction!=NULL)   //check if the handler is not null 
                                      //to avoid NULL pointer exception and code hang
    j = hUserImplementedFunction(10); //call a handler, j is 20 now