Mars Rover 2020 Firmware Repository

Platform: STM32F446xE / NUCLEO-F446RE

This repository contains:

• Applications for running on each control board [apps]
• Custom and external libaries [libs]
• Miscellaneous items [misc]
• Python scripts [scripts]
• Arm MBED OS 6 SDK source [mbed-os]
• Configuration files for each target hardware [targets]
• Test applications for testing code components [test-apps]
• Makefile [makefile]
• Github Actions configurations for automatic build testing [.github]

Best Contribution Practices and Tips

• Create a branch in the format yourName/#<issue-number>/featureName for every feature you are working on
• Rebase onto master and test on hardware before merging into master
• Add a Github Actions build target for your application if it is not a test application
• Create a pull request to merge any branch into master and select everyone else working on the feature as reviewers
  • Name the pull request Closes #<issue-number>: FeatureTitle
• When merging a pull request that fixes an issue title the commit Fixes #issueNumber: FeatureTitle
• Clean binaries between making changes to the makefile
• There seems to be an annoying mix of CamelCase and snake_case in MBED but just try to be consistent with whatever code is nearby
• Squash when merging pull requests

UWRT Firmware Development Instructions

1. Download the development toolchains and serial interface software

   For Ubuntu (20.04 preferred)

   • Update package lists: sudo apt update
   • Install Ninja: sudo apt install ninja-build
   • Install ccache: sudo apt install ccache
   • Install mbed-tools and other python requirements: pip3 install -r scripts/requirements.txt
   • sudo apt install screen can-utils for serial and CAN interfacing
   • Install/update ARM GCC toolchain:

     sudo apt autoremove gcc-arm-none-eabi
     wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/10-2020q4/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2
     sudo tar -xvf gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2 -C /opt/
     echo "PATH=/opt/gcc-arm-none-eabi-10-2020-q4-major/bin:\$PATH" >> ~/.bashrc
     export PATH=/opt/gcc-arm-none-eabi-10-2020-q4-major/bin:$PATH 
     

     Note: If you are not using Ubuntu 20.04 and/or bash you may need to modify this script's paths/files.
   • Install CMake:
     • Follow kitware instructions to add Latest CMake apt repository
     • sudo apt install cmake

   For Windows

   • Install Windows Subsystem for Linux (WSL) with Ubuntu 20.04
   • Follow Ubuntu setup instructions (optionally instead of screen you can use PuTTy, a GUI Windows app)

   For Mac (Not Recommended)

   • Open Command Line
   • Install Homebrew if not installed

     /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
     

   • Download auto-run script, which will auto install with latest version:

     brew tap ARMmbed/homebrew-formulae
     

   • Install ARM GCC toolchain via HomeBrew:

     brew install arm-none-eabi-gcc
     

   • Install ZOC for serial interfacing

2. Download source code

   git clone --recurse-submodules https://github.com/uwrobotics/MarsRover2020-firmware.git
   cd MarsRover2020-firmware
   

   Note: The repository has a submodule. To update the submodule, use git submodule update

3. Install mbed-tools and other python requirements:

   pip3 install -r scripts/requirements.txt
   

4. Verify the the toolchains were installed correctly

   Open a new Command Prompt / Terminal window and run the following commands:

   make --version                    # Should be v3.8.x or newer
   mbed-tools --version              # Should be v7.3.3 or newer
   cmake --version                   # Should be v3.20.0 or newer
   ninja --version                   # Should be v1.10.0 or newer
   arm-none-eabi-gcc --version       # Should be v10.2.1 or newer
   

5. Run make with the target application and board

   Ex. Compile the science application for the science board:

   make APP=science_2021 TARGET=SCIENCE_REV2_2021 OR make app=science_2021 target=SCIENCE_REV2_2021

   Ex. Compile the arm application for the arm board:
   make APP=arm_2021 TARGET=ARM_REV2_2021 OR make app=arm_2021 target=ARM_REV2_2021

   Note: The APP and TARGET variables can be defined in any order.

   After compiling an application you should see a message similar to the following:

   [100%] Linking CXX executable arm.arm-board.elf
   Generating bin from elf
   make[4]: Leaving directory '/home/wmmc88/MarsRover2020-firmware/build-arm-board'
   [100%] Built target arm.arm-board.elf
   make[3]: Leaving directory '/home/wmmc88/MarsRover2020-firmware/build-arm-board'
   make[2]: Leaving directory '/home/wmmc88/MarsRover2020-firmware/build-arm-board'
   make[1]: Leaving directory '/home/wmmc88/MarsRover2020-firmware/build-arm-board'
   

   Note: Ninja automatically optimizes the build process to most efficiently use all your system's resources to significantly speed up compile time. In some cases, this may slow down other processes during the compilation. You can choose to use fewer threads during build with the following command:

   CMAKE_BUILD_PARALLEL_LEVEL=<max number of threads> make APP=<app-name> TARGET=<target-name>
   

   You can add the CMAKE_BUILD_PARALLEL_LEVEL to your .bashrc to have this max thread limit be persistent.

   echo "export CMAKE_BUILD_PARALLEL_LEVEL=<max number of threads>" >> ~/.bashrc
   

   Tip: You can choose to build all the supported app/target configs at once using make all

6. Deploy onto board (see below for how to connect to a rover control board)

   Note: The following instructions only apply to Nucleo and Rev 1 boards. For Rev 2 boards and beyond, see Using the ST-Link to Program Rover Boards (Rev 2 +)

   Find the application .bin file, located in the build-<TARGET>-board/apps/<APP> directory.

   For Ubuntu

   • Install libusb sudo apt install libusb-1.0-0-dev
   • Drag and Drop .bin file into NODE_F446RC device folder

   For Windows

   • Drag and Drop .bin file into NODE_F446RC device folder OR if this does not work or debugging is required:
   • Download st-link utility. Scroll down to Get Software
   • Connect USB to nucleo board and open st-link utility
   • Load code by going to Target->Program and browse for .bin file

   For Mac

   • Drag and Drop .bin file into NODE_F446RC disk

   After deploying, the Nucleo will begin to flash red and green. Once the LED stays green, power-cycle the board by unplugging and replugging the 5V connector on the Nucleo.

• To clean the project workspace of app and library build files, run make clean
• To clean compiled MBED SDK files, run make clean-mbed

Using the ST-Link to Program Rover Boards (Rev 2 +)

Rev 2 PCBs come with ARM 10-pin SWD headers and can be programmed via ST-Link. A 20-pin to 10-pin adapter is needed to hook the ST-Link 20-pin header to the rover board 10-pin header.

ST-Link Software Installation

Ubuntu 20.04

1. sudo apt install stlink-tools

• Tested on 1.6.0

2. sudo apt install stlink-gui

• Tested on 1.6.0

3. sudo apt install openocd

• Tested on 0.10.0

Windows

1. Download st-link utility

Steps to Flashing a Rover Board

Important: Ensure your PCB is powered prior to connecting the st-link to your computer (this is an ST bug)

Ubuntu

Option 1: Use GUI

1. Launch the GUI with stlink-gui
2. Click connect
3. Click Open and select your .bin file
4. Click Flash (leave memory address as 0x8000000)

Option 2: Use CLI

1. Ensure that the st-link is connected with st-info --probe
2. Flash with st-flash write <path to .bin> 0x8000000

• If the flashing was successful, you should see the following message: Flash written and verified! jolly good!

Pro tips: To erase the loaded program from flash: st-flash erase To reset/rerun the program: st-flash reset

Windows

1. Connect the ST-Link to the rover board and to your computer
2. Open ST-Link Utility
3. Click "Connect to the target"
4. Click "Open file" and select the .bin file of the program to flash
5. Click "Program & verify:
6. Click "Start"

Using the Nucleo Dev Board to Program the Rover Boards