Public:MCUXpresso

	Use version 11.X.X
ISC Uses MCUXpresso version 11.9.1 Do not install versions 11.6.0 or older

About

MCUXpresso is an IDE from NXP who makes the family of chips we use on ISC (or at least they bought the company that did). We use MCUXpresso to build, flash, and debug all of the code on the solar car. You can use any IDE for writing code, however you must use MCUXpresso to compile, flash, and debug all code on target.

Setting Up MCUXpresso

Note: ISC has officially only ever supported windows. We are working to make our software more cross platform but instructions for non-Windows may still be lacking. Please improve them!

Windows 10 & Mac OS X

1. Download the MCUXpresso IDE from the NXP Website.
   1. Direct Download link to skip creating an account.
   2. Register for an NXP account
   3. Download MCUXpresso 11.9.x.
      1. Agree to the MCUXpresso terms*.
      2. Download the version for your OS.
2. Install MCUXpresso including Debug Drivers
   1. Also Install all device drivers when prompted (depending on your device settings you may not receive these, may only receive one for them all, or will receive a bunch)
3. At this point you will need to have github software repos set-up on your computer to move forward with the set-up process. If you are working on Brizo code you will need b-fw, the setup information can be found at the bottom of the github b-fw wiki page. Once you have completed this, continue these instructions.
4. Create your workspaces in MCUXpresso (File -> Switch Workspace -> Other...) Each repository will need its own workspace!
   1. Argo-fw (also FW): make a single workspace for all Argo projects
   2. B-fw: make a single workspace for all Brizo projects, simply create a folder somewhere on your computer (but not in the repo!) and select this folder when opening MCUExpresso
   3. FW-xxxx: Make a workspace for each repo to make project switching easy!
   4. Where should I put my workspaces files? (they are configuration files that are stored on your computer). Common advice varies but do not put them in the repo. You can put them in another folder at the same level as the repo if you like. Just know where they are, you might need to know later.
5. For b-fw and new FW-xxxx: To enable you complete the next step there is additional set-up for the static libraries (common and mbed).
   • Navigate to your repo and run the script update_LibraryProjectFiles.sh
     • On Mac/Linux you should be able to run from your built in terminal (or just by double clicking depending on distro)
     • On Windows this script can be run from Git Bash for Windows
   • If there are future updates to these files you can just run the script again and it will overwrite the old ones.
   • Note: This script was introduced in b-fw#152 so it is not available before that. If you need to work on code before this you should first checkout a commit after this PR and run the script before going back to the older code. Everything is compatible, just the method is different.
6. With MCUXpresso open, import the files into your workspace:
   1. Go to File > Import
   2. Select General > Existing Projects into Workspace
   3. Click "Browse" next to "Select root directory"
   4. Select the base folder for the git repository you are setting up the workspace for. (b-fw or ARGO-FW)
   5. Select the checkboxes for the projects you want to import to this workspace
      1. On ARGO -FW you will want mbed common and all of the projects you need
      2. On b-fw you will want mbed common mbed15x9_skeleton plus any projects you need
7. At this point you are ready to work on and edit existing projects. More info on Building and Debugging Code can be found on its wiki page. Continue below for notes and help if you run into some rare known issue.

*You may want to note the patent waiver clause in case you decide to use it for personal projects. For solar car related software this should not be a concern unless NXP intend to put a car in their IDE.

Linux

Note: these instructions are probably inaccurate. If you are using Linux please use version 10.1.x and consult John Han so we can update these directions with a tested procedure.

These steps were performed with Ubuntu 20.04 LTS.

1. Download MCUXpresso 11.9.x
2. Navigate to Downloads and run the installer

   1. cd ~/Downloads

      chmod +x <name_of_download> sudo ./<name_of_download>
3. When prompted, set an appropriate directory to use as your workspace. As mentioned above, this should be separate from where the code is stored.
4. In a directory other than your workspace directory, clone the firmware repository of your choice
   1. git clone --recursive https://github.com/IlliniSolarCar/b-fw.git
   2. For more information, see the wiki page about git
   3. If you are working on b-fw, unzip the .project and .cproject files within mbed and common
      1. cd common unzip project_files.zip mv project_files/{.cproject,.project} . rm -r project_files/ cd ../mbed unzip z_project_files.zip
5. Import the firmware files into your workspace
   1. File > Import > General > Existing Projects into Workspace
   2. Select the git repository as your root directory

Building and Debugging

Once you've completed the steps above you should be ready to build/debug your code and put it onto the MCU. For instructions on that see: Building and Debugging Code

Creating a New Project

Rarely you may have to create a new project if you are starting the code for a new vehicle system that is yet to have code. Additionally, you can do this for playing around with test code (you can also use the skeleton). To do so follow these steps, do not just copy paste in the file explorer:

• Open the Skeleton project in MCUXpresso. Wait for it to completely open and load.
• Right click on the project and click copy (Ctrl-C may also work, but sometimes is unreliable in copying the right thing)
• Right click in a blank area in the project explorer and click paste
• Rename the project appropriately
• Navigate to the b-fw folder and create a new folder for the project using the projects name. Navigate into the folder and click okay/next to use this folder
  • MCUXpresso will create the project in the current directory you select, it will not make a new folder for the project
• Once it finished copying add your project to git (including all the .(c)project files!)
• Don't forget to update the names of things to be correct, for example the include guards in the headers.

Rare Problems

If you have a Lenovo non-ThinkPad device, or maybe something else weird running Windows 10, you might run into the debuggers not working even if you've set up everything correctly. The error text when trying to debug was a popup saying Socket exception: connection reset or something similar, and the details were a whole list of things including Java code locations. This problem is probably not with the drivers. The easiest fix was to install MCUXpresso 10.1.0 instead of 10.1.1. It may work with other earlier versions as well but hasn't been tested yet. Also make sure to restart your computer after attempting any changes to MCUXpresso versions and driver installs.

Configurations

If you follow the set-up instructions above you will have everything configured as needed. This section is about why/how those configurations came to be

Note: this is written based on my understanding and may not be complete or 100% accurate. If anyone has more interest in diving deeper into the configuration of our tool chain please do and update this!

Several things have to be configured in the IDE for everything to work correctly. This will briefly discuss where configurations are stored/set. For the most part everything that is relevant can be found in propertied -> C/C++ Build. In these properties all of the different tabs that have a configuration listed at the top are changing settings in that configuration. Importantly this includes dialects, linker scripts, and optimizations. Notably, it does not include the settings on the MCU settings page! That is stored in the workspace settings. If you are using a different MCU regularly you might want separate workspaces for that - if this becomes a team wide regular thing it probably should become a standard set-up.

Linker Scripts:

The linker scripts include all of the info for memory mapping. This info comes from the MCU datasheet and MCUs with the same memory configuration (such as LPC1519 & LPC1549) can use the same one. Generally these files should not be changed.

Additional Resources

The Appendix and notes section has been moved to the Building and Debugging Code page since it most had to do with issues related to debugging. -Jonathan (Sep 2019)

MCUXpresso Product Overview (with documentation)

Doxygen - for documenting your code

Credit:

This set-up guide is adapted from Devan Lai's (of CalSol) LPCXpresso set up guide which can be found here. Our set-up is based on CalSol's the development of Zephyr