UBMP4 Introductory Programming Activity 4

The main( ) function is special

Did you notice the main( ) function declaration in the code snippet, above? The main function is required in every C language program, and every C program starts by running the first line of code inside the main( ) function.

Since main is the first part of a program to run, it makes sense that the parameter specifier in the int main(void) declaration is void, as there is no calling code that could run before main to send main any parameters. But, if main is the first function to run, isn’t it odd that it is coded with an int return type? Again, as main is the first thing to run, there is no code running before it to return data to! Nonetheless, the int type is required by MPLAB, and every PICmicro C program must begin with the same int main(void) function declaration.

The main program

The main program file in in any C program is the one that contains the main function. Many C projects name the file containing the main function, ‘main.c’, to indicate that it contains the program’s starting and main code. We have elected not to do that in these programming activities, since each open file’s name is shown in a tab in MPLAB X. Having multiple programs’ main files open for reference would result in a number of tabs all labelled ‘main.c’, making it more confusing to determine which program tab is which. Instead, each of our programs is labelled with its activity name.

Download the Intro-4-Functions program files (.zip) to create the MPLAB project for this activity, or import the files into MPLAB from its Github repository. Let’s examine the contents of the main file, Intro-4-Functions.c, below:

Program Operation

The program begins with the declarations and code for the two new functions, read_button( ) and pwm_LED4( ), followed by the required main( ) function. To anyone reading the program for the first time, these descriptive function names hopefully provide some insight into what the functions do, and how the functions might be put to use in the program.

Even though the two new functions appear above the main( ) function in the code, the compiler builds the code so that the main( ) function is first to run. Reading further into the main( ) function, it should also become apparent that the readability of the program, and potentially, comprehension of its operation, has been improved by replacing the longer function code with shorter, descriptive function call statements to the functions.

The read_button( ) function

The read_button( ) function reads the state of the pushbuttons and returns a unique value representing the first pressed button, or a different value if none of the buttons are pressed. Let’s take a look at the function to see how it does that:

The function declaration begins with the unsigned char return type indicating that this function is expected to return a piece of data – in the form of an 8-bit binary number, from 0-255 in value – to the calling code. Where does this number come from?

The code that makes up the function is an if-else condition, so one of its options will always be chosen. Each conditional block includes a return( ) statement, which explicitly returns from the function back to the calling program, even before the end of the function code is reached. Importantly, the value in the brackets – set to a number by previously-defined constants – is returned from the function to the function call. We can examine the function call statement in the main code to see how the variable is assigned a number from the read_button( ) function:

The function call statement is in the form of a variable assignment expression. The variable button will be assigned the value returned by the read_button( ) function. The value assigned to the button variable is used in the conditional statements that follow to increment or decrement the PWM value.

The pwm_LED4( ) function

After reading the pushbuttons, the conditional statements that follow will adjust the PWM value if the up or down buttons are pressed. Below that is a statement that calls a PWM function and passes it the desired LED4Brightness value:

The actual code that performs the PWM operation using the supplied brightness value is shown in the pwm_LED4( ) function, below:

Two important things to notice in the function declaration are the void return type, and the parameter variable assignment. First, the void return type shows that no data value is returned from this function. The second thing to notice is that the variable assignment copies the value of the variable passed to it – in this case the LED4Brightness value passes as a parameter in the function call – and saves it in the newly-created pwmValue local variable.

Variables created in a function declaration are local, meaning they are only available to the code within the function itself. This is in contrast to variables created in the main program which are global, or available to all of the program code. Although not used here, making a local copy of a global variable in a function offers the advantage that the copy of the variable can be modified without altering the value of the global variable for the rest of the code.

Learn more – program analysis activities

Hopefully, you have built and run this program to verify its operation. If not, do that now, as the next steps will break the build process by relocating the function code. Then, function prototypes will be added to the program to allow it to build again.

While this program is perfectly functional as is, some people may not like that the beginning of the main( ) function is below the new function code at the top of the program. You can imagine that in a program containing many more functions, anyone reading or editing the code would have to scroll all the way down past them to find the main( ) function code. So, why not just move the functions below the main code?

Let’s give that a try. Cut the two functions out of the code at the top of the program and paste them below the comment at the end of the code (below the three closing curly braces). Then, build the program. During compilation three warnings and two errors were produced, with a part of the error output shown below:

What are these warnings and errors trying to tell us? The first warning shows that the compiler sees read_button as a function, but one that has not been declared yet. The warning lets us know that implicitly declaring the function during its first use is not possible.

The reason for the error is that the C compiler generates the program’s machine code during what is know as a single pass through the program, reading all of our source code once, from the top to the bottom of the program code. When the compiler read our original program, with the function code at the top, the function declarations provided the compiler with all of the information about the code and variables it needed to know about in order to build the function code. The compiler could then easily build the the later function call, because it already knew about the functions.

Moving the functions below the main code means that the compiler tries to generate the program code without having any knowledge of the function or the variables required by the function. Clearly, this makes it impossible for the compiler to generate the program. But, we can use function prototypes to tell the compiler all it needs to know to successfully build the program.

Function prototypes

Function prototypes are like empty function declarations. Function prototypes provide the compiler with important details about the functions, namely the return-type, the function name, and the parameter types, but leave out the actual function code. Add these two function prototypes above the main( ) function in the code, where the functions were originally located, and then build the program again.

The addition of these two prototypes above the main code allow the program to build successfully, even with the function code moved below the function calls in the main code. But, how can adding these two lines possibly work? The function code is still effectively missing, since it is still located below the main( ) function, and the compiler will not know what it does, or what variables are required. How will the read_button( ) function even return data if the compiler doesn’t know about it?

The answer is that C compilers have a companion helper that takes care of these situations – the linker. The C compiler generates blocks of code for each function, and can build all of the functions separately. The function prototypes inform the compiler about the functions and variables that it will encounter, allowing the C compiler to reserve variables of the proper type (and with abstracted names) in program memory. In this program, one 8-bit byte of memory will be reserved to hold the value returned by the read_button( ) function, and another byte of memory will be reserved hold the value of the variable passed to the pwm_LED4( ) function. When the linker runs, it will link all of the variables to their functions, and may relocate program code (or just stitch it together), completing the build of the final program.

While the compiling and linking steps represents a complex process, you don’t need to understand these concepts to appreciate the benefits they provide. Function prototypes provide the compiler with the important information it needs to prepare to use the functions, and the function code can be located anywhere in the program, including in totally separate files. The UBMP420.h and UBMP420.c files for all of these activities are examples of this. The top of this program includes the directive:

This #include statement adds the contents of the UBMP420.h file to our program, invisibly, at compile time. That file contains prototypes for functions in the UBMP420.c file, which the compiler will also compile separately. The linker will stitch all of the required functions from all of the files together to build our actual program.

Activity 4 learning summary

Functions provide a number of advantages in most programs. First, functions simplify the main structure of the program by moving larger blocks of program code out of the main code and into separately located blocks of function code. These functions can remain in the main program source code file or can be part of other source code files in a programming project.

When functions are logically named, they can aid in code readability by acting as meaningful descriptions of the purpose of the function code, and abstracting away the complexity of the code in the function.

Of particular importance in small, memory constrained microcontrollers, is the ability of function code to be reused by being called from multiple locations in a program instead of being duplicated in each of those locations. This feature alone will help you make your programs smaller and easier to maintain, making you more productive.

Programming Activity 4 Challenges

1. It might be useful to have a button that instantly turns LED D4 fully on or off instead of waiting for it to brighten and dim while the UP and DOWN buttons are held to change the PWM duty cycle. But, PWM dimming dimming capability is also a useful feature that should be retained.

Modify the read_button() and main() functions to use SW2 as an instant-on button, and SW5 as an instant-off button. Pressing either of these buttons should over-write the current LED4Brightness value with either 255 or 0, while still allowing SW3 and SW4 to adjust the brightness smoothly and in smaller increments when pressed.

2. Create a new program that uses functions to turn on one LED for each pushbutton while the button is being pressed, and to turn off the LEDs when all of the buttons are released.

Start by creating a function that will return a number from 1-4 corresponding to which of the SW2 to SW5 pushbuttons is being pressed, or that returns a value of 0 if no buttons are pressed. Then, create a second function that will accept a number from 0 to 4 which will turn off all of the LEDs in response to a 0 input or light the corresponding LED for each pushbutton when receiving the numbers 1-4.

3.Create a four note music player using two functions, one to read the pushbutons (similar to Activity 2, above), and a second to play a sound on the piezo beeper using a loop.

Start by creating a sound function that will receive a parameter representing a tone's period or pitch. Then, modify the pushbutton function to return a different period or pitch in response to each button being pressed. You could even modify your pushbutton function to respond to multiple, simultaneous button presses so that your program is able to play more than four notes using just the four buttons!

4. A function that converts an 8-bit binary value into its equivalent 3-digit decimal number might be useful for helping us to debug our programs (as you will see in the next activity). Create a function that converts an 8-bit binary number into three decimal character variables representing the hundreds, tens, and ones digits of a (binary) number passed to it. For example, passing the function the value of 142 will result in the hundreds variable containing the value 1, the tens variable containing 4, and the ones variable 2. How could you test this function to verify that it works? Try it! (Hint: the BCD number system represents the decimal digits 0-9 using only 4 bits. Can you display the equivalent BCD digits on the LEDs?)

Previous: UBMP4 Introductory Programming Activity 3 - Loops