# hiwincorporation/hiwin_ros architecture

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

- Interactive diagram: https://gitdiagram.com/hiwincorporation/hiwin_ros
- Repository: https://github.com/hiwincorporation/hiwin_ros

## Overview

##### Project type and purpose
- This is a full-stack ROS-Industrial robotics integration project for HIWIN robotic arms.
- It provides:
- A URDF/XACRO-based robot description (`hiwin_description`) with collision/visual meshes
- A hardware interface driver (`hiwin_driver`) that plugs into `ros_control`
- MoveIt! configurations for three HIWIN models (`hiwin_ra605_710_moveit_config`, `hiwin_ra610_1476_moveit_config`, `hiwin_ra610_1869_moveit_config`)
- A pass-through controller plugin (`passthrough_controllers`) for simple trajectory forwarding
- Simulation launch files (Gazebo + HRSS Offline) and RViz configs

##### File structure
- Top-level packages:
- hiwin_description: URDF macros, XACRO includes, YAML kinematics/joint limits, STL meshes for several RA6xx models
- hiwin_driver: C++ hardware_interface plugin, ROS launch files to bring up the robot on real hardware
- hiwin_*_moveit_config: one MoveIt! config per robot model, each containing planning pipelines (OMPL, CHOMP, STOMP, Pilz), sensor managers, controllers, SRDF, warehouse DB setup, and demo/sim launch files
- passthrough_controllers: a minimal controller plugin to relay MoveIt! trajectory commands to hardware
- Notice the separation of concerns:
- Description (kinematics + visuals)
- Driver (control abstraction + hardware comms)
- Planning & execution (MoveIt!)
- Simulation support (Gazebo + HRSS)

##### Extract architecture cues from the README
- Dependencies: ROS Noetic, ros_control (controller_manager), industrial_robot_client, MoveIt!
- Use cases:
- Simulated planning/execution via Gazebo and HRSS Offline
- Real robot control via hiwin_driver and networked robot_ip
- Best-practice adherence to ROS-Industrial guidelines

##### Main components
a. Robot Description Layer
- XACRO files & YAML configs → Parameter Server (`robot_description`, joint_limits, kinematics)
- Mesh assets used by RViz & Gazebo
b. Simulation Layer
- Gazebo + gazebo_ros_control plugin
- HRSS Offline application (external GUI)
c. Control Layer
- ros_control’s `controller_manager`
- passthrough_controllers or model-specific controllers (position_controllers, joint_trajectory_controller)
d. Driver Layer
- hiwin_driver node/hardware_interface plugin
- Communication link (Ethernet) to physical robot or simulated joints
e. Planning & Execution Layer
- MoveIt! Move Group
- Planning pipelines (OMPL, CHOMP, STOMP, Pilz)
- sensor_manager, planning_context, warehouse DB
- RViz interfaces for visualization & teleoperation
f. External Tools
- HRSS Offline (Windows)
- roslaunch-based demo scripts

##### Relationships & data flows
- URDF → loaded into Parameter Server
- Parameter Server → Gazebo (spawn model) & MoveIt! (joint limits, kinematics)
- MoveIt! → sends TrajectoryAction goals to controller_manager
- controller_manager → dispatches to passthrough_controllers or position_controller
- Controller plugin → calls hiwin_driver hardware_interface → sends commands over Ethernet to robot
- Robot (sim or real) → reports sensor_msgs/JointState → feeds back into controller_manager & MoveIt!

##### Architectural patterns & design principles
- Modular ROS packages by concern (description, driver, planning)
- Standard ROS-Industrial & ros_control interfaces
- Separation of simulation vs. hardware launch configurations
- Reusable MoveIt! config templates for multiple robot variants

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Description & Config Layer
    subgraph "Description & Config" 
        D1["URDF & XACRO"]:::blue
        D2["Kinematics & Joint Limits"]:::blue
        D3["Mesh Assets"]:::blue
        D4["RViz View Config"]:::blue
        D5["Load Description Launch"]:::blue
    end

    %% Parameter Server
    PS["Parameter Server<br/>(/robot_description, joint_limits, kinematics)"]:::gray

    %% Simulation & External Tools
    subgraph "Simulation & Tools" 
        GZ["Gazebo + gazebo_ros_control"]:::purple
        HRSS["HRSS Offline GUI"]:::purple
        GV["Gazebo+MoveIt! Demo Launches"]:::purple
    end

    %% Planning & Execution Layer
    subgraph "Planning & Execution" 
        MG["MoveIt! Move Group"]:::orange
        PP["Planning Pipelines<br/>(OMPL, CHOMP, STOMP, Pilz)"]:::orange
        SM["Sensor Manager & Context"]:::orange
        WD["Warehouse DB"]:::orange
        RV["RViz Teleop & Viz"]:::orange
    end

    %% Control Layer
    subgraph "Control Layer" 
        CM["controller_manager"]:::green
        PC["passthrough_controllers"]:::green
        CC["Position & Trajectory Controllers"]:::green
    end

    %% Driver Layer
    subgraph "Driver Layer" 
        HWNode["hiwin_driver Node"]:::green
        HWI["Hardware Interface Plugin"]:::green
    end

    %% Robot
    Robot["HIWIN Robot<br/>(Simulated/Real)"]:::gray
    JS["/joint_states Topic"]:::gray

    %% Flows
    D1 --> PS
    D2 --> PS
    D3 --> PS
    D4 --> RV
    D5 --> GZ

    PS --> GZ
    PS --> MG

    GZ --> CM
    HRSS --> GZ
    GV --> GZ
    GV --> MG

    MG --> CM
    MG -->|"move_group Action"| CM
    MG --> RV

    CM --> PC
    CM --> CC
    PC --> HWI
    CC --> HWI

    HWI --> Robot
    Robot --> JS
    JS --> CM
    JS --> MG

    MG --> PP
    MG --> SM
    MG --> WD

    %% Click Events - Description
    click D1 "https://github.com/hiwincorporation/hiwin_ros/tree/noetic-devel/hiwin_description/urdf/"
    click D2 "https://github.com/hiwincorporation/hiwin_ros/tree/noetic-devel/hiwin_description/config/"
    click D3 "https://github.com/hiwincorporation/hiwin_ros/tree/noetic-devel/hiwin_description/meshes/"
    click D4 "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_description/rviz/view_robot.rviz"
    click D5 "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_description/launch/load_ra6.launch"

    %% Click Events - Simulation Demos
    click GV "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_ra605_710_moveit_config/launch/demo_gazebo.launch"
    click GV "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_ra610_1476_moveit_config/launch/demo_gazebo.launch"
    click GV "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_ra610_1869_moveit_config/launch/demo_gazebo.launch"

    %% Click Events - Control
    click PC "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/passthrough_controllers/src/pass_through_controllers.cpp"
    click PC "https://github.com/hiwincorporation/hiwin_ros/tree/noetic-devel/passthrough_controllers/include/pass_through_controllers/"
    click PC "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/passthrough_controllers/pass_through_controllers_plugin.xml"

    %% Click Events - Driver
    click HWI "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_driver/hardware_interface_plugin.xml"
    click HWI "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_driver/include/hiwin_driver/hardware_interface.h"
    click HWI "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_driver/src/hardware_interface.cpp"
    click HWNode "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_driver/src/hardware_interface_node.cpp"
    click HWNode "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_driver/launch/ra6_bringup.launch"
    click HWNode "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_driver/launch/hiwin_control.launch"
    click HWNode "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_driver/config/ra6_controllers.yaml"

    %% Click Events - MoveIt! Config (RA605_710)
    click MG "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_ra605_710_moveit_config/launch/move_group.launch"
    click MG "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_ra605_710_moveit_config/launch/moveit_planning_execution.launch"
    click PP "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_ra605_710_moveit_config/config/ompl_planning.yaml"
    click MG "https://github.com/hiwincorporation/hiwin_ros/blob/noetic-devel/hiwin_ra605_710_moveit_config/config/ra605_710.srdf"

    classDef blue fill:#AED6F1,stroke:#2980B9,color:#1B4F72;
    classDef purple fill:#D2B4DE,stroke:#884EA0,color:#512E5F;
    classDef orange fill:#F5B041,stroke:#D35400,color:#7E5109;
    classDef green fill:#ABEBC6,stroke:#27AE60,color:#145A32;
    classDef gray fill:#E5E8E8,stroke:#7F8C8D,color:#2C3E50;
```
