Cloning an MPLAB Xpress project from GitHub
This tutorial will lead you through the steps required to clone the first CHRP4 and UBMP4 Introductory Activity program into the cloud-based MPLAB® Xpress IDE from its mirobotech GitHub repository.
For more information on MPLAB Xpress and how it compares with the traditional MPLAB X IDE, or for information about creating a new MPLAB Xpress programming project from scratch, please refer to our getting started with MPLAB Xpress page.
Cloud-based software development
The cloud-based MPLAB Xpress IDE is a new addition to Microchip’s traditional desktop MPLAB X IDE software, and it mimics the main features of MPLAB X from inside a web browser. MPLAB Xpress enables anyone using older, under-powered, or storage-limited computer systems, and especially education users limited to using Chromebooks, to create, edit, and compile microcontroller programs in the cloud using up-to-date tools using nothing more than a web browser.
Can MPLAB Xpress program microcontrollers?
MPLAB Xpress can support Microchip’s latest PICkit 4 and PICkit 5 hardware programmers on Windows and macOS computers, and works well with microcontrollers supporting bootloaders on all devices. While MPLAB Xprress is more limited than its MPLAB X desktop counterpart in programming and debugging, its capabilities keep improving and it has matured into a viable solution for creating and maintaining simple programs used in small microcontrollers – like those used in the mirobo introductory projects.
Where are MPLAB Xpress projects stored?
Projects are temporarily stored in Microchip’s cloud sandbox, but MPLAB Xpress users should ideally use their own GitHub account to have a permanent cloud-based storage solution that integrates nicely with the MPLAB Xpress cloud-based IDE. MPLAB Xpress can also import and export projects in the MPLAB X project structure. While this is a useful capability, bouncing programs between MPLAB X and MPLAB Xpress doesn’t provide the same benefits that a fully end-to-end cloud-based solution like GitHub does.
Before starting to use MPLAB Xpress, you will need to create a myMicrochip cloud account. This can be done from the MPLAB Xpress log in page in the upcoming steps.
Let’s start cloning your first MPLAB Xpress project! You can watch the steps demonstrating the process in the video, or follow the step-by-step instructions below.
Step 1 - Start MPLAB Xpress
Get started by opening the MPLAB Xpress Cloud-Based IDE web page. (Clicking this link will open it in a new browser window.)
Click the Get Started Now button on the page. If you are already logged into a myMicrochip account, MPLAB Xpress will start to open. Otherwise, you will end up at a page where you can sign-in or register for an account.
After signing in and launching MPLAB Xpress, it will start up in your web browser. It may take some time for MPLAB Xpress to open, as it needs to pre-load its code into the browser. When it opens, you should see an empty MPLAB Xpress project, as shown here:
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 2 - Get the GitHub repository link
This programming project already exists in a shared repository in GitHub, a cloud-based software project storage and version control system. Using GitHub to share projects makes it easy for new users to get started programming quickly, and always provides them with the most up to date version of each programming project.
GitHub is a part of an incredibly useful and complex ecosystem, and this tutorial will use just a tiny subset of its features – look for GitHub tutorials on the internet when you are ready to explore its features further.
This tutorial demonstrate how to clone and build the Introductory Activity 1 programming project for either the CHRP4 or UBMP4 circuit. Navigate to the appropriate GitHub page to find the project template for your circuit.
Go to the CHRP4 Introductory Activity 1 - Input and Output GitHub project page if you are using CHRP4.
Go to the UBMP4 Introductory Activity 1 - Input and Output GitHub project page if you are using UBMP4.
The GitHub page you land on will look similar to this one for the UBMP4 project:
The GitHub repository for this project contains the MPLAB project folder, a LICENSE file, a README.md file, and some additional GitHub control files for this 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 to the right of the project’s HTTPS address.
Step 3 - Clone the Git project in MPLAB Xpress
Return to the MPLAB Xpress tab in your web browser. From the File menu, choose Clone Git Project. A Clone Repository dialogue box will open.
Click your cursor into the Enter Git Url: box, and paste in the link to the repository you copied from the GitHub project page.
Important: add a slash / at the end of the URL link, as shown below, and then click the OK button. The slash lets the server know that this is a folder, and not the actual address of the project itself, and that it has to look inside the folder to find the project.
Notice the message in Note 1 that explains that projects created in MPLAB Xpress will only remain in the Microchip cloud sandbox for three days. Projects must be exported from the cloud sandbox, or saved to a GitHub repository for longer term storage. These options will be explored later in this tutorial.
A Choose Project dialogue box opens showing the Git project. Select the project and click Open.
A second Choose Project dialogue box opens showing the MPLAB X project within the Git project. Select the project and click Open.
After cloning, the project will open in MPLAB Xpress.
The Project browser tab in the top left panel of the screen organizes the types of files in this programming project, and the Dashboard panel below it shows some of the device and compiler settings that were made when the project was initially created and configured.
Click the Header Files and Source Files organizers to expand them in the Project panel. Then, click on the Intro-1-Input-Output.c source file to open it in the code editor.
Step 4 - Build the project
Compiling the program is referred to as building the project. Click the downward-facing arrow beside the Clean and Build icon (the hammer and broom) in the toolbar and select the Clean and Build for Export option.
MPLAB Xpress will start to compile the current program and, when compilation is finished, the compiled object file (Intro-1-Input-Output.hex, for this project) will automatically be downloaded to your computer.
When compilation starts, the Output window below the code editor will open to show the build progress and results of the build operation.
If the build is successful, the compiled program object file – with the filename ending in a .hex file extension – will be downloaded to your computer, ready for programming into your microcontroller.
Any freshly-cloned project should build successfully, but you may run into build failures after editing the code. If your build fails, check any source code files that you edited for errors, and after fixing the errors try to build the file again. Common sources of errors after editing the Intro-1-Input-Output.c file include 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, or mis-matched curly-braces { } in the program.
Step 5 - 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 dowloaded object code file
First, we have to locate the compiled object code file. Navigate to your computer’s downloaded files folder to locate the recently-downloaded .hex object code file.
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 microcontrollers 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 using the bootloader takes less than a second, and the PIC16F1459 drive will automatically be ejected from your computer after the program is downloaded.
That’s it! Your program is now running in your device.
You should now be able to clone any other MPLAB X GitHub repositories into MPLAB Xpress projects, edit them in the cloud, and program them into your circuit.
Step 6 - Save your edited project
Save your MPLAb Xpress project to GitHub
After you have cloned a project and edited its program in MPLAB Xpress, you will probably want to save the changes you made. MPLAB Xpress will save your project files for a limited time in its cloud sandbox (for up to three days, as of when this page was created), but you will likely want a more permanent way to save your programs. Saving the MPLAB Xpress project to a GitHub repository is the first option.
Storing your project in GitHub isn’t as easy as hitting a save button. There are a few steps involved, commonly known as committing changes to the project, and then pushing the changes to GitHub. Watch the video below to see how it’s done:
Export your MPLAB Xpress project for use in MPLAB X
Alternatively, you can export a copy of your project from MPLAB Xpress in a format that allows it to be opened in MPLAB X. To do this, use the Export Project option in the File menu. This packages all of the project files into a .ZIP archive that will be downloaded to your computer.
MPLAB X projects can also be imported into MPLAB Xpress, including the .ZIP archives exported from MPLAB Xpress. To do this, use the Import Project option in the File menu.
MPLAB® is a registered trademark of Microchip Technology Inc. in the USA and other countries.