Cloning an MPLAB X project from GitHub
This tutorial will lead you through the steps required to clone the first Introductory Activity program for either the CHRP4 or UBMP4 circuit into the MPLAB® X IDE from its GitHub repository.
For more information on MPLAB X and how it compares with the cloud-based MPLAB Xpress IDE, or to learn how to create your own MPLAB X programming project, refer to our getting started with MPLAB X page.
MPLAB X IDE and MPLAB XC compilers
MPLAB X is a mature desktop IDE used to create and edit programming projects for all varieties of Microchip microcontrollers. In order to compile programs for each specific microcontroller family, MPLAB X needs to be paired with an appropriate MPLAB XC compiler. The mirobo projects on this website are all based on the 8-bit Microchip PIC architecture, and will require the MPLAB XC8 compiler to build their object code.
The MPLAB X IDE and the various MPLAB XC compilers can be run on computers running the Windows, Linux, and macOS operating systems. All of the versions of MPLAB X interoperate, so saved MPLAB X projects can be opened by computers using any supported operating system.
Alternatively, the cloud-based MPLAB Xpress IDE is an option for project development in a web browser on every operating system, and also enables microcontroller programming using Chromebooks.
Step 1 - Download and install MPLAB X and XC8
If this is your first time developing a project with MPLAB X, you will need to download the newest version of both the MPLAB X IDE as well as the MPLAB XC compiler from the Microchip website.
Get the MPLAB X IDE from the MPLAB X developer tools and resources page.
Get the MPLAB XC8 C compiler from the MPLAB XC developer tools and resources page.
Choose the appropriate installation packages for your operating system from Microchip’s web site, and install both applications following Microchip’s instructions. The order they are installed in doesn’t matter, but MPLAB X will have to be re-started if it is running when a new compiler is installed. The default installation and configuration choices will work best for most applications.
If you have an older version of MPLAB X installed, we recommend installing version 6.15 of MPLAB X and version 2.41 of MPLAB XC (to match the versions used for these examples), or newer versions if they are available. New versions of MPLAB X get installed into their own folder and will happily coexist with one or more older versions already installed on your computer. The same is true of MPLAB XC compilers – new versions can be installed alongside existing versions.
When you decide to remove an older version of either MPLAB X or MPLAB XC8, or no longer wish to use them, an uninstaller program is located in each version’s folder on your computer.
Step 2 - Prepare a project folder
Cross-compiling programs (building programs for microcontrollers on a desktop computer) creates a multitude of files. There are the source files, of course, but also project files, log files, debug files, error files, and the compiled object code files. To store and organize all of your MPLAB X projects, and to corral all of the files that MPLAB X generates, create a folder to organize your MPLAB X programming projects in your computer’s filesystem.
One of the first settings that has to be chosen when creating an MPLAB X project is the location of this destination project folder. MPLAB X will create a sub-folder for each new project inside your project folder, helping you to stay organized. You might even consider creating sub-folders for each circuit you plan on programming to further organize your project files.
This UBMP4 folder, created inside the MPLABX folder, will be used to organize future UBMP4 programming projects on this user’s computer.
Programming Terms
IDE (Integrated Development Environment) - software used to manage all the files in programming projects, compile programs, and download the programs into microcontrollers.
Source code files - one or more human-written files making up a computer program.
Project - a collection of source code files, IDE configuration files, and output files making up a program.
Compiler - a computer program that converts program source code into processor-specific machine code, or an intermediate machine readable format.
Assembler - a computer program that converts low-level assembly language source code into processor-specific machine code.
Machine code - the processor-specific instructions that make up a program, encoded as binary data in the memory of a computer.
Object code - compiled source code in the form of machine-readable instructions representing all, or just parts, of a program.
Linker - a computer program that combines one or more object code files into a complete program.
Hex file - a file format representing the machine code instructions and their memory locations used by a hardware programmer to write the program into the memory of a microcontroller.
Programmer - a hardware device that can read and write the memory of a microcontroller to write and verify a program’s machine code instructions into its memory.
Bootloader - a software program running in a microcontroller that is capable of writing a user program into the memory of the microcontroller without over-writing itself.
Step 3 - Get the GitHub repository link
This programming project exists as a shared repository in GitHub, a cloud-based software project storage and version control system. Sharing mirobo projects in GitHub makes it easy for new users to get started programming quickly and always provides the most current version of each programming project. GitHub is a part of an incredibly useful and complex ecosystem, and we are just going to use a tiny part of it for this tutorial – there is a wide variety of information about it on the internet when you want to find out more.
Navigate to the appropriate GitHub project template page for your circuit.
Go to the CHRP4 Introductory Activity 1 - Input and Output GitHub page for the CHRP4 project files.
Go to the UBMP4 Introductory Activity 1 - Input and Output GitHub page for the UBMP4 project files.
The page you land on will look similar to the one for the UBMP4 project, shown below:
The GitHub repository for this project contains the MPLAB project folder, a LICENSE file, a README.md file, and some additional control files for the GitHub repository.
Click the < > Code button to open a pop-down panel showing the project’s GitHub link. Copy the link by clicking the copy button, shown as two overlapping squares at the right of the project’s HTTPS address.
Step 4 - Clone the GitHub project into MPLAB X
Start MPLAB X. When MPLAB X opens, navigate to the Team menu and click Clone from the Git sub-menu. Git, which is the underlying technology used by GitHub, is one of three version control systems that are supported by MPLAB X.
The Clone Repository dialogue box opens. When using MPLAB X to clone a repository for the first time, you will have to set the destination folder. In the Specify Destination Folder section, click the Browse button and then navigate to the folder that you created to organize your MPLAB projects in step 2.
The next time you clone a project, MPLAB X should remember your previous destination folder and fill it into the Clone into: box for you.
Next, paste the link to the repository that you copied from GitHub into the Repository URL: field.
Ensure that your destination folder is set correctly, and press Next.
The Remote Branches dialogue will open with main pre-selected. These introductory projects are simple and only contain one branch. Click Next to continue.
In the Destination Directory dialogue, ensure the Parent Directory is correct. It should be the same as the Clone into: setting in the first Remote Repository dialogue. You can change the Clone Name: here if you like, or leave the name the same as in the GitHub project.
Click Finish to start cloning the repository into MPLAB X.
Once the project has been cloned into MPLAB X, you will have the option of opening the project. Since we are interested in viewing and editing the project, click Open Project in the dialogue box that pops up.
After cloning the project, the Projects browser tab should be open at the top left of the screen, with the Dashboard panel open below it. If not, choosing Reset Windows from the Window menu should arrange the windows and panels as shown below.
Double-click the Header Files and Source Files line items in the Projects tab, or click the arrow to the left of each one to open these organizers and view their files. Double-click the Intro-1-Input-Output.c source file to open it in the code editor window.
The Dashboard panel at the lower left shows some of the device and compiler settings that were made during project setup, and these can be adjusted later, if needed.
Step 5 - Build the project
Compiling a program is referred to as building the project. Click the downward-facing arrow in the toolbar beside the Clean and Build icon (with both the hammer and broom symbols) and select Clean and Build Main Project to erase any older project build files and to compile the current program.
Bonus tip: any of the project’s files that you edited will automatically be saved in their current state when the project is built, so you don’t have to worry about individually saving any updated files in each editor tab.
After compilation starts, the Output window below the code editor opens to show the build process and the results of the build operation.
If the build is successful, the program is ready to be downloaded to your circuit.
Any freshly-cloned project should build successfully, but you may run into build failures after editing the code. If the build fails, check for errors in any of the source files that you edited, and try to build the file again after fixing the errors.
Common sources of errors from editing the Intro-1-Input-Output.c file are missing characters at the start of the first comment block, missing characters at the end of the final comment block, missing semi-colons ; at the end of C statements, and mis-matched curly-braces { } in the program.
Step 6 - Program your circuit
There are a number of different ways circuits can be programmed, but since this tutorial builds the introductory activity for the CHRP4 or UBMP4 circuits, we will focus on using the USB µC bootloader which is pre-programmed into the microcontrollers for these kits. Find out more about uploading programs using a bootloader.
Locate the object code
First, we will have to locate your compiled object code file. Navigate to your MPLAB project folder you created earlier, and open the folder for this project.
The project folder contains the project source (.c) files, a header (.h) file, and a number of other files and folders.
Open the dist (distribution) folder inside the project folder.
The default folder is created by MPLAB for the default configuration of a build – MPLAB X can support multiple build configurations for each project. Some versions of MPLAB X create a free folder if the default configuration uses the free version of the XC8 compiler (more efficient compilers are available as paid upgrades).
Open the default folder to reveal the production folder nested inside it.
Open the production folder to see all of the files created during the build process. Many of these files are created by MPLAB to assist during debugging, and the .hex file inside this folder is the executable program that that you will program into your device.
Connect your circuit and press SW1
Connect your CHRP4 or UBMP4 to your computer’s USB port. The next step will only work if the USB µC bootloader is pre-installed in the PIC16F1459 microcontroller (it comes pre-installed in the microcontroller included in CHRP4 and UBMP4 kits).
Press and release pushbutton SW1, beside the USB Type-C connector on your device. A drive named PIC16F1459 will mount in your computer’s filesystem.
Drag and drop your program into the circuit
Drag and drop the program .hex file to the PIC16F1459 drive to download the program into the microcontroller using the bootloader.
Downloading this program through the bootloader takes less than a second, and the PIC16F1459 drive will be automatically ejected from your computer when the download is complete.
That’s it! Your program will now be running in the microcontroller in your device.
You should now be able to clone any other GitHub repositories into MPLAB X projects the same way you did with this first project. Any changes that you make to these cloned projects will be saved in the local MPLAB folder that you created on your local machine. To save projects into GitHub, you will have to create your own GitHub account, and then learn the steps to create your own GitHub repositories.
MPLAB® is a registered trademark of Microchip Technology Inc. in the USA and other countries.