# linorobot/linorobot2 architecture

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

- Interactive diagram: https://gitdiagram.com/linorobot/linorobot2
- Repository: https://github.com/linorobot/linorobot2

## Overview

##### Project Type & Purpose
- This is a ROS2 robot software package aimed at both real robot operation and simulation in Gazebo. It supports various robot bases (2WD, 4WD, and Mecanum) and integrates sensor drivers, URDF generation (for robot description), and navigation functions (using Nav2 and SLAM Toolbox) to enable autonomous navigation.
- The package covers the full lifecycle – from booting the physical robot (via micro-ROS for microcontroller integration) to building the simulated robot environment, mapping, and performing autonomous navigation.

##### Analyzing the File Structure
- Key top-level directories (and their roles):
- docker: Contains Dockerfiles, environment configurations, and launch scripts to set up simulation environments or containerized development.
- linorobot2: Core package files that likely include the primary ROS2 nodes and interfaces for robot control.
- linorobot2_base: Houses configuration files (e.g., ekf.yaml) and parameters related to the robot’s base, such as sensor fusion configuration.
- linorobot2_bringup: Contains launch files and configuration scripts (e.g., bringup.launch.py) to start hardware drivers, microROS communications, and initial system setup.
- linorobot2_description: Provides URDF (and parameterized xacro) files to define the robot’s physical structure, along with RViz launch files for visualization.
- linorobot2_gazebo: Contains files to integrate with the Gazebo simulator (world files, sensor bridges, and simulation-specific launch files).
- linorobot2_navigation: Includes launch files, maps, and configuration for navigation, SLAM, and autonomous movement.
- Additionally, there are utility scripts (e.g., install_linorobot2.bash, update_microros.bash) and documentation which offer deployment and troubleshooting instructions.

##### Core Components
- Robot Computer (Physical/Embedded System):
- linorobot2, linorobot2_base, and linorobot2_bringup launch the hardware drivers, sensor integration (laser, depth sensors, IMU), and microROS connectivity for the physical robot.
- This subsystem covers nodes communicating with the microcontroller via serial/UDP/TCP, including IMU fusion (e.g., the madgwick filter when enabled).

- Robot Description & Visualization:
- linorobot2_description contains the robot’s URDF/xacro elements. This component is used to generate the visual model for simulation or RViz visualization.

- Simulation Environment:
- linorobot2_gazebo sets up the simulation world (Gazebo launch files, world files, scripts for map conversion) for testing parameters and behaviors in a virtual environment.

- Navigation & SLAM:
- linorobot2_navigation integrates SLAM Toolbox and Nav2 for mapping, localization, and autonomous navigation. This includes handling map saving, adjusting parameters for real vs. simulation (e.g., `sim` and `rviz` flags).

- Host / Development Machine:
- Optionally, the host machine runs additional visualization nodes (e.g., from linorobot2_viz) to remotely monitor the robot in RViz, allowing for configuration and debugging without affecting the robot computer.

- External Dependencies and Tools:
- ROS2 (versions foxy or galactic) is required as the middleware.
- External packages like teleop_twist_keyboard, depthimage_to_laserscan, and microROS agents interact with the system.
- Docker container setups (in the docker directory) provide isolated build/deployment environments.

##### Relationships & Data Flows
- A clear separation between the physical robot system (Robot Computer) and the simulation/host machine components.
- Data flows between sensor nodes (in bringup) sending data (IMU, lidar, camera/depth) to processing nodes (for sensor fusion, odometry).
- The microROS agent/network acting as the bridge between the robot’s microcontroller and ROS2 nodes.
- The URDF generator (linorobot2_description) interacting with RViz and Gazebo for visual representation.
- Navigation nodes (in linorobot2_navigation) taking in data from sensors and SLAM/odometry outputs, outputting control commands.
- Docker containers as an alternative deployment environment for simulation, showing how container orchestration (using docker-compose) might encapsulate the overall system.

##### Architectural Patterns & Design Principles
- The architecture follows common ROS2 modular principles, with each subsystem (hardware drivers, visualization, simulation, and navigation) implemented as separate packages that communicate via ROS topics, services, and parameters.
- There is a clear separation between configuration (parameters defined in YAML files), launch files (Python-based launch scripts), and runtime nodes.
- The use of parameterized URDFs and xacro files allows for flexibility (supporting 2WD/4WD/mecanum configurations) across both simulation and physical deployments.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Robot Computer Subgraph
    subgraph "Robot Computer"
        RC1["Robot Core (linorobot2)"]:::hardware
        RC2["Bringup & Sensor Drivers (linorobot2_bringup)"]:::hardware
        RC3["Base Config (linorobot2_base)"]:::hardware
    end

    %% Robot Description & Visualization Subgraph
    subgraph "Robot Description & Visualization"
        RD1["URDF/Xacro (linorobot2_description)"]:::description
        RD2["RViz Visualization (linorobot2_description)"]:::description
    end

    %% Simulation Environment (Gazebo) Subgraph
    subgraph "Simulation Environment (Gazebo)"
        SG1["Gazebo Launch (linorobot2_gazebo)"]:::simulation
        SG2["World & Simulation Scripts (linorobot2_gazebo)"]:::simulation
    end

    %% Navigation & SLAM Subgraph
    subgraph "Navigation & SLAM"
        NS1["Navigation Launch (linorobot2_navigation)"]:::navigation
        NS2["SLAM Launch (linorobot2_navigation)"]:::navigation
    end

    %% Deployment & Containerization Subgraph
    subgraph "Deployment & Containerization"
        DC1["Docker Deployment (docker)"]:::deploy
    end

    %% Connections within Robot Computer
    RC1 -->|"initializes"| RC2
    RC1 -->|"loads"| RC3

    %% Connections from Robot Computer to Robot Description & Visualization
    RC2 -->|"publish_data"| RD1

    %% Bidirectional interaction within Robot Description
    RD1 <-->|"visualize"| RD2

    %% Connections from Robot Description to Simulation Environment
    RD1 -->|"provide_description"| SG1

    %% Sensor data flow to Navigation & SLAM
    RC2 -->|"sensor_data"| NS1
    RC2 -->|"sensor_data"| NS2

    %% Control commands from Navigation to Robot Core
    NS1 -->|"control_cmds"| RC1
    NS2 -->|"control_cmds"| RC1

    %% Docker influences Deployment over Simulation and Bringup
    DC1 -->|"containerizes"| SG1
    DC1 -->|"containerizes"| RC2

    %% Styling Classes
    classDef hardware fill:#FFCCCC,stroke:#B22222,stroke-width:2px;
    classDef description fill:#CCFFCC,stroke:#228B22,stroke-width:2px;
    classDef simulation fill:#CCCCFF,stroke:#00008B,stroke-width:2px;
    classDef navigation fill:#FFFFCC,stroke:#B8860B,stroke-width:2px;
    classDef deploy fill:#E6E6FA,stroke:#4B0082,stroke-width:2px;

    %% Click Events for Component Mapping
    click RC1 "https://github.com/linorobot/linorobot2/blob/humble/linorobot2/package.xml"
    click RC2 "https://github.com/linorobot/linorobot2/blob/humble/linorobot2_bringup/launch/bringup.launch.py"
    click RC3 "https://github.com/linorobot/linorobot2/blob/humble/linorobot2_base/config/ekf.yaml"
    click RD1 "https://github.com/linorobot/linorobot2/tree/humble/linorobot2_description/urdf"
    click RD2 "https://github.com/linorobot/linorobot2/blob/humble/linorobot2_description/rviz/description.rviz"
    click SG1 "https://github.com/linorobot/linorobot2/blob/humble/linorobot2_gazebo/launch/gazebo.launch.py"
    click NS1 "https://github.com/linorobot/linorobot2/blob/humble/linorobot2_navigation/launch/navigation.launch.py"
    click NS2 "https://github.com/linorobot/linorobot2/blob/humble/linorobot2_navigation/launch/slam.launch.py"
    click DC1 "https://github.com/linorobot/linorobot2/tree/humble/docker/Dockerfile"
```
