Mplab IDE tutorial

MPLAB IDE/C18 Tutorial for C Programming

Page 1 of 12 S. Chen 2005


This document provides information for a quick start. The MPLAB IDE software contains extensive help manuals under Help menu.

1. Create a New Folder for The Project It is best to contain all the files related to a project in a folder.

Use Windows Explorer to create a directory C:\blink for all your project files. Do not create the directory in a network drive (H:) or you may risk crashing the program or the computer.

2. Starting MPLAB IDE To launch MPLAB IDE click the MPLAB IDE icon on the desktop.

Figure 1: MPLAB IDE icon

The Microchip splash screen will appear while MPLAB IDE is loading.

3. Create a New Project You need a project to build the program. Follow the steps below to create a new project.

From MPLAB IDE, select Project>New... or click on the New Project button; the New Project dialog box will open.

Figure 2: New project button

Enter a name for your new project (blink). The project name and the project directory name do not have to match but they will for this exercise.

Use the Browse button to select the path to the directory you just created. Click OK.

4. Select the Device You must first tell MPLAB IDE the device that you are going to use. For this tutorial, we will use the PIC18F458.

Select Configure>Select Device

Select PIC18F458 from the device pull-down list. Click OK.



5. Set Language Toolsuite Select Project>Set Language Toolsuiteto choose the programming language. Select Microchip C18 Toolsuite for this tutorial.

6. Create Source Code Select File>New to open a new file for edit. Enter the example code below.

Figure 3: Sample code for the tutorial

Once you have completed entering the code, select File>Save and save the file in the project directory as: blink.c.

The editor is context sensitive. As soon as the file extension is known, it shows different colors and emphasis for reserved words.

7. Add the Source Code File to the Project Now that you have created the source code file, it needs to be added to the project so that you may build the product.

Select Project>Add Files to Project

Select the file you just created and saved (blink.c). Click Open.

The newly inserted file should appear in the project window (the window with the title blink.mcw) under "Source Files". If not, either the file extension is incorrect or the project language suite selection does not match the file extension.

Save the project files by selecting Project>Save Project.



8. Select Linker Script Linker takes the outputs of the compiler and links them with other essential parts to generate a memory image for the product. Linker script contains three pieces of information for linker: the name of the startup object file, the names of the library files, and the memory allocation. A special version of linker script written for use with bootloader program (to be covered in next lab session) is included as C:\mcc18\18f458b.lkr. Right click on Linker Scripts entry of the project window, select Add Files and browse to the file mentioned above.

After the linker script is added to the project, the project window should look like:

Figure 4: Project Window showing blink.c in source file and 18f458b.lkr in linker script

8.1 C startup file

At reset vector, a piece of code initializes the registers and the initialized data (idata section in C18). It then goes into an infinite loop that calls main( ) repetitively. (Therefore, if you allow a return from main( ), it will go right back to main!) A special version of startup program modified to work with the bootloader program is precompiled and store as an object file with the name c018ib.o in the C:\mcc18\lib\ folder.

8.2 Library file

Simplicity was the mantra of C language. A large portion of the C functions is compiled into library files. An intelligent linker will link in only the portions of the functions that are referenced by the user program. C18 provides a C library file called clib.lib in the C:\mcc18\lib\ folder. It also has a library file with many PIC18 specific I/O functions called p18f458.lib in the same folder.

8.3 Memory allocation

This portion of the linker script tells linker where to put the linked program in memory. A special memory allocation scheme of 18f458b.lkr is used for the output to work with the bootloader program.



9. Set paths Before building the project, you need to specify several paths for the MPLAB IDE to follow to find the files. Click Project>Build Options>Project to open the Build Options dialog box. Select General tab if it is not on the top already. Fill up the include path and library path as specified below (assuming C18 was installed at the default location C:\mcc18).

Figure 5: Build Options paths

Click OK button to close the Build Options dialog box.

10. Make or Build the Project Select Project>Make to make your project. Select Project>Build All to build your project. Alternatively or more conveniently, you may use the make or the build all buttons.



Figure 6: The left button is Make and the right one is Build All

The difference between Make and Build All is that Make performs the minimum required steps and Build All deletes everything except the source files and rebuilds the whole project. Normally, Make is sufficient to update the product after you make changes to the source files. You should always use Build All if you make changes in the project windows or build options.

If your file is compiled successfully, the messages will read like:

Figure 7: Build output window of a successful complete build

If your file did not compile successfully, error messages will appear in the output window. Always scroll back to the beginning of the output window to be sure that you did not miss any messages.

Figure 8: Build output window with a syntax error



Double click on the error message in the Output window will bring you to the error in the source file. A green arrow in the gutter on the left of the source file window points to the line where the error was found (It may not be the location where error occurs).

If the errors were found after compilation, it may not be able to link the error to a specific location in the source. Correct all the syntax errors and rebuild the project. Warnings are errors that were deemed not critical to produce a product. It is advised that you always read the warning messages and attempt to clean them up.

Figure 9: Double click the error message will bring to the location of the error which is indicated

by a green arrow in the left gutter

11. Compiler Output Files Upon a successful build, the compiler and the IDE create a list of output files. The following are the ones that might interest you.

11.1 The .LST File

The listing file shows the source file that the compiler sees along with the assembly code produced by the compiler.

11.2 The Memory Image Files

The linker produces three different formats of memory image files: the .COD file, the .COF file, and the .HEX file.

The .COD file contains symbol table and is used by MPLAB IDE to support debugging tools.

The .HEX file conforms to Intel Hex format. It is usually used to burn the chip. Unfortunately, the format of the hex file generated by C18 is not acceptable by the bootloader that we will use for the rest of the semester. We will cover the procedure to regenerate a hex file that is acceptable by the bootloader later.

12. Simulate the Execution of Your Program

12.1 Set Up the Simulator

Now that your project is built, you will want to check whether it is functioning properly. To do this, you will need to select a debugging tool. For this tutorial, we will use the simulator, MPLAB SIM.



Select the MPLAB SIM simulator as the debugger by Debugger>Select Tool>MPLAB SIM. The following changes should appear in MPLAB:

1. MPLAB SIM" appears in the first field of the status bar at the bottom of the MPLAB IDE window.

2. Additional menu items now appear in the Debugger menu.

3. Additional toolbar buttons should appear.

Figure 10: The simulation toolbar with the buttons starting from left: Run, Halt (gray), Animate,

Step In, Step Over, Step Out, Reset

Rest the mouse cursor over a toolbar button to see the tool tip of the buttons function.

12.2 Trace Your Code Click the Reset button will reset the processor and point the program counter to the reset vector. If you are programming in assembly language, there will be an arrow in the gutter of your source code window indicating the first source code line to be executed. But in a C program, the linker adds a startup code at the reset vector that is invisible in your source code window. Therefore, you wont see the green arrow.

Click Run button to run your application. You will see "Running" appear in the status bar.

To halt program execution, click on the Halt button. The green arrow will indicate the line of code where the program halted. (To be exact, the green arrow is pointing to the next line of code to be executed.)

You may single step through the program by clicking on the Step Into button. This will execute the line pointed by the green arrow and move the arrow to the next line.

Most likely, your program is stuck in the delay loop. To bail out of the delay loop, click on the Step Out button. Step Out brings the program out of a level of function call and return to the caller.

If you keep clicking on Step Into button, you will get back to the delay loop again. To avoid that, use Step Over button. Step Over executes the subroutine without stepping into it.

You may use the appropriate Debugger menu items or the hotkey shown next to the menu item instead of clicking on the buttons.

12.3 View Variables You can see the values of variables when the simulation is halted by putting the mouse cursor over the name of the variable in the source file. A tool tip like display will show the current value of the variable (this is called mouse over).



Rather than mouse over the name each time you want to see the value of a variable, you can open a watch window. The watch window will remain on the screen and show the current variable values when the program execution halts. Watch windows may be found under the View menu.

Figure 11: The Watch window. The value of counter was changed and indicated in red

Add variables: i, counter and PORTB in the watch window. You may click in the blank area just under the last Symbol Name and type in the name of the variable, or you may use the pull-down menu selection on the top of the window to choose the variable then click Add button. Both i and counter are variables in C program and you will find them to the right of Add Symbol button. PORTB is a special function register; you have to find it next to Add SFR button.

After the variable is added, the display format may be modified by right click on the line and select Properties. Here, you may change the displayed format to decimal from hexadecimal.

The values in the watch window do not get updated when the program is running. Only when the program execution halts will they get refreshed. The values are displayed in red when its content changed.

Since i is an autovariable in function delay, you need to step into delay before the value becomes valid. Otherwise, Out of Scope is shown as its value.

12.4 Breakpoint By double clicking on a line of code, a stop sign with a B appears in the gutter to indicate the breakpoint. If you run the program, the execution halts when encountering a breakpoint. The green arrow will rest on the stop sign. (When the execution halts, the line with the stop sign is NOT executed yet.)

Figure 12: The source file window during simulation. The stop sign with B in the gutter indicates

a breakpoint; the green arrow indicates the next statement to be executed.



13. Burn a Device In the bygone era, the one time programmable (OTP) devices were actually consisted of minute fuses and programming a device incurred applying a high voltage to burn off the fuses. Nothing gets burned in the modern erasable programmable devices during programming. But the term burn is still used to avoid the confusion created by the polymorphism of the word program.

Simulation is a good way to debug a program. Once you have done all the simulations you want to do, you will then program an actual device to test it.

1. Power up the PICSTART Plus Development Programmer

2. Connect the DB9 cable from the Programmer to the COM1 port of the PC

3. Select Programmer>Select Programmer, and click on PICSTART Plus. If the connection is established, the output window will be silent. The Programmer menu items and toolbar items will be added but in gray.

4. Establish communications with the programmer by selecting Programmer>Enable Programmer. If the connection is established, the Programmer menu items and toolbar items will change to active colors.

Figure 13: The Programmer toolbar with buttons starting from the left: Blank Check, Read,

Program, Verify, Erase

The output window may contain the following messages but you may ignore them.

Figure 14: The PICSTART output window. The PICSTART Plus Units in the lab can not be

upgraded and will always show these messages.

5. If proper connection between programmer and PC cannot be established, the output window will have the message Cannot Transmit. Please verify connection and retry the previous operation. Check the cable connection and retry enabling the PICSTART.



6. Insert the device to be programmed in the ZIF socket and lock the device. Make sure the device is in the socket with proper orientation. Reversing the device orientation is known to be a sure way to destroy it.

7. Rebuild the project after the connection between the programmer and PC is properly established.

8. Click Erase button to erase the device

9. Click Program button to program the information currently loaded in the MPLAB IDE into the device. The operation progress is indicated at the left corner of the status bar. Results will be displayed in the Output window.

10. While programming and verification are going on, the orange ACTIVE LED of PICSTART will stay on. Do not remove the device when the orange LED is on.

11. When programming is complete, the orange ACTIVE LED goes off and you may remove the device from the programmer and insert it in the circuit for testing.

12. Always check the output window for possible errors in programming before proceed with your testing.

14. Modify Program Source Code Avoid the Traps!!! One of the common problem often causes numerous hours of time wasted is to modify a source file that is not in the project. For example, you use a copy of the project directory in your H: drive or in your USB pen drive. The project was copied to C: drive and the built off files in C: drive while you opened and edited the files in H: drive. You pounded your head for hours wondering why changes did not make a difference.

To avoid this trap, close all the source file windows in MPLAB IDE but leave the project window (the one with .mcw) open. Double click the file name in the project window to open and edit the file.

15. Burn a Device at a Different PC In the lab, we will not have enough Device Programmers for each PC. Rather than moving the programmer around, it will be easier to connect the programmer to a fixed PC and bring the program image file and the device over for programming.

At your lab station: 1. Build your project without errors 2. Insert the USB pen drive or a floppy disk in the drive 3. Copy the .HEX file to the pen drive or the floppy disk

At the programmer station: 1. Make sure the proper device type is selected. The current device selection is

displayed at the bottom status bar of the MPLAB window. 2. Select Debugger>Clear Memory>All Memory 3. Insert pen drive in USB connector or floppy disk in the drive 4. Select File>Import to open the Open dialog box 5. Browse to the folder with the hex file



6. Change file type to .HEX 7. Select the file you are going to use to program the device 8. Click Open button 9. You may use View>Program Memory to verify the file content 10. Proceed to program the device

To avoid the second trap, use Build All instead of Make after you change the content of the project window or the Build Options.

16. Create Hex File for Bootloader Microchip C18 creates fragmented hex file, which conforms to the Intel Hex format but is not readable by the bootloader program (which came from Microchip Application Note AN851). One of these days, I will modify the bootloader program to read C18 output. But until then, you have to take an extra step to create a bootloader friendly hex file.

16.1 Find the Memory Range Required

MPLAB IDE allows you to dump the selected program memory into a hex file using Export menu. There are two ways (at least) to find out the range of program memory needed for your program. One is to change the Build Options to generate map file by the linker. An easier way is to use auto-range of PICSTART programmer available in MPLAB IDE version 7 or later.

Figure 15: The PICSTART Plus auto select of memory range in MPLAB IDE can be used to

determine the program memory usage



Follow the procedure before to select PICSTART Plus as the programmer. (You do not need to enable the programmer.) Select Programmer>Settings in the menu to get the following dialog box. When Auto select memory areas and range is selected, the program memory range is indicated in gray below. Write down the start address and end address. The program memory range changes as you change the program source. It would be a good idea to use a much higher end address in case you forgot to look for the new value. The start address shall always be 200.

16.2 Export to a Hex File

Select File>Export menu to open the Export dialog box. Fill in the start and end address then uncheck all other selections. Click OK button and browse to the project directory. You may choose the same file name as the one created by C18 and overwrite it since you have no use of the original one.

Figure 16: The Export dialog box where the memory range is specified

17. Keep This Tutorial for Future Reference

Documents

Mplab IDE tutorial