What is an IDE?

IDE stands for Integrated Development Environment. An IDE contains all of the tools a programmer needs to create, edit, debug, compiler/assemble, and download microcontroller programs in one integrated software suite. The MPLAB X IDE is a free and open IDE based on Netbeans and replaces Microchip's older MPLAB 8 IDE. All of the programs on this site can be used in the MPLAB X IDE.

Projects vs. files

A project is the term used to describe the collection of source code files, programming information, debugging information, and settings that you use when creating your program. MPLAB X manages all of the files in your programming projects, and manages all of your programming projects as well.

This tutorial will lead you through creating a C-language project with two files, providing you with the basic knowledge you need to create or load new projects.

MPLAB X - C language tutorial

This tutorial will demonstrate how to create an MPLAB X project, create, and compile C language source code files, single-step and debug your code in a simulator, and download the finished program to a target microcontroller.

We'll start this tutorial by creating a simple C language project for the CHRP 3 circuit using the PIC16F886 microcontroller. To download the code into a target system later, you will need either Microchip's PICkit-2 or PICkit-3 USB programmer.

Before you begin - get MPLAB X

MPLAB X is open source and freely available for Windows, Macintosh and Linux on the development tools page of the website. You will need to download both the MPLAB X IDE software and the XC8 C compiler. This tutorial is based on MPLAB X version 1.7 and XC8 version 1.12, but any later versions of MPLAB X should work equally well for this tutorial.

Install MPLAB X and XC8 using the default settings. You may need to install or update Java during the installation to support Netbeans, the core of the MPLAB X IDE, which is written in Java. On Windows computers, you may be prompted to install USB driver support for specific programmers, but Microchip's PICkit-2 and PICkit3 programmers should work without any additional software being installed.

Start an MPLAB X project

When you first run MPLAB X you will be greeted by a start screen. (click to expand each image to a larger size):

MPLAB X start screen

Click the Create New Project link on the start screen to start a new project.

MPLAB X New Project window

Choose the Standalone Project option and click Next.

Select the target processor, tool and compiler

MPLAB X Select Device window

Select the Mid-Range 8-bit MCU family and the PIC16F886 device. Click Next.

MPLAB X Select Tool window

Select the Simulator as the hardware tool and click Next.

MPLAB X Select Compiler window

Select the XC8 Compiler and click Next.

MPLAB X Project Name window

Choose an appropriate folder to store your MPLAB X projects. Then enter Output as the project name and choose Finish. Important: MPLAB X project and file names may not contain spaces or characters typically reserved for directory separators.

The Output project opens. The Projects window at the top left of the MPLAB X screen displays a list of file types that can be associated with the project.

Add files to the project

MPLAB X Output Project overview screen

From the menu above the projects window select the new file button: new file button

MPLAB X New File window

Select a C Source File from the C category of the New File window.

MPLAB X New File name window

Name the new file main. MPLAB X will add the .c extension to the file name. Again, it's important to remember that MPLAB X file and folder names must not contain spaces or characters typically used as directory separators.


The main.c file appears in the projects windows. Drag it into the Source Files section if it was created in another section.

A empty file editor window labelled main.c also opens up on the right side of the MPLAB X screen. Copy and paste the output project main code, below, into the editor window.

	Project: Output
	Version: 3.1 				Date: December 1, 2013
	Target: CHRP3				Processor: PIC16F886

	A simple output program that flashes the LEDs on PORTB of the CHRP3 board
	using the C compiler's built-in millisecond time delay macro.

#include	"xc.h"				// XC general include file

#include	"stdint.h"			// Integer definition
#include	"stdbool.h"			// Boolean (true/false) definition

#define	_XTAL_FREQ	4000000		// Set xtal frequency for time delays

	Initialize ports. This function is called from within main().

void initPorts(void)
	// Initialize user ports and peripherals.

	ANSEL = 0b00000000;			// Make all PORTA pins digital I/O
	ANSELH = 0b00000000;		// Make all PORTB pins digital I/O
	OPTION_REG = 0b01010111;	// PORTB pull-ups on, TMR0 interal div 256

	// Set port directions for I/O pins: 0 = Output, 1 = Input

	TRISA = 0b00101111;			// Set runLED, IR LEDs as outputs in PORTA
	TRISB = 0b00000000;			// Set all PORTB pins for LED output

	// Set initial port outputs.

	PORTA = 0;					// Turn all PORTA outputs off, Run LED on

	Main program loop. The main() function is called first by the compiler.

int main(void)
	// Initialize I/O and peripherals for PORTB output

	// Make the main program loop repeat continuously
		// Turn all LEDs on and wait for a time delay
		PORTB = 0b11111111;

		// Turn all LEDs off and wait for a time delay
		PORTB = 0b00000000;

Create another file using the new file button: new file button.

MPLAB X New File window

As before, select a C Source File from the C category of the New File window.

MPLAB X New File name window

Name the new file configuration and let MPLAB X add the .c extension to the file name.

Configuration parameters are required to control the function of some microcontroller hardware features, such as its clock source. Each microcontroller needs a unique configuration file, which may also vary for each target circuit the microcontroller will be used in.

Paste the configuration code, below, into the configuration.c file editing window.

// PIC16F886 Configuration Bit Settings

#include	"xc.h"

#pragma config FOSC = INTRC_NOCLKOUT// Oscillator Selection bits (INTOSCIO oscillator: I/O function on RA6/OSC2/CLKOUT pin, I/O function on RA7/OSC1/CLKIN)
#pragma config WDTE = OFF       // Watchdog Timer Enable bit (WDT disabled and can be enabled by SWDTEN bit of the WDTCON register)
#pragma config PWRTE = ON       // Power-up Timer Enable bit (PWRT enabled)
#pragma config MCLRE = ON       // RE3/MCLR pin function select bit (RE3/MCLR pin function is MCLR)
#pragma config CP = OFF         // Code Protection bit (Program memory code protection is disabled)
#pragma config CPD = OFF        // Data Code Protection bit (Data memory code protection is disabled)
#pragma config BOREN = OFF      // Brown Out Reset Selection bits (BOR disabled)
#pragma config IESO = OFF       // Internal External Switchover bit (Internal/External Switchover mode is disabled)
#pragma config FCMEN = OFF      // Fail-Safe Clock Monitor Enabled bit (Fail-Safe Clock Monitor is disabled)
#pragma config LVP = OFF        // Low Voltage Programming Enable bit (RB3 pin has digital I/O, HV on MCLR must be used for programming)

#pragma config BOR4V = BOR40V   // Brown-out Reset Selection bit (Brown-out Reset set to 4.0V)
#pragma config WRT = OFF        // Flash Program Memory Self Write Enable bits (Write protection off)

Dashboard settings

You may have to click the Dashboard window tab, or choose Dashboard from the Window menu to make the Dashboard visible.

MPLAB X Dashboard showing project properties

The dashboard window provides an overview of the current project's device, development tool, debug tool, as well as an summary of the resources used.

Along the left side of the dashboard window are tools for the project's properties, debug tool status refresh, data sheet downloads and compiler help.

MPLAB X Dashboard showing Project Properties button

Click on the Project Properties button (the wrench) at the left side of the Dashboard window.

MPLAB X Project Properties window

The Project Properties window shows an overview of all the current project settings and provides a single interface to edit and modify the project's settings.

Click the Simulator item in the Categories pane to view and edit simulator options, for example.

MPLAB X Project Properties Simulator settings

The first simulator option window shows oscillator settings. Ensure the instruction frequency is 1 MHz.

Choosing the Option Categories pull-down allows you to edit other simulator options.

Next, select the XC8 compiler option in the left-hand categories pane.

MPLAB X Project Properties XC8 compiler settings

The example shows the Strict ANSI Conformance and Use CCI syntax options have been enabled. Select these in your project if you would like to have your programs checked for best portability and standards compliance. Then press Ok.

Click the Clean and Build Project button in the main toolbar. clean and build project button

MPLAB X scrren after pressing the Clean and Build Project button

The project should build successfully. The tabbed Output window below the code editor shows compilation messages, warning and errors (if there are any) and a summary of memory use.

The Dashboard window at the lower left of the MPLAB X screen also summarizes the resource use of the compiled code.

What if there are errors?

The Output window below the code editor window will display any errors and alert you if the build was unsuccessful. If there is an error, make sure you copied and pasted the text properly and followed all of the steps, above. Commonly, errors occur if you miss copying the first comment (/*) at the top of the code, or the closing brace (}) at the end.

When the code builds successfully, continue on to the simulator tutorial.