AIRO-300: Package install instructions (#79)

* AIRO-300: Ancillary package install instructions, FAQ update
* Gripper rotation, ROSGeometry addition (#81)

Author: at669

Diff for: README.md

@@ -16,6 +16,7 @@ For any questions or feedback, connect directly with the Robotics team at [unity
 
 | Tutorial | Description |
 |---|---|
+| [Quick Installation Instructions](tutorials/quick_setup.md) | Brief steps on installing the Unity Robotics packages |
 | [Pick-and-Place Demo](tutorials/pick_and_place/README.md) | A complete end-to-end demonstration, including how to set up the Unity environment, how to import a robot from URDF, and how to set up two-way communication with ROS for control |
 | [ROS–Unity Integration](tutorials/ros_unity_integration/README.md) | A set of component-level tutorials showing how to set up communication between ROS and Unity |
 | [URDF Importer](tutorials/urdf_importer/urdf_tutorial.md) | Steps on using the Unity package for loading [URDF](http://wiki.ros.org/urdf) files (Unified Robot Description Format) | 
@@ -50,5 +51,8 @@ In addition to robot simulation, here are some additional, relevant Unity simula
 - Training a performant object detection ML model on synthetic data using Unity Perception tools [blog post](https://blogs.unity3d.com/2020/09/17/training-a-performant-object-detection-ml-model-on-synthetic-data-using-unity-perception-tools/)
   - Unity Perception [repository](https://github.com/Unity-Technologies/com.unity.perception)
 
+## FAQs
+- [FAQs](faq.md)
+
 ## License
 [Apache License 2.0](LICENSE)

Diff for: faq.md

@@ -1,4 +1,23 @@
-# Frequently Asked Questions
+# Frequently Asked Questions & Troubleshooting
+
+- [Frequently Asked Questions & Troubleshooting](#frequently-asked-questions--troubleshooting)
+- [General Questions](#general-questions)
+	- [Is ROS 2 support planned?](#is-ros-2-support-planned)
+	- [How does your Unity integration compare to ROS#?](#how-does-your-unity-integration-compare-to-ros)
+	- [How can I install the Unity Packages without starting from a template project?](#how-can-i-install-the-unity-packages-without-starting-from-a-template-project)
+- [ROS-TCP Endpoint/Connector](#ros-tcp-endpointconnector)
+	- [How does the TCP Endpoint compare to Rosbridge Server?](#how-does-the-tcp-endpoint-compare-to-rosbridge-server)
+	- [I receive a `Starting server on ...` message in my ROS terminal, but see a `SocketException: A connection attempt failed because the connected party did not respond after a period of time, or established connection failed because connected host has failed to respond.` in my Unity console.](#i-receive-a-starting-server-on--message-in-my-ros-terminal-but-see-a-socketexception-a-connection-attempt-failed-because-the-connected-party-did-not-respond-after-a-period-of-time-or-established-connection-failed-because-connected-host-has-failed-to-respond-in-my-unity-console)
+	- [I'm getting the error: `...failed because unknown error handler name 'rosmsg'`.](#im-getting-the-error-failed-because-unknown-error-handler-name-rosmsg)
+	- [Unity can't connect to ROS!](#unity-cant-connect-to-ros)
+- [URDF-Importer](#urdf-importer)
+	- [I don't see an option to Import Robot from URDF, or I have compile errors upon importing the URDF-Importer.](#i-dont-see-an-option-to-import-robot-from-urdf-or-i-have-compile-errors-upon-importing-the-urdf-importer)
+- [Can't find what you're looking for?](#cant-find-what-youre-looking-for)
+
+# General Questions
+Is ROS 2 support planned?
+---
+We definitely plan to support ROS 2 in the future. Let us know more about your use case in order to prioritize our work by reaching out to us at [[email protected]](mailto:[email protected]).
 
 How does your Unity integration compare to [ROS#](https://github.com/siemens/ros-sharp)?
 ---
@@ -8,11 +27,18 @@ In the URDF Importer we have added the functionality to instantiate a robot from
 
 Aside from facilitating communication with the TCP Endpoint, the TCP Connector contains the `MessageGeneration` code from ROS#. We added the extra functionality that when generating a C# class from a ROS message, functions are also generated that will serialize and deserialize the messages as ROS would internally.
 
+How can I install the Unity Packages without starting from a template project?
+---
+Refer to the [Quick Start](tutorials/quick_setup.md) instructions on how to import these packages.
+
+
+# ROS-TCP Endpoint/Connector
+
 How does the TCP Endpoint compare to [Rosbridge Server](http://wiki.ros.org/rosbridge_server)?
 ---
 To put it simply, the TCP Endpoint does not have the extra overhead of having to serialize and deserialize from JSON as its only function is to pass 'ROS serialized' messages between Unity and ROS. That being said the TCP Endpoint is not as general as ROS Bridge and has the strict requirement that all messages be serialized by the TCP Connector code.
 
-Here are some prelminary numbers from a few initial tests done during the discovery stage of this project. We will publish more test results publicly after we go through more rigorous testing but these results should be generally close enough for those curious about performance improvements.
+Here are some preliminary numbers from a few initial tests done during the discovery stage of this project. We will publish more test results publicly after we go through more rigorous testing but these results should be generally close enough for those curious about performance improvements.
 
 **Note:** These tests were run on a single machine that was only running ROS and a Unity executable.
 
@@ -29,3 +55,24 @@ The time was logged when the message was sent from Unity before being serialized
 
 - ROS# with ROS Bridge Suite took ~2 seconds
 - TCP Connector with TCP Endpoint took ~0.17 seconds
+
+I receive a `Starting server on ...` message in my ROS terminal, but see a `SocketException: A connection attempt failed because the connected party did not respond after a period of time, or established connection failed because connected host has failed to respond.` in my Unity console.
+---
+This is likely an issue with how your network adapters are set up if you are using a virtual machine. You may need to do some troubleshooting to ensure that your guest OS can talk to your host OS and vice versa. One simple way to do this is to set up a "Host-Only" style network, but this varies based on what virtualization software you're using. Try to ensure that you can `ping` your host OS's IP from inside the guest, and can `ping` the guest from the host, then try this last step again. 
+
+I'm getting the error: `...failed because unknown error handler name 'rosmsg'`.
+---
+This is due to a bug in an outdated package version. Try running `sudo apt-get update && sudo apt-get upgrade` to upgrade.
+
+Unity can't connect to ROS!
+---
+Ensure that the ROS IP address is entered correctly as the `Host Name` in the RosConnect component in Unity, and if you are using a `params.yaml` file, that the appropriate IP addresses are filled in.
+
+# URDF-Importer
+
+I don't see an option to Import Robot from URDF, or I have compile errors upon importing the URDF-Importer.
+---
+The [ArticulationBody](https://docs.unity3d.com/2020.2/Documentation/ScriptReference/ArticulationBody.html) has dependencies on Unity Editor versions [2020.2.0](https://unity3d.com/unity/whats-new/2020.2.0)+. Try updating your project to the latest 2020.2 release.
+
+# Can't find what you're looking for?
+Connect directly with the Robotics team at [[email protected]](mailto:[email protected])!

Diff for: images/packman.png

@@ -41,7 +41,7 @@ This part includes downloading and installing the Unity Editor, setting up a bas
 
 ## Setting Up the Robot 
 
-> Note: Presumably when you opened this project, the Package Manager automatically checked out and built the URDF-Importer package for you. You can double-check this now by looking for `Packages/URDF-Importer` in the Project Browser or by opening the Package Manager window.
+> Note: Presumably when you opened this project, the Package Manager automatically checked out and built the URDF-Importer package for you. You can double-check this now by looking for `Packages/URDF-Importer` in the Project Browser or by opening the Package Manager window. See the [Quick Setup](../quick_setup.md) steps for adding this package to your own project.
 
 1. Open the Physics Project Settings (Edit > Project Settings > Physics) and ensure the `Solver Type` is set to `Temporal Gauss Seidel`. This prevents erratic behavior in the joints that may be caused by the default solver.
 

Diff for: tutorials/pick_and_place/1_urdf.md

@@ -42,7 +42,7 @@ To enable communication between Unity and ROS, a TCP endpoint running as a ROS n
 
 1. If the PickAndPlaceProject Unity project is not already open, select and open it from the Unity Hub.
 
-   > Note: The Package Manager automatically checked out and built the ROS-TCP-Connection package in this project. You can verify this now by looking for `Packages/ROS-TCP-Connector` in the Project Browser or by opening the Package Manager window.
+   > Note: The Package Manager automatically checked out and built the ROS-TCP-Connection package in this project. You can verify this now by looking for `Packages/ROS-TCP-Connector` in the Project Browser or by opening the Package Manager window. See the [Quick Setup](../quick_setup.md) steps for adding this package to your own project.
 
    > The ROS-TCP-Connector package includes two pieces: TcpConnector, which contains the `ROSConnection` script described above, and MessageGeneration, which generates C# scripts from ROS msg and srv files.
 
@@ -104,23 +104,16 @@ To enable communication between Unity and ROS, a TCP endpoint running as a ROS n
       // Pick Pose
       sourceDestinationMessage.pick_pose = new RosMessageTypes.Geometry.Pose
       {
-         position = new Point(
-               target.transform.position.z,
-               -target.transform.position.x,
-               target.transform.position.y
-         ),
-         orientation = pickOrientation
+         position = target.transform.position.To<FLU>(),
+         // The hardcoded x/z angles assure that the gripper is always positioned above the target cube before grasping.
+         orientation = Quaternion.Euler(90, target.transform.eulerAngles.y, 0).To<FLU>()
       };
 
       // Place Pose
       sourceDestinationMessage.place_pose = new RosMessageTypes.Geometry.Pose
       {
-         position = new Point(
-               targetPlacement.transform.position.z,
-               -targetPlacement.transform.position.x,
-               targetPlacement.transform.position.y
-         ),
-         orientation = pickOrientation
+         position = targetPlacement.transform.position.To<FLU>(),
+         orientation = pickOrientation.To<FLU>()
       };
 
       // Finally send the message to server_endpoint.py running in ROS
@@ -130,7 +123,7 @@ To enable communication between Unity and ROS, a TCP endpoint running as a ROS n
 
    > This function first takes in the current joint target values. Then, it grabs the poses of the `target` and the `targetPlacement` objects, adds them to the newly created message `sourceDestinationMessage`, and calls `Send()` to send this information to the ROS topic `topicName` (defined as `"SourceDestination_input"`). 
 
-   > Note: Going from Unity world space to ROS world space requires a conversion. Unity's `(x,y,z)` is equivalent to the ROS `(z,-x,y)` coordinate.
+   > Note: Going from Unity world space to ROS world space requires a conversion. Unity's `(x,y,z)` is equivalent to the ROS `(z,-x,y)` coordinate. These conversions are provided via the [ROSGeometry component](https://github.com/Unity-Technologies/ROS-TCP-Connector/blob/main/ROSGeometry.md) in the ROS-TCP-Connector package.
 
 1. Return to the Unity Editor. Now that the message contents have been defined and the publisher script added, it needs to be added to the Unity world to run its functionality. 
 
@@ -176,7 +169,7 @@ To enable communication between Unity and ROS, a TCP endpoint running as a ROS n
 
 > Note: This project has been tested with Python 2 and ROS Melodic, as well as Python 3 and ROS Noetic.
 
-Most of the ROS setup has been provided via the `niryo_moveit` package. This section will describe the `.launch` files and start the necessary ROS nodes for communication. Two methods are provideds to launch ROS nodes and services: either using a ROS docker container or doing it manually in your own ROS environment.
+Most of the ROS setup has been provided via the `niryo_moveit` package. This section will describe the `.launch` files and start the necessary ROS nodes for communication. Two methods are provided to launch ROS nodes and services: either using a ROS docker container or doing it manually in your own ROS environment.
 
 ### Use Docker Container
 

Diff for: tutorials/pick_and_place/2_ros_tcp.md

@@ -37,27 +37,16 @@ Steps covered in this tutorial includes invoking a motion planning service in RO
         // Pick Pose
         request.pick_pose = new RosMessageTypes.Geometry.Pose
         {
-            position = new Point(
-                target.transform.position.z,
-                -target.transform.position.x,
-                // Add pick pose offset to position the gripper above target to avoid collisions
-                target.transform.position.y + pickPoseOffset
-            ),
-            // Orientation is hardcoded for this example so the gripper is always directly above the target object
-            orientation = pickOrientation
+            position = (target.transform.position + pickPoseOffset).To<FLU>(),
+            // The hardcoded x/z angles assure that the gripper is always positioned above the target cube before grasping.
+            orientation = Quaternion.Euler(90, target.transform.eulerAngles.y, 0).To<FLU>()
         };
 
         // Place Pose
         request.place_pose = new RosMessageTypes.Geometry.Pose
         {
-            position = new Point(
-                targetPlacement.transform.position.z,
-                -targetPlacement.transform.position.x,
-                // Use the same pick pose offset so the target cube can be seen dropping into position
-                targetPlacement.transform.position.y + pickPoseOffset
-            ),
-            // Orientation is hardcoded for this example so the gripper is always directly above the target object
-            orientation = pickOrientation
+            position = (targetPlacement.transform.position + pickPoseOffset).To<FLU>(),
+            orientation = pickOrientation.To<FLU>()
         };
 
         ros.SendServiceMessage<MoverServiceResponse>(rosServiceName, request, TrajectoryResponse);
@@ -160,7 +149,7 @@ def plan_trajectory(move_group, destination_pose, start_joint_angles):
 
 ### Use Docker Container
 
-1. If you are using ROS docker container and have not already build the ROS docker image. Follow the steps in [Part 2](2_ros_tcp.md) to build the `unity-robotics:pick-and-place` docker image.
+1. If you are using ROS docker container and have not already built the ROS docker image. Follow the steps in [Part 2](2_ros_tcp.md) to build the `unity-robotics:pick-and-place` docker image.
 
 ### Manually Setup ROS
 

Diff for: tutorials/pick_and_place/3_pick_and_place.md

@@ -1,7 +1,8 @@
 using RosMessageTypes.Geometry;
 using RosMessageTypes.NiryoMoveit;
 using UnityEngine;
-using RosQuaternion = RosMessageTypes.Geometry.Quaternion;
+using ROSGeometry;
+using Quaternion = UnityEngine.Quaternion;
 
 public class SourceDestinationPublisher : MonoBehaviour
 {
@@ -16,7 +17,7 @@ public class SourceDestinationPublisher : MonoBehaviour
     public GameObject target;
     public GameObject targetPlacement;
 
-    private readonly RosQuaternion pickOrientation = new RosQuaternion(0.5,0.5,-0.5,0.5);
+    private readonly Quaternion pickOrientation = Quaternion.Euler(90, 90, 0);
 
     // Articulation Bodies
     private ArticulationBody[] jointArticulationBodies;
@@ -60,23 +61,15 @@ public void Publish()
         // Pick Pose
         sourceDestinationMessage.pick_pose = new RosMessageTypes.Geometry.Pose
         {
-            position = new Point(
-                target.transform.position.z,
-                -target.transform.position.x,
-                target.transform.position.y
-            ),
-            orientation = pickOrientation
+            position = target.transform.position.To<FLU>(),
+            orientation = Quaternion.Euler(90, target.transform.eulerAngles.y, 0).To<FLU>()
         };
 
         // Place Pose
         sourceDestinationMessage.place_pose = new RosMessageTypes.Geometry.Pose
         {
-            position = new Point(
-                targetPlacement.transform.position.z,
-                -targetPlacement.transform.position.x,
-                targetPlacement.transform.position.y
-            ),
-            orientation = pickOrientation
+            position = targetPlacement.transform.position.To<FLU>(),
+            orientation = pickOrientation.To<FLU>()
         };
 
         // Finally send the message to server_endpoint.py running in ROS

Diff for: tutorials/pick_and_place/Scripts/SourceDestinationPublisher.cs

@@ -3,8 +3,13 @@
 using RosMessageTypes.Geometry;
 using RosMessageTypes.NiryoMoveit;
 using UnityEngine;
-using RosQuaternion = RosMessageTypes.Geometry.Quaternion;
+
+using ROSGeometry;
+using Quaternion = UnityEngine.Quaternion;
+using RosImage = RosMessageTypes.Sensor.Image;
 using Transform = UnityEngine.Transform;
+using Vector3 = UnityEngine.Vector3;
+
 
 public class TrajectoryPlanner : MonoBehaviour
 {
@@ -15,10 +20,10 @@ public class TrajectoryPlanner : MonoBehaviour
     // Hardcoded variables 
     private readonly float jointAssignmentWait = 0.1f;
     private readonly float poseAssignmentWait = 0.5f;
-    private readonly float pickPoseOffset = 0.1f;
+    private readonly Vector3 pickPoseOffset = Vector3.up * 0.1f;
 
     // Assures that the gripper is always positioned above the target cube before grasping.
-    private readonly RosQuaternion pickOrientation = new RosQuaternion(0.5,0.5,-0.5,0.5);
+    private readonly Quaternion pickOrientation = Quaternion.Euler(90, 90, 0);
 
     // Variables required for ROS communication
     public string rosServiceName = "niryo_moveit";
@@ -107,27 +112,16 @@ public void PublishJoints()
         // Pick Pose
         request.pick_pose = new RosMessageTypes.Geometry.Pose
         {
-            position = new Point(
-                target.transform.position.z,
-                -target.transform.position.x,
-                // Add pick pose offset to position the gripper above target to avoid collisions
-                target.transform.position.y + pickPoseOffset
-            ),
-            // Orientation is hardcoded for this example so the gripper is always directly above the target object
-            orientation = pickOrientation
+            position = (target.transform.position + pickPoseOffset).To<FLU>(),
+            // The hardcoded x/z angles assure that the gripper is always positioned above the target cube before grasping.
+            orientation = Quaternion.Euler(90, target.transform.eulerAngles.y, 0).To<FLU>()
         };
 
         // Place Pose
         request.place_pose = new RosMessageTypes.Geometry.Pose
         {
-            position = new Point(
-                targetPlacement.transform.position.z,
-                -targetPlacement.transform.position.x,
-                // Use the same pick pose offset so the target cube can be seen dropping into position
-                targetPlacement.transform.position.y + pickPoseOffset
-            ),
-            // Orientation is hardcoded for this example so the gripper is always directly above the target object
-            orientation = pickOrientation
+            position = (targetPlacement.transform.position + pickPoseOffset).To<FLU>(),
+            orientation = pickOrientation.To<FLU>()
         };
 
         ros.SendServiceMessage<MoverServiceResponse>(rosServiceName, request, TrajectoryResponse);