Jump to content

Contributors to this blog

Using the MPLAB-X Simulator to debug UART code



One feature of MPLAB-X which is not nearly used enough is the Simulator. It is actually very powerful and useful for testing and debugging code which will run on your board and interact with the outside world via external stimuli. There is more information on the developer help site here http://microchipdeveloper.com/mplabx:scl

This is how you can use the IDE to debug your serial command line interface code using stimulus files and the UART OUTPUT window.

The first trick is to enable the UART output window in the IDE. We are going to start by creating a new project using MCC which drives the UART on the PIC16F18875. Settings should look as follows:


Then go on the project settings and enable the UART output window in the simulator 


We can now update our main code to do something simple to test the UART output.

#include "mcc_generated_files/mcc.h"
uint8_t buffer[64];

void main(void)
    // initialize the device


    printf("Hello World\r\n");

If you run this code in the simulator it will open an additional output window which will show the output from the UART as follows


Now the next trick is to use a stimulus file to send your test data into the device via the UART to allow you to test your serial processing code.

First we will make a test file, there is more information on the format of these files on the developer help site, but it is fairly easy to understand just by looking at the example.

// Start off by sending 0x00

// First string, send the bytes H E L L O (no \0 will be sent)

// Wait for 100 ms before sending the next bit
wait 100 ms

// Second string

// Wait for 100 ms before sending the next bit
wait 100 ms

// Send an entirely binary packet
90 03 00 14 55 12

We now simply save this text file so that we can import it into the stimulus system. We will just call it data.txt for now.

Next we have to set up the IDE to send the data in this file. We are going to start by opening the Stimulus editor, this is under the menu "Window | Simulator | Stimulus" in MPLAB-X.

Navigate to the tab labeled "Register Injection" and do the following steps:

  1. To add the file we will enter a new row here. Just type in the empty boxes (or you can use the icons on the left to add a new row) 
  2. Provide any label (we are using TEST)
  3. Select the UART1 Receive Register under Reg/Var - it is called RC1REG
  4. Choose "Message" for the trigger
  5. Click on the filename block to select the file we made above
  6. Set "Wrap" to no - this means it will not repeat
  7. Format should show Pkt and be raed-only

The stimulus is now set up and ready for a test drive.

Screen Shot 2019-01-08 at 7.44.52 PM.png

As a test we are just going to update the program to echo back what it receives and we will be able to see the output in the Simulator Output window as the stimulus is being sent in. Here is the test code:

#include <stdint.h>
#include "mcc_generated_files/mcc.h"

void main(void)
    // initialize the device

    printf("Hello World\r\n");

    while (1)

If you now run the simulator the UART output will just show "Hello World" as the start message. When you hit the green run button on the stimulus it will send the data in the file to the program. Hitting the run button a second time will remove the stimulus and if you hit it one more time it will apply the stimulus a second time.

That is a very basic introduction of how to use a stimulus which feeds data from a text file into the UART for testing purposes.

It is a small step from here to feed data into a variable or into a different peripheral, we will not go into that right here, but know that it is easy to also do this. 

When you combine this feature with running MDB from the command line and using a test framework such as Unity http://www.throwtheswitch.org/unity/ you should have all the tools to create automated tests for your serial port code.

As always the project with the code we used is attached.



1 Comment

Recommended Comments

If you experience strange behavior with MPLAB double check your simulator stimulus files for bad syntax.  I just created a stimulus file for a blog post that will hit tomorrow morning.  I inadvertently placed two sequential quotation marks at the start of a string.  like this:

""lots of stuff to send"

As soon as the simulation was started, MPLAB went into the weeds.  Some stuff could be clicked on, but in the end I had to kill the process and restart.  Only by checking everything with a second pair of eyes was the problem detected.

Share this comment

Link to comment
Add a comment...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

  • Create New...