NTF Classic Micromouse project with a STM32 microcontroller

📑 Summary

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

📁 Folder structure

• .github/ - GitHub Actions workflow files.
• .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.
• docker/ - Docker build and format scripts for CI/CD.
• 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.
• micras_nav - Mapping, planning and control algorithms to navigate inside a maze.

🔨 Building

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

sudo apt install cmake make gcc-arm-none-eabi

And initialize the libraries submodules:

git submodule update --init --recursive

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

It also possible to build all tests at once, using the command:

make test_all -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

And then generate the launch files for debugging with the command:

make 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

🐋 Docker

Docker can be used to build the project inside a container, which makes it possible to implement CI/CD pipelines and develop in any environment, for this, it is necessary to have Docker installed on your system.

🐳 Building

The project can be built without entering a container by running the following command:

docker compose run build

This also works for formatting (docker compose run format) and linting (docker compose run lint).

🧑‍💻 Development

To enter a container and mount the project folder, run the following command:

docker compose run dev

From inside the container, most of the previous sections can be executed, such as building and code style.

If Visual Studio Code is being used, it is possible to use the Dev Containers extension to develop inside the container with the other recommended extensions.

📝 Documentation

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

sudo apt install doxygen texlive-latex-extra texlive-fonts-extra

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 GitHub Flow.

✨ Contributors

Thanks goes to these wonderful people (emoji key):

Gabriel Cosme Barbosa 💻 📖 🔬 👀

Pedro de Santi 💻 📖 🔬 👀

Matheus Rezende Pereira 💻 📖 🔬 👀

Eduardo Barreto 💻 📖 🔬 👀

Claudio Dardengo 💻 📖 🔬 👀

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