1 

 

MPLAB X / ICD 3 Tutorial This document is adapted for MPLAB X and the ICD 3 In‐circuit Debugger from the tutorials that form chapter 3 of the “MPLAB ICD 2 In‐Circuit Debugger User’s Guide” and chapter 3 of the “MPLAB ICD 3 In‐Circuit Debugger User’s Guide”. 

1  INTRODUCTION  

This tutorial walks you through the process of developing a simple project using a sample program, TUT452.asm. This program uses the analog‐to‐digital (A/D) converter of the PIC18F452 on the PICDEM 2 Plus Demo Board (DM163022). The program configures the A/D module to convert input from A/D channel 0 (connected to the potentiometer on the demo board) and display the results as a binary number on the four PORTB LEDs. 

Topics covered in this tutorial: 

Creating a directory on the Lab fileserver 

Setting up the development environment 

Creating and configuring a project 

Adding source files to the project 

Building the project 

Debugging the project 

Programming the application 

TUT452.asm source code 

2  CREATING A DIRECTORY ON THE FILE SERVER  

In the Mechatronics Lab we may update the image on the computers at any time without warning. This means that any files that you have stored locally on a Mx Lab PC will be destroyed. 

You must always (and only) store your files on the File Server, mxlabserver. For this tutorial, the first thing that you must do is create a directory on the File Server to work in.   

1. Depending on whether you are working alone for this tutorial, or with a lab partner, follow the instructions in section 1.1 of the “Mechatronics Laboratory – Facilities” document to either 

a. create a personal directory on the U: drive (\\mxlabserver\Users)   OR   

b. create and assign permissions to a directory on the V: drive (\\mxlabserver\Groups) that you can share with your lab partner.   

2. Make a new directory ‐ say Demo ‐ in the directory that you created in step 1. 

3  SETTING UP THE DEVELOPMENT ENVIRONMENT  

The MPLAB X integrated development environment (IDE) software is installed and configured before you begin this tutorial. In the Mechatronics Lab we will always power the ICD 3 from the USB cable that connects it to the host PC. An external power supply will always be used to power the target board (the PICDEM 2 Plus Demo Board for this tutorial).  

Remember: You must not inject a signal into the ICD 3 when it is not powered. This means that the ICD 3 must be connected to the host PC first and disconnected last. 

Use the following connection/power‐up sequence: 

1. Plug the PC’s USB cable into MPLAB ICD 3 puck to apply power to it. The Power and Active LEDs on the puck should go on. Plugging in the ICD 3 will ensure that MPLAB X can find it during creation of a project. DO NOT power the target board yet. DO NOT connect the ICD 3 to the target yet.  

2. Start the MPLAB X IDE application, which should initially look similar to Figure 1. It will be useful to maximise the MPLAB X window.  

 

 

2 

 

 Figure 1: Initial view of MPLAB X, with no project open. 

4  CREATING AND CONFIGURING A PROJECT  

MPLAB X is an integrated development environment based on the open‐source, cross‐platform NetBeans IDE. Within MPLAB X everything is project‐based; you must create a project to develop your application. Creating a project involves selecting a specific microcontroller device, as well as selecting and setting up language tools, debug tools, programming tools and other project specifics. This ensures all items needed for successfully developing an application are present. 

4.1 Creating a project 

To create a new project, select “File” > “New Project”. The New Project Dialogue will open. Follow the steps below to configure the project.  

1. Choose Project ‐ Select Category “Microchip Embedded” and Project “Standalone Project”. Click [Next>] 

2. Select Device ‐ Choose Family: “Advanced 8‐bit MCUs (PIC18)” and Device: “PIC18F452”. Click [Next>] 

4. Select Tool – Under “Hardware Tools”, click on the serial number (SN: JITxxxx) of the ICD 3 that is shown. There should only be one; this is the ICD 3 that is connected to the PC. Click [Next>] 

6. Select Compiler – Under “Compiler Toolchains”, click on “mpasm (v5.51)” under mpasm. Click [Next>] 

7. Select Project Name and Folder – In the “Project Name” box, type a suitable name – “Tute0” for example, – for the project. In “Project Location” browse to the “Demo” directory that you created in step 3.2 of this tutorial. Tick the “Set as main project” tick box. Leave “Encoding” (the character set) at ISO‐8859‐1. Click [Finish]. 

MPLAB X should now look similar to Figure 2.  

 

3 

 

 Figure 2: MPLAB X after project creation. 

Figure 2 shows the four main MPLAB X windows in their default arrangement. The File Window shows different views of all of the files in the project. Even though we have not yet put even one source file in the project there are a lot of files that can be seen in Figure 2 in the File tab of the File Window. All of the files that you can see are automatically created and maintained by MPLAB X. These files define the project, including the exact microcontroller, the software toolchain (assembler, compiler, linker, etc.) and the hardware debugging tools. Do not edit any of the files in the nbproject tree! 

Double‐clicking on any file name in the File Window opens the file in the Editor Window. This is where you will edit your source files and view them when debugging. 

The Navigator Window is where you can view the project configuration and make changes to it.  

The Task Window is where output from the IDE is shown, such as output from the software toolchain during a project build and status messages from the debugging hardware for example, together with the internal state of the microcontroller’s memory. Memory values can only be inspected or changed when the microcontroller is not executing instructions. 

4.2 Configuring the project 

To inspect the project configuration, click on the Project name (here it is called Tute0) in the File Window and select “File” > “Project Properties (Tute0)” from the main menu bar. You will see something like the view shown in Figure 3. 

 

 

4 

 

 Figure 3: Project Properties – initial view. 

Have a look at what can be configured. You should not have to change anything for this project as it should have all been correctly configured during project creation.  

In the “General” configuration (Figure 4) you will see that MPLAB X has created a project folder called Tute0.X under your Demo directory to store the project, and will ignore sub‐folders according to the regular expression ^(nbproject|build|test)$. 

 

 Figure 4: Project Properties – General configuration. 

Please check to make sure that in the “Power” options category of the ICD3 configuration (Figure 5) that “Power target circuit from ICD 3” is NOT selected since we will always power the target microcontroller board and other circuitry from an external power supply. 

 

5 

 

 Figure 5: Project Properties – ICD3 Power configuration. 

5  ADDING SOURCE FILES TO THE PROJECT  

5.1 Obtain the source files 

You first need to obtain the two assembly language files that you will need for the tutorial and place them in the directory that you made in step 2. 

1. On the desktop there is a link to Coursework Files on Server. Open that link and go to Mtrx3700\Initial Workspace\   

2. Copy the files from Initial Workspace into the directory Demo\Tute0.X that was created by MPLAB X when the project was created. Make these files writable.  

5.2 Add source files to the project 

1. To add an existing source file to the project, right‐click on the project name in the File Window and select “Add existing item...” 

2. Select TUT452.asm, make sure that “Store path as Relative” is active and click [Select]. Using relative paths makes it much easier to move a project from one computer to another. 

3. Now if you double‐click on the filename TUT452.asm in the Files Window the file will open in the Editor Window as can be seen in Figure 6.  

6.  BUILDING THE PROJECT 

We can now build the project. Since this project contains assembly language source code, building it means assembling the source code using the MPASM assembler to produce relocatable object code, and linking that code with the MPLINK linker to create an executable binary file.  

Building in MPLAB X uses the UNIX make tool to build and link all source files in the project (only one in this simple tutorial example) in the correct order, accounting for dependencies between source files.  Only files that have been changed between builds, and their dependant files, will be re‐built by make. 

1. To build the project, click on the Hammer icon. If the Hammer icon is not visible, click “View” > “Toolbars” > “Run”. The Hammer and Broom icon does a clean and build, deleting intermediate files (for example relocatable object files) before building. This will force all source files in the project to be rebuilt. 

2. As the project builds, output from make is shown in the Output window (Figure 7). You will first see the result of assembler execution. If the assembler succeeds, the linker will then execute. The project should build successfully, producing two output files: 

a. Demo/Tute0.X/dist/default/production/Tute0.X.production.hex – This is the executable binary file ready to be loaded into the particular microcontroller and executed.   

6 

 

b. Demo/Tute0.X/dist/default/production/Tute0.X.production.cof  – This is a file in “common object file format” (COFF) that contains symbols (variable names, etc) from the source code and associated addresses. It allows the IDE to show you the source code instead of memory addresses when debugging.  

c. Intermediate files are also produced – files TUT452.err, TUT452.lst, TUT452.o and TUT452.o.d in the directory Demo/Tute0.X/build/default/production/ 

 

 Figure 6: Project with a single assembly language file added. 

 Figure 7: Output Window after successful build. 

7.  DEBUGGING THE PROJECT 

Now that the project builds we can download it to the target board – in this case a PICDEM 2 Plus – and attempt to run the code.   

1. Important: The ICD 3 should be connected to the PC via a USB cable at this point, providing power to the ICD 3. 

2. Make sure the PICDEM 2 Plus Demo Board is set up as follows:  

7 

 

d. The packaged oscillator has been selected by removing jumper J7. This selects the clock hardware that matches the way that the microcontroller clock circuits have been configured by the “EC OSC” selection in configReg.inc which is included from TUT452.asm. 

a. The LEDs have been enabled by fitting jumper J6. 

3. Power the PICDEM 2 Plus board using the 5V plug pack supplied and then connect the board to the ICD 3 using the short RJ‐11 cable. 

4. Click the “Make and Program Device Main Project “ icon (blue rectangle with downwards green arrow). MPLAB will attempt to connect to the target board through the ICD 3. You will see a Caution message pop up, warning you to check that the device selected in MPLAB is the same one as is actually on the target board; you can safely dismiss this message. 

5. MPLAB should connect to the target board, program the microcontroller and verify that programming was correct. The Output Window should appear as in Figure 8. 

 

 Figure 8: Output Window after executable successfully downloaded to target. 

7.1 What should the TUT452.asm program do? 

When run, the program TUT452.asm repeatedly converts the analog voltage that is present on analog to digital channel 0 to an eight‐bit number, scales that number to lie in the range 0 to 15 and then writes the scaled number to the digital output port PORTB. When run on a PICDEM 2 Plus Demo Board (Microchip DM163022) the analog voltage varies between 0V and +5V as the potentiometer RA0 is turned, and the scaled number varies between 0 and 15. If the software and hardware are working together correctly you should see the LEDs changing between 1 and 15 in binary as you turn the potentiometer. 

 

7.2 Run TUT452.asm program to verify that it works correctly 

The MPLAB ICD 3 executes user code in either real‐time mode or in step mode.  

Real time execution occurs when the PIC18F452 in the PICDEM 2 Plus demo board is put in the MPLAB IDE’s run mode. The user program executes at the full speed of the hardware clock on the target board – 4 MHz in this case. 

In step mode, execution of the target processor is controlled by MPLAB through the ICD 3. The user can, for example, execute a single assembly language instruction, or execute the code until a breakpoint is reached. The icons in the MPLAB X Run Toolbar are described in Figure 9. When execution of user code is halted under control of the ICD 3 the user can inspect or change the values in any of the microcontroller’s registers.  

1. Now let us see if the TUT452.asm program executes correctly. During a debug session, execution of the program is controlled by the ICD 3 through MPLAB X, so we must first launce a debug session. Click on the “Debug Main Project” icon (code listing schematic with small right‐facing green arrow) and several things will occur: firstly the project will be re‐built if necessary. Several tabs will open in the Output Window and you will again see a Caution message pop up, warning you to check that the device selected in the MPLAB project configuration is the same one as is actually on the target board; you can safely dismiss this message. The executable code will then be downloaded to the target board and executed. MPLAB X will then look something like Figure 9.  

2. You can turn the potentiometer all you like but none of the PORTB LEDs will light because the program TUT452.asm is deliberately broken... 

 

 

 

8 

 

 Figure 9: Start of debugging session. 

 

 

Table 1: Buttons on the Run toolbar. 

Debugger Menu  Button Action

Finish Debugger Session  

Exit from the debugger session. 

Pause  

Finish the current instruction and give control to MPLAB 

Reset  

Set the PC to the reset address (0x0000) 

Continue  

Resume running the user program 

Step Over  

At a function call, step over the function 

Step Into  

At a function call, step into the function 

Run to Cursor  

Resume running user program, pause at cursor 

Set PC to Cursor  

What it says! Equivalent of jump to cursor. 

Focus Cursor at PC  

 

 

 

 

9 

 

7.3 Debug TUT452.asm  

Any of the following could prevent the TUT452 program from working.  

The jumper J6 is not fitted, so the LEDs will never light. Check it! 

The A/D converter value is not being properly written to the PORTB LEDs.   

The A/D converter is not enabled or has not been set to start a conversion.  

A typing error in the source code is causing the program to function improperly.  

We will investigate these possibilities in the Debug session. 

To explore the second possibility, we want to set a breakpoint at the line of the file that writes the value of the A/D result to PORTB so that user program execution will pause there. When the program is paused we can inspect values in the microcontroller’s registers.  

1. First, click on the Pause icon – NOT the Finish Debug Session icon since this will close the session, disconnecting the ICD 3 from MPLAB. On Pause, the currently executing instruction finishes and MPLAB shows the next instruction to be executed by highlighting the whole line with a light green background. 

2. Next, click the Reset icon. This resets the microcontroller’s PC (program counter register) to the reset address and sets all other registers to their reset values. Running the program from here is the same as it coming out of reset. 

3. Now, click the cursor on the following line of code from TUT452.asm in the Editor Window: 

movwf PORTB ;Write A/D result to PORTB

4. Right‐click on the line to display a shortcut menu and select Toggle Line Breakpoint. This sets a breakpoint at the line which is marked as can be seen in Figure 10. 

 

 Figure 10: Breakpoint set at line 56. 

10 

 

5. Next, click the Run icon to again free‐run the user program.  If program execution ever reaches the breakpoint the program will pause before executing the line at which the breakpoint is set. However, the sample program does not pause so it is never reaching the breakpoint.  

6. Click Pause to pause the program wherever it happens to be. In the Edit Window, the program will have halted on one of the two lines under the label WaitForAdConversion. Try Run and Pause a few more times – the program will always pause at one of these two lines. 

Based on the pause location and the fact that the program never reaches the breakpoint, it can be concluded that the problem is in the A/D conversion. The program at line 51 tests a bit for A/D conversion complete; this bit never becomes set. A/D initialization occurs under the Setup label at the beginning of the program.  

7. To verify that the flag bit (bit ADIF in register PIR1) is not being set, Click on the SFR tab in the Output Window. This shows the Special Function Registers which are the microcontroller’s control and status registers. Click on “Name” to sort the SFRs by name, then scroll down and click on PIR1. If you hover the mouse over the text “PIR1”, MPLAB will show the symbolic names of the bits in the register as can be seen in Figure 11. ADIF is bit 6 and it is always zero – the A/D conversion never completes. The A/D converter in the PIC18F452 has an organisation such that if a conversion starts then it must complete. The A/D conversion is therefore not starting.  

 

 Figure 11: Inspecting the value of bits in the PIR1 register with the program paused. 

8. A/D conversion not starting could be caused by incorrect configuration of the A/D hardware, or by the program’s failure to initiate a conversion. To investigate, first click Reset. Then set a breakpoint at the first instruction after the label Setup.  Click on the following line of code from TUT452.asm:  

clrf PORTB ;Clear PORTB

Then right‐click on the line and toggle the breakpoint at the line.  

11 

 

9. We will want to inspect the values that are written into the two registers ADCON0 and ADCON1. These two registers contain the control and status bits for the A/D converter hardware. We want to inspect how the A/D converter is configured.  A Watch Window is another way to inspect registers (and variables). Click Debug and then select New Watch. In the pop‐up, click on “SFRs”, then select ADCON0 and ADCON1 and click [OK]. The Variables Window will open, showing the state of the two registers that we have added.  

10. Before continuing, make sure that “Unlimited BP (S/W)” is Enabled under “Debug Resources” in the Dashboard. This enables software breakpoints. Only one hardware breakpoint can be active, but an unlimited number of software breakpoints can be used. 

11. Now run the code again: click Reset then Continue. Execution will pause before executing the line of code at the breakpoint. MPLAB will look like Figure 12. Line 31 (the breakpoint) has not executed. The little green arrow points to the next instruction to be executed.  

 

 Figure 12: Program paused at breakpoint at line 31. 

12. Now, single‐step the code five times, inspecting the values in ADCON0 and ADCON1 after each step. You can use Step‐Over or Step‐Into: it doesn’t matter here as there is no function call. Pay particular attention to the values in ADCON0 and ADCON1 when the instructions movwf ADCON0 and movwf ADCON1 execute. These instructions move values into the registers. You will see that the values change; they are shown in red to indicate that they changed as a result of the previous instruction. The following line of code should be indicated when finished:  

movlw B’11000111’ ;TMR0 prescaler, 1:256

13. Notice that ADCON0 has a value of 0x40. This corresponds to the binary value designated in the program, but is this value correct? If you expand the display of ADCON0 in the Variables Window the value of each bit will be shown as can be seen in Figure 13.  

 

12 

 

 

 Figure 13: Variables Window showing values of ADCON0 bits. 

14. In Figure 13, bit 0 of ADCON0 has the symbolic name ADON, and the value 0. A review of the PIC18F452 Data Sheet section on A/D (Chapter 17) indicates that function of this bit is to enable the A/D circuitry. The conversion is never finishing because it is never starting, and it is never starting because the A/D hardware module is not enabled. 

15. The least significant bit of ADCON0 should be a one, not a zero, to enable the A/D module. To fix this bug, change:  

movlw B’01000000’ ;Fosc/8, A/D enabled

to:  

movlw B’01000001’ ;Fosc/8, A/D enabled

16. To rebuild the project we have to get out of the debugging session, so click on Finish Debugger Session.  Clicking on Debug Main Project will force a rebuild of the project, followed by downloading and running on the target board. 

17. When the code executes you should see the LEDs counting in binary as the potentiometer RA0 is turned. 

The source code in this tutorial contained only one simple bug. Real code is certain to have more, particularly when you are learning a new processor. Using the MPLAB ICD 3 and MPLAB IDE debugging functions, together with careful thought and simple experimentation, users can successfully find and fix all problems in their code. 

8  PROGRAMMING THE APPLICATION  

When the program is successfully debugged and running, usually the last step is to program the microcontroller for stand‐alone operation in the finished design. When doing this, the resources reserved by the ICD are released for use by the application. The device can be programmed from within MPLAB X by following these steps:  

1. End the debugging session by clicking Finish Debugger Session. 

2. Click on Make and Program Device Main Project. This will rebuild the project as a production build (which does not include the small debug monitor program for communicating with the ICD 3), program the microcontroller and run the program. You will be able to disconnect the ICD 3 from the target board, power‐cycle the target board and the program will execute. 

 

 

13 

 

;********************************************************** ;* TUT452.asm ;********************************************************** ;* Microchip Technology Incorporated ;* 17 March 2003 ;* Assembled with MPASM V3.20 and MPLINK v3.20 ;********************************************************** ;* This program configures the A/D Module to convert on ;* A/D channel 0 (the potentiometer) and display the ;* results on the LEDS on PORTB. ;********************************************************** list p=18f452 ; Include file, change directory if needed include "p18f452.inc" include "configReg.inc" ; Start at the reset address. There *must* be code at address ; 0x000 since the PC is loaded with address 0 when the processor ; comes out of reset. This declares a code section named 'RST'. RST code 0x0000 goto Setup ; Start application beyond vector area. ; This declares an 'unnamed' code section. code 0x0030 Setup: clrf PORTB ; Clear PORTB clrf TRISB ; PORTB all outputs, display 4 MSB's ; of A/D result on LEDs movlw B'01000000' ; Fosc/8, A/D enabled movwf ADCON0 movlw B'00001110' ; Left justify, 1 analog channel movwf ADCON1 ; VDD and VSS references movlw B'11000111' ; TMR0 prescaler, 1:256 movwf T0CON Main: btfss INTCON, TMR0IF ; Wait for Timer0 to timeout goto Main bcf INTCON, TMR0IF bsf ADCON0, GO ; Start A/D conversion WaitForAdConversion: btfss PIR1, ADIF ; Wait for conversion to complete goto WaitForAdConversion swapf ADRESH, W ; Swap A/D result nibbles andlw 0x0f ; Mask off lower 4 bits movwf PORTB ; Write A/D result to PORTB clrf PORTB WaitForSwitchRelease: ; Pause while switch is pressed btfss PORTA, 4 goto WaitForSwitchRelease movwf PORTB goto Main ; Do it again end