# carpit680/giraffe architecture

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

- Interactive diagram: https://gitdiagram.com/carpit680/giraffe
- Repository: https://github.com/carpit680/giraffe

## Overview

##### Project Type and Purpose
- This is a full-stack, open-source ROS2 robotic manipulator project (“Giraffe v1.1”) that spans CAD assets, embedded firmware, hardware control scripts, ROS2 packages (description, control, hardware interface, MoveIt! config), and simulation. Its goal is to provide a low-cost, leader-follower robotic arm with both real-hardware and Gazebo/MoveIt! simulation support.

##### File Structure Analysis
- Top-level directories:
- CAD/ – all CAD models (MuJoCo XML, Gerber PCB, STEP/STL files)
- STservo_sdk/ – Python library for low-level servo communication
- giraffe_ws/src/ – ROS2 workspace containing four main packages:
– giraffe_description (URDF/XACRO, meshes, launch)
– giraffe_control (ROS2 node “giraffe_driver”, scripts, configs)
– giraffe_hardware (ros2_control SystemInterface plugin)
– giraffe_moveit_config (MoveIt! SRDF/URDF, planners, controllers)
- scripts/ – calibration and test scripts for servos
- requirements.txt, setup.py – Python packaging and dependencies
- assets/ – README images

##### Key README Insights
- Four ROS2 launch flows: display, simulation (Gazebo + rviz), moveit_sim, moveit_interface
- STservo_sdk drives Feetech motors via serial bus
- giraffe_control bridges ROS2 ↔ servos (subscribes to /command, publishes /feedback)
- giraffe_hardware implements ros2_control plugin for real-hardware drivers
- MoveIt! config package for motion planning

##### Main Components
A. CAD & Physical Components (hardware layer)
- 3D-printed parts (common, leader, follower)
- PCB (I²C mux, AS5600 encoders, Wemos D1 Mini MCU) for leader arm
- Feetech serial-bus servos and Servo Driver Board
B. Embedded Controller (firmware layer)
- Wemos D1 Mini + AS5600 encoders + TCA9548A mux
- Firmware that reads encoders and streams data / receives commands (via Wi-Fi or serial)
C. Low-Level Python SDK
- STservo_sdk (port_handler, protocol handler, sync read/write modules)
- scripts (st_configurator.py, sync_read/write examples)
D. ROS2 Software Layer
1. giraffe_description – URDF/XACRO + meshes + robot_state_publisher + joint_state_publisher
2. giraffe_hardware – hardware_interface::SystemInterface plugin (“GiraffeInterface”)
3. giraffe_control – ROS2 node “giraffe_driver” subscribing to /command, publishing /feedback
4. giraffe_moveit_config – MoveIt! planners, controllers, RViz config
E. Simulation Environment
- Gazebo Ignition Fortress + model spawner
- ros2_control controllers spawned for simulation
- RViz for visualization
F. Teleoperation / External Interfaces
- Teleop Tongs integration (Dex Teleop) via fiducials, separate project

##### Relationships & Data Flows
- Application Layer (user CLI / teleop GUI) → publishes JointTrajectory (or custom /command topic)
- giraffe_control node → uses STservo_sdk to send commands over serial to servo driver board → servos
- Servos & encoders → position feedback over bus → STservo_sdk → giraffe_control publishes /feedback
- giraffe_hardware plugin → also subscribes /command and publishes /feedback for ros2_control controllers
- move_group (MoveIt! 2) → executes trajectories via ros2_control controller_manager → giraffe_hardware
- Gazebo simulation: gazebo_ros2_control plugin binds model to controller_manager → mimics hardware
- URDF/XACRO → robot_state_publisher publishes transforms → RViz visualizes

##### Architectural Patterns & Principles
- Layered architecture: hardware → firmware → SDK → ROS2 middleware → planning/visualization
- Plugin pattern: ros2_control SystemInterface for hardware abstraction
- Publisher–Subscriber: ROS2 topics for decoupling nodes
- Configuration as code: YAML parameters for controllers, kinematics, joint limits

##### Essential Elements
- Layer separation: CAD/physical, firmware/embedded, SDK, ROS2 middleware, simulation/planning
- Notes on config: YAML files feed into nodes (annotate configuration inputs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CAD & Physical Components
    subgraph "CAD & Physical Components"
        direction TB
        MuJoCo_XML["MuJoCo XML & meshes"]:::hardware
        STEP["STEP files"]:::hardware
        STL["STL files"]:::hardware
        PCB["PCB Gerber (Leader Arm)"]:::hardware
        Servos["Feetech Serial-Bus Servos"]:::hardware
        SDB["Servo Driver Board"]:::hardware
        MCU["Wemos D1 Mini + AS5600 + TCA9548A"]:::hardware
    end

    %% Firmware Layer
    subgraph "Firmware Layer"
        direction TB
        FW["Firmware on MCU"]:::hardware
    end

    %% SDK Layer
    subgraph "Low-Level Python SDK"
        direction TB
        STSDK["STservo_sdk Python SDK"]:::software
        Scripts["Calibration & Test Scripts"]:::software
    end

    %% ROS2 Software Layer
    subgraph "ROS2 Middleware Layer"
        direction TB
        subgraph "giraffe_description" 
            direction TB
            GD["URDF/XACRO & Meshes"]:::software
            DescConfig["Description Configs"]:::software
            models["Gazebo Models (SDF)"]:::software
            DISPLAY["display.launch.py"]:::software
            SIM["simulation.launch.py"]:::software
            MOVEIT_SIM["moveit_sim.launch.py"]:::software
            MOVEIT_IF["moveit_interface.launch.py"]:::software
            TELEOP_LAUNCH["teleop_hardware.launch.py"]:::software
        end
        GHW["giraffe_hardware plugin"]:::software
        GC["giraffe_control (giraffe_driver)"]:::software
        GMC["giraffe_moveit_config"]:::software
        TeleopRViz["teleop.rviz"]:::software
        ControlParams["giraffe_control_params.yaml"]:::software
        MCparams["ros2_controllers.yaml"]:::software
        RSP["robot_state_publisher"]:::software
        JSP["joint_state_publisher"]:::software
    end

    %% Simulation Environment
    subgraph "Simulation Environment"
        direction TB
        Gazebo["Gazebo Ignition Fortress"]:::simulation
        RVSIM["RViz (Simulation)"]:::simulation
        MG["move_group (MoveIt!)"]:::simulation
    end

    %% Real Visualization
    RZ["RViz (Real Hardware)"]:::software

    %% External Teleop
    TeleopGUI["Teleop Tongs / Dex Teleop GUI"]:::external

    %% User Interface
    UI["User CLI / Teleop GUI"]:::external

    %% Connections - Hardware Flow
    UI -->|"publishes /command"| GC
    GC -->|"uses SDK"| STSDK
    STSDK -->|"serial write"| SDB
    SDB --> Servos
    Servos -->|"feedback"| SDB
    SDB --> STSDK
    STSDK -->|"feedback topic"| GC

    %% Firmware interactions
    MCU --> FW
    FW --> Servos
    Servos --> FW
    FW --> GHW
    GHW -->|"ros2_control interface"| GC

    %% MoveIt & Controller Flow
    GMC --> MCparams
    MG -->|"trajectory"| GHW
    GHW --> FW
    FW --> Servos
    Servos --> FW
    FW --> GHW
    GHW --> MG

    %% ROS2 State Publishing & RViz
    GD --> RSP
    RSP --> JSP
    JSP --> RZ
    GD --> models
    Gazebo --- GC
    Gazebo --> MG
    MG --> RVSIM

    %% Teleop GUI
    TeleopGUI -->|"fiducial data"| UI

    %% Launch flows
    SIM --> Gazebo
    MOVEIT_SIM --> MG
    MOVEIT_IF --> GC
    TELEOP_LAUNCH --> GC
    DISPLAY --> RZ

    %% Scripts
    Scripts --> STSDK

    %% Click Events
    click MuJoCo_XML "https://github.com/carpit680/giraffe/tree/v1.1/CAD/MuJoCo/giraffe/"
    click STEP "https://github.com/carpit680/giraffe/tree/v1.1/CAD/STEP/"
    click STL "https://github.com/carpit680/giraffe/tree/v1.1/CAD/STL/"
    click PCB "https://github.com/carpit680/giraffe/blob/v1.1/CAD/PCB/Gerber_OpenBot-Leader-Arm-v0.9.zip"
    click STSDK "https://github.com/carpit680/giraffe/tree/v1.1/STservo_sdk/"
    click Scripts "https://github.com/carpit680/giraffe/tree/v1.1/scripts/"
    click GD "https://github.com/carpit680/giraffe/tree/v1.1/giraffe_ws/src/giraffe_description/"
    click models "https://github.com/carpit680/giraffe/tree/v1.1/giraffe_ws/src/giraffe_description/models/"
    click DISPLAY "https://github.com/carpit680/giraffe/blob/v1.1/giraffe_ws/src/giraffe_description/launch/display.launch.py"
    click SIM "https://github.com/carpit680/giraffe/blob/v1.1/giraffe_ws/src/giraffe_description/launch/simulation.launch.py"
    click MOVEIT_SIM "https://github.com/carpit680/giraffe/blob/v1.1/giraffe_ws/src/giraffe_description/launch/moveit_sim.launch.py"
    click MOVEIT_IF "https://github.com/carpit680/giraffe/blob/v1.1/giraffe_ws/src/giraffe_description/launch/moveit_interface.launch.py"
    click TELEOP_LAUNCH "https://github.com/carpit680/giraffe/blob/v1.1/giraffe_ws/src/giraffe_description/launch/teleop_hardware.launch.py"
    click DescConfig "https://github.com/carpit680/giraffe/tree/v1.1/giraffe_ws/src/giraffe_description/config/"
    click GHW "https://github.com/carpit680/giraffe/tree/v1.1/giraffe_ws/src/giraffe_hardware/"
    click GC "https://github.com/carpit680/giraffe/tree/v1.1/giraffe_ws/src/giraffe_control/"
    click TeleopRViz "https://github.com/carpit680/giraffe/blob/v1.1/giraffe_ws/src/giraffe_control/config/teleop.rviz"
    click ControlParams "https://github.com/carpit680/giraffe/blob/v1.1/giraffe_ws/src/giraffe_control/config/giraffe_control_params.yaml"
    click GMC "https://github.com/carpit680/giraffe/tree/v1.1/giraffe_ws/src/giraffe_moveit_config/"
    click MCparams "https://github.com/carpit680/giraffe/blob/v1.1/giraffe_ws/src/giraffe_moveit_config/config/ros2_controllers.yaml"

    %% Styles
    classDef hardware fill:#a2f5a2,stroke:#2c8f2c,color:#000;
    classDef software fill:#add8e6,stroke:#1f4f8b,color:#000;
    classDef simulation fill:#ffcc80,stroke:#e65c00,color:#000;
    classDef external fill:#d3d3d3,stroke:#555,color:#000;
```
