Overview

Regardless of previous experience, all MPLAB X users should be aware that the MPLAB X Integrated Development Environment (IDE) website has documentation available under Help on the MPLAB tool bar. The primary software development tool is the integrated development environment (IDE) that provides an interface between the development platform and the target embedded system. The target system for this project is the Digilent chipKIT Pro MX7 processor board. Conventional IDE systems consist of software that runs on the PC or Linux^® computer and special hardware that manages the microcontroller on the target system. A separate PIC microcontroller on the chipKIT Pro MX7 processor board provides the special hardware needed to interface with the PC that is running the MPLAB X IDE. The IDE assists the program developer in converting one or more text files written using C or assembly language instructions into a file that contains a set of binary instructions that is programmed into a microprocessor.

The MPLAB X IDE does this transformation in four steps. First, the editor is where the programmer writes his or her C language programs. A project consists of one or more text files that the compiler converts into one or more object files. The object files are combined using a linker that generates a single file that the loader then programs into the microprocessor.

Source files with the “.c” extension contain C statements that define the functionality of the file such as the interface to an LCD or the implementation of a software time delay. Files with the “.h” extension are called header files that contain C instructions and directives that allow the source code to be reused in different application. Generally each “.c” file has a companion “.h” file that contains function prototypes and definitions.

The MPLAB X editor has many features to help you to write C code that the compiler can convert into an object file. The compiler checks each source file for proper C syntax and that all references are resolved. Compiler errors are identified with the file name, the line number in the file where the error was detected, and a description of the error. The link and load processes will be completed only if the compiler completes its task without finding any errors. There may be times that the compiler generates warnings. In such cases, the link and load operations will still be completed. Compiler warnings are generated if the source code attempts to give the compiler an instruction that is ambiguous or confusing but the syntax is correct. In these cases, the compiler makes a reasonable but not necessarily correct interpretation of your instruction. Clean code is code that compiles with no errors or warnings when using the setting for the highest level of error and warning generation.

Project_0 consists of five text files: Project0.c, Project0.h, chipKIT_Pro_MX7.c, chipKIT_Pro_MX7.h, and config_bits.h. Project0.c contains the C source code for this application that contains the function “main”. Every project must have one and only one source file containing the function main. Project0.h contains the function prototypes as well as “#define” statements used in Project0.c.

The config_bits.h file contains pragma directives that configure the operating characteristics of the PIC^®32 processor. The reader should refer to the chipKIT Pro MX7 Board Reference Manual for additional information concerning the directives in config_bits.h. Files chipKIT_Pro_MX7.c and chipKIT_Pro_MX7.h contain functions that initialize the PIC32 processor for the interface to hardware on the Digilent chipKIT Pro MX7 processor board. These three files will be used in this project as well as all future projects.

A fundamental skill to learn in this project is how to use the MPLAB IDE to develop software that runs on the PIC32 processor. The steps in this exercise are designed to show you how to create a new stand-alone project and how to use the software instrumentation to verify that the program is executing as designed. You will use “cursor over variable” and “watch window” to allow you to observe the values of data variables. You will use single stepping and break points to examine the sequence of program execution. You will also use the compiler error messages to assist you in finding syntactical errors.

Another commonly overlooked software development tool is the common handheld calculator. Computer algorithms can become convoluted and complex. For the synthesis phase of code development, it is good practice to write out the algorithm as a series of expressions that can be implemented using a series of steps with a calculator. Then, convert these expressions into C program statements. For the code development test phase, generate a set of input parameters and work through your series of expressions using the calculator and record the results for each step. Finally, run the C program using the same set of parameters. If the results do not match, then there is an error in your expressions or C code, or possibly both. Thorough algorithm testing requires that the input parameters vary over the possible range of values.

MPLAB X IDE Tutorial

The following tutorial is specific to the chipKIT Pro MX7 processor board that using the “licensed debugger” provided by Digilent. Microchip^® provides additional tutorials that the reader should also use to become familiar with the tools and features of MPLAB X IDE.

Connecting the chipKIT Pro MX7 Processor Board

Figure 1 is a picture of the chipKIT Pro MX7 processor board. Before connecting the debugging USB cable to the PC, verify that the Board Power select jumpers shown on the upper left are positioned correctly. As shown, the processor board is powered using the debugging PC USB connection. The board power switch is located in the lower left corner. Once the board power is turned on, the red power indication LED should be on. It is helpful to connect the processor board with the debugging USB cable and power it on before launching a new MPLAB X project.

Software Generation—Program Synthesis

All of the text files for Project 0 are provided in the tabs located at the right. After completing the steps to create a project, you can either create additional source and header files, or you can add existing files by clicking on either the source files folder icon or the headers files folder icon in the Project window, as shown in Fig. 15. This process is also described in the Minute Video discussed in paragraph C of Launching a New Project. Click on Add existing item… or Add existing item from Folders… to add additional existing files to the project. The process is the same for adding and creating header files. It is possible to include precompiled files in projects. However, the use of files like linker files and library files are beyond the scope of this project.

The C source file named Project0.c contains the function “main”. The execution of the user- generated code starts here. The main function, such as the one in Project0.c, contains three common elements: program statements that are executed only once such as the initialization routines, an infinite loop that conditionally repeats the execution of statements that implements the application, and a return statement that should never be executed but is there to satisfy the fact that the main function has a non-void return data type.

Software Testing — Program Analysis

There are two major debugging resources provided by the MPLAB X IDE: observing code execution and observing the values of variables. Code execution is observed by using two execution controls: breakpoints and single stepping. Break-points allow the program to run to a specific line of code and halting execution before executing the line of code where the breakpoint is placed. Single-stepping executes only the current line of code. The controls along the top of the screen shown in Fig. 16 control the flow of program execution. After generating the needed source files, the user clicks on the Debug button. The code in the project is processed through the compile, link and load operations and the program begins execution. The program runs until the execution encounters a breakpoint or the Program Pause control is selected. The processor resumes running if the Run Program control is selected.

By default, MPLAB X begins execution as soon as the program is loaded into the processor. During program development, it is useful to halt the program execution on the first executable line of code in the main function. To change the default setting, select: Tools -> Options -> Embedded -> Generic Settings. Change the selection for Debug startup from Run to Main as shown in the figure below.

Breakpoints are enabled by clicking on the line number beside the source code where you want the program to halt. The two enabled breakpoints shown in Fig. 16 are at lines with the pink box that replaces the line number. If the line of source code is shaded green, the processor has halted before executing that line of code. The maximum number of breakpoints available on the chipKIT Pro MX7 is six. (See question 6 in Try It on Your Own!)

Figure 17 identifies two types of single-stepping: step-over and step-into. The difference in single-step operation is observed only if the next line of code to be executed is a call to a function. Step-over executes all of the lines of code in the function call instruction as if it is a single instruction. The step-into halts code execution at the first line of code in the function that is called.

There are two types of windows used for observing variable data: Watch windows and Variables windows. Those not familiar MPLAB X are directed to the Microchip web based tutorials that cover the Watch and Variable windows. Data displayed in the Watch window are for global variables and variables declared as static local variables. Watch window variables must be individually added to the window.

Data displayed in the Variables window are function local variables and automatically displayed when executing a particular function. Figure 17 shows the screen when the Variables window is selected for display. Take note of the three control icons on the left. The user should place the mouse pointer over each of those icons to have a description of control functionality displayed. Clicking on the middle icon, the blue diamond gem with an arrow, toggles the display between local variables only to local variables and global variables as shown in Fig. 17. Note that values shown for static local variables declared outside the function where program execution is halted are marked as “Out of Scope.” These are variables that are declared as static in functions other than the function where execution is halted.

Complete descriptions of the Watch window and the Variables window are available using MPLAB X Help.

Another method of observing the value assigned to a variable is by placing the cursor on the variable. This only works if working in the debug mode and the processor is halted.