# mwlock/webots_ros2_conveyor architecture

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

- Interactive diagram: https://gitdiagram.com/mwlock/webots_ros2_conveyor
- Repository: https://github.com/mwlock/webots_ros2_conveyor

## Overview

##### Project Type & Purpose
- This is a ROS2 simulation package that provides a Webots interface for a conveyor belt and camera–equipped robot.
- Its primary purpose is to control a conveyor’s motor via ROS2 topics and stream camera/depth data into ROS2.

##### File Structure
- Top-level:
- launch/robot_launch.py – ROS2 launch script bringing up all nodes & loading the Webots world.
- protos/ConveyorBelt.proto – protobuf definitions (used to generate message types or gRPC services).
- resource/*.urdf – URDF robot and conveyor definitions for Webots.
- worlds/*.wbt – Webots world files embedding those URDFs.
- webots_ros2_conveyor/ – Python ROS2 nodes:
– camera_driver.py
– conveyor_belt_driver.py
– object_recognition_controller.py

##### Extract Key Architectural Elements from README
- Topics:
– `<robot_name>/cmd_vel` (geometry_msgs/Twist) → conveyor motor commands
– `/<cambot>/camera` & `camera_info` (sensor_msgs/Image, CameraInfo) → vision stream
– `/<cambot>/depth` (sensor_msgs/Image) → depth stream

##### Main Components & Boundaries
A. Webots Simulation (World)
- Loads URDF models (resource/*.urdf) inside worlds/ure.wbt.
- Contains two simulated entities:
– Conveyor belt (motor)
– Cambot (camera + depth sensor)

B. ROS2 Middleware
- Topic bus for message exchange.
- Launch manager to start all nodes.

C. ROS2 Nodes (in `webots_ros2_conveyor/`)
1. ConveyorBeltDriver
– Subscribes to `<robot_name>/cmd_vel`
– Translates Twist → Webots motor API via ROS2-Webots bridge
2. CameraDriver
– Interfaces with Webots camera device
– Publishes `/<cambot>/camera` & `camera_info`
– Publishes `/<cambot>/depth`
3. ObjectRecognitionController
– Subscribes to camera & depth topics
– Runs vision algorithms, can publish recognition results (if extended)

D. Protobuf Definitions
- ConveyorBelt.proto may define custom messages or gRPC services for a more formalized API.

##### Relationships & Data Flows
- User (or higher-level planner) → publishes on `<robot_name>/cmd_vel` → ConveyorBeltDriver → Webots motor.
- Webots camera device → CameraDriver → publishes on camera and depth topics → ROS2 bus.
- ObjectRecognitionController → subscribes to those topics → processes frames → (optional) publishes results.

##### Architectural Patterns & Principles
- Publisher/Subcriber (ROS2 topics) decoupling.
- Single-responsibility nodes: each driver handles one device.
- Resource directory separates URDFs, keeping code vs. model assets distinct.
- Launch file orchestrates node lifecycles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Launch Manager
    LaunchManager["Launch Manager"]:::launch
    click LaunchManager "https://github.com/mwlock/webots_ros2_conveyor/blob/master/launch/robot_launch.py"

    %% Assets
    subgraph "Assets" 
        direction TB
        subgraph "URDF Models"
            direction TB
            URDF1["cambot_1.urdf"]:::assets
            URDF2["cambot_2.urdf"]:::assets
            URDF3["cambot_3.urdf"]:::assets
            URDF4["conveyor_1.urdf"]:::assets
            URDF5["conveyor_2.urdf"]:::assets
            URDF6["conveyor_3.urdf"]:::assets
        end
        subgraph "Webots Worlds"
            direction TB
            World1["ure.wbt"]:::assets
            World2["ure_original.wbt"]:::assets
        end
    end
    click URDF1 "https://github.com/mwlock/webots_ros2_conveyor/blob/master/resource/cambot_1.urdf"
    click URDF2 "https://github.com/mwlock/webots_ros2_conveyor/blob/master/resource/cambot_2.urdf"
    click URDF3 "https://github.com/mwlock/webots_ros2_conveyor/blob/master/resource/cambot_3.urdf"
    click URDF4 "https://github.com/mwlock/webots_ros2_conveyor/blob/master/resource/conveyor_1.urdf"
    click URDF5 "https://github.com/mwlock/webots_ros2_conveyor/blob/master/resource/conveyor_2.urdf"
    click URDF6 "https://github.com/mwlock/webots_ros2_conveyor/blob/master/resource/conveyor_3.urdf"
    click World1 "https://github.com/mwlock/webots_ros2_conveyor/blob/master/worlds/ure.wbt"
    click World2 "https://github.com/mwlock/webots_ros2_conveyor/blob/master/worlds/ure_original.wbt"

    %% Protobuf Layer
    Protobuf["Protobuf Definitions"]:::protos
    click Protobuf "https://github.com/mwlock/webots_ros2_conveyor/blob/master/protos/ConveyorBelt.proto"

    %% Simulation Engine
    subgraph "Simulation Engine" 
        direction TB
        WebotsSim["Webots Simulator"]:::simulation
        subgraph "Entities"
            direction TB
            ConveyorSim["Conveyor Belt"]:::simulation
            CambotSim["Cambot (Camera & Depth)"]:::simulation
        end
    end

    %% ROS2 Core
    TopicBus(["ROS2 Topic Bus"]):::ros2core

    %% ROS2 Nodes
    subgraph "ROS2 Nodes" 
        direction TB
        CBD["ConveyorBeltDriver"]:::drivers
        CD["CameraDriver"]:::drivers
        ORC["ObjectRecognitionController"]:::drivers
    end
    click CBD "https://github.com/mwlock/webots_ros2_conveyor/blob/master/webots_ros2_conveyor/conveyor_belt_driver.py"
    click CD "https://github.com/mwlock/webots_ros2_conveyor/blob/master/webots_ros2_conveyor/camera_driver.py"
    click ORC "https://github.com/mwlock/webots_ros2_conveyor/blob/master/webots_ros2_conveyor/object_recognition_controller.py"

    %% Relationships
    LaunchManager -->|orchestrates| WebotsSim
    LaunchManager -->|launches| CBD
    LaunchManager -->|launches| CD
    LaunchManager -->|launches| ORC

    URDF1 -->|loads| WebotsSim
    URDF2 -->|loads| WebotsSim
    URDF3 -->|loads| WebotsSim
    URDF4 -->|loads| WebotsSim
    URDF5 -->|loads| WebotsSim
    URDF6 -->|loads| WebotsSim

    World1 -->|defines scene| WebotsSim
    World2 -->|defines scene| WebotsSim

    WebotsSim -->|camera frames| CD
    WebotsSim -->|depth frames| CD
    WebotsSim -->|motor API| CBD

    CBD -->|"<robot_name>/cmd_vel"| TopicBus
    CD -->|"publishes camera & depth"| TopicBus
    TopicBus -->|"cmd_vel"| CBD
    TopicBus -->|"camera, depth"| ORC
    CD -->|"camera info"| TopicBus

    ORC -->|"processes frames"| TopicBus

    Protobuf -->|defines messages| CBD
    Protobuf -->|defines messages| CD
    Protobuf -->|defines messages| ORC

    %% Styles
    classDef simulation fill:#D0E6F8,stroke:#4D88E6,stroke-width:1px
    classDef ros2core fill:#D8F5D3,stroke:#4CAF50,stroke-width:1px
    classDef drivers fill:#FDE0C2,stroke:#F57C00,stroke-width:1px
    classDef assets fill:#E8E8E8,stroke:#A0A0A0,stroke-width:1px
    classDef protos fill:#E2D4F0,stroke:#7B1FA2,stroke-width:1px
    classDef launch fill:#F0F8FF,stroke:#1976D2,stroke-width:1px
```
