Importing the Arduino project into MPLAB X

Published April 26, 2024 © GPL3+

How to use the Arduino Import Tool in MPLAB X

This guide shows you how to import an Arduino project into MPLAB X, so that you can set breakpoints, debug, use Watches, and I/O View

IntermediateProtip30 minutes1,072

How to use the Arduino Import Tool in MPLAB X

Things used in this project

Hardware components

Microchip AVR-DB Curiosity Nano dev board

Software apps and online services

Arduino IDE

Microchip MPLAB X IDE

Story

Importing an Arduino project into MPLAB X gives the user many additional features, such as being able to set breakpoints and step through code during debugging. The user can leverage microcontroller core-independent peripheral features that are not available in Arduino.

For example, the user can create a fully featured ADC driver that supports modes such as Burst Average (very useful when dealing with noisy analog signals), tune the ADC sampling rate away from periodic noise from mains power and other sources, perform oversampling and decimation (to increase the effective number of bits in an ADC result), setting ADC thresholds or windows in hardware to trigger interrupts when the threshold conditions are met, using differential inputs (when working with Wheatstone Bridges), and much more.

Additionally, the user can leverage MPLAB X tools such as:

Setting Watches
Observing variables and their scope
Observing contents of Special Function Registers (SFR) change as each line of code is executed
IO View
Where users can observe individual register bits and multi-bit register settings,
Turn on and off individual bits and settings in registers, or
Change the value of entire registers
Code auto-completion
CTRL + Click on variables and functions to find where they are declared
CTRL + Esc to return
Accessing header files to use built-in macros for register settings

This guide will import an Arduino project that uses an AVR128DB48 Curiosity Nano dev board and the Curiosity Nano Explorer board (about to be released around mid 2024).

The project uses the potentiometer, OLED display, and NeoPixel ring on the Explorer board. Adafruit libraries for the OLED display and NeoPixels were used for the Arduino project.

The AVR-Dx (DA, DB and DD) series of microcontrollers can be used with Arduino by leveraging the DxCore library in the Arduino IDE. DxCore installation instructions for the Arduino IDE can be found here.

https://github.com/SpenceKonde/DxCore/blob/master/Installation.md

Note: It is required to install DxCore in Arduino version 1.8.x before using the Arduino Import Tool.

Note 1: There is now a NeoPixel library within DxCore that overcomes the 16MHz limitation of the Adafruit NeoPixel library and allows the microcontroller to run at clock speeds exceeding 16MHz.

Note 2: Before starting, this process requires either Arduino 1.8.x or the Arduino CLI to be installed on your machine.

Note 3: After downloading the Arduino code from this article, open the code with Arduino 1.8.x in which you have already installed DxCore, and click the Verify button. Arduino will ask you to place the file into a folder with the same name. Click OK to do that.
If you do NOT have the Adafruit_Neopixel.h and Adafruit_SSD1306.h libraries installed, you will need to do this in Arduino and build the project before importing the project into MPLAB X. To install these libraries in Arduino: Sketch -> Include Libraries -> Manage Libraries. Then search for Adafruit NeoPixel and install the Adafruit NeoPixel Library. Then search for Adafruit SSD1306 and install the Adafruit SSD1306 library. It may ask you whether you want to install all dependencies, or just the library itself. You need to install all dependencies in Arduino before importing into MPLAB X.
After installing those libraries in Arduino, go to Tools -> Board and select the AVR-DB series (no bootloader). Select the COM port your AVR-DB Curiosity Nano is connected to. Then configure the settings as shown below.

Arduino Board Settings

Now click the Verify button in Arduino to build the project. If it builds successfully, you are ready to import the project into MPLAB X.

If it does NOT build successfully, it is recommended you enable Verbose output during both compilation and upload. This will give detailed information on why a build or upload failed. To enable verbose mode, go to File -> Preferences and check the boxes next to Compilation and Upload (see below).

Enable verbose output during compilation and upload

Importing the Arduino project into MPLAB X

To use the Arduino Import Tool in MPLAB X, the plugin must first be installed.

Open MPLAB X, then click Tools -> Plugins

Click on the Available Plugins tab. Next click on the Name field to sort the plugins alphabetically. Click the checkbox next to Arduino Import Plugin and then click Install. If MPLAB X asks to restart the application, click Ok. If MPLAB X does NOT ask to restart the application, a fresh start is recommended.

Now it's time to import an Arduino project!

We have provided the Arduino project described at the beginning of this article and will now import it.

IMPORTANT NOTE: Its strongly recommended to NOT use online storage such as OneDrive as you may encounter problems when importing the project. Instead store the original Arduino project and the imported MPLAB X project locally.

In MPLAB X go to File -> Import -> Import Arduino Project.

Import an Arduino Project

The Project Setup pop-up window will appear.

Project Settings

1. Navigate to the local directory where you saved your Arduino project. Select the .ino file.

2. To keep everything easy to find, I usually set the Target Project Location to match the imported sketch folder location.

3. Navigate to the Arduino 1.8.x or Arduino-CLI location on your computer. This is often under C:\ProgramFiles (x86)\Arduino

4. Under Platform, select DxCore

5. The default platform location for DxCore is C:\Users\<username>\AppData\Local\Arduino15\packages\DxCore\hardware\megaavr\<select highest version>

6. This project used an AVR DB-series (no bootloader)

7. Give your project a name. I kept the same name as the original Arduino project

8. Project directory. I used the same directory as the original Arduino project directory

9. Ensure the Copy All Dependencies box is checked

Click Next.

The Board Configuration pop-up window will appear.

Board Configuration

1. Select the microcontroller. The Arduino project used an AVR128DB48.

2. Millis()/micros() Timer. TCB2 (recommended)

3. attachInterrupt() version: On all pins, with new implementation

4. Multivoltage I/O (MVIO): Enabled

5. Clock Speed: The Arduino project used the 16MHz internal oscillator

Note: The Arduino project leveraged Adafruit’s NeoPixel library which requires a 16MHz clock. If the user wants to include a faster clock, consider the DxCore NeoPixel library which supports faster clock speeds.

Click Next.

The Select Tool pop-up window will appear.

Select Tool

Select the programming tool. The Arduino project used an AVR128DB48 Curiosity Nano.

Click Next.

The tool will then start importing your Arduino project.

Tool Importing Arduino Project

A pop-up will appear stating that a file has been renamed in order to build the project.

File renamed

Click OK.

The project will then complete importing into MPLAB X. Two projects will appear. One is for the libraries, the other is for the project itself.

Arduino Project Imported into MPLAB X

Next the compiler needs to be set up.

In MPLAB X select Tools -> Options

1. Click on Embedded

2. Click on the Build Tools tab.

3. Click Add

Navigate to Compiler Setup

Next we need to navigate to the DxCore build tools.

The base directory for the DxCore build tools will be found at the following location:

C:\Users\<username>\AppData\Local\Arduino15\packages\DxCore\tools\avr-gcc\7.3.0-atmel3.6.1-azduino7b1\bin

It will then auto-populate the other fields for the C Compiler, Assembler, and Make Command.

Click OK.

You will then see AVR-GCC (v1.00) in the list of available toolchains on the left.

Click OK.

Toolchain available

Next under MPLAB X projects, right click on the libraries project, and select Properties.

Open libraries Project Properties

Under Compiler Toolchain, select AVR-GCC (v1.00). Click Apply.

Select Toolchain

Next, click on AVR GCC (Global Options). Under Additional Options add: -Og -g2.

Click Apply.

AVR GCC (Global Options)

Next, click avr-gcc. Under Option Categories select Optimization and confirm the optimization-level field is set to s. If it is not set to s, do so now.

Optimization Level

Click Apply, then click OK.

Build libraries Project

Now you can build the libraries project. Clean the dropdown next to the Clean and Build toolbar button and select Clean and Build project.

Build Successful

You will see the green Build Successful message in the lower pane.

Now you need to repeat that process for the project itself.

Right click on the project itself and select Properties.

Open Project Properties

Project Properties - Avr GCC (Global Options)

Under Categories click Avr GCC (Global Options). Under Additional Options add: -Og -g2.

Click Apply.

Optimization

Next, click avr-gcc. Under Option Categories select Optimization and confirm the optimization-level field is set to s. If it is not set to s, do so now.

Click Apply, then click OK.

Build Project

Now you can build the libraries project. Clean the dropdown next to the Clean and Build toolbar button and select Clean and Build project.

You will see the green Build Successful message in the lower pane.

Build Successful

Now you can program the microcontroller, set breakpoints in your code, enter debug mode, and step through your code.

Set breakpoint

To set a breakpoint, click on the line number next to where you want to set the breakpoint.

Launch Debugger

Now you can begin debugging the project. Click the Debug button on the toolbar.

Debugger stopped at breakpoint

You can now use the microcontroller's onboard peripherals with much more control than Arduino gives you.

For example, you could write a fully featured ADC driver to take many samples in a single burst to mitigate random noise. You could change the sampling duration to tune the ADC away from periodic noise (such as mains power noise). You could perform a differential ADC read (useful for Wheatstone Bridges).

Arduino Project

// Include libraries
#include <SPI.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <Adafruit_NeoPixel.h>

// OLED display parameters
#define SCREEN_WIDTH 128 // OLED display width, in pixels
#define SCREEN_HEIGHT 64 // OLED display height, in pixels
#define OLED_RESET -1    // Reset pin # (or -1 if sharing Arduino reset pin)
#define SCREEN_ADDRESS 0x3D // See datasheet for Address; 0x3D for 128x64, 0x3C for 128x32

// NeoPixel parameters
#define PIN PIN_PE3
#define NUMPIXELS 9
#define DELAYVAL 500

// Define LED pins

#define LED0 PIN_PB0  //LED0
#define LED1 PIN_PB1  //LED1
#define LED2 PIN_PC0  //LED2
#define LED3 PIN_PC1  //LED3
#define LED4 PIN_PA0  //LED4
#define LED5 PIN_PA1  //LED5
#define LED6 PIN_PB2  //LED6
#define LED7 PIN_PB3  //LED7
#define POT PIN_PD6   //POT

// Initialize NeoPixels
Adafruit_NeoPixel pixels(NUMPIXELS, PIN, NEO_GRB + NEO_KHZ800);

// Initialize OLED display
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

uint32_t result = 0;
const int POT_MIN = 0;
const int POT_MAX = 4095;
const int SEGMENT_SIZE = POT_MAX / (NUMPIXELS); // Divide the range into segments for each NeoPixel

void setup() {
  Serial3.begin(9600);

  if (!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
    Serial3.println(F("SSD1306 allocation failed"));
    for (;;); // Don't proceed, loop forever
  }

  ADC0.CTRLA = 0x1;
  pixels.begin(); // Initialize NeoPixel strip
}

void loop() {

  uint16_t result = analogRead(POT);

  int segment = result / SEGMENT_SIZE; // Calculate which segment the potentiometer reading falls into
  pixels.clear(); // Clear all NeoPixels

  for (int i = 0; i < segment && i < NUMPIXELS; i++) {
    if(i % 2 == 0) { // Check if the index is even or odd
      pixels.setPixelColor(i, pixels.Color(10, 0, 0)); // Set red color for even indices
    } else {
      pixels.setPixelColor(i, pixels.Color(0, 0, 10)); // Set blue color for odd indices
    }
  }
  pixels.show(); // Update NeoPixels

  // Display potentiometer value on OLED
  display.setTextSize(2);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.clearDisplay();
  display.print("Pot: ");
  display.println(result); // Print potentiometer value
  display.println(); // Empty line


  // Calculate and display potentiometer percentage
  double percentage = (double)result / POT_MAX * 100;
  display.print("Pot%: ");
  display.print(percentage, 1); // Print potentiometer percentage with one decimal place
  display.println();

  display.display();
}