Lab 2: MPLAB Introduction

This lab introduces you to the Microchip MPLAB X Integrated Design Environment. The objectives of this lab are:

• Become familiar with the MPLAB X environment.

• Do some simple programming tasks using PIC24 assembly language.

As always, read/scan through the entire lab before starting to work.

Basics

• If you've not already done so, download the pic24_code_examples.zip archive from Canvas > Files > Labs S2025 > Lab 0. Extract it into  C:\ece3724\pic24_code_examples . This lab requires files from the chap03 directory.

• Download lab2.zip from Canvas > Files > Labs S2025 > Lab 2. Extract it into C:\ece3724\pic24_code_examples\chap03\. This archive contains two assembly files you'll be working with in the lab:

  • mplab_test.s - This is a very simple program you'll be using for Task 1 to get used to MPLAB.

  • netid.s - You'll be using this program in Task 2. It does some calculations with your netID and student ID number. You'll be submitting this file.

The following sections will cover basic usage of MPLAB X IDE 6.20:

Opening a project

To open a project, go to File > Open Project...

For these examples, I will be using the project C:\ece3724\pic24_code_examples\chap03\mptst_byte.X. Feel free to open it and follow along.

Closing a project

To close a project, choose the appropriate option from the File menu. To close a file, just click the X in the editor tab. Closing a file does not close a project and vice versa. A common error is to be working on a file that is not part of the project you are compiling. No matter what you do to the file, it won't fix your program! To avoid this frustrating problem, it is highly recommended that you only keep one project open at a time. If you need to look at other files that aren't in the project, just open them separately. If you absolutely must have multiple projects open, be sure to set the one that you're trying to compile as the main project.

Opening an assembly source file

The assembly source files (the code) will be in the Source Files folder of the project. Doubleclick to open them in the editor:

Running (debugging) a project

To debug (run in the MPLAB simulator) the project, click the button that looks like a piece of paper with a play button on the lower right corner.

The red square next to it - you guessed it - stops the debugger. You can also go to Debug > Debug Main Project or Debug > Finish Debugger Session through the menu.

Viewing program memory

To view program memory,  Window > Target Memory Views > Program Memory.

This opens up a tab at the bottom where you can view the (virtual) PIC's program memory.

Try switching the Format from Code to Hex (and then back, unless you're a computer). Right-click somewhere in the program memory, and make sure Symbolic Mode and Verbose Labels are checked. They also make it a lot easier to read. Uncheck/recheck them and try to figure out why.

Viewing data memory (file registers)

Data memory is called "File Registers" in MPLAB. If you click Memory on the bottom right of the Program Memory tab, it opens up a dropdown. If you select File Registers, this will show data memory in that tab instead. If you want to have both open at the same time, then Window > Target Memory Views > File Registers.

Format: Symbol makes this easier to read. For example, you can see the registers, starting at 0x0000, and below, starting at 0x1000, the variables in the program. Instead of scrolling through, you can click the magnifying glass below the output tab and search for line 1000. 

Viewing registers

In MPLAB, instead of W0-W15, the working registers are called WREG0 - WREG15. All the registers with names are referred to as SFRs, or Special Function Registers. There's a number of ways to view their contents. One is by going to address 0x0000 of data memory, as mentioned above:

You can also Window > Target Memory Views > SFRs:

However, generally we're interested in only a few of the working registers. Also we might want to look at the values of some variables as well, and we'd like to do all this without scrolling back and forth through memory locations. Fortunately, there's a way to do this - setting Watches!

Setting Watches

To get the Watches tab to show up, you Window > Debugging > Watches (or just Alt-Shift-2).

To add a variable or register you want to watch, right click in the Watches tab. Another way to add expressions to the Watch window is to right-click in the source code and select "New Watch..." 

You can also highlight variables to save typing, or select multiple expressions at the same time:

Variables are found in Global Symbols. Registers are found in SFR's (Special Function Registers). Important: To watch a working register, add WREG#. For example, to watch W2, select WREG2. If you're not able to add variables to the Global Symbols list, debug the program once first and try again.

If we look through mptst_byte, we can see it uses 3 variables (u8_i, u8_j, and u8_k), and 2 registers (W0 & W1 aka WREG0 & WREG1). So, if you're following along, add those to your watches:

The last two lines of this program (visible in the above picture) just loop endlessly, doing nothing. So the watches are showing the final values in the registers and variables at the very end of the program. But what if our program screws up somewhere along the way and we want to find out where we went wrong? That is what breakpoints are for, and it's the last thing you need to know about in MPLAB - at least in order to do the prelab.

Breakpoints

A breakpoint is a place where we make our program pause its execution so we can examine memory and register contents in midstream. Setting a breakpoint is easy - just click on the line number in the left margin. Click again to make the breakpoint go away. Stop your debugger if it's running, and set a breakpoint on line 60:

Some important things to know about breakpoints:

• They pause execution of the program right before the line runs.

• You can't set a breakpoint on a line without valid assembly (or later, C) code on it. Well you can, but you'll just get a warning message when you debug. Labels, comments, and compiler directives don't count as code.

• You also may get warning messages if you have breakpoints in random files that aren't open anymore. Right-click in the breakpoint tab and select Delete All to make them go away.

Now start the debugger. The program should halt, the output tab should say:

Launching

Initializing simulator

User program running

Breakpoint hit at line 60 in file C:/ece3724/pic24_code_examples/chap03/mptst_byte.s.

User program stopped

And if we look at the Watches window, you should see...

...a bunch of nothing. That's because this is the first line of code, and as mentioned earlier, it hasn't executed yet. If you click on File Registers to view the contents of data memory, you can see that, indeed, the registers (at 0x0000) and the variables (at 0x1000) are all zeroes. (Except for W15, which is the stack pointer - don't mess with this). Slightly more interestingly, if you click on Program Memory, you can see the line of assembly that's about to execute:

The program counter (green arrow) indicates the location in program memory that is about to execute, and as might be expected, it's the same assembly instruction as the line in the program (0x64 = 100). Notice the __reset label. Scroll up to the top of program memory and you will see a GOTO __reset, which is how we got here, as program execution always begins at 0x0000

After we've paused at a breakpoint, we can step through the program line-by-line and examine:

• Where in the program we are (Program Memory)

• The contents of variables and registers (Watches)

• The current contents of every location in data memory (File Registers)

To do this, we use the debugger commands:

These commands can also be accessed through the Debug menu, but you never will. In fact, you also probably will not want to click the icons dozens of times, so you need to learn the hotkeys, or at least the most important one (especially if you want to get all your prelab points).

F7 - Step Into - executes a single line of the program

F8 - Step Over - executes a single line of the program, but skips past whole functions (does the same thing as Step Into here since there are no functions to get into, and will also get you prelab credit).

F5 (unless you messed around with your shortcut keys like I did) - Continue  - This is the green play button. It resumes execution of the program and goes on to the end (or until you hit another breakpoint).

You can learn about all the debug commands here if you're curious, but you'll probably never use the other ones. Just take a moment to play around with these three and marvel at how the contents of the registers and variables change as each line of code executes.

PIC24 Assembly

In order to complete this lab, you'll need to know some assembly. Besides the ebook and lecture slides, the required information can be found in the PIC24 Assembly Primer. (Just the first half, up to where it says "YOU NEED TO KNOW THIS MUCH ASSEMBLY TO DO LAB 2".)

Code commenting and neatness

Proper commenting and neat, organized code is more important than writing correct assembly code (except on the exams). You may never program assembly again in your life after you take this class, but you will almost certainly be required to write code that your employers, coworkers, and/or subordinates can understand. For the assembly labs (2-5), since most of what you are translating is just random math code in C, you are not expected to write "traditional" comments like:

; move register contents to variables and increment counter

or

; this shifts W2 left by 3 bits, then adds #0x3423 to W1

(Though you can if you want to and won't be penalized - use whatever additional comments you want that help you write the program.) 

You are expected to:

• write the C code you are translating as a comment and write the assembly code below it

• write register assignments as comments

• not have incorrect comments (usually left from a previous program when copying a file)

• remove "junk" from the files you turn in

• put a proper header on top

• indent and use blank lines reasonably

• in general, submit professional-looking work

Prelab (20 points)

Before the TA arrives:

• Start MPLAB X, close any other projects, and open the mptst_word project from chap03.

• Debug the project. 

• Stop the debugger session.

• Open the program memory tab to view your program.

• Open the file registers tab to view your program's data.

• Open the watch tab, then add u16_i, u16_j, u16_k, and WREG0, WREG1, WREG2.

• Set a breakpoint in the program on the first line of assembly code (mov #2047, W0). Debug the project again.

TA checkoff

With the TA watching:

• Show the TA that you can single-step through instructions.

  • You can do this with a keyboard shortcut (10).

  • You can only do it with the mouse (5).

  • You cannot (0).

• Show the TA the requested variable in data memory.

  • You show it to the TA (10).

  • You show the TA the tab labeled "program memory" (0). 

  • You frantically look for the "data memory" tab (0).

  • You tell the TA it's in the Watches/Variable window so you don't need to know how to find it in data memory (0).

Task 1 (20)

Adding a file to a project

It is a pain in the neck to create a new MPLAB project. You have to be sure that all the header files and libraries from pic24_code_examples are included and that the makefile is configured correctly. Copying an existing project is somewhat easier, but you can run into trouble doing this as well. So in lab, follow these steps when you want to begin something new:

1. Open an existing project.

2. Then either:

a. Add a provided file (we'll be doing this in Task 1 and Task 2, as well as many other labs) or

b. Create a new file (you might want to do this on the practicum).

Do not open up an existing file from pic24_code_examples or one of your completed labs and start modifying it. Why not? Because if you change it and suddenly start getting a bunch of errors, you don't know whether the problem is buggy code, your computer, MPLAB, or the PIC! (Instead, when nothing seems to be working, go back to one of these known good files. If it does, the problem is your code. If not, it's something else.)

• If you have not already done so, extract the contents of lab2.zip into C:\ece3724\pic24_code_examples\chap03\

• Right-click on Source Files in the Projects window and select "Add Existing Item...":

• Select mplab_test.s:

• Under Source Files in the Projects Window, right-click on mptst_word.s and select "Exclude file(s) from current configuration":

In the Projects window, mplab_test.s should be in regular font, and mptst_word.s should be grayed out.

• Doubleclick mplab_test.s to open it. You can go ahead and close the mptst_word.s file if it is open.

For this task, you perform a simple calculation with the first four digits of your student ID number, then observe that the proper result is stored in data memory.

• Examine the mplab_test.s file. You will see that it consists of the following:

1. A header explaining what the program is and who wrote it. All the programs you submit in this class should have a similar header (with your own name and info in them):

2. The C code that is to be translated:

3. Variable declarations:

Note:

• We start this section with .bss.

• The assembly variables have underscores before them to indicate that they are translations of C variables. In this class, this is the standard on tests, the e-book homework, and as of Spring 2025, the labs. (The old programs from pic24_code_examples.zip, such as mptst_word.s, do not follow this practice.)

• For 16-bit variables, we use .space 2 to reserve 2 bytes. The 8-bit variables in mptst_byte.s use .space 1. Later, when you work with 32-bit variables, you'll use .space 4.

• MPLAB has a bug that causes the last variable declared to display funny in the Watches window. So we make an extra variable that we don't care about,  u16_bug. This way the variables we do care about will display properly. (Try removing this line later on and you will see what I mean.)

4. Start of code section:

5. Assembly code:

• Set watches for W0, W1, _u16_first_four, and _u16_doubled. 

• Debug the project. Your Watches window should look like this:

• Stop debugging.

• Fill in the two blanks in the comments with the first four digits of your student ID number (the one on your student ID card, not your NetID from your email address). Everybody's student ID number starts with a '9'.

• Change #0x1234 to this number. This is the only line of code you have to change for this task. Literally four numbers. Note: In assembly, all numbers (aka literals) must begin with a # sign. The '0x' means that it is in hexadecimal. You don't need to do the conversion manually - for example if the first four digits of your student ID number are 5678, just change it to #0x5678. On this and all other labs, including the practicum, do not use the wrong number or you will not get credit for the task.

• Debug the project.

• Read the section entitled "Screenshots" at the bottom of the page. 

• Take a screenshot of the Watches window contents (showing address, hexadecimal, and decimal values for W0, W1, _u16_first_four, and _u16_doubled).

• Use the address in the Watches window to find the location of _u16_doubled in data memory. Take another screenshot.

TA Checkoff

• You've changed the number in the code.

• You have changed the comments in both places.

• You have the correct screenshots. It's on you to check that you have the correct number - the TA is not going to do math for you. 

Task 2 (40)

In this task, you'll write a program in PIC24 assembly to perform some calculations, then use MPLAB to observe data memory and verify that your answer is correct.

• Keep the mptst_word project open, but close the mplab_test.s file.

• Add netid.s to the project. Exclude mplab_test.s:

• Debug the project to see that it runs without errors.

• There's a heading on the top:. Fill it out before you forget. Your section number is your LAB section number. 

  • If it's Spring 2025, it will be 03, 04, 05, 06, or 07. 

  • It will not be "Tuesday" or "3:30 PM" or "Kishor Joshi".

  • If you're still not sure, check Banner or Canvas. It may also be written on the blackboard in the lab.

• Type the last 4 of your student ID and the numbers from your net ID (email address) into the blanks here:

• And put them into the code and comments here:

• u16_netid is already taken care of. So you just need to initialize u16_studentid. Use W1, and change the W? in the comments to W1.

• Now the actual task: You must translate each line of the C program to assembly instruction(s). Some hints/guidelines:

  • You MUST include, in comments, a register assignment and the line of C code you're translating, followed by your translation to assembly. The lines of C code are already there for you with double semicolons next to them. Above each one is a single semicolon, where you should put your register assignments. Use spaces, tabs, or dashes to line them up neatly with the variables/literals that they correspond to. Don't forget a register assignment for the output variables as well.

  • mptst_word.s moves the variables into registers for each instruction. This is something you'll have to do for Labs 3 and 4 or your program won't run.  However, you are not required to do this for this task, e.g. if u16_netid is in W0 after one instruction and you need to do something with it in the next instruction, you don't need to move it into W0 again. Either way is fine, it's up to you.

• Use only registers W0-W7. Do not use registers W8-W15.

• Leave a blank line between each block of code to make it easier to read. And don't put random blank lines in the middle of the code, or indent crazily. It was neat when you got it - keep it that way.

• Use the Watches window to watch variables _u16_netid, _u16_studentid, and _u16_answer, as well as any registers you use. Delete the watches of variables you were watching before and any registers you're not using.

• Debug your program. Take a screenshot of the Watch window contents. Take a screenshot of the the data memory showing _u16_answer (File Registers window).

Checkoff: You have the correct value in _u16_answer. 

Note: If you left everything in W0 and W1 like the left screenshot above, _u16_netid and _u16_studentid should still contain your original numbers. If you did it like the right screenshot, these variables will have random numbers in them. Either way is fine, but they should not be 0 (which means you failed to initialize them).

Report

See Lab Policy Summary for formatting guidance and a sample report.

• The title page should contain the following:  Lab name & number, your name & NetID, and course & lab section on successive lines.

• Second page should begin with a brief description of the overall lab activity, intelligible to an outside reader.

• Task 1 (write "Task 1" or "Task 1 - mptst_word" in your report, do the same for every Task so the grader can tell them apart)

  • Write a brief description of Task 1, intelligible to an outside reader, e.g. "I translated the following C code into PIC24 assembly..." not "I did mptst_word"

  • Copy/paste the C code you translated (using a monospace font) or include a screenshot of it in the report.

A monospace font is a font where all the characters are the same width. This is not a monospace font:

WWWWW

.....

See how the five Ws take up way more space than the five periods? Courier New is an example of a monospace font. So are other fonts with "Mono" in the name. This is a monospace font:

WWWWW

.....

• • Include your two screenshots.

  • Explain how it is that you doubled a number like 9103 and got something like 2228.

• Task 2

  • Write a brief description of Task 2, intelligible to an outside reader.

  • Copy/paste the C code you translated (using a monospace font) or include a screenshot of it in the report.

  • Include your two screenshots.

  • Verify that the value of _u16_answer in your screenshots is correct. See below for an example of how to do this.

• Include the source code of netid.s as an attachment to your submission. Check that the header is correct, that it has register assignments, and that it looks tidy. If you make changes after being checked off, it's up to you to check that your code still runs.

How to Verify

You need to do the calculations by hand to show the grader that the answer in your screenshots are correct.

• You don't need to show how you convert between bases or perform elementary math operations. The Windows Calculator (in programmer mode) can do this for you.

• If you get a weird answer (hint: 0xFFFF + 1 = 0??) you need to explain it. 

• You need to use binary numbers to show bitwise operations (left and right shifts, XOR, IOR, NOT, and AND).

• Do not handwrite on lab reports, ever. This includes MS Paint, using a stylus, or writing very neatly on graph paper and scanning it.

• If you get an incorrect answer, don't just skip over it and hope the TA doesn't notice.

For example, let's say the C code you were translating was: 

u16_netid = u16_studentid << 3;

Satisfactory verification

u16_studentid = 2047

2047 = 0x07FF = 0000 0111 1111 1111

<< 3 = 0011 1111 1111 1000

u16_netid = 0x3FF8 = 16,376

Unsatisfactory verification

2047 <<3 = 3FF8

Grading

If you do not successfully complete a task and your report fails to mention or glosses over this fact, you will receive a zero for the report portion of your grade as well as for the task. If you attempt to deceive the grader, e.g. by including screenshots not generated by the code you submitted, your instructor will be notified and you will be recommended for an Honor Code violation.

The report is worth 20 points for neatly and coherently presenting your information to a reader. The following non-exhaustive list of errors will result in losing credit from the report portion of the lab grade:

• bad screenshots (not cropped properly, blurry, too small)

• text is "lab jargon" unintelligible to an outside reader ("u16_studentid declared and watch set 0x1000.")

• text is phrased as instructions to a second party ("Increment variable.")

• text is copy-pasted from the lab directions rather than using your own words.

• text is a literal recap of the activities you performed rather than communicating your results and understanding ("First, I set a breakpoint. Then I added the following variables to the Watches window...")

• blatantly erroneous text ("The program adds the first four digits of my student ID to the last four digits")

• garbled / confusing / gibberish text ("Sure, I can help you with that! In assembly language written for the PIC24 microprocessor, a MOV command typically...")

• using vague or incorrect terminology ("We wrote C code and ran it in MatLab")

• excessive text

• careless use of pagebreaks that leave blank pages, 1-2 lines of text on a page, etc.

• general unprofessional appearance

• code is untidy

• code is missing header, has wrong header, and/or contains default header

The tasks are worth 60 points. If your report indicates that you did not successfully complete or do not understand a task, you will lose credit, even if you performed it during the lab. The same is true for tasks performed during the prelab. There are two tasks. The first task is worth 20 points. The second task is worth 40 points. The following non-exhaustive list of errors will result in losing credit from a task:

• missing screenshot

• screenshot of the wrong thing

• screenshots show wrong values

• cannot read screenshot

• code won't run

• code performs incorrectly

• code is convoluted

• code doesn't follow lab directions - no/missing/wrong register assignments, no/missing/wrong C code, etc.

• didn't do calculations / calculations are incorrect/incomplete

Lab reports that flagrantly violate submission policy (wrong lab, no screenshots, no title page, no text besides headings/labels, mostly blank, assembly code pasted into pdf, paragraphs of lab text pasted in, extremely sloppy/unprofessional, missing code etc.) will not be accepted. You will receive a zero for the lab and may resubmit with late penalty.

Screenshots

When taking screenshots, use a snipping tool for screen capture. Don't select the entire screen or most of it.

But don't zoom in so much that you're missing important information. Leave some surroundings, such as labels, headings, addresses, to give your image meaning.

If you resize the image in your report, be sure to preserve aspect ratio. (In Word, hold down the Shift key)

If you're taking screenshots of the Watches Window, adjust the size of the columns to make them fit nicely. Also, do not highlight one of the watches as the dark blue makes it hard to read:

I found this article, How to Change Default Action on PrtScrn Button in Windows 11 from askdavetaylor.com to be helpful.