Practical PIC Projects

Using MPLAB to create a HEX file

Quick guide to assembling firmware with MPLAB

 


This is a very quick guide to allow you to assemble and generate the programmer HEX files from source code files downloaded from the Picprojects website.  It's not a comprehensive guide to using the MPLAB IDE and it's not intended to be...

 


Overview

One page 'Program a Microchip PIC'  quick overview flow chart.

And video

Many of the projects on the site already provide the necessary HEX file to program into the PIC.  In this case all you need to do is download the HEX file and program it into the PIC,  you do not need to do anything else.  Other projects on the site allow you to modify or edit the source code to suit your own needs.  With these projects it is necessary to assemble the modified source code to create a new HEX file.

To turn the source code into something that can be programmed into the actual PIC microcontroller chip you need to assemble the code.  This is done using the MPASM assembler which takes the source files and creates a HEX file that your programmer hardware can write into the PIC chip.

You can do this by opening the source code files in the MPLAB IDE program and using the Quickbuild option to generate the HEX file.  If you have a PICkit2 programmer attached you can also program the generated HEX file directly into the PIC from within MPLAB.  For other programmer hardware you will need to use the application that came with the programmer to write the HEX file into the PIC.

Getting started

  • If you haven't already done so, download MPLAB from the Microchip website and install it.
     
  • Download the source code for the project you are interested in from the Picprojects website and save or unzip all the files to a working directory.

    Tip: the MPASM assembler doesn't like directory path + file name to be  longer than 62 characters so avoid using a directory in 'My Documents'; instead create one off the root of C:, for example c:\pic\project1\

     
  • Run the Microchip MPLAB IDE application.

    From the menu select File - Open and select the file with the .asm extension. 
     
  • The files with a .inc extension are include files. They are named in the .asm file and are read by the assembler during the Quickbuild; don't change or delete them.  Some code may require you to open and edit one of the .inc files.  If this is the case it will be covered in the documentation on the project page.
     
  • Don't use the project wizard or or attempt to add the code to a project.  It may not assemble correctly if you do. 


Selecting the PIC

  • Select the correct PIC type from from the drop down list as shown below.
     
  • The projects on the Picprojects website use a number of different PIC microcontrollers.  You must select the same device that is used in the project for the source code to assemble correctly.


  • If you need to edit and change the contents of one of the include files before assembling, open the file and make the changes.  When you've done, save the file before going to the next step. 


Assembling the source code with Quickbuild

  • Highlight the file with the .asm extension in the editing window.
     
  • Next select Quickbuild from the Project menu.  The Quickbuild option will run the Microchip MPASM assembler that creates the .HEX file from the source .asm and .inc files. 
     
  • Note: if the Quickbuild menu option doesn't show the name of the .asm file, you haven't selected the window in the last step.


  • Once the Quickbuild has finished check the output window to make sure the build succeeded.   If you get the 'Build Succeeded' text at the end you will find a .HEX file in the working directory with the same name as the .asm file.  e.g.  pwmc_main123.asm will generate a file named pwmc_main123.HEX if the build is successful.
     
  • If there are any errors reported here, or the build fails you need to investigate and fix them before programming the PIC.  Common errors
     
  • Be aware that if the .HEX file already exists from a previous successful build and the build subsequently fails, the .HEX file in the working directory is the one from the last successful build.  (this is a tip worth remembering before wasting hours trying to understand why the changes you make don't appear to work:-)
     


Some well known errors

Error 173

If you see an error 173 similar to this when you run Quickbuild your file path is too long:

Error[173] E:\MY PROJECTS\PICPROJECTS\MY LATEST PROJECT\SOURCE CODE\PICPROJECT.ASM 64 : Source file path exceeds 62 characters (E:\MY PROJECTS\PICPROJECTS\MY LATEST PROJECT\SOURCE CODE\PICPROJECT.ASM) Halting build on first failure as requested.

Fix

The MPASM assembler doesn't like directory path + file name to be  longer than 62 characters so avoid using a directory in 'My Documents'; instead create one off the root of C:, for example c:\pic\project1\

Error 301

If you see an error 301 similar to the one shown below the processor selected in the device drop down list doesn't match the one specified in the source code.  Select the correct processor before moving to the next step.

Message[301] C:\PROGRAM FILES\MICROCHIP\MPASM SUITE\P12F675.INC 36 : MESSAGE: (Processor-header file mismatch. Verify selected processor.)

Fix

Select the correct processor from the Configure menu.  See here

Error 151

Error[151] C:\Picproject\LONGDELAYF4.ASM 279 : Operand contains unresolvable labels or is too complex

Fix

The code on my website is written as absolute code.  I've seen the 151 error when people have tried to build it as relocatable code.  If you follow the steps on this page, using the Quickbuild option to assemble the code the error should not occur.

Error 220

Warning[220] C:\CODE\RGBSA-INET.ASM 158 : Address exceeds maximum range for this processor.

If you see an Error [220] the assembled code is bigger than the memory on the specified PIC.  You will typically see this error if you have added data to one of the included files (for example the RGB sequences in the RGB LED drivers) and got carried away :-)
 


Help with errors during Quickbuild
  • If there are errors you can open the file with a .err extension in the source code directory to see them in detail.
     
  • From the Help menu in MPLAB select Topics.. - MPASM Assembler.  Search for assembler errors to get more information on the specific error number.

 


How much memory has the program used

  • This step is not necessary but you may find the information useful with some projects that allow you to add information to an include file.
     
  • After a successful build, if you look in the working directory you will see a file with a .lst extension.  If you open this file in a text editor and go to the very end of it you will see a memory usage map.  This is a quick way to see how much memory has been used.

MEMORY USAGE MAP ('X' = Used, '-' = Unused)


0000 : X---XXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0040 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0080 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
00C0 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0100 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0140 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0180 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
01C0 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0200 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0240 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0280 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
02C0 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0300 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0340 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0380 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
03C0 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0400 : XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX
0440 : XXXXXXXXXXXXXXX- ---------------- ---------------- ----------------
2000 : -------X-------- ---------------- ---------------- ----------------

All other memory blocks unused.

Program Memory Words Used: 1100
Program Memory Words Free: 948


Errors : 0
Warnings : 0 reported, 0 suppressed
Messages : 0 reported, 3 suppressed