# my-rice/autonomous-navigation-turtlebot4 architecture

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

- Interactive diagram: https://gitdiagram.com/my-rice/autonomous-navigation-turtlebot4
- Repository: https://github.com/my-rice/autonomous-navigation-turtlebot4

## Overview

##### Project type and purpose
- This is a ROS2-based robotics application (“Mobile Robots for Critical Missions”) comprising several ROS2 packages:
- config_pkg – holds all maps, parameters, and configuration files
- diem_gazebo – launches the Gazebo/Ignition simulator with the TurtleBot4 model and the diem_map world
- discovery_interface – defines the custom ROS Action (DiscoveryAction) used by the discovery node
- discovery_pkg – implements the QR‐code reading node (uses QReader, pyzbar, PyTorch, etc.)
- finetuning_pkg – a helper node that publishes test circles/waypoints for tuning
- planner_pkg – brings up the navigation (Nav2) stack, localization, RViz, and implements the high‐level planner

##### High‐level architecture and components
a. Simulation Environment
- Gazebo/Ignition (ignition.launch.py, spawn launch files) with the TurtleBot4 model
- World description (diem_map.sdf, meshes, model.config)
b. ROS2 Middleware Layer
- ROS2 master (DDS) – the communication bus
- Topics:
- /scan, /camera/image – sensor data from simulation or real robot
- /tf – transforms
- /cmd_vel – velocity commands to the robot
- Actions: DiscoveryAction (defined in discovery_interface)
c. Core ROS2 Nodes
- Server & AMCL (launched via startup_launch.py in planner_pkg)
- Nav2 Planner & Controller (from planner_pkg)
- RViz2 (visualization)
- discovery_pkg node – subscribes to camera, processes frames with QReader, sends goal or result via DiscoveryAction
- finetuning_pkg node – publishes circle waypoints for testing
- planner_pkg’s planner node – consumes goals (from discovery or finetuning), sends Nav2 goals
d. Configuration & Resources
- config_pkg – YAML parameter files (nav2_params.yaml), diem_map files (.pgm + .yaml), packaged via setup.py
- planner_pkg includes rviz config
- discovery_pkg & finetuning_pkg each have their own config.yaml

##### Relationships & Data Flow
- Simulation → sensor topics (/scan, /camera/image) → nodes
- discovery_pkg → after detection → calls DiscoveryAction server → planner_pkg’s planner node
- finetuning_pkg → publishes test waypoints on a dedicated topic → planner_pkg
- planner_pkg → via Nav2 action interface → Nav2 Server → robot motion → Gazebo cmd_vel
- config_pkg & package.xml → loaded at node start‐up to configure Nav2, map server, and RViz

##### Architectural patterns / design principles
- Component‐based modularity: each ROS package is a self‐contained component
- Publish/Subscribe and Action patterns (ROS2 DDS) for loose coupling
- Separation of concerns: simulation (diem_gazebo), configuration (config_pkg), interface definition (discovery_interface), functionality (discovery_pkg, finetuning_pkg, planner_pkg)

##### Final checklist for the engineer
[ ] Show simulation ↔ ROS middleware ↔ application node interactions
[ ] Highlight config_pkg as the central source of parameters/maps
[ ] Show discovery_interface defining the Action contract
[ ] Illustrate Nav2 stack within planner_pkg
[ ] Annotate external libraries and tools beneath the respective components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Simulation Layer
    subgraph "Simulation Layer"
        direction TB
        Gazebo["Ignition Gazebo"]:::simulation
        TurtleBot4["TurtleBot4 Model"]:::simulation
        World["diem_map World (SDF)"]:::simulation
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        direction TB
        DDS["ROS2 DDS (ROS2 Master)"]:::middleware
        Scan["/scan Topic"]:::middleware
        Camera["/camera/image Topic"]:::middleware
        TF["/tf Topic"]:::middleware
        CmdVel["/cmd_vel Topic"]:::middleware
        DiscoveryAction["DiscoveryAction (Action)"]:::middleware
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        config_pkg["config_pkg\n(YAML params, maps)"]:::config
        discovery_interface["discovery_interface\n(DiscoveryAction definition)"]:::interface
        discovery_pkg["discovery_pkg\n(QR reader node)"]:::node
        finetuning_pkg["finetuning_pkg\n(Test waypoint publisher)"]:::node
        planner_pkg["planner_pkg\n(Nav2, AMCL, RViz, planner)"]:::node
    end

    %% Simulation to Middleware
    Gazebo -->|publishes| Scan
    Gazebo -->|publishes| Camera
    TurtleBot4 -->|uses world| World
    World -->|loaded by| Gazebo

    %% Middleware Core
    Scan -->|subscribes| discovery_pkg
    Camera -->|subscribes| discovery_pkg
    Scan -->|subscribes| planner_pkg
    CmdVel -->|publishes| TurtleBot4
    planner_pkg -->|publishes| CmdVel
    DDS -->|manages topics| Scan
    DDS -->|manages topics| Camera
    DDS -->|manages topics| TF
    DDS -->|manages topics| CmdVel
    DDS -->|manages actions| DiscoveryAction

    %% Actions and Topics
    discovery_pkg -.->|sends goal| DiscoveryAction
    DiscoveryAction -.->|received by| planner_pkg
    finetuning_pkg -->|publishes waypoints| planner_pkg

    %% Config Dependencies
    config_pkg -->|provides nav2_params| planner_pkg
    config_pkg -->|provides map| planner_pkg
    config_pkg -->|provides params| discovery_pkg
    config_pkg -->|provides params| finetuning_pkg

    discovery_interface -->|defines action| DiscoveryAction

    planner_pkg -->|uses Nav2| DDS

    %% Click Events
    click config_pkg "https://github.com/my-rice/autonomous-navigation-turtlebot4/tree/main/src/config_pkg"
    click discovery_interface "https://github.com/my-rice/autonomous-navigation-turtlebot4/tree/main/src/discovery_interface"
    click discovery_pkg "https://github.com/my-rice/autonomous-navigation-turtlebot4/tree/main/src/discovery_pkg"
    click finetuning_pkg "https://github.com/my-rice/autonomous-navigation-turtlebot4/tree/main/src/finetuning_pkg"
    click planner_pkg "https://github.com/my-rice/autonomous-navigation-turtlebot4/tree/main/src/planner_pkg"
    click Gazebo "https://github.com/my-rice/autonomous-navigation-turtlebot4/tree/main/src/diem_gazebo"

    %% Styles
    classDef simulation fill:#D0E8F2,stroke:#3B8EA5,color:#000
    classDef middleware fill:#F3F3F3,stroke:#888,color:#000
    classDef config fill:#DFF2D8,stroke:#4A8F29,color:#000
    classDef interface fill:#FFF3CD,stroke:#C19A00,color:#000
    classDef node fill:#FFE5B4,stroke:#D47A00,color:#000
```
