-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
0b0c654
commit 0289c9f
Showing
1 changed file
with
276 additions
and
55 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,97 +1,318 @@ | ||
| # dVRK URDF Description | ||
| [](https://docs.ros.org/en/humble/index.html) | ||
|  | ||
|
|
||
| This README provides an overview of the da Vinci Research Kit (dVRK) Unified Robot Description Format (URDF) models. This document combines information on various robotic elements, including the Patient Side Manipulator (PSM), Endoscope Camera Manipulator (ECM), Master Tool Manipulator (MTM), Setup Joints (SUJ), and the Patient Cart. | ||
| # dVRK URDF Description | ||
|
|
||
| --- | ||
| This package provides the Unified Robot Description Format (URDF) models for the **da Vinci Research Kit (dVRK)**. It includes detailed models of the various robotic components used in the **da Vinci Surgical System**, allowing for simulation and visualization in **ROS 2**. | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| - [Introduction](#introduction) | ||
| - [Components Overview](#components-overview) | ||
| - [Patient Side Manipulator (PSM)](#patient-side-manipulator-psm) | ||
| - [Endoscope Camera Manipulator (ECM)](#endoscope-camera-manipulator-ecm) | ||
| - [Master Tool Manipulator (MTM)](#master-tool-manipulator-mtm) | ||
| - [Setup Joints (SUJ)](#setup-joints-suj) | ||
| - [Patient Cart](#patient-cart) | ||
| - [Launching the URDF Models](#launching-the-urdf-models) | ||
| - [Notes](#notes) | ||
| - [Introduction](#introduction) | ||
| - [Package Structure](#package-structure) | ||
| - [Components Overview](#components-overview) | ||
| - [da Vinci Core Description](#da-vinci-core-description) | ||
| - [Subcomponents](#subcomponents) | ||
| - [Readme](#readme) | ||
| - [Patient Side Manipulator (PSM)](#patient-side-manipulator-psm) | ||
| - [Subcomponents](#subcomponents-1) | ||
| - [Readme](#readme-1) | ||
| - [Endoscopic Camera Manipulator (ECM)](#endoscopic-camera-manipulator-ecm) | ||
| - [Subcomponents](#subcomponents-2) | ||
| - [Readme](#readme-2) | ||
| - [Master Tool Manipulator (MTM)](#master-tool-manipulator-mtm) | ||
| - [Subcomponents](#subcomponents-3) | ||
| - [Readme](#readme-3) | ||
| - [Setup Joints (SUJ)](#setup-joints-suj) | ||
| - [Subcomponents](#subcomponents-4) | ||
| - [Readme](#readme-4) | ||
| - [Patient Cart](#patient-cart) | ||
| - [Subcomponents](#subcomponents-5) | ||
| - [Readme](#readme-5) | ||
| - [Building the Packages](#building-the-packages) | ||
| - [Usage Examples](#usage-examples) | ||
| - [Simulate the Robots with Controllers](#simulate-the-robots-with-controllers) | ||
| - [da Vinci Core Robot](#da-vinci-core-robot) | ||
| - [Patient Side Manipulator (PSM)](#patient-side-manipulator-psm-1) | ||
| - [Endoscopic Camera Manipulator (ECM)](#endoscopic-camera-manipulator-ecm-1) | ||
| - [Master Tool Manipulator (MTM)](#master-tool-manipulator-mtm-1) | ||
| - [Setup Joints (SUJ)](#setup-joints-suj-1) | ||
| - [Patient Cart](#patient-cart-1) | ||
| - [Launch Files README](#launch-files-readme) | ||
| - [Visualize and Manipulate the Robots with GUI](#visualize-and-manipulate-the-robots-with-gui) | ||
| - [da Vinci Core Robot](#da-vinci-core-robot-1) | ||
| - [Other Components](#other-components) | ||
| - [Launch Files README](#launch-files-readme-1) | ||
| - [Dependencies](#dependencies) | ||
| - [Additional Resources](#additional-resources) | ||
| - [Notes](#notes) | ||
|
|
||
| --- | ||
|
|
||
| ## Introduction | ||
|
|
||
| The dVRK URDF models provide detailed representations of the robotic components used in the da Vinci Surgical System. This README combines information from multiple components to serve as a unified guide for the `dvrk_urdf` package. | ||
| The **dVRK URDF** models provide detailed representations of the robotic components used in the **da Vinci Surgical System**. This package combines information from multiple components to serve as a unified guide for simulation and development within **ROS 2**. | ||
|
|
||
| --- | ||
|
|
||
| ## Package Structure | ||
|
|
||
| ``` | ||
| dvrk_urdf | ||
| ├── davinci_core_description | ||
| ├── ecm_description | ||
| ├── mtm_description | ||
| ├── patient_cart_description | ||
| ├── psm_description | ||
| ├── suj_description | ||
| └── README.md | ||
| ``` | ||
|
|
||
| Each sub-package contains URDF models, launch files, configurations, meshes, and additional resources specific to each component. | ||
|
|
||
| --- | ||
|
|
||
| ## Components Overview | ||
|
|
||
| ### da Vinci Core Description | ||
|
|
||
| The `davinci_core_description` package provides the URDF descriptions, launch files, and configurations necessary to simulate and visualize the da Vinci Surgical System's core components in ROS 2. | ||
|
|
||
| #### Subcomponents | ||
|
|
||
| - **URDF and Xacro Files** | ||
| - **Meshes** | ||
| - **Controllers** | ||
| - **RViz Configurations** | ||
|
|
||
| #### Readme | ||
|
|
||
| - **README:** [`davinci_core_description/README.md`](./davinci_core_description/README.md) | ||
|
|
||
| ### Patient Side Manipulator (PSM) | ||
|
|
||
| The PSM is a robotic arm that performs surgical procedures. It can be equipped with various tools, and its URDF model includes detailed links and joints representing its mechanical structure. | ||
| The `psm_description` package provides URDF models and configurations for the Patient Side Manipulator, a robotic arm that performs surgical procedures. | ||
|
|
||
| #### Subcomponents | ||
|
|
||
| - **Classic and Si Versions** | ||
| - **Support for Various Surgical Tools** | ||
| - **URDF and Xacro Files** | ||
| - **Meshes** | ||
| - **Controllers** | ||
| - **RViz Configurations** | ||
|
|
||
| - **Tool Types**: Different surgical tools can be mounted on the PSM. Change the tool type by modifying the `tool_name` parameter in the URDF files. | ||
| - **Meshes**: PSM meshes are located in the `meshes` directory within the `psm_description` package. | ||
| #### Readme | ||
|
|
||
| ### Endoscope Camera Manipulator (ECM) | ||
| - **README:** [`psm_description/README.md`](./psm_description/README.md) | ||
|
|
||
| The ECM controls the endoscopic camera, providing visual feedback during surgery. Its URDF model includes all necessary links and joints to simulate its movements. | ||
| ### Endoscopic Camera Manipulator (ECM) | ||
|
|
||
| - **Variants**: Full ECM models and base models can be launched separately. | ||
| - **Meshes**: ECM meshes are found in the `meshes` directory within the `ecm_description` package. | ||
| The `ecm_description` package provides URDF models and configurations for the Endoscopic Camera Manipulator, which controls the endoscopic camera during surgery. | ||
|
|
||
| #### Subcomponents | ||
|
|
||
| - **Full ECM Models and Base Models** | ||
| - **URDF and Xacro Files** | ||
| - **Meshes** | ||
| - **Controllers** | ||
| - **RViz Configurations** | ||
|
|
||
| #### Readme | ||
|
|
||
| - **README:** [`ecm_description/README.md`](./ecm_description/README.md) | ||
|
|
||
| ### Master Tool Manipulator (MTM) | ||
|
|
||
| The MTM serves as the master control interface for the surgeon, translating hand movements into robot actions. | ||
| The `mtm_description` package provides URDF models and configurations for the Master Tool Manipulator, which serves as the master control interface for the surgeon. | ||
|
|
||
| #### Subcomponents | ||
|
|
||
| - **Variants**: Both left (MTML) and right (MTMR) manipulators are available. | ||
| - **Meshes**: MTM meshes are stored in the `meshes` directory within the `mtm_description` package. | ||
| - **Left (MTML) and Right (MTMR) Manipulators** | ||
| - **URDF and Xacro Files** | ||
| - **Meshes** | ||
| - **Controllers** | ||
| - **RViz Configurations** | ||
|
|
||
| #### Readme | ||
|
|
||
| - **README:** [`mtm_description/README.md`](./mtm_description/README.md) | ||
|
|
||
| ### Setup Joints (SUJ) | ||
|
|
||
| The SUJ provides the mounting and positioning mechanism for the PSMs and ECM. | ||
| The `suj_description` package provides URDF models and configurations for the Setup Joints, which are the mounting and positioning mechanisms for the PSMs and ECM. | ||
|
|
||
| #### Subcomponents | ||
|
|
||
| - **Classic and Si Versions** | ||
| - **URDF and Xacro Files** | ||
| - **Meshes** | ||
| - **Controllers** | ||
| - **RViz Configurations** | ||
|
|
||
| #### Readme | ||
|
|
||
| - **Variants**: Classic and Si versions are available. | ||
| - **Meshes**: SUJ meshes are located in the `meshes` directory within the `suj_description` package. | ||
| - **README:** [`suj_description/README.md`](./suj_description/README.md) | ||
|
|
||
| ### Patient Cart | ||
|
|
||
| The Patient Cart holds the PSMs and ECM during surgical procedures. | ||
| The `patient_cart_description` package provides URDF models and configurations for the Patient Cart, which holds the PSMs and ECM during surgical procedures. | ||
|
|
||
| - **Variants**: Classic and Si models are provided. | ||
| - **Integration**: The Patient Cart URDF includes the SUJ and mounting points for the PSMs and ECM. | ||
| #### Subcomponents | ||
|
|
||
| - **Classic and Si Models** | ||
| - **Integration with SUJ and Mounting Points for PSMs and ECM** | ||
| - **URDF and Xacro Files** | ||
| - **Controllers** | ||
| - **RViz Configurations** | ||
|
|
||
| #### Readme | ||
|
|
||
| - **README:** [`patient_cart_description/README.md`](./patient_cart_description/README.md) | ||
|
|
||
| --- | ||
|
|
||
| ## Launching the URDF Models | ||
|
|
||
| Use the following ROS 2 commands to launch the URDF models: | ||
|
|
||
| - **PSM Classic Model**: | ||
| ```bash | ||
| ros2 launch psm_description urdf.launch.py file:=psm.classic.urdf.xacro | ||
| ``` | ||
| - **ECM Model**: | ||
| ```bash | ||
| ros2 launch ecm_description view_robot.launch.py file:=ecm.urdf.xacro | ||
| ``` | ||
| - **MTM Models**: | ||
| ```bash | ||
| ros2 launch mtm_description urdf.launch.py file:=mtms.urdf.xacro | ||
| ``` | ||
| - **SUJ Classic Model**: | ||
| ```bash | ||
| ros2 launch suj_description urdf.launch.py file:=suj.classic.urdf.xacro | ||
| ``` | ||
| - **Patient Cart Classic Model**: | ||
| ```bash | ||
| ros2 launch patient_cart_description urdf.launch.py file:=patient_cart.classic.urdf.xacro | ||
| ``` | ||
| ## Building the Packages | ||
|
|
||
| Ensure you have a **ROS 2** workspace set up. Clone the `dvrk_urdf` meta-package into the `src` directory of your workspace, and then build the workspace: | ||
|
|
||
| ```bash | ||
| colcon build | ||
| ``` | ||
|
|
||
| Source your workspace after building: | ||
|
|
||
| ```bash | ||
| source install/setup.bash | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Notes | ||
| ## Usage Examples | ||
|
|
||
| ### Simulate the Robots with Controllers | ||
|
|
||
| #### da Vinci Core Robot | ||
|
|
||
| To simulate the da Vinci core robot with **ROS 2 control** and visualize it in **RViz**: | ||
|
|
||
| ```bash | ||
| ros2 launch davinci_core_description davinci_core_bringup.launch.py | ||
| ``` | ||
|
|
||
| - **Launch File:** [`davinci_core_description/launch/davinci_core_bringup.launch.py`](./davinci_core_description/launch/davinci_core_bringup.launch.py) | ||
| - **Launch Files README:** See [`davinci_core_description/launch/README.md`](./davinci_core_description/launch/README.md) for detailed explanations. | ||
|
|
||
| #### Patient Side Manipulator (PSM) | ||
|
|
||
| To simulate the PSM with **ROS 2 control** and visualize it in **RViz**: | ||
|
|
||
| ```bash | ||
| ros2 launch psm_description psm_bringup.launch.py | ||
| ``` | ||
|
|
||
| - **Further Information**: For detailed information on each component, refer to their individual README files within their respective packages. | ||
| - **Launch File:** [`psm_description/launch/psm_bringup.launch.py`](./psm_description/launch/psm_bringup.launch.py) | ||
| - **Launch Files README:** See [`psm_description/launch/README.md`](./psm_description/launch/README.md) for detailed explanations. | ||
|
|
||
| #### Endoscopic Camera Manipulator (ECM) | ||
|
|
||
| To simulate the ECM with **ROS 2 control** and visualize it in **RViz**: | ||
|
|
||
| ```bash | ||
| ros2 launch ecm_description ecm_bringup.launch.py | ||
| ``` | ||
|
|
||
| - **Launch File:** [`ecm_description/launch/ecm_bringup.launch.py`](./ecm_description/launch/ecm_bringup.launch.py) | ||
| - **Launch Files README:** See [`ecm_description/launch/README.md`](./ecm_description/launch/README.md) for detailed explanations. | ||
|
|
||
| #### Master Tool Manipulator (MTM) | ||
|
|
||
| To simulate the MTM with **ROS 2 control** and visualize it in **RViz**: | ||
|
|
||
| ```bash | ||
| ros2 launch mtm_description mtms_bringup.launch.py | ||
| ``` | ||
|
|
||
| - **Launch File:** [`mtm_description/launch/mtms_bringup.launch.py`](./mtm_description/launch/mtms_bringup.launch.py) | ||
| - **Launch Files README:** See [`mtm_description/launch/README.md`](./mtm_description/launch/README.md) for detailed explanations. | ||
|
|
||
| #### Setup Joints (SUJ) | ||
|
|
||
| To simulate the SUJ with **ROS 2 control** and visualize it in **RViz**: | ||
|
|
||
| ```bash | ||
| ros2 launch suj_description suj_bringup.launch.py | ||
| ``` | ||
|
|
||
| - **Launch File:** [`suj_description/launch/suj_bringup.launch.py`](./suj_description/launch/suj_bringup.launch.py) | ||
| - **Launch Files README:** See [`suj_description/launch/README.md`](./suj_description/launch/README.md) for detailed explanations. | ||
|
|
||
| #### Patient Cart | ||
|
|
||
| To simulate the Patient Cart with **ROS 2 control** and visualize it in **RViz**: | ||
|
|
||
| ```bash | ||
| ros2 launch patient_cart_description patient_cart_classic_bringup.launch.py | ||
| ``` | ||
|
|
||
| - **Launch File:** [`patient_cart_description/launch/patient_cart_classic_bringup.launch.py`](./patient_cart_description/launch/patient_cart_classic_bringup.launch.py) | ||
| - **Launch Files README:** See [`patient_cart_description/launch/README.md`](./patient_cart_description/launch/README.md) for detailed explanations. | ||
|
|
||
| #### Launch Files README | ||
|
|
||
| For detailed explanations of the launch files and their configurations, refer to the individual **Launch Files README** in each component's `launch` directory. | ||
|
|
||
| ### Visualize and Manipulate the Robots with GUI | ||
|
|
||
| #### da Vinci Core Robot | ||
|
|
||
| To launch the da Vinci core robot and manipulate its joints using the **Joint State Publisher GUI**: | ||
|
|
||
| ```bash | ||
| ros2 launch davinci_core_description view_robot.launch.py | ||
| ``` | ||
|
|
||
| - **Launch File:** [`davinci_core_description/launch/view_robot.launch.py`](./davinci_core_description/launch/view_robot.launch.py) | ||
| - **Launch Files README:** See [`davinci_core_description/launch/README.md`](./davinci_core_description/launch/README.md) for detailed explanations. | ||
|
|
||
| #### Other Components | ||
|
|
||
| To visualize and manipulate other components, use their respective `view_robot.launch.py` files: | ||
|
|
||
| ```bash | ||
| ros2 launch [component]_description view_robot.launch.py | ||
| ``` | ||
|
|
||
| Replace `[component]` with the specific component name, such as `psm`, `ecm`, `mtm`, `suj`, or `patient_cart`. | ||
|
|
||
| #### Launch Files README | ||
|
|
||
| For detailed explanations of the visualization launch files, refer to the **Launch Files README** in each component's `launch` directory. | ||
|
|
||
| --- | ||
|
|
||
| ## Dependencies | ||
|
|
||
| Ensure that you have the following dependencies installed: | ||
|
|
||
| - **ROS 2 (Foxy, Galactic, Humble, etc.)** | ||
| - **robot_state_publisher** | ||
| - **joint_state_publisher_gui** | ||
| - **ros2_control** | ||
| - **rviz2** | ||
|
|
||
| --- | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| - **da Vinci Core Description README:** [`davinci_core_description/README.md`](./davinci_core_description/README.md) | ||
| - **PSM Description README:** [`psm_description/README.md`](./psm_description/README.md) | ||
| - **ECM Description README:** [`ecm_description/README.md`](./ecm_description/README.md) | ||
| - **MTM Description README:** [`mtm_description/README.md`](./mtm_description/README.md) | ||
| - **SUJ Description README:** [`suj_description/README.md`](./suj_description/README.md) | ||
| - **Patient Cart Description README:** [`patient_cart_description/README.md`](./patient_cart_description/README.md) | ||
|
|
||
| For detailed information on each component, including URDF and Xacro files, meshes, controllers, and RViz configurations, please refer to the READMEs in the respective packages. | ||
|
|
||
| --- | ||
|
|
||
| [](https://github.com/shashank3199) |