Embedded system development @ Illini RoboMaster
You can follow the instructions below to setup the necessary environments for building the source code and flashing the embedded chips.
-
Go to the official download page for ARM Toolchain.
-
Download the pre-built toolchain according to your operating system.
-
Decompress it to some directory and find an absolute path to the
bin
directory.In my case:
/Users/alvin/gcc-arm-none-eabi-10.3-2021.10/bin
. -
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
-
Go to your project root directory in a terminal.
-
Run the following command to build the entire project.
mkdir build && cd build cmake -DCMAKE_BUILD_TYPE=Release .. make -j
Change build type to
Debug
orRelWithDebInfo
in order to debug withgdb
. Note thatDebug
build could be much slower than the other two due to lack of compiler optimizations.
-
Install stlink.
- For Mac users,
brew install stlink
could be a shortcut. - For Ubuntu users,
sudo apt install stlink-tools
could be a shortcut. - For Arch users,
sudo pacman -S stlink
could be a shortcut. - For Linux users, either use prebuilt binaries, or build from source following their compile manual.
- For Mac users,
-
Flash one of the example programs by running
make flash-<xxx>
in thebuild/
directory created at compilation.e.g.
make flash-example_buzzer
-> and you shall hear some music (or noise)
You will need Doxygen.
- For Mac users,
brew install doxygen
could be a shortcut. - For Ubuntu users,
sudo apt install doxygen
could be a shortcut. - For Arch users,
sudo pacman -S doxygen
could be a shortcut. - 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 thebuild/
directory
To view the generated document:
- Run
firefox docs/html/index.html
Use the following guide when making contributions to this repo.
The continuous integration system will check the source code against Google C++ Style Guide. 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
(version 10 recommended)
- Linux users can simply install it using
sudo apt install clang-format-10
. - Mac users need to download prebuilt binaries from here. For now, we CANNOT use version 11 or above.
With clang-format
installed, you can run the following commands inside build/
to automatically format your changes.
make check-format
: Checkdiff
between current source and formatted source (without modifying any source file)make format
: Format all source files (Modifies file in place)
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.
-
st-util
This tool comes with stlink, but be aware that this is a third-party implementation and is not stable. The most recent release tested to be working is
v1.5.1
(Notice:st-util
have poor performance, it could malfunction most of the time, so it is not recommended). -
OpenOCD
This tool is much more stable but is slightly less intelligent in detecting ST-LINK version and it has not been updated since 2017. To install it,
brew install openocd
for Mac userssudo apt install openocd
for Ubuntu userssudo pacman -S openocd
for Arch users
Follow the steps below to debug an executable
- Launch a
gdb
server by either choicest-util
openocd -f <project root>/debug/OpenOCD/st-link-v2-1.cfg
- In a separate terminal,
cd
into thebuild
directory and runmake debug-xxx
(e.g.make debug-example_buzzer
). This will open up agdb
session. - Run
target extended-remote :<port>
(ortar ext :<port>
in short ) to connect to thegdb
server.- For
st-util
, replace<port>
with4242
. - For
openocd
, replace<port>
with3333
.
- For
- Run
load
to flash the executable (Note that you can also runmake
here without exitinggdb
to re-build the executable if you modified some source code). - Debug just like any regular
gdb
debugger: use commands likecontinue
,run
,break
,watch
,next
,step
the same way you will expect.
-
Generate a new ssh key if you don't have any (Follow the instruction of "Generating a new SSH key" from this link).
-
Add your new SSH key to your Github account.
-
(You only need to complete this step if you cloned our repository using https instead of ssh). Go to your local repository directory, open
.git/config
and changeurl=https://github.com/illini-robomaster/iRM_Embedded_2023.git
tourl=git@github.com:illini-robomaster/iRM_Embedded_2023.git
. -
Make sure you have created a personal access token.
-
Create a new branch from main and make all of your changes in that branch. After pushing it to the remote repository, create a pull request and assign at least one reviewer. After one reviewer approves your changes, your code can be merged to main. Learn more about pull requests here.