# miroboticslab/cyberdog_ros2 architecture

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

- Interactive diagram: https://gitdiagram.com/miroboticslab/cyberdog_ros2
- Repository: https://github.com/miroboticslab/cyberdog_ros2

## Overview

##### Main Components
a. ROS 2 runtime environment: Mark the ROS 2 framework (Galactic) and underlying Cyclone DDS, which underpin all communications.
b. CyberDog Bringup: Contains launch files, parameters, and initial node configuration used for bootstrapping the robot.
c. Perception (“cyberdog_ception”): Comprised of packages such as bms (battery/system monitoring), body state, lightsensor, obstacle detection, and scene detection.
d. Common Utilities (“cyberdog_common”): Provides GRPC communication components, utilities (e.g., CAN bus interfaces and lifecycle handling), and third-party vendor packages.
e. Decision-making (“cyberdog_decision”): Implements the robot’s decision maker, including modules for automation, ception integration, and motion management with parameter-driven orders.
f. Interaction (“cyberdog_interaction”): Includes multiple submodules:
- Audio (with further division into audio assistant, audio base, and audio interaction)
- Camera (handling image capture, processing, and service nodes)
- LED, Livestream, Touch, and Wireless modules (which, for example, include the bluetooth and wifi signal processing and sensor interfaces).
g. Interfaces (“cyberdog_interfaces”): Hosts all the ROS message, service, action, and LCM definitions that standardize the communication between these components (perception, decision, interaction, etc.).

##### Relationships & Data Flows
- The Bringup package initializes the entire ROS ecosystem and launches nodes from the perception, decision, and interaction modules.
- The Decision-making module interacts bi-directionally with the Perception modules to receive sensor data (e.g., battery state, obstacles, body state) and with the Interaction modules to send feedback or control commands.
- The Common Utilities assist in cross-module communication (e.g., via GRPC services and utility functions) as well as shared data processing.
- The Interfaces layer acts as the contract – showing how nodes publish/subscribe messages and call services across the architecture.
- External communications: the ROS 2 network (using Cyclone DDS) as the backbone for inter-node communication and any external devices (e.g., the robot’s hardware, network interfaces).

##### Architectural Patterns & Design Principles
- A modular, component-based architecture where each major functional area is developed and maintained as a separate ROS package.
- Use of declarative launch files and parameter files (YAML and TOML) to configure behavior at runtime.
- Separation of concerns: bringup for initialization, ception for sensing, decision for autonomous control, and interaction for user and external interface functionalities.
- Employing vendor-specific submodules (as seen in the “*_vendor” directories) to integrate third-party libraries and hardware drivers.
- Distributed communication between nodes using standardized ROS interfaces (topics, services, actions) based on the definitions in the cyberdog_interfaces.

##### Relevant Technologies & Frameworks
- ROS 2 Galactic, Cyclone DDS, and external dependencies such as GRPC, vendor drivers (e.g., for audio, camera, CAN bus interfaces), and Docker for deployment.
- That parts of the system are tailored for Jetson hardware and Ubuntu 18.04 adaptations provided by custom forks (as seen in the mini.repos file).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    R2("ROS 2 Runtime (Galactic & Cyclone DDS)"):::runtime

    %% CyberDog Bringup Cluster
    subgraph "CyberDog Bringup"
        direction TB
        B1("Bringup"):::bringup
        LF("Launch Files"):::bringup
        P("Parameters"):::bringup
        B1 --> LF
        B1 --> P
    end

    %% Perception Cluster
    subgraph "Perception (Cyberdog_ception)"
        direction TB
        PHeader("Perception"):::perception
        BMS("BMS"):::perception
        BS("Body State"):::perception
        LS("Light Sensor"):::perception
        OD("Obstacle Detection"):::perception
        SD("Scene Detection"):::perception
        PHeader --> BMS
        PHeader --> BS
        PHeader --> LS
        PHeader --> OD
        PHeader --> SD
    end

    %% Decision-making Cluster
    subgraph "Decision-making (Cyberdog_decision)"
        direction TB
        DHeader("Decision-making"):::decision
        DM("Decision Maker"):::decision
        DU("Decision Utils"):::decision
        DHeader --> DM
        DHeader --> DU
    end

    %% Interaction Cluster
    subgraph "Interaction (Cyberdog_interaction)"
        direction TB
        IHeader("Interaction"):::interaction
        Audio("Audio"):::interaction
        Camera("Camera"):::interaction
        LED("LED"):::interaction
        Livestream("Livestream"):::interaction
        Touch("Touch"):::interaction
        Wireless("Wireless"):::interaction
        IHeader --> Audio
        IHeader --> Camera
        IHeader --> LED
        IHeader --> Livestream
        IHeader --> Touch
        IHeader --> Wireless
    end

    %% Common Utilities Cluster
    subgraph "Common Utilities (Cyberdog_common)"
        direction TB
        UHeader("Common Utilities"):::utilities
        GRPC("GRPC"):::utilities
        Utils("Utilities"):::utilities
        VendorBT("Vendor: behaviortreecppv3"):::utilities
        VendorGRPC("Vendor: grpc"):::utilities
        VendorLCM("Vendor: lcm"):::utilities
        VendorMPG("Vendor: mpg123"):::utilities
        VendorSDL("Vendor: sdl2"):::utilities
        VendorTOML("Vendor: toml11"):::utilities
        UHeader --> GRPC
        UHeader --> Utils
        UHeader --> VendorBT
        UHeader --> VendorGRPC
        UHeader --> VendorLCM
        UHeader --> VendorMPG
        UHeader --> VendorSDL
        UHeader --> VendorTOML
    end

    %% Interfaces Cluster
    subgraph "Interfaces (Cyberdog_interfaces)"
        direction TB
        Intf("ROS Interfaces"):::interfaces
    end

    %% Relationships & Data Flows
    R2 --> B1
    B1 --> PHeader
    B1 --> DHeader
    B1 --> IHeader

    DM ---|bi-directional| PHeader
    DM --> IHeader

    UHeader --> PHeader
    UHeader --> DHeader
    UHeader --> IHeader

    PHeader --> Intf
    DHeader --> Intf
    IHeader --> Intf

    %% Styles
    classDef runtime fill:#f9ead9,stroke:#b36b00,stroke-width:2px;
    classDef bringup fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef perception fill:#d5f5e3,stroke:#145a32,stroke-width:2px;
    classDef decision fill:#f5b7b1,stroke:#922b21,stroke-width:2px;
    classDef interaction fill:#d6eaf8,stroke:#1b4f72,stroke-width:2px;
    classDef utilities fill:#fcf3cf,stroke:#b7950b,stroke-width:2px;
    classDef interfaces fill:#e8daef,stroke:#6f42c1,stroke-width:2px;

    %% Click Events for CyberDog Bringup
    click B1 "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_bringup"
    click LF "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_bringup/launch"
    click P "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_bringup/params"

    %% Click Events for Perception Components
    click BMS "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_ception/cyberdog_bms"
    click BS "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_ception/cyberdog_body_state"
    click LS "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_ception/cyberdog_lightsensor"
    click OD "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_ception/cyberdog_obstacledetection"
    click SD "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_ception/cyberdog_scenedetection"

    %% Click Events for Common Utilities Components
    click GRPC "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_common/cyberdog_grpc"
    click Utils "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_common/cyberdog_utils"
    click VendorBT "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_common/behaviortreecppv3_vendor"
    click VendorGRPC "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_common/grpc_vendor"
    click VendorLCM "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_common/lcm_vendor"
    click VendorMPG "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_common/mpg123_vendor"
    click VendorSDL "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_common/sdl2_vendor"
    click VendorTOML "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_common/toml11_vendor"

    %% Click Events for Decision-making Components
    click DM "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_decision/decision_maker"
    click DU "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_decision/decision_utils"

    %% Click Events for Interaction Components
    click Audio "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_interaction/cyberdog_audio"
    click Camera "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_interaction/cyberdog_camera"
    click LED "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_interaction/cyberdog_led"
    click Livestream "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_interaction/cyberdog_livestream"
    click Touch "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_interaction/cyberdog_touch"
    click Wireless "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_interaction/cyberdog_wireless"

    %% Click Event for Interfaces
    click Intf "https://github.com/miroboticslab/cyberdog_ros2/tree/main/cyberdog_interfaces"
```
