Unity-Technologies · mpinol · Apr 27, 2021 · Apr 7, 2021 · Apr 27, 2021 · Apr 27, 2021
diff --git a/faq.md b/faq.md
@@ -7,9 +7,7 @@
 	- [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)
@@ -58,23 +56,16 @@ 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/Manual/class-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 --git a/tutorials/pick_and_place/2_ros_tcp.md b/tutorials/pick_and_place/2_ros_tcp.md
@@ -140,7 +140,7 @@ To enable communication between Unity and ROS, a TCP endpoint running as a ROS n
 
    - If you are **not** running ROS services in a Docker container, replace the `ROS IP Address` value with the IP address of your ROS machine. Ensure that the `Host Port` is set to `10000`.
 
-   - If you **are** running ROS services in a Docker container, fill `ROS IP Address` and `Override Unity IP Address` with the loopback IP address `127.0.0.1`. Otherwise, leave the `Override Unity IP Address` field empty.
+   - If you **are** running ROS services in a Docker container, fill `ROS IP Address` with the loopback IP address `127.0.0.1` and the `Override Unity IP Address` as your local machine's IP address. Otherwise, leave the `Override Unity IP Address` field empty.
 
    ![](img/2_settings.png)
 

diff --git a/tutorials/ros_unity_integration/README.md b/tutorials/ros_unity_integration/README.md
@@ -14,6 +14,8 @@ The `ROSConnection` plugin (also from [ROS TCP Connector](https://github.com/Uni
 
 
 ## Tutorials
+- [ROS–Unity Integration: Initial Setup](setup.md) - ROS-Unity Initial Setup
+- [ROS–Unity Integration: Network Description](network.md) - Description of network settings and troubleshooting
 - [ROS–Unity Integration: Publisher](publisher.md) - Adding a Publisher to a Unity Scene
 - [ROS–Unity Integration: Subscriber](subscriber.md) - Adding a Subscriber to a Unity Scene
 - [ROS–Unity Integration: Service](service.md) - Adding a Service call to a Unity Scene

diff --git a/tutorials/ros_unity_integration/images/troubleshoot-docker-unity.png b/tutorials/ros_unity_integration/images/troubleshoot-docker-unity.png
diff --git a/tutorials/ros_unity_integration/images/troubleshoot-port-firewall.png b/tutorials/ros_unity_integration/images/troubleshoot-port-firewall.png
diff --git a/tutorials/ros_unity_integration/images/troubleshoot-ros-settings.png b/tutorials/ros_unity_integration/images/troubleshoot-ros-settings.png
diff --git a/tutorials/ros_unity_integration/images/troubleshoot-unity-firewall.png b/tutorials/ros_unity_integration/images/troubleshoot-unity-firewall.png
diff --git a/tutorials/ros_unity_integration/images/troubleshoot-windows-firewall_i.png b/tutorials/ros_unity_integration/images/troubleshoot-windows-firewall_i.png
diff --git a/tutorials/ros_unity_integration/network.md b/tutorials/ros_unity_integration/network.md
@@ -0,0 +1,119 @@
+# ROS–Unity Integration Networking
+
+## Table of Contents
+- [Definitions](#definitions)
+- [Communicaton Minimum Requirements](#communication-minimum-requirements)
+	- [If Using Docker](#if-using-docker)
+	- [Explicitly Setting UNITY_IP](#explicitly-setting-unity_ip)
+- [Troubleshoooting](#troubleshooting)
+	- [Where Does Communication Break Down](#where-does-communication-break-down)
+		- [1. Can Unity send messages to ROS?](#1-can-unity-send-messages-to-ros)
+		- [2. Can ROS send messages to Unity?](#2-can-ros-send-messages-to-unity)
+	- [Open Port on Windows Firewalll](#open-port-on-windows-firewall)
+
+# Definitions
+
+`ROS_IP` : The IP address of the machine, VM, or container running ROS.
+
+`UNITY_IP` : The IP address of the machine running Unity.
+
+> It is possible to set both of these variables on the machines running Unity and ROS. The specifics of where and why each of these settings will be described below.
+
+On the ROS machine these settings are set as a rosparam and will typically be set in a launch file like [this](https://github.com/Unity-Technologies/Unity-Robotics-Hub/blob/main/tutorials/ros_packages/robotics_demo/launch/robo_demo.launch) or in a [param file](https://github.com/Unity-Technologies/Unity-Robotics-Hub/blob/main/tutorials/pick_and_place/ROS/src/niryo_moveit/config/params.yaml) loaded by a launch file like [this](https://github.com/Unity-Technologies/Unity-Robotics-Hub/blob/main/tutorials/pick_and_place/ROS/src/niryo_moveit/launch/part_3.launch#L2). The param file can also be loaded manually by running the `rosparam load params.yaml` command.
+
+On the Unity machine these settings are set from the menu by going to `Robotics` -> `ROS Settings`
+
+
+# Communication Minimum Requirements
+
+The minimum settings required for Unity to communicate with ROS is to set the `ROS_IP` on the ROS side in a launch file and on the Unity side in `Robotics` -> `ROS Settings`.
+
+## If Using Docker
+
+The container will need to be started with the following arguments to forward the ports used for communication between ROS and Unity. 
+
+`-p 10000:10000 -p 5005:5005`
+
+
+- On the ROS side, set `ROS_IP` to `0.0.0.0`.
+
+- On the Unity side, set `ROS_IP` to `127.0.0.1` and the `Override Unity IP Address` to your local machine's IP address.
+
+![](images/troubleshoot-docker-unity.png)
+
+## Explicitly setting `UNITY_IP`
+
+The `UNITY_IP` can be set in two different places.
+
+1. If set on the ROS side as a rosparam, the `server_endpoint` will only use this IP to send messages to Unity.
+1. If set on the Unity side as the `Override Unity IP Address`, the `UNITY_IP` on the ROS side will be set to this value during the initial handshake between ROS and Unity once play is pressed in the Editor.
+
+> If the `UNITY_IP` is not set in either of these places, then the IP that makes the first connection to ROS during the initial handshake will be used.
+
+# Troubleshooting
+
+## Where Does Communication Break Down
+
+### 1. Can Unity send messages to ROS?
+
+When play is pressed in the Editor, a handshake message is sent from Unity to ROS.
+
+If Unity can communicate with ROS, the following message should be printed to the console screen running the `server_endpoint.py` script.
+
+```[UnityTcpSender]: ROS-Unity Handshake received, will connect to UNITY_IP_ADDRESS:5005```
+
+With the corresponding response message printed to the Unity console,
+
+```ROS-Unity server listening on UNITY_IP_ADDRESS:5005```
+
+
+If the previous message is not shown and either of the following errors are thrown instead:
+
+```
+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.
+```
+
+```
+SocketException: Connection refused
+```
+
+Confirm that:
+
+- `server_endpoint` is running
+- You can ping ROS machine from Unity machine
+	- From a terminal on the Unity machine, run the following command to confirm whether the ROS machine is reachable over the network. ```ping ROS_IP```
+
+If issue still persists:
+
+- Confirm your IP addresses
+- If on Windows you may need to [open ports for the firewall](#open-port-on-windows-firewall).
+
+### 2. Can ROS send messages to Unity?
+
+After it is confirmed that Unity can communicate with ROS, publish a message to a ROS topic to which Unity has instantiated a subscriber.
+
+If an error is thrown in the `server_endpoint` console then ROS cannot connect to Unity.
+
+If issue still persists:
+
+- Confirm your IP addresses
+- Explicitly set the `UNITY_IP`
+- If on Windows you may need to [open ports for the firewall](#open-port-on-windows-firewall).
+
+## Open port on Windows Firewall
+- Open port in Windows Firewall by opening `Windows Defender Firewall` then selecting `Action` -> `New Rule...`
+	- Port `10000` will need to be added as an outbound rule
+	- Port `5005` will need to obe added as an inbound rule
+
+![](images/troubleshoot-port-firewall.png)
+
+In some instances opening a port did not resolve the communication issues and the Unity Editor had to be allowed through the firewall
+
+- Allow the Editor through the firewall by opening `Windows Defender Firewall` -> `Allowed Apps` and then modifying the settings for the Unity Editor to allow communication on private and public networks.
+
+![](images/troubleshoot-unity-firewall.png)
+
+
+
+
+
diff --git a/tutorials/ros_unity_integration/publisher.md b/tutorials/ros_unity_integration/publisher.md
@@ -99,6 +99,8 @@ public class RosPublisherExample : MonoBehaviour
 
 - Pressing play in the Editor should publish a message to the terminal running the `rostopic echo pos_rot` command every 0.5 seconds
 
+> Please reference [networking troubleshooting](network.md) doc if any errors are thrown.
+
 ![](images/tcp_1.gif)
 
 Continue to the [ROS Subscriber](subscriber.md) tutorial.
diff --git a/tutorials/ros_unity_integration/service.md b/tutorials/ros_unity_integration/service.md
@@ -106,4 +106,7 @@ public class RosServiceExample : MonoBehaviour
 - Attach the `RosServiceExample` script to the `RosService` GameObject. Drag the cube GameObject onto its `cube` parameter.
 - Pressing play in the Editor should start communication with the `position_service` script, running as a ROS node, causing the cube to move to random positions in the scene.
 
+
+> Please reference [networking troubleshooting](network.md) doc if any errors are thrown.
+
 ![](images/tcp_3.gif)
diff --git a/tutorials/ros_unity_integration/subscriber.md b/tutorials/ros_unity_integration/subscriber.md
@@ -66,6 +66,8 @@ public class RosSubscriberExample : MonoBehaviour
 ### In ROS Terminal Window
 - After the scene has entered Play mode, run the following command: `rosrun robotics_demo color_publisher.py` to change the color of the cube GameObject in Unity to a random color
 
+> Please reference [networking troubleshooting](network.md) doc if any errors are thrown.
+
 ![](images/tcp_2.gif)
 
 Continue to the [ROS–Unity Integration Service](service.md).