GitHub is a good way to collaborate on shared software projects if you're looking for an off-site, third-party system for storing and sharing the code. The repositories on the GitHub site can be either private or public, but they are available to the company that owns GitHub, Microsoft.
I use MCUXpresso on macOS to develop code for NXP microcontrollers. It's based on the Eclipse IDE, a general purpose IDE but it's been customized to enable features that are critical to embedded systems development. Alternative development pathways include compiling and debugging from the command line, using VSCode and selecting the right plugins or using the Arduino 2.x IDE. Personally, I prefer MCUXpresso as it works out of the box when developing for NXP microcontrollers.
Clone via the Command Line
There are GUI approaches to making a local copy of a GitHub repository on your computer and then there are more traditional, command-line approaches. I'll start with the command-line approach. (Alternate Instructions are found here)
First, make sure that you've installed the GitHub command line tools. (beyond the scope here)
Once you have confirmed that you have the command line tools, open a terminal. Then, navigate to the folder where you want to make the repository clone on your local computer.
git clone git@github.com:onnimikki/K32xxxxxxxxx.git
This is what it looks like when typing it out in the command line:
In this case I was in a folder called temp3 and I downloaded the K32xxxxxxxxx project from user onnimikki using git's clone command.
Once you're done with cloning the repository you can then use the MCUXpresso import tool to import it as an Eclipse project, assuming that the original authors of the code wrote it as such.
Clone via the GUI: MCUXpresso Import Tool
There are two steps to using an online clone in MCUXpresso:
- Making a local copy
- Importing the copy as an Eclipse project
We'll start with the coping.
Step 1: Make a local copy of the online repository
MCUXpresso already has Git tools built-in as it is based on Eclipse. Depending on your version of MCUXpresso, you can try one of these two approaches :
File -> Import -> Git -> clone URI, orFile -> Import -> Git -> Project From Git -> Clone URI
where URI is an internet link, or web address, to the repository. You will need to find this web address for the project. That's the "URI". You can find it by navigating to the web page for the project on GitHub, then click on the green "Code" button and you'll see three location options for cloning. The one you want is in the SSH tab on the GitHub page for the project. The following is a screenshot of the webpage for a particular repository. You can see how I've selected the SSH tab. The URI that you want is the "git@github.com/onnimkki/K32xxxxxxxx" text. Copy that.
Next, take that copied URI and paste it into MCUXpresso in the "Import Projects from Git" window. Past into the URI field and then MCUXpressor will fill in the details from there.
From there you may be asked to choose a specific branch of the repository on GitHub. These days it's often, rightly, called the "main" branch, but in some projects (like this example) it's called the "master" branch.
Step 2: Import the local copy as an Eclipse project
Next, MCUXpresso will attempt to take the local copy of the repository and arrange the files so that it fits the formatting and organization of a typical "Eclipse" programming project. This shouldn't take much effort as the original GitHub repository should have already been formatted as an Eclipse project because it was developed on MCUXpresso before being uploaded to GitHub.
From there you should have a working MCUXpresso project that should compile and download to your development board.
Another Possibility: Keys instead of Passwords
Some developers would like to have some security on their GitHub repositories. The standard login + password approach to accessing repositories was removed by GitHub a few years ago and replaced with a key process.
Instructions for generating the SSH key are here. I won't get into details about it here.
The Future: Integrate your changes into the online repository
An important step for many software projects is to reintegrate your locally-developed project into the online repository. This is often called "merging" the committed changes in a branch back into the repository. I'll look into tackling that issue in a future blog post.
Notes
I've blocked out the specific name of the project as it isn't important to the general instructions. If I've missed a step or a detail is unclear, just let me know.
James Andrew Smith is a Professional Engineer and Associate Professor in the Electrical Engineering and Computer Science Department of York University’s Lassonde School, with degrees in Electrical and Mechanical Engineering from the University of Alberta and McGill University. Previously a program director in biomedical engineering, his research background spans robotics, locomotion, human birth, music and engineering education. While on sabbatical in 2018-19 with his wife and kids he lived in Strasbourg, France and he taught at the INSA Strasbourg and Hochschule Karlsruhe and wrote about his personal and professional perspectives. James is a proponent of using social media to advocate for justice, equity, diversity and inclusion as well as evidence-based applications of research in the public sphere. You can find him on Twitter. You can find him on BlueSky. Originally from Québec City, he now lives in Toronto, Canada.