NTF Classic Micromouse simulation environment

📑 Summary

• 📑 Summary
• 📁 Folder structure
• 🔨 Building
• 🚀 Running
• 🧪 Testing
• 🐛 Debugging
• 🐋 Docker
• ✉️ Messages
  • ➡️ Topics subscribed
  • ⬅️ Topics published
• 💄 Code style
  • 🎨 Format
  • 🚨 Linter
• 👥 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
• docker/ - Dockerfiles and scripts to build and run the project
• gazebo/ - Gazebo world, models and plugin files
• include/ - Header files for class definitions
• launch/ - ROS 2 launch files
• MicrasFirmware/ - Micras firmware source code
• src/ - Source file for HAL and Proxy mocks
• tests/ - Executable test files mocks

🔨 Building

To build the project, you need to run the following command in the current colcon workspace root:

colcon build

🚀 Running

Before running the project, it is necessary to source the workspace:

source colcon_workspace/install/setup.bash

To run the project, use the following command:

ros2 launch micras_simulation micras.launch.xml

🧪 Testing

To run the tests, it is necessary to compile the project with the COMPILE_TESTS flag set to ON:

colcon build --cmake-args -DCOMPILE_TESTS=ON

After compiling the project, run the following command to execute the tests, replacing [test_name] with the desired test name without the file extension at the end:

ros2 launch micras_simulation micras.launch.xml name:=[test_name]

The test name must be the same as the test file name, at the MicrasFirmware tests directory, without the file extension at the end.

🐛 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 colcon build command with the BUILD_TYPE set to Debug or RelWithDebInfo, for example:

colcon build --cmake-args -DBUILD_TYPE=Debug

Finally, for debugging the project, the ROS extension for Visual Studio Code must be installed. After installing the extension you can press Ctrl + Shift + D to open the debug panel and select between the available configurations:

• ROS: Attach - Attach the debugger to a running ROS 2 node
• ROS: Launch - Opens a dialog box to input the executable name (defaults to micras_node) to debug, and launches it with the debugger attached

🐋 Docker

To build the Docker image and run the simulation, use the following command:

docker compose run sim

For building the Docker image for running the tests, use the following command:

docker compose run test

After running the command above, a terminal will be opened, and you can run the tests using the following command:

ros2 launch micras_simulation micras.launch.xml name:=[test_name]

✉️ Messages

The current topic message flow is the following:

➡️ Topics subscribed

The Proxy mock subscribes to the following topics:

• Gazebo Simulation
  • /micras/battery - std_msgs/msg/Float32 - Battery voltage level
  • /micras/button - std_msgs/msg/Bool - Button state
  • /micras/dip_switch_0 - std_msgs/msg/Bool - Dip switch 0 state
  • /micras/dip_switch_1 - std_msgs/msg/Bool - Dip switch 1 state
  • /micras/dip_switch_2 - std_msgs/msg/Bool - Dip switch 2 state
  • /micras/dip_switch_3 - std_msgs/msg/Bool - Dip switch 3 state
  • /micras/distance_sensor_0 - sensor_msgs/msg/LaserScan - Distance sensor 0 data
  • /micras/distance_sensor_1 - sensor_msgs/msg/LaserScan - Distance sensor 1 data
  • /micras/distance_sensor_2 - sensor_msgs/msg/LaserScan - Distance sensor 2 data
  • /micras/distance_sensor_3 - sensor_msgs/msg/LaserScan - Distance sensor 3 data
  • /micras/imu - sensor_msgs/msg/Imu - IMU data
  • /micras/odometry - nav_msgs/msg/Odometry - Odometry data
  • /micras/rotary_sensor_left - sensor_msgs/msg/JointState - Left rotary sensor data
  • /micras/rotary_sensor_right - sensor_msgs/msg/JointState - Right rotary sensor data
  • /micras/torque_flw - geometry_msgs/msg/WrenchStamped - Front left wheel torque
  • /micras/torque_frw - geometry_msgs/msg/WrenchStamped - Front right wheel torque
  • /micras/torque_rlw - geometry_msgs/msg/WrenchStamped - Rear left wheel torque
  • /micras/torque_rrw - geometry_msgs/msg/WrenchStamped - Rear right wheel torque

⬅️ Topics published

The Proxy mock publishes to the following topics:

• Gazebo Simulation
  • /micras/rgb_0 - std_msgs/msg/ColorRGBA - RGB LED 0 color
  • /micras/rgb_1 - std_msgs/msg/ColorRGBA - RGB LED 1 color
  • /micras/led - std_msgs/msg/Bool - LED state
  • /micras/buzzer - std_msgs/msg/UInt32 - Buzzer frequency
  • /micras/fan - std_msgs/msg/Float32 - Fan speed
  • /micras/cmd_vel - geometry_msgs/msg/Twist - Robot velocity

💄 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:

./format.sh

🚨 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:

colcon build --cmake-args -DLINTER_MODE=ON

To disable the linter while compiling, do as follows:

colcon build --cmake-args -DLINTER_MODE=OFF

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

colcon build --cmake-args -DLINTER_MODE=FIX

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