README.md

UIC RoboMaster Embedded

Embedded system development @ BNU-HKBU UIC RoboMaster

User Guide

You can follow the instructions below to set up the necessary environments for building the source code and flashing the embedded chips.

Install ARM Toolchain (manual)

1. Go to the official download page for ARM Toolchain.

2. Download the pre-built toolchain according to your operating system.

3. Decompress it to some directory and find an absolute path to the bin directory.

   In my case: /Users/yry0008/gcc-arm-none-eabi-10.3-2021.10/bin.

4. For Windows users, add the following line (replace <path> with the actual binary path found in step 3) to PATH environment variable.

   For Linux / Mac users, add the following line (replace <path> with the actual binary path found in step 3) to ~/.bashrc for bash users or ~/.zshrc for zsh users.

   export PATH=<path>:$PATH

Install OpenOCD (manual)

1. Go to the official download page for OpenOCD.

2. Download the pre-built toolchain according to your operating system.

3. Decompress it to some directory and find an absolute path to the bin directory.

   In my case: /Users/yry0008/openocd-0.11.0-2021.10/bin.

4. For Windows users, add the following line (replace <path> with the actual binary path found in step 3) to PATH environment variable. For Linux / Mac users, add the following line (replace <path> with the actual binary path found in step 3) to ~/.bashrc for bash users or ~/.zshrc for zsh users.

   export PATH=<path>:$PATH

Install CMake

1. Go to the official download page for CMake.

If you are using Clion, this step is not required.

Install Ninja (Windows only)

1. Go to the official download page

Compile Project (CLion)

You can directly open the project in CLion and build it. You need to set the path of the embedded toolchain in the CLion settings.

In Windows, you should open `Settings`, `Build, Execution, Deployment`, `CMake`, then set the `Generator` to Ninja.

Compile Project (Manual)

1. Go to your project root directory in a terminal.

2. Run the following command to build the entire project.

   mkdir build && cd build
   cmake -DCMAKE_BUILD_TYPE=Release ..
   make -j

   In Windows, you should add the option to let cmake use ninja to build.

   cmake -DCMAKE_BUILD_TYPE=Release ... -G "Ninja"

   Using ninja to build.

   ninja -j

   Change build type to Debug or RelWithDebInfo in order to debug with gdb. Note that Debug build could be much slower than the other two due to lack of compiler optimizations.

Flash Binary to Chip (Clion)

Choose the target you want to flash and click the Run button.

The default configuration is for CMSIS-DAP debugger. If you are using ST-LINK, you need to change the configuration in the CLion settings.

Flash Binary to Chip (OpenOCD)

TODO

Document Usage

You will need Doxygen.

1. For Mac users, brew install doxygen could be a shortcut.
2. For Ubuntu users, sudo apt install doxygen could be a shortcut.
3. For Arch users, sudo pacman -S doxygen could be a shortcut.
4. For Linux users, either use prebuilt binaries, or build from source following their compile manual.

To generate documentations after compiling the project.

• Run make doc in the build/ directory
• In windows, you need to run ninja doc in the build/ directory

To view the generated document:

• Run firefox docs/html/index.html, or
• Open docs/html/index.html in your browser.

Developer Guide

Use the following guide when making contributions to this repo.

Edit the code

You can use any editor you like, but we recommend using CLion.

Format Code

The continuous integration system will check the source code against a specific coding style. If the code does not follow the style, the formatting check will fail and the code will not be merged. All codes are required to be formatted correctly before merging. There are several integrated build commands that can help you automatically format your changes.

Prerequisite: install clang-format

• Linux's users can simply install it using sudo apt install clang-format-10.
• Mac and Windows users need to download prebuilt binaries from here.

With clang-format installed, you can run the following commands inside build/ to automatically format your changes.

1. make check-format: Check diff between current source and formatted source (without modifying any source file)
2. make format: Format all source files (Modifies file in place)

Debug with gdb

To debug embedded systems on a host machine, we would need a remote gdb server. There are 2 choices for such server, with tradeoffs of their own.

• Clion Debugger

This is the easiest way to debug. Choose the target and Directly click the Debug button in CLion.

• OpenOCD

Thought directly using openocd is possible, but it is only recommended for advanced users.