# varunvaidhiya/mecanum-wheel-robot architecture

> Architecture diagram of the GitHub repository varunvaidhiya/mecanum-wheel-robot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/varunvaidhiya/mecanum-wheel-robot
- Repository: https://github.com/varunvaidhiya/mecanum-wheel-robot

## Overview

##### Project type and purpose
- This is a robotics software/firmware project built on ROS2 (Jazzy) for an omnidirectional Mecanum-wheel robot.
- It comprises three main software packages (bringup, description, driver) running on a Raspberry Pi (Ubuntu + ROS2) and embedded firmware on an STM32F407VG Discovery board.
- Purpose: Provide a modular, layered robotics control stack—high-level ROS2 nodes for motion commands, URDF/model description for visualization, and real-time motor control on the microcontroller.

##### File structure
- Top-level directories:
- src/omnibot_bringup – launch files and RViz config
- src/omnibot_description – URDF/XACRO robot model
- src/omnibot_driver – C++ and Python ROS2 nodes for motor control and serial bridging
- src/omnibot_firmware – STM32 embedded C code (HAL drivers for GPIO, USART, TIM)
- build/ and install/ hold colcon build artifacts and install layouts.
- config and launch subdirectories group ROS2 parameters and launch definitions.
- CMakeLists.txt and package.xml in each package denote ROS2/CMake build integration.

##### README for additional insights
- Hardware architecture layered into Compute (Raspberry Pi 5 + ROS2), Control (STM32 + L298N drivers), Perception (future sensors).
- Workflow: colcon build → source install → ros2 launch → topics (/cmd_vel) → firmware flash via OpenOCD.

##### Main components & interactions
a. Components
- Compute Layer (Raspberry Pi 5)
- ROS2 Core
- omnibot_drive nodes
- omnibot_bringup launch manager
- omnibot_description URDF server (for RViz)
- Control Layer (STM32F407VG Discovery)
- Embedded firmware (motor control tasks)
- HAL: USART for serial comm, Timer for PWM, GPIO for direction
- L298N motor driver boards
- Communication
- Serial/UART link between ROS2 serial_bridge_node and STM32 firmware
- Peripherals (future)
- ROS2 sensors (LIDAR, cameras)
- AI/ML inference modules
b. Relationships and data flow
- ROS2 user publishes Twist messages → omnibot_driver/mecanum_controller_node → serial_bridge_node formats and sends over UART → STM32 firmware reads commands → PWM & GPIO drive L298N → motors turn wheels.
- omnibot_description supplies URDF to RViz via bringup launch → visualization of robot state.
- bringup launch script kicks off driver nodes, loads parameters (from config/*.yaml), and opens RViz for monitoring.
c. Architectural patterns and principles
- Layered architecture: separation of high-level planning (ROS2) and low-level control (firmware).
- Modular ROS2 packages: clear boundaries (bringup vs description vs driver).
- Publish/subscribe for decoupled inter-node communication.
d. Relevant technologies
- ROS2 (rclcpp, rclpy)
- colcon/CMake build system
- Python launch API for ROS2
- STM32Cube HAL, OpenOCD for flashing
- L298N motor drivers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Compute Layer
    subgraph "Compute Layer" 
        style ComputeLayer fill:#D0E8FF,stroke:#000
        ROS2Core["ROS2 Core"]:::compute
        subgraph omnibot_bringup
            RobotLaunch["robot.launch.py"]:::compute
            DisplayLaunch["display.launch.py"]:::compute
            RVizConfig["omnibot.rviz"]:::compute
            BringupCMake["CMakeLists.txt"]:::compute
            BringupPkg["package.xml"]:::compute
        end
        subgraph omnibot_description
            URDF["omnibot.urdf.xacro"]:::compute
            DescCMake["CMakeLists.txt"]:::compute
            DescPkg["package.xml"]:::compute
        end
        subgraph omnibot_driver
            MC_Cpp["mecanum_controller.cpp"]:::compute
            MC_Hpp["mecanum_controller.hpp"]:::compute
            MC_Py["mecanum_controller_node.py"]:::compute
            SB_Py["serial_bridge_node.py"]:::compute
            DriverLaunch["base_control.launch.py"]:::compute
            Params["mecanum_params.yaml"]:::compute
            DriverCMake["CMakeLists.txt"]:::compute
            DriverPkg["package.xml"]:::compute
        end
    end

    %% Control Layer
    subgraph "Control Layer"
        style ControlLayer fill:#D4F8D4,stroke:#000
        subgraph omnibot_firmware
            FW_Main["main.c"]:::control
            FW_GPIO["gpio.c"]:::control
            FW_TIM["tim.c"]:::control
            FW_USART["usart.c"]:::control
            FW_H["main.h"]:::control
            FW_Readme["README.md"]:::control
        end
    end

    %% Physical Actuators
    subgraph "Actuation Layer"
        style ActuationLayer fill:#FFE4B2,stroke:#000
        MotorDriver["L298N Motor Driver"]:::actuator
        Wheels["Mecanum Wheels"]:::actuator
    end

    %% Connections
    ROS2Core -->|launch| RobotLaunch
    RobotLaunch -->|starts| MC_Py
    RobotLaunch -->|starts| SB_Py
    RobotLaunch -->|loads| RVizConfig
    RVizConfig -->|visualizes URDF| URDF
    URDF -->|serves model| RVizConfig
    MC_Py -->|publishes /cmd_vel Twist| SB_Py
    SB_Py -->|"UART Serial"| FW_Main
    FW_Main -->|uses| FW_USART
    FW_Main -->|uses| FW_TIM
    FW_Main -->|uses| FW_GPIO
    FW_USART -->|drives| MotorDriver
    FW_TIM -->|PWM signals| MotorDriver
    FW_GPIO -->|direction signals| MotorDriver
    MotorDriver -->|turns| Wheels

    %% Click Events
    click RobotLaunch "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_bringup/launch/robot.launch.py"
    click DisplayLaunch "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_bringup/launch/display.launch.py"
    click RVizConfig "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_bringup/config/omnibot.rviz"
    click BringupCMake "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_bringup/CMakeLists.txt"
    click BringupPkg "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_bringup/package.xml"
    click URDF "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_description/urdf/omnibot.urdf.xacro"
    click DescCMake "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_description/CMakeLists.txt"
    click DescPkg "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_description/package.xml"
    click MC_Cpp "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_driver/src/mecanum_controller.cpp"
    click MC_Hpp "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_driver/include/omnibot_driver/mecanum_controller.hpp"
    click MC_Py "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_driver/scripts/mecanum_controller_node.py"
    click SB_Py "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_driver/scripts/serial_bridge_node.py"
    click DriverLaunch "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_driver/launch/base_control.launch.py"
    click Params "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_driver/config/mecanum_params.yaml"
    click DriverCMake "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_driver/CMakeLists.txt"
    click DriverPkg "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_driver/package.xml"
    click FW_Main "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_firmware/Core/Src/main.c"
    click FW_GPIO "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_firmware/Core/Src/gpio.c"
    click FW_TIM "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_firmware/Core/Src/tim.c"
    click FW_USART "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_firmware/Core/Src/usart.c"
    click FW_H "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_firmware/Core/Inc/main.h"
    click FW_Readme "https://github.com/varunvaidhiya/mecanum-wheel-robot/blob/main/src/omnibot_firmware/README.md"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#000;
    classDef control fill:#D4F8D4,stroke:#000;
    classDef actuator fill:#FFE4B2,stroke:#000;
```
