NTF Classic Micromouse project with a STM32 microcontroller

📑 Summary

• 📑 Summary
• 📁 Folder structure
• 📦️ Packages
• 🔨 Building
• 🚀 Running
• 🧪 Testing
• 🐛 Debugging
• 💄 Code style
  • 🎨 Format
  • 🚨 Linter
• 📝 Documentation
• 👥 Contributing
  • 💬 Git commit messages
  • 🔀 Git workflow
• ✨ Contributors

📁 Folder structure

• .vscode - Visual Studio Code configuration files
• cmake/ - Functions to include in the main CMake
• config/ - Target and constants configuration values
• cube/ - STM32CubeMX configuration and build files
• include/ - Header files for class definitions
• src/ - Source file for class implementations and executables
• tests/ - Executable test files

📦️ Packages

• micras_hal - Wrapper to the STM32 HAL, implementing the needed functionalities in C++ classes.
• micras_proxy - Intermediate abstraction layer for the hardware components.

🔨 Building

To build the project, it is first necessary to install some dependencies:

sudo apt install cmake build-essential gcc-arm-none-eabi

The STM32CubeMX program is also needed. After the installation is completed, it is necessary to set the environment variable CUBE_PATH to the installation directory path of STM32CubeMX.

The building process can be started by creating a build folder with:

mkdir build && cd build

And then generating the build commands:

cmake ..

The project can then be compiled by running:

make -j

It is possible to get all possible make commands by running:

make helpme

🚀 Running

The binaries can be flashed into the microcontroller using the STM32CubeProgrammer, which needs to be installed. For flashing the main program, run the following command:

make flash -j

If the project hasn't already been compiled, this command also automatically compiles the desired target.

🧪 Testing

Any test can be compiled and run using the same commands as the ones used for the main executable, but adding the test name without the file extension at the end:

make [test_name] -j

make flash_[test_name] -j

🐛 Debugging

It is possible to debug the project using gdb. To do that, first install gdb-multiarch, on Ubuntu, just run:

sudo apt install gdb-multiarch

To be able to debug the project, it is necessary run the cmake command with the BUILD_TYPE set to Debug or RelWithDebInfo, for example:

cmake .. -DBUILD_TYPE=Debug

It is also possible to debug test executables, by first running the command:

make debug_[test_name]

Finally, to debug the project, the Cortex Debug extension for VSCode must be installed. There are three configurations for debugging present at the .vscode/launch.json file that uses different programs:

• J-Link
• OpenOCD (sudo apt install openocd)
• ST-Util (sudo apt install stlink-tools)

For each debug type, it is necessary to install the respective gdb server.

If using J-Link, the flashing process can be done by running the following command:

make jflash -j

or if you want to flash a test:

make jflash_[test_name] -j

💄 Code style

🎨 Format

The project uses clang-format to format files, there is a .clang-format with the formatting rules for the project. To install it, on Ubuntu, run the following command on the terminal:

sudo apt install clang-format

In order to format the project, run the following command in the build folder:

make format

🚨 Linter

The project uses a linter in order to follow the best code practices. The linter used is clang-tidy, there is a .clang-tidy with the linting rules for the project. To install it on Ubuntu, run the following command on the terminal:

sudo apt install clang-tidy

The linting process is done when compiling the project using a special config variable, the LINTER_MODE cmake variable. You can enable the linter by running:

cmake .. -DLINTER_MODE=ON

To disable the linter while compiling, do as follows:

cmake .. -DLINTER_MODE=OFF

It is also possible to lint the project and let the linter fix it using its suggestions:

cmake .. -DLINTER_MODE=FIX

📝 Documentation

The project is documented using Doxygen. In Ubuntu, it is possible to install it with the following command:

sudo apt install doxygen pdflatex

For other operating systems, you can see download options on the official Doxygen page.

To generate the pdf documentation at the docs/ folder, run the following command inside the build folder:

make docs

The configuration is in the file Doxyfile.

👥 Contributing

To learn how to contribute to the project, see the following contribution guidelines.

💬 Git commit messages

• Use the present tense ("Add feature" not "Added feature")

• Use the imperative mood ("Move cursor to..." not "Moves cursor to...")

• It is strongly recommended to start a commit message with a related emoji

  • 📝 :memo: for documentation
  • 🐛 :bug: for bug issues
  • 🚑 :ambulance: for critical fixes
  • 🎨 :art: for formatting code
  • ✨ :sparkles: for new features

  For more examples, see this reference.

🔀 Git workflow

The project workflow is based on Git Flow.

✨ Contributors

Thanks goes to these wonderful people (emoji key):

Gabriel Cosme Barbosa 💻 📖 🔬 👀

Pedro de Santi 💻 📖 🔬 👀

Matheus Rezende Pereira 💻 📖 🔬 👀

Eduardo Barreto 💻 👀

This project follows the all-contributors specification. Contributions of any kind welcome!