NTF Classic Micromouse project with an STM32 microcontroller

📑 Summary

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

📁 Folder structure

• .docker/ - Docker build and format scripts for CI/CD.
• .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.
• 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

Then, initialize the library submodules:

git submodule update --init --recursive

The STM32CubeMX program is also required. After the installation is completed, it is necessary to set the CUBE_CMD environment variable to the path of the STM32CubeMX executable or add it to the PATH.

Start the build process by creating a build folder inside the project root:

mkdir build && cd build

And then generating the build commands:

cmake ..

The project can then be compiled by running:

make -j

You can list all available make commands by running:

make helpme

🚀 Running

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

make flash -j

If the project has not been compiled yet, this command will also automatically compile the 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 is 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 debug the project, you need to run the cmake command with BUILD_TYPE set to Debug or RelWithDebInfo, for example:

cmake .. -DBUILD_TYPE=Debug

If you are using Visual Studio Code, install the Cortex Debug extension. 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]

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, you need to install the respective GDB server.

If using J-Link, flash the firmware 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 by running the following command in the build folder:

make lint

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

make lint_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 graphviz 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.

🛠️ Windows Development Environment

If you are developing on a Windows machine using Windows Subsystem for Linux (WSL), we recommend installing the following tools on Windows and add them to the WSL PATH:

• STM32CubeMX
• STM32CubeProgrammer
• J-Link
• OpenOCD
• ST-Util

Our recommended workflow for Windows users is to use WSL for building the project while running STM32CubeMX, flashing tools, and GDB servers directly in the Windows environment. This setup provides a smoother development experience and avoids the need to passthrough the USB connections to WSL, allowing you to use the native Windows tools for flashing and debugging the project inside WSL.

However, if you prefer to keep everything inside WSL, you can manually define the environment variables JLINK_CMD and PROGRAMMER_CMD to point to the respective executables. If you need to passthrough USB devices to WSL, refer to the official WSL USB documentation for setup instructions.

Note

To debug while using WSL, it is recommended to enable Mirrored mode networking, so that you can directly access the ports created by the GDB server from inside the WSL.

👥 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!