The MPLAB IDE

What is an IDE?

IDE stands for Integrated Development Environment. An IDE contains all of the tools that you, as a programmer, need to create, edit, debug, assemble, and download microcontroller programs in one integrated software suite. MPLAB is a free IDE available from www.microchip.com.

Projects vs. files

A project is the term used to describe the collection of source code files, debugging information, and settings that you use when creating your program. Although MPLAB can directly assemble a single source file into a program, its real benefit is managing all aspects of creating and debugging a program within a project.

MPLAB tutorial

In this tutorial you will learn how to create an MPLAB project, assemble source code into object code, single-step and debug your code in a simulator, and download the finished program to a target microcontroller.

We'll start by creating the output project for the WAND circuit. Both the CHRP and the UFO circuits also have similar output programs. If you have one of these two boards, you can substitute the output file for your circuit instead of the WAND.

Get MPLAB

MPLAB is freely available from www.microchip.com. There, you'll find a link to the latest version of the software on the MPLAB IDE download page. This tutorial is based on version 8.53, but any version of MPLAB from 7 and up will be similar enough that you should be albe to follow along and successfully build a program.

After you download MPLAB, install using all of the default settings. At one point during the installation you will be asked if you would like to install the Hi-Tech C compiler. At some point, you may find it easier to program complex or higher level functions using less code and in less time using the C compiler rather than using assembly code. However, using C in a microcontroller like the PICmicro still requires you to have an intimate knowledge of the PIC's internal registers, and you might find it easier to work with these using the simpler assembly code instructions. Since a light version of Hi-Tech C is included free with MPLAB, so you might as well install it.

Starting MPLAB

Once you've installed and started MPLAB, you'll see an empty screen holding a toolbar as well as one or more small windows. (click to expand to full size):

Empty MPLAB screen.

Notice that the toolbar at the top contains what seem to be two file open icons, a yellow and a green one. There is an important distinction between the yellow and green sets of file manipulation icons. The yellow icons represent file operations—they create, open and save individual files, such as your program code. The green icons represent project operations—they create, open and save all of the files in a project.

You will find that the first few times you go to open a project, you'll accidentally open just its assembly file instead because you'll instinctively use the left-most icons or the left-positioned File menu to try to open your file. After a while, it becomes easier to remember to open projects with the green icons or from the Project menu.

The status bar at the bottom of the screen is also worth noting. The first piece of information listed is the microcontroller type—which we'll soon change. The status bar also displays some debugging and editing information when working with files or in a project.

Before starting a project

The MPLAB projects you make will contain a number of files and the MPASM assembler invoked by MPLAB has limits on the maximum length of file paths. To better manage the various project files it is recommended to create a subfolder for each project that you make. Locate the project folders close to your computer's drive root rather than in the Windows My Documents folder. This tutorial uses a folder in the following location:

C:\MPLAB\WAND20\Output

Make a similar folder for your project before you continue.

Select the right target

The first task is selecting the target microcontroller. From the Configure menu, choose the Select Device option. A microcontroller selection window listing all of the tools supported by that device will open. Select the PIC16F676 for the WAND (or the PIC16F886 for the CHRP, or the PIC12F675 for the UFO).

Selecting the correct device.

Create the source code file

We'll create the source code file first, before creating the project, because the Output source code is already complete and supplied for you here. Later, when developing your own programs, you'll probably reverse these steps creating the project first, then adding the source file later.

Output program

The entire OUTPUT.ASM program for the WAND is shown below. Copy all of this code, or get the code from the CHRP Output program for pasting into MPLAB.


;OUTPUT.ASM 	v2.0	Last modified on August 3, 2010
;===============================================================================
;Description:	Output test program. Lights up PORTC LEDs.

;Start of MPLAB and processor configuration.

	include	"p16f676.inc"		;Include processor definitions 

	__config _CPD_OFF & _CP_OFF & _BODEN_OFF & _MCLRE_ON & _PWRTE_ON & _WDT_OFF & _INTRC_OSC_NOCLKOUT 

;End of MPLAB and processor configuration.

	org	3FFh			;Oscillator calibration location

oscillator				

	org	00h			;Start of program memory

		bsf	STATUS,RP0	;Select memory register page 1
		call	oscillator	;Store pre-programmed oscillator calibration
		movwf	OSCCAL		;constant in OSCCAL register
		goto	init		;Start program after Interrupt vector

	org     05h             	;Continue after interrupt vector

init		;Initialize ports A and C for digital I/O

		bcf	STATUS,RP0
		movlw	7		;Disable comparator and make
		movwf	CMCON		;RA0-2 digital I/O
		banksel	ANSEL		;Switch to register bank 1
		movlw	11010111b	;Disable Port A pull-ups, set TMR0 to
		movwf	OPTION_REG	;internal clock with prescaler 256
		clrf	ANSEL		;Set all PORTA pins to digital
		movlw	11011111b	;Set RA5 as output and all
		movwf	TRISA		;other PORTA pins as inputs
		clrf	TRISC		;Set all PORTC pins as outputs
		banksel	PORTC		;Return to PORTC register bank
		clrf	PORTA		;Turn off phototransistor LED

main		movlw	00111111b	;Send light pattern to
		movwf	PORTC		;Port C LEDs

		sleep			;Shut down the processor

	end
		

From the file menu, choose New, or click the new file icon (the one at the far left that looks like a piece of paper). Then, copy the output code from above and paste it into the empty file window that opened.

After pasting in the assembly code source.

Save the assembly source file

Saving the file to the project folder.

From the File menu, select Save As. Navigate to the folder you previously created and save the file as Output.asm. Make sure you add the .asm extension. MPLAB uses the extension to designate the type of source code and colour codes the assembly syntax.

MPLAB colour codes the source file

Create the project

The Project Wizard leads you through all of the required steps to start a project. From the Project menu, choose Project Wizard.

mplab-start6-projectwizard

After clicking Next, confirm that the device is set to PIC16F676 (or PIC16F886 for the CHRP, or PIC12F675 for the UFO).

mplab-start7-projectdevice

Next, accept the default Microchip MPASM toolsuite.

mplab-start8-projecttoolsuite

Name the project Output. Browse to the folder you created earlier and select it as the save path for the project.

mplab-start9a-projectfolder

At this point MPLAB provides the opportunity to add files to the project. Add the Output.asm file.

mplab-start10-projectaddfiles

If you don't have your assembly source code file created when you start the project, it's okay to skip this step and add files to the project later. Just choose Add Files to Project from the Project menu, and select the source code file(s) to be added.

The summary screen allows you to verify your settings. Ensure all of the settings are correct and press Finish.

mplab-start11-projectsummary

Hmm. Did your source code window disappear, too? No problem.

mplab-start12-projectfinished

Double click on the Output.asm filename in the Output window to display the source code.

mplab-start13-projectsource

Set the build options and assemble the project

Assembling this project now would produce some errors. The project build options need to be set properly first. From the Project menu, choose Build Options, then Project.

After the Build Options window opens, click on the MPASM Assembler tab.

Check Disable Case Sensitivity and select Decimal as the default number system (radix). Then click OK.

mplab-start14-buildoptions

Press the Make button mplab-buildbuttons (it's the left-most of the build buttons group, the one with the single arrow) to start the assembly process. You may see a window asking about the type of code to generate. Choose Absolute.

mplab-start15-buildabsolute

The Output window displays the build process as well as any messages, warnings or errors generated. Assuming you followed the steps correctly, using the supplied code, the build should have succeeded.

mplab-start16-buildsucceeded

What if there are errors?

The Output window displays any messages, warnings or errors. Double-clicking on any message, warning or error will highlight the line that caused the problem in the source code window, while the Output window displays the error message. Often these error messages are difficult to decipher. Some common errors:

Did you properly select all of the text? If you missed the first semicolon, there will be an error on the first line of the program.

Did you set the correct build options? If not, you'll see 'Argument out of range' errors on lines containing binary data.