AIRO-300: Package install instructions (#79)

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

README.md

 
 | 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) | 
 - Unity Industrial Simulation [site](https://unity.com/products/unity-simulation)
 - 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)

faq.md

-# 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 [unity-robotics@unity3d.com](mailto:unity-robotics@unity3d.com).
 
 How does your Unity integration compare to [ROS#](https://github.com/siemens/ros-sharp)?
 ---
 
 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
+
-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.
 
 
 - 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 [unity-robotics@unity3d.com](mailto:unity-robotics@unity3d.com)!

tutorials/pick_and_place/1_urdf.md

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

tutorials/pick_and_place/2_ros_tcp.md

 
 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.
 
       // 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>()
-         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
 
    > 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. 
 
 
 > 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
 

tutorials/pick_and_place/3_pick_and_place.md

         // 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>()
-            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);
 
 ### 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
 

tutorials/pick_and_place/Scripts/SourceDestinationPublisher.cs

 using RosMessageTypes.Geometry;
 using RosMessageTypes.NiryoMoveit;
 using UnityEngine;
-using RosQuaternion = RosMessageTypes.Geometry.Quaternion;
+using ROSGeometry;
+using Quaternion = UnityEngine.Quaternion;
 
 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;
         // 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>()
-            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

tutorials/pick_and_place/Scripts/TrajectoryPlanner.cs

 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 Vector3 = UnityEngine.Vector3;
+
 
 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;
-    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";
         // 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>()
-            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);

tutorials/quick_setup.md

+# Installing the Unity Robotics packages
+
+This page provides brief instructions on installing the Unity Robotics packages. Head over to the [Pick-and-Place Tutorial](pick_and_place/README.md) for more detailed instructions and steps for building a sample project.
+
+1. Create or open a Unity project. 
+    > Note: If you are adding the URDF-Importer, ensure you are using a [2020.2.0](https://unity3d.com/unity/whats-new/2020.2.0)+ version of Unity Editor.
+
+1. Open `Window` -> `Package Manager`.
+
+1. In the Package Manager window, find and click the `+` button in the upper lefthand corner of the window. Select `Add package from git URL...`. 
+
+    ![](../images/packman.png)
+
+1. Enter the git URL for the desired package. 
+   1. For the [ROS-TCP-Connector](https://github.com/Unity-Technologies/ROS-TCP-Connector), enter `https://github.com/Unity-Technologies/ROS-TCP-Connector.git`. 
+   1. For the [URDF-Importer](https://github.com/Unity-Technologies/URDF-Importer), enter `https://github.com/Unity-Technologies/URDF-Importer.git`. 
+
+1. Click `Add`. 
+
+To install from a local clone of the repository, see [installing a local package](https://docs.unity3d.com/Manual/upm-ui-local.html) in the Unity manual.