diff --git a/README.md b/README.md new file mode 100644 index 0000000..e79a6a2 --- /dev/null +++ b/README.md @@ -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:
1. International Space Station
2. Interior of International Space Station
3. Lunar Surface
4. Mars Surface
5. Simple Chess Environment for Robonaut2
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:
[1. Curiosity Mars Rover](./docs/robots/curiosity.md)
2. Perseverance Mars Rover
[3.Ingenuity Helicopter V3](./docs//robots/ingenuity-helicopter.md)
[4.Canadarm2](./docs/robots/canadarm2.md)
[5.Robonaut2](./docs/robots/robonaut2.md) | +| [Space Robotics Scenes](docs/assets/scenes.md) | The environment assets provided by Space ROS for Nvidia's IsaacSim:
1. International Space Station with Canadarm2
2. Curiosity Mars Rover on Mars Surface
3. Simple Chess Environment for Robonaut2
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:
1. Example Omnigraph Extension for Space ROS
2. Omnigraph Extension for Rover Simple Mobile Base Controller | \ No newline at end of file diff --git a/docs/action_graph.md b/docs/action_graph.md new file mode 100644 index 0000000..a0e90fe --- /dev/null +++ b/docs/action_graph.md @@ -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. + +

+ IMU Data Publisher +

+ +> #### 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. + +

+ Odom Data Publisher +

+ +> #### 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. + +

+ Camera Data Publisher +

+ +> #### 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. + +

+ Joint State Subscriber +

+ +> #### 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. + +

+ Twist Subscriber +

+ +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. \ No newline at end of file diff --git a/docs/assets/environments.md b/docs/assets/environments.md new file mode 100644 index 0000000..8805122 --- /dev/null +++ b/docs/assets/environments.md @@ -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](../resources/images/international-space-station.png) | +| ISS Interior | International Space Station Interior for Astrobee and Robonaut2 | ![ISS Interior](../resources/images/interior-of-international-space-station.png) | +| Mars | Mars Surface of size 800 sq.m for extraction and exploration related tasks | ![Mars](../resources/images/mars-environment-curiosity-rover.png) | +| Moon | Lunar Surface of size 800 sq.m for extraction and exploration related tasks | ![Moon](../resources/images/moon-environment.png) | +| Robotnaut2 | Robotnaut2 in Manipulation Room | ![Robotnaut2](../resources/images/robonaut2-chessboard-manipulation.png) | +| Ingenuity Rover Simple Scene | Simple scene with Ingenuity Helicopter for Visual Odometry and Navigation | ![Ingenuity Rover Simple Scene](../resources/images/ingenuity-helicopter-simple.png) | + +## 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). diff --git a/docs/assets/robots.md b/docs/assets/robots.md new file mode 100644 index 0000000..da28a66 --- /dev/null +++ b/docs/assets/robots.md @@ -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](../resources/images/canadarm2.png) | +| Canadarm2 17DoFs | Canadarm2 with 17 Degrees of Freedom (DoFs) | ![Canadarm2 17DoFs](../resources/images/canadarm2-17dof.png) | +| 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. | ![Space Robot Manipulator](../resources/images/space-station-robotic-arm.png) | +| [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. | ![Robotnaut2](../resources/images/robonaut.png) | +| [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. | ![Robonaut2 Upper Body](../resources/images/robonaut-upperbody.png) | +| [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. | ![Curiosity Rover](../resources/images/curiosity-rover.png) | +| 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. | ![Perseverance Rover](../resources/images/perseverance-rover.png) | +| [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. | ![Ingenuity Helicopter](../resources/images/ingenuity-helicopter.png) | diff --git a/docs/assets/scenes.md b/docs/assets/scenes.md new file mode 100644 index 0000000..30b3d4f --- /dev/null +++ b/docs/assets/scenes.md @@ -0,0 +1,36 @@ +# Working with IsaacSim Scenes + +Scenes are the core of the IsaacSim simulation environment. They are the virtual world where you can place robots, objects, and other assets to simulate various scenarios. This document provides an overview of how to work with scenes in IsaacSim. + +You are already provided with a set of scenes in the IsaacSim. You can find the scenes in the directory `./assets/Scenes`. These scenes are simulation ready and can be used in the IsaacSim. + + +## List of Scenes + +| Scene Name | Description | Preview | +| ----------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| ISS | International Space Station | ![ISS](../resources/images/canadarm2-iss.png) | +| Robotnaut2 | Robotnaut2 in Manipulation Room | ![Robotnaut2](../resources/images/robonaut2-chessboard-manipulation.png) | +| Curiosity Rover in Mars | Mars Surface with Curiosity Rover for exploration related tasks | ![Mars](../resources/images/mars-environment-curiosity-rover.png) | +| Ingenutiy Helicopter | Ingenuity Helicopter in Simple Mars Replica Environment | ![Ingenuity Helicopter](../resources/images/ingenuity-helicopter-simple.png) | + + +## Custom Scenes + +You can create your own custom scenes using the IsaacSim Scene Editor. The Scene Editor allows you to create a new scene from scratch or modify an existing scene. You can add robots, objects, and other assets to the scene and configure their properties. The Scene Editor provides a visual interface to place and configure assets in the scene. The assets can be imported from the Asset Browser or created using the Asset Builder. + +The available assets are listed here: + - `./assets/Robots` - Contains robot models like Canadarm2, Robotnaut2, etc. + - `./assets/Props` - Contains objects like earth, etc. + - `./assets/Environments` - Contains environment models like Mars, ISS, etc. + - `./assets/Scenes` - Contains the scenes that are simulation ready. + +To creaste a custom scene, the simulation environment should have three components: + +1. **Environment**: The environment is the background of the scene. It can be a room, a building, a planet, etc. The environment provides the context for the scene. You can choose from the available environment models or create a custom environment using the Asset Builder. +2. **Robot**: The robot is the main actor in the scene. It can be a robot arm, a mobile robot, a humanoid robot, etc. You can choose from the available robot models or create a custom robot using the Asset Builder. +3. **Physics**: The physics engine simulates the physical interactions between the objects in the scene. You can configure the physics properties like gravity, friction, etc. to simulate the real-world physics. + 1. **Gravity**: The gravity in the scene can be set to simulate the real-world gravity. You can set the gravity in the scene using the Scene Editor. + 2. **Friction**: The friction in the scene can be set to simulate the real-world friction. You can set the friction in the scene using the Scene Editor. + 3. **Collision**: The collision properties in the scene can be set to simulate the real-world collisions. You can set the collision properties in the scene using the Scene Editor. + 4. **Dynamics**: The dynamics properties in the scene can be set to simulate the real-world dynamics. You can set the dynamics properties in the scene using the Scene Editor. diff --git a/docs/extensions/index.md b/docs/extensions/index.md new file mode 100644 index 0000000..4e8d180 --- /dev/null +++ b/docs/extensions/index.md @@ -0,0 +1,6 @@ +## Extensions + +Extensions are a way to add new functionality to the core of the application. They can be used to add new features, modify existing ones, or even remove them. Extensions are a powerful way to customize the application to your needs. The extension module of Space ROS has a collection of extensions that can be used to add new features to the application. The extensions that are available in the extension module are: + + - [Rover Simle Controller](./rover-simle-controller.md) - This extension adds a simple controller for the rover in the simulation environment to allow controlling mobile platforms using teleoperation. + - [Omnigraph Example](./omnigraph-example.md) - This extension provides an example of how to use the omnigraph node feature in the application to create custom graphs for the simulation environment. diff --git a/docs/extensions/negate-number.md b/docs/extensions/negate-number.md new file mode 100644 index 0000000..8f8ed3e --- /dev/null +++ b/docs/extensions/negate-number.md @@ -0,0 +1,26 @@ +## Negate Number - Omnigraph Node Extension Example + +The Negate Number extension is an omnigraph node extension that adds a node to negate the input number. This extension allows negating the input number and provides the negated number as the output. + +This is an example extension to demonstrate how to create an omnigraph node extension in Space ROS. + +### Node Configuration + +The Negate Number extension can be enabled from Extension Manager of Space ROS. The node can be added to the action graph by searching "Negate Number" in the Node Search Panel of Action Graph. The node provides the following configuration options: + +

+ Negate Number +

+ +| Node Connection | Description | +| --------------- | ------------------------------ | +| A | The input number to be negated | +| B | The negated output number | + +## Sample Usage + +

+ Negate Number Usage +

+ +The above example shows how to use the Negate Number extension in the omnigraph node. The extension provides a node that negates the input number and provides the negated number as the output. The extension allows negating the input number and provides the negated number as the output. \ No newline at end of file diff --git a/docs/extensions/rover-simle-controller.md b/docs/extensions/rover-simle-controller.md new file mode 100644 index 0000000..650ca77 --- /dev/null +++ b/docs/extensions/rover-simle-controller.md @@ -0,0 +1,28 @@ +## Rover Simple Controller - Omnigraph Node Extension + +The Rover Simple Controller extension is an omnigraph node extension that adds a simple controller for the rover in the simulation environment. This extension allows controlling mobile platforms using teleoperation. The extension provides a simple controller that can be used to control the rover in the simulation environment using the keyboard. + +### Node Configuration + +The Rover Simple Controller extension can be enabled from Extension Manager of Isaac Sim. The node can be added to the action graph by searching "Rover Simple Controller" in the Node Search Panel of Action Graph. The node provides the following configuration options: + +

+ Rover Simple Controller +

+ +| Node Connection | Description | +| ------------------------ | ---------------------------------------------------------------------------------- | +| Chassis Length | The length of the chassis of the rover in meters | +| Chassis Width | The width of the chassis of the rover in meters | +| Angular Velocity Vectory | The angular velocity vector of the rover in radians per second [format: (x, y, z)] | +| Linear Velocity Vector | The linear velocity vector of the rover in meters per second [format: (x, y, z)] | +| Steering Position | The steering position of the rover in radians | +| Wheel Velocity | The wheel velocity of the rover in meters per second. Size of (6*1) | + +## Sample Usage + +

+ Rover Simple Controller Usage +

+ +The above example shows how to use the Rover Simple Controller extension in the omnigraph node. The extension provides a simple controller that can be used to control the rover in the simulation environment using the keyboard. The extension allows controlling mobile platforms using teleoperation. \ No newline at end of file diff --git a/docs/resources/action_graphs/imu-graph.png b/docs/resources/action_graphs/imu-graph.png new file mode 100644 index 0000000..07f9837 Binary files /dev/null and b/docs/resources/action_graphs/imu-graph.png differ diff --git a/docs/resources/action_graphs/joint-states.png b/docs/resources/action_graphs/joint-states.png new file mode 100644 index 0000000..baf7bf6 Binary files /dev/null and b/docs/resources/action_graphs/joint-states.png differ diff --git a/docs/resources/action_graphs/negate-number-example.png b/docs/resources/action_graphs/negate-number-example.png new file mode 100644 index 0000000..887c98d Binary files /dev/null and b/docs/resources/action_graphs/negate-number-example.png differ diff --git a/docs/resources/action_graphs/odometry-graph.png b/docs/resources/action_graphs/odometry-graph.png new file mode 100644 index 0000000..d25ee8d Binary files /dev/null and b/docs/resources/action_graphs/odometry-graph.png differ diff --git a/docs/resources/action_graphs/rover-simple-controller.png b/docs/resources/action_graphs/rover-simple-controller.png new file mode 100644 index 0000000..457f6e4 Binary files /dev/null and b/docs/resources/action_graphs/rover-simple-controller.png differ diff --git a/docs/resources/action_graphs/simple-camera-graph.png b/docs/resources/action_graphs/simple-camera-graph.png new file mode 100644 index 0000000..2ead4e5 Binary files /dev/null and b/docs/resources/action_graphs/simple-camera-graph.png differ diff --git a/docs/resources/action_graphs/subscribe-joint-state.png b/docs/resources/action_graphs/subscribe-joint-state.png new file mode 100644 index 0000000..6d18fa9 Binary files /dev/null and b/docs/resources/action_graphs/subscribe-joint-state.png differ diff --git a/docs/resources/extensions/negate-number.png b/docs/resources/extensions/negate-number.png new file mode 100644 index 0000000..29f6e07 Binary files /dev/null and b/docs/resources/extensions/negate-number.png differ diff --git a/docs/resources/extensions/rover-simple-controller.png b/docs/resources/extensions/rover-simple-controller.png new file mode 100644 index 0000000..ffa2ad6 Binary files /dev/null and b/docs/resources/extensions/rover-simple-controller.png differ diff --git a/docs/resources/images/canadarm2-17dof.png b/docs/resources/images/canadarm2-17dof.png new file mode 100644 index 0000000..afffeb9 Binary files /dev/null and b/docs/resources/images/canadarm2-17dof.png differ diff --git a/docs/resources/images/canadarm2-iss.png b/docs/resources/images/canadarm2-iss.png new file mode 100644 index 0000000..83d363d Binary files /dev/null and b/docs/resources/images/canadarm2-iss.png differ diff --git a/docs/resources/images/canadarm2.png b/docs/resources/images/canadarm2.png new file mode 100644 index 0000000..ba0b8c4 Binary files /dev/null and b/docs/resources/images/canadarm2.png differ diff --git a/docs/resources/images/curiosity-rover.png b/docs/resources/images/curiosity-rover.png new file mode 100644 index 0000000..7a180e5 Binary files /dev/null and b/docs/resources/images/curiosity-rover.png differ diff --git a/docs/resources/images/ingenuity-helicopter-collision.png b/docs/resources/images/ingenuity-helicopter-collision.png new file mode 100644 index 0000000..3b980fc Binary files /dev/null and b/docs/resources/images/ingenuity-helicopter-collision.png differ diff --git a/docs/resources/images/ingenuity-helicopter-simple.png b/docs/resources/images/ingenuity-helicopter-simple.png new file mode 100644 index 0000000..1b9cfd5 Binary files /dev/null and b/docs/resources/images/ingenuity-helicopter-simple.png differ diff --git a/docs/resources/images/ingenuity-helicopter.png b/docs/resources/images/ingenuity-helicopter.png new file mode 100644 index 0000000..d250648 Binary files /dev/null and b/docs/resources/images/ingenuity-helicopter.png differ diff --git a/docs/resources/images/interior-of-international-space-station.png b/docs/resources/images/interior-of-international-space-station.png new file mode 100644 index 0000000..92d7e5f Binary files /dev/null and b/docs/resources/images/interior-of-international-space-station.png differ diff --git a/docs/resources/images/international-space-station.png b/docs/resources/images/international-space-station.png new file mode 100644 index 0000000..a7b6662 Binary files /dev/null and b/docs/resources/images/international-space-station.png differ diff --git a/docs/resources/images/mars-environment-curiosity-rover.png b/docs/resources/images/mars-environment-curiosity-rover.png new file mode 100644 index 0000000..5d761d9 Binary files /dev/null and b/docs/resources/images/mars-environment-curiosity-rover.png differ diff --git a/docs/resources/images/moon-environment.png b/docs/resources/images/moon-environment.png new file mode 100644 index 0000000..1db699e Binary files /dev/null and b/docs/resources/images/moon-environment.png differ diff --git a/docs/resources/images/perseverance-rover.png b/docs/resources/images/perseverance-rover.png new file mode 100644 index 0000000..bba9c4a Binary files /dev/null and b/docs/resources/images/perseverance-rover.png differ diff --git a/docs/resources/images/robonaut-upperbody.png b/docs/resources/images/robonaut-upperbody.png new file mode 100644 index 0000000..c904dce Binary files /dev/null and b/docs/resources/images/robonaut-upperbody.png differ diff --git a/docs/resources/images/robonaut.png b/docs/resources/images/robonaut.png new file mode 100644 index 0000000..4318fd8 Binary files /dev/null and b/docs/resources/images/robonaut.png differ diff --git a/docs/resources/images/robonaut2-chessboard-manipulation.png b/docs/resources/images/robonaut2-chessboard-manipulation.png new file mode 100644 index 0000000..96c18bc Binary files /dev/null and b/docs/resources/images/robonaut2-chessboard-manipulation.png differ diff --git a/docs/resources/images/space-station-robotic-arm.png b/docs/resources/images/space-station-robotic-arm.png new file mode 100644 index 0000000..663393c Binary files /dev/null and b/docs/resources/images/space-station-robotic-arm.png differ diff --git a/docs/robots/canadarm2.md b/docs/robots/canadarm2.md new file mode 100644 index 0000000..991921e --- /dev/null +++ b/docs/robots/canadarm2.md @@ -0,0 +1,47 @@ +## SSRMS Canadarm2 + +The Space Station Remote Manipulator System (SSRMS) is a robotic system used to move equipment and supplies around the International Space Station (ISS). The SSRMS is also known as Canadarm2, because it was built by the Canadian Space Agency. + +The Canadarm2 is a large robotic arm that is attached to the ISS. It is used to move cargo, equipment, and astronauts around the station. The arm is controlled by astronauts inside the station, who use joysticks and computer screens to operate it. + +### Scene Info + +| Simple Environment | Canadarm2 with ISS | +| -------------------------------------------------------- | ------------------------------------------------------------ | +| ![Simple Environment](../resources/images/canadarm2.png) | ![Canadarm2 with ISS](../resources/images/canadarm2-iss.png) | + + - The simple environment is available in the `./assets/Robots/Canadarm2/SSRMS_Canadarm2.usd`. + - The Canadarm2 with ISS environment is available in the `./assets/Scenes/InternationalSpaceStationCanadarm2.usd`. + +### Action Graphs + +The canadarm2 has one action graph as presented below: + +- **Canadarm2 Joint Control Action Graph**. The graph is available at Prim Path: `/SSRMS_Canadarm2/JointControlGraph`. + +The above action graph pulls the joint states of the Canadarm2 and publishes them through the ROS2 bridge. You can also send joint states to the Canadarm2 using the same action graph. The same action graph is used to control the Canadarm2 in the simulation. You can find more information about the action graphs in the detailed [documentation](../action_graphs.md). + +### ROS2 Interface + +| Topic Name | Message Type | Description | +| -------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------- | +| `/canadarm2/joint_states` | `sensor_msgs/JointState` | The joint states of the Canadarm2. The message contains the joint positions, velocities, and efforts. | +| `/canadarm2/joint_command` | `sensor_msgs/JointState` | The joint commands for the Canadarm2. The message contains the joint positions, velocities, and efforts. | +| `/clock` | `rosgraph_msgs/Clock` | The clock topic for the simulation. | + +## Usage + +1. Open IsaacSim. +2. Open the scene with Canadarm2. +3. Press 'Play' button from the left panel to start the simulation. +4. You should now see the topic names in the terminal using the command as shown below: +```bash +ros2 topic list + +# /canadarm2/joint_command +# /canadarm2/joint_states +# /clock +# /parameter_events +# /rosout +``` +5. You can now publish the joint commands to the Canadarm2 using the `/canadarm2/joint_command` topic. There is an example provided in the demos repository for the same. You can find more information [here](https://github.com/space-ros/demos/tree/main/canadarm2). \ No newline at end of file diff --git a/docs/robots/curiosity.md b/docs/robots/curiosity.md new file mode 100644 index 0000000..5b630f2 --- /dev/null +++ b/docs/robots/curiosity.md @@ -0,0 +1,76 @@ +## Curiosity Mars Rover + +The Curiosity Mars Rover is a robotic vehicle that was launched by NASA in 2011. It is a part of the Mars Science Laboratory mission and is designed to explore the Gale Crater on Mars. The rover is equipped with a variety of scientific instruments to study the Martian surface and environment. The Curiosity Mars Rover is one of the most advanced robotic vehicles ever built and has provided valuable data about the geology and climate of Mars. + +### Scene Info + +| Simple Environment | Curiosity Mars Rover on Mars Surface | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| ![Simple Environment](../resources/images/curiosity-rover.png) | ![Curiosity Mars Rover on Mars Surface](../resources/images/mars-environment-curiosity-rover.png) | + + - The simple environment is available in the `./assets/Robots/Curiosity_Mars_Rover/CuriosityMarsRover.usd`. + - The Curiosity Mars Rover on Mars Surface environment is available in the `./assets/Scenes/MarsEnvironment.usd`. + +### Action Graphs + +The Curiosity Mars Rover has the following action graphs: + +1. **IMU Publish Action Graph**. Available at Prim Path: `/curiosity_mars_rover/Graph/ROS_Imu`. +2. **Mobile Base Controller Action Graph**. Available at Prim Path: `/curiosity_mars_rover/Graph/MobilePlatformController`. +3. **Tool Arm Controller Action Graph**. Available at Prim Path: `/curiosity_mars_rover/Graph/ArmController`. +4. **Mast Arm Controller Action Graph**. Available at Prim Path: `/curiosity_mars_rover/Graph/MastArmController`. +5. **Odometry Publish Action Graph**. Available at Prim Path: `/curiosity_mars_rover/Graph/ROS_Odometry`. +6. **Camera Publish Action Graph**. Available at Prim Path: `/curiosity_mars_rover/Graph/ROS_Camera`. + +The action graphs mentioned above are some of the common action graphs used across the Space ROS assets. The action graphs are used to publish the data from the Curiosity Mars Rover to the ROS2 bridge. The data includes the IMU data, odometry data, camera data, and the control commands for the mobile base, tool arm, and mast arm. You can find more information about the action graphs in the detailed [documentation](../action_graphs.md). + +### ROS2 Interface + +The Curiosity Mars Rover publishes the following topics: + +| Topic Name | Message Type | Description | +| ---------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `/curiosity/tf` | `tf2_msgs/TFMessage` | The transformation data from the Curiosity Mars Rover. The message contains the transformation data. | +| `/curiosity/imu` | `sensor_msgs/Imu` | The IMU data from the Curiosity Mars Rover. The message contains the linear acceleration, angular velocity, and orientation. | +| `/curiosity/odometry` | `nav_msgs/Odometry` | The odometry data from the Curiosity Mars Rover. The message contains the position, orientation, linear velocity, and angular velocity. | +| `/curiosity/mast_camera/camera_info` | `sensor_msgs/CameraInfo` | The camera information from the Curiosity Mars Rover. The message contains the camera calibration data. | +| `/curiosity/mast_camera/rgb` | `sensor_msgs/Image` | The camera data from the Curiosity Mars Rover. The message contains the image data. | +| `/curiosity/mast_camera/depth` | `sensor_msgs/Image` | The depth data from the Curiosity Mars Rover. The message contains the depth image data. | +| `/curiosity/mast_camera/depth_pcl` | `sensor_msgs/PointCloud2` | The point cloud data from the Curiosity Mars Rover. The message contains the point cloud data. | +| `/curiosity/mast_camera/instance_segmentation` | `sensor_msgs/Image` | The instance segmentation data from the Curiosity Mars Rover. The message contains the instance segmentation image data. | +| `/curiosity/mast_camera/semantic_segmentation` | `sensor_msgs/Image` | The semantic segmentation data from the Curiosity Mars Rover. The message contains the semantic segmentation image data. | +| `/curiosity/mast_camera/semantic_labels` | `std_msgs/String` | The semantic labels from the Curiosity Mars Rover. The message contains the semantic labels. | +| `/curiosity/arm/joint_command` | `sensor_msgs/JointState` | The joint commands for the Curiosity Mars Rover's tool arm. The message contains the joint positions, velocities, and efforts. | +| `/curiosity/mast_arm/joint_command` | `sensor_msgs/JointState` | The joint commands for the Curiosity Mars Rover's mast arm. The message contains the joint positions, velocities, and efforts. | +| `/curiosity/cmd_vel` | `geometry_msgs/Twist` | The velocity commands for the Curiosity Mars Rover's mobile base. The message contains the linear and angular velocities. | +| `/clock` | `rosgraph_msgs/Clock` | The ROS clock message. The message contains the ROS time. | + +## Usage + +1. Open IsaacSim. +2. Open the scene with Curiosity Mars Rover. +3. Press 'Play' button from the left panel to start the simulation. +4. You should now see the topic names in the terminal using the command as shown below: +```bash +ros2 topic list + +# Output +# /clock +# /curiosity/arm/joint_command +# /curiosity/cmd_vel +# /curiosity/imu +# /curiosity/mast_arm/joint_command +# /curiosity/mast_camera/camera_info +# /curiosity/mast_camera/depth +# /curiosity/mast_camera/depth_pcl +# /curiosity/mast_camera/instance_segmentation +# /curiosity/mast_camera/rgb +# /curiosity/mast_camera/semantic_labels +# /curiosity/mast_camera/semantic_segmentation +# /curiosity/odometry +# /curiosity/tf +# /parameter_events +# /rosout +``` + +5. You can now publish the joint commands to the Curiosity Mars Rover's tool arm and mast arm using the `/curiosity/arm/joint_command` and `/curiosity/mast_arm/joint_command` topics respectively. You can also publish the velocity commands to the Curiosity Mars Rover's mobile base using the `/curiosity/cmd_vel` topic. There are examples provided in the demos repository for the same. You can find more information [here](https://github.com/space-ros/demos/tree/main/curiosity). \ No newline at end of file diff --git a/docs/robots/ingenuity-helicopter.md b/docs/robots/ingenuity-helicopter.md new file mode 100644 index 0000000..1c08e97 --- /dev/null +++ b/docs/robots/ingenuity-helicopter.md @@ -0,0 +1,52 @@ +## Ingenuity Helicopter + +The Ingenuity Helicopter is a small robotic helicopter that is part of the Mars 2020 mission. It is designed to demonstrate the technology of powered flight in the thin atmosphere of Mars. The helicopter is equipped with a camera and other sensors to help it navigate and explore the Martian surface. + +The robot is available in the IsaacSim as a simulation asset. You can import the robot in your scene and use it for various tasks such as visual odometry, navigation, and exploration. The robot can be found at a location `./assets/Robots/Ingenuity_Helicopter`. + +### Scene Info + +| Simple Environment | Ingenuity Helicopter with Mars Replica Environment | +| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| ![Simple Environment](../resources/images/ingenuity-helicopter.png) | ![Ingenuity Helicopter with Mars Surface](../resources/images/ingenuity-helicopter-simple.png) | + +- The simple environment is available in the `./assets/Robots/Ingenuity_Helicopter/IngenuityV3.usd`. +- The Ingenuity Helicopter with Mars Surface environment is available in the `./assets/Scenes/SimpleIngenuityHelicopterScene.usd`. + +### Action Graphs + +The Ingenuity Helicopter has the following action graph as presented below: + + - **ROS IMU Action Graph**. The graph is available at Prim Path: `/Ingenuity/Graphs/ImuSensorGraph`. + - **Downward Camera Action Graph**. The graph is available at Prim Path: `/Ingenuity/Graphs/DownFacingCamera`. + +The above action graphs pull the sensor data from the Ingenuity Helicopter and publish them through the ROS2 bridge. You can also send commands to the Ingenuity Helicopter using the same action graphs. The same action graphs are used to control the Ingenuity Helicopter in the simulation. You can find more information about the action graphs in the detailed [documentation](../action_graphs.md). + +### ROS2 Interface + +| Topic Name | Message Type | Description | +| ----------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | +| `/ingenuity_helicopter/imu` | `sensor_msgs/Imu` | The IMU sensor data of the Ingenuity Helicopter. The message contains the linear acceleration, angular velocity, and orientation. | +| `/ingenuity_helicopter/camera_info` | `sensor_msgs/CameraInfo` | The camera info topic for the Ingenuity Helicopter. | +| `/ingenuity_helicopter/rgb` | `sensor_msgs/Image` | The raw image topic for the Ingenuity Helicopter. | +| `/clock` | `rosgraph_msgs/Clock` | The clock topic for the simulation. | + +## Usage + +1. Open IsaacSim. +2. Open the scene with Ingenuity Helicopter. +3. Press 'Play' button from the left panel to start the simulation. +4. You should now see the topic names in the terminal using the command as shown below: +```bash +ros2 topic list + +# /ingenuity_helicopter/imu +# /ingenuity_helicopter/camera_info +# /ingenuity_helicopter/rgb +# /clock +# /parameter_events +# /rosout +``` + +5. You can now subscribe to the topics and visualize the data from the Ingenuity Helicopter. There is an example provided in the demos repository for the same. You can find more information [here](https://github.com/space-ros/demos/tree/main/ingenuity-helicopter). + diff --git a/docs/robots/robonaut2.md b/docs/robots/robonaut2.md new file mode 100644 index 0000000..457c545 --- /dev/null +++ b/docs/robots/robonaut2.md @@ -0,0 +1,52 @@ +## Robonaut 2 + +The Robonaut 2 is a humanoid robot developed by NASA and General Motors. It is designed to assist astronauts with various tasks on the International Space Station (ISS). The robot is equipped with a variety of sensors and tools to help it perform tasks such as maintenance, repairs, and experiments. + +There are two versions of the Robonaut 2: R2A and R2B. The R2A version was sent to the ISS in 2011 and was used for various experiments and demonstrations. The R2B version is a ground-based version of the robot that is used for research and development. + +### Scene Info + +| Simple Environment | Robonaut 2 in Simple Chess Environment | +| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| ![Simple Environment](../resources/images/robonaut-upperbody.png) | ![Robonaut 2 in Simple Chess Environment](../resources/images/robonaut2-chessboard-manipulation.png) | + + - The simple environment is available in the `./assets/Robots/Robonaut2/Robonaut2UpperBody.usd`. + - The Robonaut 2 in Simple Chess Environment is available in the `./assets/Scenes/Robonaut2Manipulation.usd`. + +### Action Graphs + +The Robonaut 2 has the following action graphs: + +1. **IMU Publish Action Graph**. Available at Prim Path: `/Robonaut2/Graph/IMUPublishGraph`. +2. **Joint State Publish Action Graph**. Available at Prim Path: `/Robonaut2/Graph/ROS_JointStates`. + +The action graphs mentioned above are some of the common action graphs used across the Space ROS assets. The action graphs are used to publish the data from the Robonaut 2 to the ROS2 bridge. The data includes the IMU data and joint states. You can find more information about the action graphs in the detailed [documentation](../action_graphs.md). + +### ROS2 Interface + +The Robonaut 2 publishes the following topics: + +| Topic Name | Message Type | Description | +| -------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------ | +| `/robonaut2/imu` | `sensor_msgs/Imu` | The IMU data from the Robonaut 2. The message contains the linear acceleration, angular velocity, and orientation. | +| `/robonaut2/joint_states` | `sensor_msgs/JointState` | The joint states from the Robonaut 2. The message contains the joint positions, velocities, and efforts. | +| `/robonaut2/joint_command` | `sensor_msgs/JointState` | The joint commands for the Robonaut 2. The message contains the joint positions, velocities, and efforts. | +| `/clock` | `rosgraph_msgs/Clock` | The ROS clock message. The message contains the ROS time. | + +## Usage + +1. Open IsaacSim. +2. Open the scene with Robonaut 2 in Simple Chess Environment. +3. Press 'Play' button from the left panel to start the simulation. +4. You should now see the topic names in the terminal using the command as shown below: +```bash +ros2 topic list + +# Output +# /clock +# /robonaut2/imu +# /robonaut2/joint_command +# /robonaut2/joint_states +# /rosout +# /parameter_events +``` diff --git a/docs/ros2.md b/docs/ros2.md new file mode 100644 index 0000000..8457114 --- /dev/null +++ b/docs/ros2.md @@ -0,0 +1,20 @@ +# ROS Bridge for IsaacSim + +This document provides an overview of the ROS2 interface for the IsaacSim simulation environment. The ROS2 interface allows you to communicate with the IsaacSim simulation environment using ROS2 messages and services. You can use the ROS2 interface to send commands to the robots, receive sensor data, and interact with the simulation environment. + +## Overview + +You can refer to the official documentation for the ROS2 interface [here](https://docs.omniverse.nvidia.com/isaacsim/latest/features/external_communication/ext_omni_isaac_ros_bridge.html). + +More information will be added soon. + + +## Usage + +1. Make sure the ros2 bridge extension is enabled in IsaacSim. +2. All robot assets are equipped with omnigraphs that publish the data to the ROS2 bridge. You can find the action graphs for the robots in the `Graph` folder of the robot asset. +3. You can use the ROS2 interface to communicate with the robots using the topics and services provided by the ROS2 bridge. +4. You can find more information about the ROS2 interface in the official documentation [here](https://docs.omniverse.nvidia.com/isaacsim/latest/features/external_communication/ext_omni_isaac_ros_bridge.html). + +### References +1. You can find more information on using ros2 bridge omnigraph nodes [here](./action_graph.md). \ No newline at end of file