forked from space-ros/simulation
-
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.
Add documentation for the repository
Related to space-ros#18 - Add documentation and description for environment and robot assets - Add documentation on extensions and usage - Add documentation on setting up ROS2 interface and ROS2 action graphs - Update README.md for system requirements, getting started guide and overview
- Loading branch information
1 parent
1db6977
commit 30b02dc
Showing
38 changed files
with
523 additions
and
0 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 |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| # Space ROS IsaacSim Extension Package | ||
|
|
||
| This repository is an extension module for Nvidia's IsaacSim. It provides the following features: | ||
|
|
||
| - Simulation Assets for Space Robotics | ||
| - ROS2 Interface for Space Robotics | ||
| - Extenstions for IsaacSim for Space Robotics | ||
|
|
||
| ## System Requirements | ||
|
|
||
| The following are the system requirements to run the project: | ||
|
|
||
| | Requirement | Description | | ||
| | ----------- | -------------------------------- | | ||
| | OS | Ubuntu 22.04 | | ||
| | RTX GPU | Nvidia RTX 30XX Series or higher | | ||
| | RAM | 16 GB or higher | | ||
| | CPU | Intel i7 or higher | | ||
|
|
||
|
|
||
| ## Prerequisites | ||
|
|
||
| The work is based on Nvidia's IsaacSim. The changes are tested on Ubuntu 22.04. The following dependencies are required to run the project: | ||
|
|
||
| | Dependency | Version | Description | | ||
| | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | IsaacSim | >=4.0.0 | Nvidia's IsaacSim. You can setup the simulation from official website. Instructions [here](https://docs.omniverse.nvidia.com/isaacsim/latest/installation/install_workstation.html) | | ||
| | ROS2 | ==Humble | ROS2 Humble acts as a middle layer. This will be soon ported to the native project. Installation Instructions [here](https://docs.ros.org/en/humble/Installation.html) | | ||
|
|
||
| ## Get Started | ||
|
|
||
| 1. Make sure the prerequisites are installed. If not, follow the instructions in the prerequisites section. | ||
| 2. Clone the repository to your local machine in your desired location. Run the following command in the terminal: | ||
| ```bash | ||
| git clone https://github.com/space-ros/simulation.git | ||
| ``` | ||
| 3. The repository contains two folders in the root directory: | ||
| - `extensions`: Contains the extensions for IsaacSim | ||
| - `assets`: Contains the ROS2 interface for IsaacSim | ||
| 4. For easier access to the assetss, you can bookmark the assets folder in the IsaacSim by following the steps: | ||
| 1. Open IsaacSim. | ||
| 2. In the Context Browser, navigate to the root of the repository and right-click on the `assets` folder. | ||
| 3. Click on the `Add Bookmark` option. | ||
| 4. You will be prompted to enter the name of the bookmark. Enter "Space ROS Assets" and click on `OK`. | ||
| 5. Now, you can access the assets from the bookmarks section in the Context Browser. | ||
| 5. For the extensions, you need to allow the extension manager of IsaacSim to know the location of the extensions. Follow the steps: | ||
| 1. Open IsaacSim. | ||
| 2. Go to `Windows` in the top menu bar and click on `Extensions`. | ||
| 3. Click on the hamburger icon on the top right corner of the Search bar in the extension manager and select `Settings`. | ||
| 4. On the right panel of the extension manager, find the section for extension search paths and click on the `+` icon at the end of the list. | ||
| 5. Navigate to the `extensions` folder in the repository and select the `extensions` folder. | ||
| 6. The extensions of Space ROS will now be available in the extension manager. You can search for the extensions in the search bar. The list of extensions is provided in the documentation below. | ||
| 7. Click on the extension and enable it by toggling the switch on the right side of the extension. You can also check the `Auto-Enable` option to enable the extension automatically when IsaacSim starts. | ||
| 8. You can repeat the steps for other extensions as well. | ||
| 6. Now, you can start using the assets and extensions in the IsaacSim. | ||
|
|
||
| > NOTE: Make sure ROS2 Bridge is extension is enabled in the IsaacSim. You can enable it by the previous steps mentioned for the extensions. | ||
| ## Documentation | ||
|
|
||
| This is a brief overview of the documentation provided in the repository. The detailed documentation can be found in the `docs` folder in the repository. | ||
|
|
||
| | Section | Description | | ||
| | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | [Space Robotics Environments](docs/assets/environments.md) | The environment assets provided by Space ROS for Nvidia's IsaacSim:<br>1. International Space Station<br>2. Interior of International Space Station<br>3. Lunar Surface<br>4. Mars Surface<br>5. Simple Chess Environment for Robonaut2<br>6. Simple Mars Replica Environment for Ingenuity Helicopter | | ||
| | [Space Robotics Robots](docs/assets/robots.md) | The robot assets provided by Space ROS for Nvidia's IsaacSIM:<br>[1. Curiosity Mars Rover](./docs/robots/curiosity.md)<br>2. Perseverance Mars Rover<br>[3.Ingenuity Helicopter V3](./docs//robots/ingenuity-helicopter.md)<br>[4.Canadarm2](./docs/robots/canadarm2.md)<br>[5.Robonaut2](./docs/robots/robonaut2.md) | | ||
| | [Space Robotics Scenes](docs/assets/scenes.md) | The environment assets provided by Space ROS for Nvidia's IsaacSim:<br>1. International Space Station with Canadarm2<br>2. Curiosity Mars Rover on Mars Surface<br>3. Simple Chess Environment for Robonaut2<br>4. Simple Mars Replica Environment for Ingenuity Helicopter | | ||
| | [ROS2 Interface](docs/ros2.md) | The ROS2 bridge and usage description for integration with Space ROS | | ||
| | [Extensions for IsaacSim](docs/extensions/index.md) | The extensions provided by Space ROS for Nvidia's IsaacSim:<br>1. Example Omnigraph Extension for Space ROS<br>2. Omnigraph Extension for Rover Simple Mobile Base Controller | |
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 |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| ## Action Graphs | ||
|
|
||
| The Action Graph is a visual programming tool that allows users to create complex robotic behaviors by connecting nodes. The nodes in the Action Graph represent different functionalities that can be used to create a robotic behavior. The nodes can be connected to create a flow of data between them. The Action Graph provides a user-friendly interface to create complex robotic behaviors without writing any code. The Action Graph is a powerful tool that can be used to create custom behaviors for robots in the simulation environment. | ||
|
|
||
| This article provides an overview of commonly used action graphs in Space ROS. The article covers the following topics: | ||
|
|
||
| - [Action Graphs](#action-graphs) | ||
| - [ROS2 Publisher for IMU Data](#ros2-publisher-for-imu-data) | ||
| - [ROS2 Publisher for Odom Data](#ros2-publisher-for-odom-data) | ||
| - [ROS2 Publisher for Camera Data](#ros2-publisher-for-camera-data) | ||
| - [Action Graph for Subscribing to Joint State Messages](#action-graph-for-subscribing-to-joint-state-messages) | ||
| - [ROS2 Suscriber for Twist Messages](#ros2-suscriber-for-twist-messages) | ||
|
|
||
| ### ROS2 Publisher for IMU Data | ||
|
|
||
| The ROS2 Publisher for IMU Data action graph is used to publish IMU data to the ROS2 network. The action graph reads IMU data from the simulation environment and publishes it to the ROS2 network. The action graph provides a node that reads IMU data from the simulation environment and publishes it to the ROS2 network. The action graph can be used to publish IMU data to the ROS2 network for further processing. | ||
|
|
||
| <p align="center"> | ||
| <img src="./resources/action_graphs/imu-graph.png" alt="IMU Data Publisher"> | ||
| </p> | ||
|
|
||
| > #### Note | ||
| > - The node 'Isaac Read IMU Node' expects the prim path of the IMU sensor to provide the IMU data. If rover is used, the IMU sensor is expected to be attached to the main body of the rover. | ||
| > - If you are using the rover in different gravity conditions, make sure the `readGravity` parameter of Node 'Isaac Read IMU Node' is set to true. This will read the gravity vector from the simulation environment and apply it to the IMU data. | ||
| ### ROS2 Publisher for Odom Data | ||
|
|
||
| The ROS2 Publisher for Odom Data action graph is used to publish odometry data to the ROS2 network. The action graph reads odometry data from the simulation environment and publishes it to the ROS2 network. The action graph provides a node that reads odometry data from the simulation environment and publishes it to the ROS2 network. The action graph can be used to publish odometry data to the ROS2 network for further processing. | ||
|
|
||
| <p align="center"> | ||
| <img src="./resources/action_graphs/odometry-graph.png" alt="Odom Data Publisher"> | ||
| </p> | ||
|
|
||
| > #### Note | ||
| > - The node 'Isaac Compute Odom Node' expects the target prim path of the rover to provide the odometry data. Make sure the prim path of the rover mesh body is provided to the 'Isaac Compute Odom Node'. | ||
| ### ROS2 Publisher for Camera Data | ||
|
|
||
| The ROS2 Publisher for Camera Data action graph is used to publish camera data to the ROS2 network. The action graph reads camera data from the simulation environment and publishes it to the ROS2 network. The action graph provides a node that reads camera data from the simulation environment and publishes it to the ROS2 network. The action graph can be used to publish camera data to the ROS2 network for further processing. | ||
|
|
||
| <p align="center"> | ||
| <img src="./resources/action_graphs/simple-camera-graph.png" alt="Camera Data Publisher"> | ||
| </p> | ||
|
|
||
| > #### Note | ||
| > - The node 'Isaac Create Render Product' expects the camera prim path to provide the camera data. Make sure the prim path of the camera is provided to the 'Isaac Read Camera Node'. | ||
| > - IsaacSim comes with different types of image data which can be selected from the 'Type' parameter of the 'ROS2 Camera Helper'. Make sure the correct image type is selected to get the desired camera data. The above graph show the configuration for RGB image data and the camera info data. | ||
| ### Action Graph for Subscribing to Joint State Messages | ||
|
|
||
| The Action Graph for Subscribing to Joint State Messages is used to subscribe to joint state messages from the ROS2 network. The action graph reads joint state messages from the ROS2 network and provides the joint state data to the simulation environment. The action graph provides a node that subscribes to joint state messages from the ROS2 network and provides the joint state data to the simulation environment. The action graph can be used to subscribe to joint state messages from the ROS2 network and update the joint states of the robot in the simulation environment. | ||
|
|
||
| <p align="center"> | ||
| <img src="./resources/action_graphs/subscribe-joint-state.png" alt="Joint State Subscriber"> | ||
| </p> | ||
|
|
||
| > #### Note | ||
| > - The node 'ROS2 Subscribe Joint State' should receive the name of the joints that need to be updated in the simulation environment. Make sure the correct joint names are provided to the 'ROS2 Subscribe Joint State' node. | ||
| > - The joint state action graph can be duplicated to multiple graphs for better organization of the joint state messages. The joint state action graph can be used to subscribe to joint state messages from the ROS2 network and update the joint states of the robot in the simulation environment. | ||
| ### ROS2 Suscriber for Twist Messages | ||
|
|
||
| The ROS2 Subscriber for Twist Messages action graph is used to subscribe to twist messages from the ROS2 network. The action graph reads twist messages from the ROS2 network and provides the twist data to the simulation environment. The action graph provides a node that subscribes to twist messages from the ROS2 network and provides the twist data to the simulation environment. The action graph can be used to subscribe to twist messages from the ROS2 network and update the twist data of the robot in the simulation environment. | ||
|
|
||
| <p align="center"> | ||
| <img src="./resources/action_graphs/rover-simple-controller.png" alt="Twist Subscriber"> | ||
| </p> | ||
|
|
||
| The above action graph is used to subscribe to twist messages from the ROS2 network and update the twist data of the rover in the simulation environment. | ||
|
|
||
| > #### Note | ||
| > - The node 'ROS2 Subscribe Twist' should receive the name of the twist topic that needs to be subscribed. Make sure the correct twist topic name is provided to the 'ROS2 Subscribe Twist' node. | ||
| > - The twist action graph can be duplicated to multiple graphs for better organization of the twist messages. The twist action graph can be used to subscribe to twist messages from the ROS2 network and update the twist data of the robot in the simulation environment. |
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 |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| # Space ROS Environments | ||
|
|
||
| At the moment, we only provide the support for environments focusing on International Space Station (ISS), Mars surface ans Lunar surface. | ||
|
|
||
| You can find the assets in the directory `./assets/Environments`. These environments are simulation ready and can be used in the IsaacSim. | ||
|
|
||
| ## List of Environments | ||
|
|
||
| | Environment | Description | Preview | | ||
| | ------------ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | ||
| | ISS | International Space Station |  | | ||
| | ISS Interior | International Space Station Interior for Astrobee and Robonaut2 |  | | ||
| | Mars | Mars Surface of size 800 sq.m for extraction and exploration related tasks |  | | ||
| | Moon | Lunar Surface of size 800 sq.m for extraction and exploration related tasks |  | | ||
| | Robotnaut2 | Robotnaut2 in Manipulation Room |  | | ||
| | Ingenuity Rover Simple Scene | Simple scene with Ingenuity Helicopter for Visual Odometry and Navigation |  | | ||
|
|
||
| ## Usage | ||
|
|
||
| You can use the environments in your simulation by importing the assets in the IsaacSim. The assets are provided in the `./assets/Environments` directory. | ||
|
|
||
| You will need to create scenes in the IsaacSim and import the assets in the scene. The scenes can be created using either IsaacSim's Omniverse Kit or Omniverse Create. More information on creating scenes can be found in the [documentation](./scenes.md). |
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 |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # Robot Assets | ||
|
|
||
| The robot assets are the models of the robots that can be used in the IsaacSim simulation environment. The robot assets are available in the `./assets/Robots` directory. | ||
|
|
||
| ## List of Robots | ||
|
|
||
| | Robot Name | Description | Preview | | ||
| | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | ||
| | [Canadarm2](../robots/canadarm2.md) | Canadarm2 is a robotic arm used on the International Space Station (ISS) for various tasks like capturing and docking spacecraft, moving equipment, etc. |  | | ||
| | Canadarm2 17DoFs | Canadarm2 with 17 Degrees of Freedom (DoFs) |  | | ||
| | Canadarm1 | Canadarm1 is a robotic arm used for manipulation tasks in space. It is designed for tasks like capturing and docking spacecraft, moving equipment, etc. |  | | ||
| | [Robotnaut2](../robots/robonaut2.md) | Robotnaut2 is a humanoid robot designed for space exploration. It is equipped with a manipulator arm and a camera for performing tasks in space. |  | | ||
| | [Robonaut2 Upper Body](../robots/robonaut2.md) | Robonaut2 Upper Body is the upper part of the Robonaut2 humanoid robot. It is equipped with a manipulator arm and a camera for performing tasks in space. |  | | ||
| | [Curiosity Rover](../robots/curiosity.md) | Curiosity Rover is a Mars rover designed for exploration tasks on the Mars surface. It is equipped with a manipulator arm and a camera for performing tasks. |  | | ||
| | Perseverance Rover | Perseverance Rover is a Mars rover designed for exploration tasks on the Mars surface. It is equipped with a manipulator arm and a camera for performing tasks. |  | | ||
| | [Ingenuity Helicopter](../robots/ingenuity-helicopter.md) | Ingenuity Helicopter is a Mars helicopter designed for aerial exploration tasks on the Mars surface. It is equipped with a camera for performing tasks. |  | |
Oops, something went wrong.