AIRO-300: Package install instructions (#79)

* AIRO-300: Ancillary package install instructions, FAQ update
* Gripper rotation, ROSGeometry addition (#81)
This commit is contained in:
Amanda 2021-01-04 10:50:42 -07:00 коммит произвёл GitHub
Родитель 3e229040e5
Коммит 8c87be84e9
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
9 изменённых файлов: 108 добавлений и 68 удалений

Просмотреть файл

@ -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)

51
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 [unity-robotics@unity3d.com](mailto:unity-robotics@unity3d.com).
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 [unity-robotics@unity3d.com](mailto:unity-robotics@unity3d.com)!

Двоичные данные
images/packman.png Normal file

Двоичный файл не отображается.

После

Ширина:  |  Высота:  |  Размер: 30 KiB

Просмотреть файл

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

Просмотреть файл

@ -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

Просмотреть файл

@ -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

Просмотреть файл

@ -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 class SourceDestinationPublisher : MonoBehaviour
// 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

Просмотреть файл

@ -3,8 +3,13 @@ using System.Linq;
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 class TrajectoryPlanner : MonoBehaviour
// 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);

20
tutorials/quick_setup.md Normal file
Просмотреть файл

@ -0,0 +1,20 @@
# 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.