# intelligentsystemslabutv/ros2-examples architecture

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

- Interactive diagram: https://gitdiagram.com/intelligentsystemslabutv/ros2-examples
- Repository: https://github.com/intelligentsystemslabutv/ros2-examples

## Overview

##### Project Type and Purpose
- This is a tutorial/example full-stack ROS 2 workspace: it provides a collection of C++ and Python packages that demonstrate core ROS 2 concepts (topics, services, actions, parameters, plugins, image processing, lifecycle, etc.).

##### File-Structure Analysis
- Top-level:
- .github/workflows – GitHub Actions CI for syncing and testing
- bin – DUA template artifacts and install scripts (bash context snippets, Dockerfile templates, dua_setup.sh, ros2_jazzy_install.sh)
- config – helper scripts for sourcing ROS 2
- docker – ready-made container definitions for each target (devcontainer.json, Dockerfile, shell config)
- src – the ROS 2 workspace
– src/cpp – all C++ packages
– src/python – Python examples
– src/ros2_examples_interfaces – message/service/action definitions
– src/ros2_examples_bringup – launch‐file conventions
- README.md, dua-template.md, interfaces.md, launch_files.md – documentation and guidelines

##### Key README Insights
- The workspace is built and orchestrated via colcon and the DUA template.
- Supports VS Code devcontainers and local Docker
- Contains three container targets (x86-dev, x86-cudev for CUDA-enabled, armv8-dev)
- Examples are grouped by functionality (pub/sub, custom messages, services, parameters, actions, plugins, image pipelines)

a. Main Components
- Developer Environment (Host OS + VS Code IDE)
- DUA Template / bin Scripts
- Docker Container Targets (x86-dev, x86-cudev, armv8-dev)
- colcon Build System
- ROS 2 Middleware (rclcpp, rclpy, DDS/RMW)
- Example Node Groups:
- pub/sub (topic_pubsub_cpp / py)
- services (simple_service_cpp)
- actions (actions_example_cpp / complete_actions_cpp)
- parameters (parameters_example_cpp)
- plugins (polygon_base, polygons, polygons_tester)
- image processing (aruco_detector, ros2_usb_camera, rqt_image_view)
- interfaces-only (ros2_examples_interfaces)
- bringup/launch (ros2_examples_bringup)
- External Services & Tools: GitHub Actions, Docker Engine, colcon, CMake, GCC, Python

b. Relationships & Interactions
- Developer pushes code → GitHub Actions CI → builds/tests examples
- Developer launches VS Code devcontainer (select target) → mounts workspace → runs bin/dua_setup.sh → colcon build
- Built nodes (C++ binaries, Python entry points) register with ROS 2 middleware
- Nodes communicate over topics/services/actions via DDS network; some pipelines use image_transport (camera → detector → GUI)
- Launch files (in bringup) orchestrate multi-node graphs
- Plugins: polygons_tester loads shared-object plugins at runtime via pluginlib

c. Architectural Patterns & Principles
- Modular, multi-package ROS 2 workspace
- DUA template for unified containerized development
- Layered separation: build layer (colcon/CMake), runtime layer (ROS 2 middleware), application layer (example nodes)
- Plugin pattern (pluginlib) for runtime extensibility
- Message-oriented middleware (pub/sub, request/response, action feedback)
- Devcontainers for environment reproducibility

d. Key Technologies & Frameworks
- ROS 2 (rclcpp, rclpy, DDS/RMW implementation)
- Docker, Devcontainer specs (VS Code)
- CMake, colcon build system
- GCC (C++17), Python 3
- image_transport, pluginlib

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment" 
        direction TB
        VSCode["VS Code (.vscode/)"]:::infra
        ROS2Cmds["ROS2 Cmds (config/ros2_cmds.sh)"]:::infra
    end
    click VSCode "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/.vscode/"
    click ROS2Cmds "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/config/ros2_cmds.sh"

    %% CI
    GitHubCI["GitHub Actions CI"]:::infra
    click GitHubCI "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/.github/workflows/sync-dua-template.yaml"

    %% Containerization Layer
    subgraph "Containerization" 
        direction TB
        DUASetup["dua_setup.sh"]:::infra
        JazzyInstall["ros2_jazzy_install.sh"]:::infra
        DUA_Templates["dua-templates/"]:::infra
        X86Dev["x86-dev container"]:::infra
        X86CUDA["x86-cudev container"]:::infra
        ARMv8["armv8-dev container"]:::infra
    end
    click DUASetup "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/bin/dua_setup.sh"
    click JazzyInstall "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/bin/ros2_jazzy_install.sh"
    click DUA_Templates "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/bin/dua-templates/"
    click X86Dev "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/docker/container-x86-dev/"
    click X86CUDA "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/docker/container-x86-cudev/"
    click ARMv8 "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/docker/container-armv8-dev/"

    %% Build Layer
    colcon["colcon Build System"]:::infra
    click colconTemplate "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/bin/dua-templates/context/colcon-defaults.yaml.template"

    %% Workspace src
    subgraph "Workspace src/" 
        direction TB
        Interfaces["ros2_examples_interfaces"]:::app
        Bringup["ros2_examples_bringup (Launch)"]:::app
        click Interfaces "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/ros2_examples_interfaces/"
        click Bringup "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/ros2_examples_bringup/"
        subgraph "Example Nodes" 
            direction TB
            subgraph "Pub/Sub" 
                direction TB
                PubSubCPP["topic_pubsub_cpp"]:::app
                PubSubPy["topic_pubsub_py"]:::app
                PubSubComp["pub_sub_components"]:::app
                click PubSubCPP "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/topic_pubsub_cpp/"
                click PubSubPy "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/python/topic_pubsub_py/"
                click PubSubComp "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/pub_sub_components/"
            end
            subgraph "Services" 
                direction TB
                ServiceNode["simple_service_cpp"]:::app
                click ServiceNode "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/simple_service_cpp/"
            end
            subgraph "Actions" 
                direction TB
                Actions1["actions_example_cpp"]:::app
                Actions2["complete_actions_cpp"]:::app
                click Actions1 "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/actions_example_cpp/"
                click Actions2 "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/advanced/complete_actions_cpp/"
            end
            subgraph "Parameters" 
                direction TB
                ParamNode["parameters_example_cpp"]:::app
                click ParamNode "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/parameters_example_cpp/"
            end
            subgraph "Plugins" 
                direction TB
                PluginBase["polygon_base"]:::app
                PluginPoly["polygons"]:::app
                PluginTester["polygons_tester"]:::app
                click PluginBase "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/plugins_demo/polygon_base/"
                click PluginPoly "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/plugins_demo/polygons/"
                click PluginTester "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/plugins_demo/polygons_tester/"
            end
            subgraph "Image Processing" 
                direction TB
                Aruco["aruco_detector"]:::app
                USBCam["ros2_usb_camera"]:::app
                RQTView["rqt_image_view"]:::app
                click Aruco "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/image_processing/aruco_detector/"
                click USBCam "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/image_processing/ros2_usb_camera/"
                click RQTView "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/src/cpp/image_processing/rqt_image_view/"
            end
        end
    end

    %% Documentation & Scripts
    subgraph "Documentation & Scripts" 
        direction TB
        README["README.md"]:::docs
        DuaMD["dua-template.md"]:::docs
        InterfacesMD["interfaces.md"]:::docs
        LaunchMD["launch_files.md"]:::docs
        ComponentsMD["components.md"]:::docs
        ConfigDir["config/"]:::docs
    end
    click README "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/README.md"
    click DuaMD "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/dua-template.md"
    click InterfacesMD "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/interfaces.md"
    click LaunchMD "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/launch_files.md"
    click ComponentsMD "https://github.com/intelligentsystemslabutv/ros2-examples/blob/jazzy/components.md"
    click ConfigDir "https://github.com/intelligentsystemslabutv/ros2-examples/tree/jazzy/config/"

    %% Runtime Middleware
    Bus["ROS 2 Middleware (rclcpp, rclpy, DDS)"]:::runtime

    %% Connections
    VSCode -->|launches| DUASetup
    ROS2Cmds -->|sources| colcon
    GitHubCI -->|build & test| colcon
    DUASetup -->|configures| colcon
    X86Dev -->|uses| colcon
    X86CUDA -->|uses| colcon
    ARMv8 -->|uses| colcon
    colcon -->|builds| PubSubCPP
    colcon -->|builds| PubSubPy
    colcon -->|builds| PubSubComp
    colcon -->|builds| ServiceNode
    colcon -->|builds| Actions1
    colcon -->|builds| Actions2
    colcon -->|builds| ParamNode
    colcon -->|builds| PluginBase
    colcon -->|builds| PluginPoly
    colcon -->|builds| PluginTester
    colcon -->|builds| Aruco
    colcon -->|builds| USBCam
    colcon -->|builds| RQTView
    colcon -->|builds| Interfaces

    %% Node interactions with middleware
    PubSubCPP -->|publish/subscribe| Bus
    PubSubPy -->|publish/subscribe| Bus
    PubSubComp -->|publish/subscribe| Bus
    ServiceNode -->|request/response| Bus
    Actions1 -->|action protocol| Bus
    Actions2 -->|action protocol| Bus
    ParamNode -->|parameter server| Bus
    PluginTester -->|loads plugins| PluginBase
    PluginTester -->|loads plugins| PluginPoly
    Aruco -->|image_transport| Bus
    USBCam -->|image_transport| Bus
    RQTView -->|image view| Bus

    %% Launch orchestration
    Bringup -->|orchestrates| PubSubCPP
    Bringup -->|orchestrates| ServiceNode
    Bringup -->|orchestrates| Actions1
    Bringup -->|orchestrates| ParamNode
    Bringup -->|orchestrates| Aruco
    Bringup -->|coordinates| Bus

    %% Styles
    classDef infra fill:#bbdefb,stroke:#2196f3,color:#0d47a1
    classDef runtime fill:#c8e6c9,stroke:#4caf50,color:#1b5e20
    classDef app fill:#ffe0b2,stroke:#ff9800,color:#e65100
    classDef docs fill:#eeeeee,stroke:#9e9e9e,color:#424242
```
