# joshnewans/articubot_one architecture

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

- Interactive diagram: https://gitdiagram.com/joshnewans/articubot_one
- Repository: https://github.com/joshnewans/articubot_one

## Overview

##### Project type and purpose
- This is a ROS2 robot package template that unifies:
- Robot description (URDF/XACRO)
- Sensor and actuator configurations (Gazebo, ROS2 Control)
- Parameter files for mapping, navigation, controllers, trackers
- Launch files for both simulation and real hardware
- Its goal is to let users clone and immediately run a robot in Gazebo, then deploy on real hardware, swapping configs.

##### File structure
- Top-level:
- CMakeLists.txt & package.xml – build / package metadata
- config/ – YAML parameter sets for robot controllers, navigation (Nav2), trackers, RViz, joystick
- description/ – XACRO macros and URDF fragments for robot body, sensors (camera, lidar), control plugins
- launch/ – Python-based ROS2 launch scripts (simulation vs. hardware, mapping, navigation, ball tracker, joystick)
- worlds/ – Gazebo world definitions (empty, obstacles)
- Patterns:
- Modular description: each sensor in its own XACRO
- Separate launch files for each major use case (sim vs real, perception vs navigation)
- Parameterization by YAML for easy swapping

##### Extract insights from the README
- It’s intended as a template—rename instances of “my_bot”
- Directories can be pruned once you adapt your own robot

##### Main components & their relationships
a. Components:
1. Robot Description Layer
– XACRO files → URDF model
2. Simulation / Hardware Layer
– Gazebo + world file + robot Gazebo plugins
– Real hardware interface via ros2_control
3. ROS2 Control Manager
– Reads config/my_controllers.yaml
– Spawns controllers for wheels, joints
4. Sensor Nodes & Drivers
– Depth camera node (camera.xacro + camera.launch.py)
– LIDAR node (rplidar.launch.py)
5. Perception & Tracking
– ball_tracker.launch.py (tracks ball pose)
6. Teleoperation
– joystick.launch.py → publishes Twist commands
7. Mapping & Localization
– mapper_params_online_async.yaml + online_async_launch.py
– localization_launch.py
8. Navigation (Nav2)
– navigation_launch.py + nav2_params.yaml
9. Visualization
– RViz config files in config/…rviz

b. Data flows & interactions
– The Gazebo plugin publishes sensor topics (/camera/image, /scan) into the ROS graph
– Sensor nodes publish into TF tree and topic streams
– Perception node (/ball_tracker) subscribes to image topics, publishes ball pose
– Mapping node subscribes to /scan, /odom → publishes map, pose
– Localization node fuses odom + map → /amcl_pose
– Navigation node subscribes to /amcl_pose + /goal → publishes /cmd_vel to ROS2 Control
– Teleop node can also publish /cmd_vel, gated by twist_mux
– Controllers subscribe to /cmd_vel, send actuator commands via ros2_control

c. Architectural patterns & principles
– Modular XACRO composition for reusability
– Clear environment separation: simulation vs hardware via launch files
– Parameter-driven design: all tuning resides in config/*.yaml
– ROS2 node-based microservices communicating over well-defined topics

d. Key technologies
– ROS2 Foxy (or later)
– Gazebo (physics, sensor plugins)
– ros2_control + controller_manager
– Nav2 (navigation stack)
– AMCL (localization), SLAM (online async)
– RViz2 for visualization
– Python-based launch system

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Description Layer"
    RU["robot.urdf.xacro"]:::hardware
    RC["robot_core.xacro"]:::hardware
    IM["inertial_macros.xacro"]:::hardware
    RCtrl["ros2_control.xacro"]:::hardware
    GCtrl["gazebo_control.xacro"]:::hardware
    CamX["camera.xacro"]:::hardware
    DCamX["depth_camera.xacro"]:::hardware
    LidarX["lidar.xacro"]:::hardware
    FaceX["face.xacro"]:::hardware
  end

  subgraph "Simulation / Hardware Layer"
    SimLaunch["launch_sim.launch.py"]:::hardware
    HardLaunch["launch_robot.launch.py"]:::hardware
    EmptyW["empty.world"]:::hardware
    ObsW["obstacles.world"]:::hardware
    SimCfg["gaz_ros2_ctl_use_sim.yaml"]:::config
  end

  subgraph "ROS2 Control Manager"
    CtrlMgr["controller_manager"]:::app
    MyCtrl["my_controllers.yaml"]:::config
    RspLaunch["rsp.launch.py"]:::hardware
  end

  subgraph "ROS2 Core (Middleware)"
    TF["TF Tree"]:::middleware
    Topics["ROS2 Topics"]:::middleware
  end

  subgraph "Application Nodes"
    subgraph "Sensors & Drivers"
      CamLaunch["camera.launch.py"]:::app
      LidarLaunch["rplidar.launch.py"]:::app
    end
    subgraph "Perception & Tracking"
      BallTrack["ball_tracker.launch.py"]:::app
      BTParamsSim["ball_tracker_params_sim.yaml"]:::config
      BTParamsReal["ball_tracker_params_robot.yaml"]:::config
    end
    subgraph "Teleoperation"
      JoyLaunch["joystick.launch.py"]:::app
      JoyCfg["joystick.yaml"]:::config
      TwistMux["twist_mux.yaml"]:::config
    end
    subgraph "Mapping & Localization"
      SLAMLaunch["online_async_launch.py"]:::app
      SLAMCfg["mapper_params_online_async.yaml"]:::config
      LocLaunch["localization_launch.py"]:::app
      EmptyCfg["empty.yaml"]:::config
    end
    subgraph "Navigation (Nav2)"
      NavLaunch["navigation_launch.py"]:::app
      NavCfg["nav2_params.yaml"]:::config
    end
    subgraph "Visualization"
      RViz1["drive_bot.rviz"]:::config
      RViz2["main.rviz"]:::config
      RViz3["map.rviz"]:::config
      RViz4["view_bot.rviz"]:::config
    end
  end

  %% Data Flows
  RU -->|generates URDF| SimLaunch
  RC -->|generates URDF| HardLaunch

  SimLaunch -->|spawns| Topics
  HardLaunch -->|spawns| Topics

  Topics --> CamLaunch
  Topics --> LidarLaunch
  CamLaunch -->|publishes /camera/image| Topics
  LidarLaunch -->|publishes /scan| Topics
  CamLaunch --> TF
  LidarLaunch --> TF

  Topics --> BallTrack
  BTParamsSim --> BallTrack
  BTParamsReal --> BallTrack
  BallTrack -->|publishes /ball_pose| Topics
  BallTrack --> TF

  Topics --> SLAMLaunch
  SLAMCfg --> SLAMLaunch
  SLAMLaunch -->|publishes /map| Topics

  Topics --> LocLaunch
  EmptyCfg --> LocLaunch
  LocLaunch -->|publishes /amcl_pose| Topics

  Topics --> NavLaunch
  NavCfg --> NavLaunch
  NavLaunch -->|publishes /cmd_vel| Topics

  Topics --> JoyLaunch
  JoyCfg --> JoyLaunch
  TwistMux --> JoyLaunch
  JoyLaunch -->|publishes /cmd_vel| Topics

  Topics --> CtrlMgr
  MyCtrl --> CtrlMgr
  RspLaunch --> CtrlMgr
  CtrlMgr -->|commands actuators| HardLaunch

  Topics --> RViz1
  Topics --> RViz2
  Topics --> RViz3
  Topics --> RViz4

  %% Click Events
  click RU "https://github.com/joshnewans/articubot_one/blob/main/description/robot.urdf.xacro"
  click RC "https://github.com/joshnewans/articubot_one/blob/main/description/robot_core.xacro"
  click IM "https://github.com/joshnewans/articubot_one/blob/main/description/inertial_macros.xacro"
  click RCtrl "https://github.com/joshnewans/articubot_one/blob/main/description/ros2_control.xacro"
  click GCtrl "https://github.com/joshnewans/articubot_one/blob/main/description/gazebo_control.xacro"
  click CamX "https://github.com/joshnewans/articubot_one/blob/main/description/camera.xacro"
  click DCamX "https://github.com/joshnewans/articubot_one/blob/main/description/depth_camera.xacro"
  click LidarX "https://github.com/joshnewans/articubot_one/blob/main/description/lidar.xacro"
  click FaceX "https://github.com/joshnewans/articubot_one/blob/main/description/face.xacro"
  click SimLaunch "https://github.com/joshnewans/articubot_one/blob/main/launch/launch_sim.launch.py"
  click HardLaunch "https://github.com/joshnewans/articubot_one/blob/main/launch/launch_robot.launch.py"
  click EmptyW "https://github.com/joshnewans/articubot_one/blob/main/worlds/empty.world"
  click ObsW "https://github.com/joshnewans/articubot_one/blob/main/worlds/obstacles.world"
  click SimCfg "https://github.com/joshnewans/articubot_one/blob/main/config/gaz_ros2_ctl_use_sim.yaml"
  click MyCtrl "https://github.com/joshnewans/articubot_one/blob/main/config/my_controllers.yaml"
  click RspLaunch "https://github.com/joshnewans/articubot_one/blob/main/launch/rsp.launch.py"
  click CamLaunch "https://github.com/joshnewans/articubot_one/blob/main/launch/camera.launch.py"
  click LidarLaunch "https://github.com/joshnewans/articubot_one/blob/main/launch/rplidar.launch.py"
  click BallTrack "https://github.com/joshnewans/articubot_one/blob/main/launch/ball_tracker.launch.py"
  click BTParamsSim "https://github.com/joshnewans/articubot_one/blob/main/config/ball_tracker_params_sim.yaml"
  click BTParamsReal "https://github.com/joshnewans/articubot_one/blob/main/config/ball_tracker_params_robot.yaml"
  click JoyLaunch "https://github.com/joshnewans/articubot_one/blob/main/launch/joystick.launch.py"
  click JoyCfg "https://github.com/joshnewans/articubot_one/blob/main/config/joystick.yaml"
  click TwistMux "https://github.com/joshnewans/articubot_one/blob/main/config/twist_mux.yaml"
  click SLAMLaunch "https://github.com/joshnewans/articubot_one/blob/main/launch/online_async_launch.py"
  click SLAMCfg "https://github.com/joshnewans/articubot_one/blob/main/config/mapper_params_online_async.yaml"
  click LocLaunch "https://github.com/joshnewans/articubot_one/blob/main/launch/localization_launch.py"
  click EmptyCfg "https://github.com/joshnewans/articubot_one/blob/main/config/empty.yaml"
  click NavLaunch "https://github.com/joshnewans/articubot_one/blob/main/launch/navigation_launch.py"
  click NavCfg "https://github.com/joshnewans/articubot_one/blob/main/config/nav2_params.yaml"
  click RViz1 "https://github.com/joshnewans/articubot_one/blob/main/config/drive_bot.rviz"
  click RViz2 "https://github.com/joshnewans/articubot_one/blob/main/config/main.rviz"
  click RViz3 "https://github.com/joshnewans/articubot_one/blob/main/config/map.rviz"
  click RViz4 "https://github.com/joshnewans/articubot_one/blob/main/config/view_bot.rviz"

  %% Styles
  classDef hardware fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
  classDef middleware fill:#c8e6c9,stroke:#43a047,color:#1b5e20
  classDef app fill:#ffcc80,stroke:#fb8c00,color:#e65100
  classDef config fill:#ffe0b2,stroke:#ffa000,color:#bf360c
```
