# utra-robosoccer/soccerbot architecture

> Architecture diagram of the GitHub repository utra-robosoccer/soccerbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/utra-robosoccer/soccerbot
- Repository: https://github.com/utra-robosoccer/soccerbot

## Overview

##### Project type and purpose
- This is a full-stack robotics application built on ROS2.
- Purpose: from low-level firmware on an STM32 microcontroller, through sensor/actuator interface, perception, strategy, and control, all the way to simulation (Webots/Gazebo) and real-robot execution.

##### Main architectural components
a. Hardware layer
- STM32 microcontroller running the soccer_firmware
- Motors, IMU, encoders, USB device layer
b. Firmware interface
- soccer_firmware_interface ROS2 node (publishes raw sensors, subscribes motor commands)
c. Common libraries
- soccer_common (config, transformations, PID, helpers)
- soccer_msgs (custom ROS messages)
d. Game Controller Interface
- game_controller_interface nodes (gc_client, gamestate)
- Publishes /game_state, /robot_state topics
e. Perception layer
- soccer_object_detection (YOLO‐based detection, camera drivers)
- soccer_object_localization (field/object position estimation)
- soccer_localization (field line UKF)
f. Strategy layer
- soccer_strategy (behavior state machine, team communication, autopilot_context_ros)
- Subscribes perception & game_state, publishes high-level trajectory commands
g. Trajectory & Control layer
- soccer_trajectories (predefined CSV trajectories, managers, ROS interface)
- soccer_pycontrol (inverse kinematics, model, walk_engine, pybullet simulation)
- Publishes low-level joint commands
h. Simulation & Visualization
- soccer_description + soccer_webots (URDF, meshes, Webots bridge)
- Launchable Webots / Gazebo environments
- Rviz, Foxglove bridge
i. Orchestration & Tools
- launch files in soccerbot/launch/modules (sensors, control, strategy, gui, localization, webots)
- Docker Compose (compose.yaml + tools/docker/*)
- CI workflows, pre-commit, readthedocs

##### Interactions and data flows
- Hardware → firmware → soccer_firmware_interface → ROS topics
- Game controller → game_controller_interface → /game_state
- Camera → soccer_object_detection → /detections → soccer_object_localization → /objects, field lines → soccer_localization → /pose
- /pose & /game_state + team messages → soccer_strategy → /trajectory_command
- /trajectory_command + /common/config → soccer_trajectories → joint trajectories → soccer_pycontrol → low-level joint commands → soccer_firmware_interface
- Simulation components subscribe/publish same topics—replace physical hardware & firmware interface

##### Architectural patterns & principles
- Layered ROS-package decomposition
- Pub/Sub (topic) communication, clearly separate concerns
- Reusable libraries (soccer_common, soccer_msgs)
- Simulation parity: real hardware ↔ Webots/Gazebo swap
- Dockerized microservices approach

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        STM32["STM32 MCU"]:::hardware
    end

    %% Firmware Interface Layer
    subgraph "Firmware Interface Layer"
        FW_IF["soccer_firmware_interface"]:::interface
    end

    %% Common Libraries
    subgraph "Common Libraries"
        COMMON_LIB[(soccer_common)]:::common
        MSG_LIB[(soccer_msgs)]:::common
    end

    %% Game Controller Interface
    subgraph "Game Controller Interface"
        GC_CLIENT["gc_client"]:::game
        GC_STATE["gamestate"]:::game
    end

    %% Perception Layer
    subgraph "Perception Layer"
        OBJ_DET["soccer_object_detection"]:::perception
        OBJ_LOC["soccer_object_localization"]:::perception
        UKF_LOC["soccer_localization"]:::perception
    end

    %% Strategy Layer
    subgraph "Strategy Layer"
        STRAT["soccer_strategy"]:::strategy
    end

    %% Control Layer
    subgraph "Control Layer"
        TRAJ["soccer_trajectories"]:::control
        PYCTRL["soccer_pycontrol"]:::control
    end

    %% Simulation Overlay
    subgraph "Simulation Overlay" style dashed
        DESC["soccer_description"]:::simulation
        WEBOTS["soccer_webots"]:::simulation
    end

    %% Orchestration & Tools
    subgraph "Orchestration & Tools"
        LAUNCH["Launch Modules"]:::orchestration
        DOCKER_COMPOSE["Docker Compose"]:::orchestration
        DOCKER_TOOLS["Docker Tools"]:::orchestration
    end

    %% Connections - Hardware to Interface
    STM32 -->|"USB/CDC"| FW_IF

    %% Firmware Interface to ROS topics
    FW_IF -->|"/cmd_vel, /joint_cmds"| STRAT
    FW_IF -->|"/sensor_data"| OBJ_DET

    %% Game Controller flow
    GC_CLIENT -->|"/game_state"| GC_STATE
    GC_STATE -->|"/game_state"| STRAT

    %% Perception flows
    OBJ_DET -->|"/detections"| OBJ_LOC
    OBJ_LOC -->|"/objects"| UKF_LOC
    UKF_LOC -->|"/pose"| STRAT

    %% Strategy to Control
    STRAT -->|"/trajectory_command"| TRAJ
    TRAJ -->|"/joint_points"| PYCTRL
    PYCTRL -->|"/joint_commands"| FW_IF

    %% Common libraries usage
    COMMON_LIB --> TRAJ
    COMMON_LIB --> PYCTRL
    COMMON_LIB --> STRAT
    MSG_LIB --> OBJ_DET
    MSG_LIB --> OBJ_LOC
    MSG_LIB --> UKF_LOC
    MSG_LIB --> STRAT
    MSG_LIB --> TRAJ
    MSG_LIB --> PYCTRL
    MSG_LIB --> GC_CLIENT
    MSG_LIB --> GC_STATE

    %% Simulation connections (swap hardware & interface)
    WEBOTS -->|"/sensor_data"| OBJ_DET
    WEBOTS -->|"/joint_commands"| PYCTRL
    DESC --> WEBOTS

    %% Orchestration links
    LAUNCH --> FW_IF
    LAUNCH --> OBJ_DET
    LAUNCH --> OBJ_LOC
    LAUNCH --> UKF_LOC
    LAUNCH --> STRAT
    LAUNCH --> TRAJ
    LAUNCH --> PYCTRL
    LAUNCH --> WEBOTS
    DOCKER_COMPOSE --> FW_IF
    DOCKER_COMPOSE --> OBJ_DET
    DOCKER_COMPOSE --> STRAT
    DOCKER_COMPOSE --> PYCTRL
    DOCKER_COMPOSE --> WEBOTS
    DOCKER_TOOLS --> DOCKER_COMPOSE

    %% Click Events
    click STM32 "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_hardware/soccer_firmware"
    click FW_IF "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_hardware/soccer_firmware_interface"
    click COMMON_LIB "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_common"
    click MSG_LIB "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_msgs"
    click GC_CLIENT "https://github.com/utra-robosoccer/soccerbot/tree/master/game_controller_interface"
    click GC_STATE "https://github.com/utra-robosoccer/soccerbot/tree/master/game_controller_interface"
    click OBJ_DET "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_perception/soccer_object_detection"
    click OBJ_LOC "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_perception/soccer_object_localization"
    click UKF_LOC "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_perception/soccer_localization"
    click STRAT "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_strategy"
    click TRAJ "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_control/soccer_trajectories"
    click PYCTRL "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_control/soccer_pycontrol"
    click DESC "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_description"
    click WEBOTS "https://github.com/utra-robosoccer/soccerbot/tree/master/soccer_webots"
    click LAUNCH "https://github.com/utra-robosoccer/soccerbot/tree/master/soccerbot/launch/modules"
    click DOCKER_COMPOSE "https://github.com/utra-robosoccer/soccerbot/blob/master/compose.yaml"
    click DOCKER_TOOLS "https://github.com/utra-robosoccer/soccerbot/tree/master/tools/docker"

    %% Styles
    classDef hardware fill:#FFC0CB,stroke:#333,stroke-width:1px
    classDef interface fill:#98FB98,stroke:#333,stroke-width:1px
    classDef common fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef game fill:#FFD700,stroke:#333,stroke-width:1px
    classDef perception fill:#FFA500,stroke:#333,stroke-width:1px
    classDef strategy fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef control fill:#90EE90,stroke:#333,stroke-width:1px
    classDef simulation fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef orchestration fill:#E6E6FA,stroke:#333,stroke-width:1px
```
